Feat/multi repo workspace#4
Merged
Merged
Conversation
…s detection v1.4.0 workspace feature complete across CLI, TUI, and MCP interfaces. Workspace module (src/workspace/): - types.ts: WorkspaceConfig, MergedReport, MergeDiffSummary, tag registry types - metadata.ts: workspace.yaml parser/serializer, report metadata with repo/workspace fields - merge.ts: N-repo merge with tag registry, cross-repo ref resolution, stale/schema warnings, diff computation, markdown summary + dashboard generation - link.ts: link-project with auto-init, sibling discovery, --add/--remove mutations, agent instruction file injection for cross-repo annotation context - index.ts: public exports CLI (src/cli/index.ts): - guardlink report --format json — JSON report output with metadata - guardlink merge <files...> --json --diff-against -o --workspace --summary-only - guardlink link-project <repos...> --workspace --registry - guardlink link-project --add <repo> --from <existing> - guardlink link-project --remove <name> --from <existing> TUI (src/tui/): - /workspace — show config, sibling repos, registries - /link — fresh link + --add/--remove mutations - /merge — merge with --json, --diff-against, -o dashboard - Autocomplete registration for all workspace commands MCP (src/mcp/server.ts): - guardlink_workspace_info tool — workspace name, this_repo, tag prefixes, sibling list, cross-repo annotation rules for agents Parser (src/parser/parse-project.ts): - detectExternalRefs() — scans relationship annotations for tags with dot-prefix matching sibling repo names from workspace.yaml - Wired into parseProject: model.external_refs populated on every parse - Fixed optional asset.id type guard Types (src/types/index.ts): - ExternalRef interface (tag, context_verb, location, inferred_repo) - ThreatModel.external_refs field - ReportMetadata with repo, workspace, commit_sha, schema_version
examples/ci/per-repo-report.yml: - Validates annotations on PRs (diff + SARIF + PR comment) - Generates report JSON on push to main - Uploads as artifact for workspace merge consumption examples/ci/workspace-merge.yml: - Weekly cron (Monday 9am UTC) + manual dispatch - Downloads report artifacts from all workspace repos via gh CLI - Runs guardlink merge with --diff-against previous week - Commits baseline for week-over-week tracking - Optional: GitHub Pages deployment, Slack webhook summary examples/ci/README.md: - Setup guide, architecture diagram, configuration reference Also updated examples/github-action.yml with pointer to workspace templates.
- docs/WORKSPACE.md: multi-repo setup guide covering workspace.yaml spec, link-project commands, cross-repo annotation rules, merge behavior, CI integration, and weekly workflow - CHANGELOG.md: v1.4.0 release notes (workspace, merge, link, CI templates, external refs, TUI/MCP tools, report --format json) - package.json: 1.3.0 → 1.4.0 - src/mcp/server.ts: MCP server version 1.3.0 → 1.4.0
README.md: - Add guardlink_workspace_info to MCP tools table - Add link-project, merge, report --format json to command table - Add Multi-Repo CI paragraph under CI section with link to CI guide - Add Multi-Repo Workspaces section with working example and links examples/ci/README.md: - Rewrite as step-by-step setup guide (Steps 1-5) - Add prerequisite check, exact GitHub navigation paths - Add What the Merge Output Looks Like with weekly diff example - Add Troubleshooting section for common failure modes
Animesh-Sri-bugb
added a commit
that referenced
this pull request
May 12, 2026
A @flows annotation may now contain more than two participants connected by ->. The parser expands the chain into N-1 pairwise flows sharing the same mechanism, description, and source location: // @flows User -> #api -> #db via HTTPS -- 'auth path' becomes { source: 'User', target: '#api', mechanism: 'HTTPS', description: 'auth path' } { source: '#api', target: '#db', mechanism: 'HTTPS', description: 'auth path' } Previously, more than one -> caused 'Malformed @flows annotation: could not parse arguments' because the regex required exactly two ASSET_REF captures separated by a single arrow. Users had to manually decompose multi-hop flows into N-1 separate annotation lines. Implementation: - src/parser/parse-line.ts: PATTERNS.flows now captures the full chain as a single group (ASSET_REF (-> ASSET_REF)+) and the parser splits it on /\\s+->\\s+/ to recover the participants array. - ParseLineResult gains an optional extraAnnotations: Annotation[] field for parser branches that emit multiple annotations from one line. New okMulti() helper wraps an array into the result shape. - src/parser/parse-file.ts: call site pushes extraAnnotations and updates lastAnnotation to the final hop so '--' continuations on the next line attach to the last emitted flow (matches existing semantics). All downstream consumers (dashboard DFD, sequence diagram generator, MCP guardlink_lookup flows queries, SARIF export) still see the pairwise flow shape they always saw — multi-hop is purely a parser-side expansion. Single-hop A -> B continues to emit exactly one flow with identical fields to before. Adds 8 tests in tests/parser.test.ts covering two/three/four-hop chains, mechanism propagation, description propagation, mixed #id refs, source-location preservation across hops, and a regression guard confirming single-hop output is unchanged. Known limitation (not addressed here): the ASSET_REF pattern still only accepts #id or Dotted.Path, so URL-style refs like /rest/user/login or whitespace-containing refs like 'SQLite db' will still fail with 'Malformed @flows annotation' even after this fix. Users should declare such targets as @asset App.Routes.Login (#login) in .guardlink/definitions.ts and reference them as #login. Extending ASSET_REF to support quoted or URL-shaped refs is a separate concern. Fixes punch-list bug #4.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?
Adds multi-repo workspace support to GuardLink (v1.4.0). Multiple service repos can be linked into a unified threat model with cross-repo tag resolution, merged dashboards, and weekly risk tracking.
Workspace module (
src/workspace/): Types, workspace.yaml parser/serializer, N-repo merge engine with tag registry and cross-repo reference resolution, link-project with auto-init, sibling discovery, and--add/--removemutations, agent instruction file injection for cross-repo annotation context.CLI:
guardlink report --format jsonfor per-repo report generation.guardlink merge <files...>with--json,--diff-against,-o,--summary-only.guardlink link-projectwith--workspace,--registry,--add,--remove.TUI:
/workspace,/link,/mergecommands with autocomplete.MCP:
guardlink_workspace_infotool returning workspace context for AI agents.Parser:
detectExternalRefs()scans relationship annotations for tags whose dot-prefix matches a sibling repo name from workspace.yaml. PopulatesThreatModel.external_refson every parse.Types:
ExternalRefinterface,ThreatModel.external_refsfield,ReportMetadatawith repo/workspace/commit_sha/schema_version.CI templates (
examples/ci/): Per-repo workflow (validate on PRs, generate + upload report JSON on push to main) and weekly workspace merge workflow (download artifacts from all repos, merge, dashboard, weekly diff, optional GitHub Pages + Slack).Docs:
docs/WORKSPACE.md— setup guide, workspace.yaml spec, cross-repo annotation rules, merge behavior, CI integration.Type
Checklist
npm run buildpassesnpm testpassesguardlink validate .passes (if annotations changed)Spec changes
Adds
ExternalRefinterface and optionalexternal_refsfield toThreatModel. Adds optionalReportMetadatatoThreatModelwithrepo,workspace,commit_sha, andschema_versionfields. These are additive — existing reports without these fields remain valid.