From acd3b8442d8c8dcfce18b53bf8691e9f97a9aa84 Mon Sep 17 00:00:00 2001 From: Kelly Sovacool Date: Thu, 25 Jun 2026 17:51:39 -0400 Subject: [PATCH 1/2] docs: rough diagrams for demo --- docs/demo/index.qmd | 0 docs/guide/index.qmd | 187 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 187 insertions(+) create mode 100644 docs/demo/index.qmd create mode 100644 docs/guide/index.qmd diff --git a/docs/demo/index.qmd b/docs/demo/index.qmd new file mode 100644 index 0000000..e69de29 diff --git a/docs/guide/index.qmd b/docs/guide/index.qmd new file mode 100644 index 0000000..ea8526a --- /dev/null +++ b/docs/guide/index.qmd @@ -0,0 +1,187 @@ +--- +title: "Demo" +echo: false +--- + +## Overview + +The diagram below shows how syncweaver coordinates a **source repo** and a **host repo** +through the CCBR/syncweaver orchestrator. + +```{mermaid} +sequenceDiagram + actor Dev as Developer + participant Src as Source Repo
(demo-syncweaver-source) + participant SW as Orchestrator
(CCBR/syncweaver) + participant Host as Host Repo
(demo-syncweaver-host) + + Note over Src: .github/workflows/
syncweaver-source-dispatch.yml + + Dev->>Src: push release tag + Src->>SW: repository_dispatch
(source_repository, ref) + + SW->>Host: repository_dispatch
(source_repository, ref) + + Note over Host: .github/workflows/
syncweaver-host-update.yml + + Host->>Host: resolve source_path
from .syncweaver-lock.json + Host->>Src: fetch code at ref + Host->>Host: vendor code into source_path + Host->>Host: open pull request
with updated vendored code + + Note over Host,Src: If the host has local patches... + + Dev->>Host: trigger contribute-patch + Note over Host: .github/workflows/
syncweaver-host-contribute-patch.yml + Host->>Src: open pull request
with patch applied upstream +``` + +## Repository layouts + +This view emphasizes a different question than the sequence diagram: which +source repositories are vendored into which host capsules. + +```{mermaid} +flowchart LR + subgraph H1[demo-syncweaver-host] + H1A[code/hello] + H1B[code/MOSuite] + end + + subgraph H2[MOSuite-create] + H2A[code/MOSuite] + end + + subgraph H3[MOSuite-clean] + H3A[code/MOSuite] + end + + S1[demo-syncweaver-source
modules/hello] + S2[CCBR/MOSuite
R package source] + + S1 --> H1A + S2 --> H1B + S2 --> H2A + S2 --> H3A +``` + +In these examples, one host capsule can aggregate multiple upstream sources, +while other capsules vendor just a single shared source package. + +### Source repo - monorepo + +The source repo holds the canonical code. A single workflow template triggers +the dispatch chain on every release. + +``` +demo-syncweaver-source/ +├── .github/ +│ └── workflows/ +│ └── syncweaver-source-dispatch.yml ← notifies orchestrator on release +└── modules/ + └── hello/ ← vendored into host as code/hello + ├── DESCRIPTION + ├── NAMESPACE + ├── R/ + ├── inst/ + └── man/ +``` + +### Host repo - Code Ocean capsule + +The host repo consumes vendored code and carries a lockfile that pins each +dependency to a specific ref and git SHA. + +``` +demo-syncweaver-host/ +├── .github/ +│ └── workflows/ +│ ├── syncweaver-host-update.yml ← receives dispatch, opens update PR +│ └── syncweaver-host-contribute-patch.yml ← sends local patches upstream +├── .syncweaver-lock.json ← pins source repos + refs +└── code/ + ├── main.R + ├── hello/ ← vendored from demo-syncweaver-source modules/hello + │ ├── DESCRIPTION + │ ├── NAMESPACE + │ ├── R/ + │ └── inst/ + └── MOSuite/ ← vendored from CCBR/MOSuite +``` + +### Source repo - MOSuite + +This is a package-style source repository. The canonical implementation lives in +the package root, and the syncweaver source-dispatch workflow is defined under +`.github/workflows/`. + +``` +multiOmicsSuite/ +├── .github/ +│ └── workflows/ +│ └── syncweaver-source-dispatch.yml ← notifies syncweaver on release +├── DESCRIPTION +├── NAMESPACE +├── R/ ← primary package implementation +│ ├── cli.R +│ ├── clean.R +│ ├── differential.R +│ ├── normalize.R +│ └── ... +├── inst/ +│ ├── extdata/ +│ └── quarto/ +├── man/ +└── tests/ +``` + +### Host repo example - MOSuite-create capsule + +This host repo is a Code Ocean capsule. It vendors source code into `code/`, +tracks upstream state in `.syncweaver-lock.json`, and keeps capsule runtime +files alongside the vendored package. + +``` +MOSuite-create/ +├── .github/ +│ └── workflows/ +│ └── syncweaver-update-source.yml ← host-side sync workflow in this repo +├── .syncweaver-lock.json ← pins vendored sources to refs + SHAs +├── code/ +│ ├── main.R +│ ├── run/ +│ └── MOSuite/ ← vendored from multiOmicsSuite +├── environment/ +│ ├── Dockerfile +│ └── postInstall +├── metadata/ +│ └── metadata.yml +└── tests/ +``` + +## Repos + +| Role | Example repo | Key file | +|------|-------------|----------| +| Source | [demo-syncweaver-source](https://github.com/NIDAP-Community/demo-syncweaver-source) | `.github/workflows/syncweaver-source-dispatch.yml` | +| Host | [demo-syncweaver-host](https://github.com/NIDAP-Community/demo-syncweaver-host) | `.syncweaver-lock.json`, `.github/workflows/syncweaver-host-update.yml` | +| Orchestrator | [CCBR/syncweaver](https://github.com/CCBR/syncweaver) | `.github/host-repositories.yml`, `.github/workflows/syncweaver-update-hosts` | + +## Lockfile + +The host repo tracks each vendored dependency in `.syncweaver-lock.json`: + +```json +{ + "sources": { + "code/hello": { + "repo_url": "https://github.com/NIDAP-Community/demo-syncweaver-source", + "ref": "main", + "remote_subdir": "modules/hello" + } + } +} +``` + +When the source repo publishes a release, the dispatch chain updates the +vendored code at `code/hello` and opens a pull request in the host repo. From a58aaf2430296c326a22704b7410f1c23c5dabb1 Mon Sep 17 00:00:00 2001 From: Kelly Sovacool Date: Thu, 25 Jun 2026 18:12:25 -0400 Subject: [PATCH 2/2] docs: improve diagrams --- docs/guide/index.qmd | 42 +++++++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/docs/guide/index.qmd b/docs/guide/index.qmd index ea8526a..b52fab9 100644 --- a/docs/guide/index.qmd +++ b/docs/guide/index.qmd @@ -6,28 +6,27 @@ echo: false ## Overview The diagram below shows how syncweaver coordinates a **source repo** and a **host repo** -through the CCBR/syncweaver orchestrator. +through the CCBR/syncweaver orchestrator. Host repos can become Code Ocean capsules. ```{mermaid} sequenceDiagram actor Dev as Developer participant Src as Source Repo
(demo-syncweaver-source) participant SW as Orchestrator
(CCBR/syncweaver) - participant Host as Host Repo
(demo-syncweaver-host) + participant Host as Host (Capsule) Repo
(demo-syncweaver-host) Note over Src: .github/workflows/
syncweaver-source-dispatch.yml Dev->>Src: push release tag Src->>SW: repository_dispatch
(source_repository, ref) - SW->>Host: repository_dispatch
(source_repository, ref) + Note over SW: .github/workflows/
syncweaver-update-hosts.yml - Note over Host: .github/workflows/
syncweaver-host-update.yml + SW->>SW: resolve target hosts from
.github/host-repositories.yml + SW->>Src: fetch code at ref + SW->>SW: run functracer release impact
for each host - Host->>Host: resolve source_path
from .syncweaver-lock.json - Host->>Src: fetch code at ref - Host->>Host: vendor code into source_path - Host->>Host: open pull request
with updated vendored code + SW->>Host: open pull request
with updated vendored code
if host is impacted by release Note over Host,Src: If the host has local patches... @@ -79,7 +78,13 @@ demo-syncweaver-source/ │ └── workflows/ │ └── syncweaver-source-dispatch.yml ← notifies orchestrator on release └── modules/ - └── hello/ ← vendored into host as code/hello + ├── hello/ ← vendored into host as code/hello + │ ├── DESCRIPTION + │ ├── NAMESPACE + │ ├── R/ + │ ├── inst/ + │ └── man/ + └── heatmap/ ← new module for hypothetical heatmap capsule ├── DESCRIPTION ├── NAMESPACE ├── R/ @@ -185,3 +190,22 @@ The host repo tracks each vendored dependency in `.syncweaver-lock.json`: When the source repo publishes a release, the dispatch chain updates the vendored code at `code/hello` and opens a pull request in the host repo. + +## dependency analysis and release impact tracing + +This view highlights how `functracer` narrows updates to only affected capsules +after a source release. + +```{mermaid} +flowchart TD + A["Source release tagged
(e.g. in demo-syncweaver-source or MOSuite)"] + B[functracer analyzes call graph
from capsule entry scripts] + C{Capsule affected
by changed functions?} + D[syncweaver updates lockfile
and opens update PR] + E[No update PR
for this capsule] + + A --> B + B --> C + C -->|Yes| D + C -->|No| E +```