fix: correct /gal reference syntax to match parser, add /unannotated …#5
Merged
Merged
Conversation
…to /help — v1.4.1 - Fix /gal (TUI + CLI): description format ': text' → '-- "quoted text"' - Fix /gal: severity format 'severity:high' → '[high]' / '[P0]' - Fix /gal: @flows connector 'to' → '->' arrow syntax - Fix /gal: @validates preposition 'on' → 'for' - Fix /gal: @owns add missing 'for' preposition - Fix /gal: @mitigates document 'using' as primary keyword - Add /gal: external refs section (cwe:, owasp:, capec:, attack:) - Add /gal: @boundary alternate syntaxes and (#id) support - Add /gal: standalone @shield single-line marker - Fix /help: add missing /unannotated command - Fix CLI: guardlink --version was stuck at 1.1.0 - Bump version to 1.4.1 - Annotation edits: @Audit on launcher timeout, suggest module - Sync agent instruction files with current model
Animesh-Sri-bugb
added a commit
that referenced
this pull request
May 12, 2026
…mmand The report command printed 'Fix errors above before generating report' when diagnostics contained errors, then proceeded to generate the report anyway. Per-annotation parse errors don't block report generation — malformed annotations are skipped and the rest of the model still renders. This matches the existing behavior of dashboard, sarif, threat-report, and mcp commands, which print diagnostics and continue silently. Fixes punch-list bug #5.
Animesh-Sri-bugb
added a commit
that referenced
this pull request
May 12, 2026
ASSET_REF and THREAT_REF previously matched only two forms: '#id' (with characters limited to [a-zA-Z0-9_-]) and 'Dotted.Path'. Real projects often want to reference URL-style routes like /rest/user/login or human-readable identifiers with spaces like 'SQLite db' or 'User Browser'. Without a quoting mechanism, those annotations failed with 'Malformed @<verb> annotation: could not parse arguments' and forced users to either declare every reference as an @asset first or rewrite identifiers as awkward dotted paths ('/rest/user/login' as 'Rest.User.Login'). This commit adds a third alternative — double-quoted strings — to both ASSET_REF and THREAT_REF: // @flows User -> '/rest/user/login' -> 'SQLite db' // @exposes '/api/v1/users' to 'Cross Site Scripting' [high] // @confirmed 'SQL Injection' on '/login' [critical] // @boundary 'User Browser' and 'Backend API' // @Audit '/admin/dashboard' -- 'release-gated review' (Single quotes shown above for readability — the actual syntax is ASCII double-quote, mirroring the existing DESC pattern.) Implementation: - New QUOTED_REF regex fragment: '(?:[^"\\\n]|\\.)*' matching any non-newline content with backslash-escape support. - ASSET_REF and THREAT_REF gain QUOTED_REF as a third alternative alongside #id and Dotted.Path / Name. - resolveRef() (previously a no-op pass-through) now strips surrounding double quotes and processes \" / \\\ escape sequences via unescapeDescription. Single semantics for all three ref forms — quoted is just sugar for the canonical string. - Every captured asset/threat ref in the parser branches now goes through resolveRef(). Most relationship types previously assigned m[N] raw to asset/source/target slots, which would have stored literal quotes in the model. After this change they all normalize. - @flows chain extraction switches from m[1].split(/\s+->\s+/) to matchAll(new RegExp(ASSET_REF, 'g')) so a quoted ref containing a literal '->' (e.g. 'step1 -> step2') isn't shredded by the arrow separator. The outer chain regex has already validated shape, so matchAll on the inner pattern is safe. What this fix does NOT do: extend definition annotations (@asset, @threat, @control). Those use COMPONENT and NAME patterns respectively. Declarations remain strict — the canonical id system (#id) is the right way to define entities with awkward names. Quoted refs are for *referencing* informal identifiers in relationships, not for *declaring* them. Adds 11 tests in tests/parser.test.ts covering: URL-style refs in @flows, whitespace-containing refs, the user's actual Juice Shop annotation, mixed quoted+unquoted in a chain, the 'foo -> bar' chain edge case, escape sequences, quoted refs in @exposes / @confirmed / @boundary / @Audit, and a regression case confirming unquoted forms still parse identically. Verified live against a Juice Shop fixture: User -> '/rest/user/login' -> 'SQLite db' parses to two clean flows with no quotes in the stored source/target strings. Fixes punch-list bug #5.
Animesh-Sri-bugb
added a commit
that referenced
this pull request
May 12, 2026
Reconcile version references across the project to 1.4.3, the agreed
target for the v1.5.1-deferred bug-fix batch on the feat/v1.5.0 branch.
Touched:
- package.json: 1.4.1 -> 1.4.3
- package-lock.json: 1.4.1 -> 1.4.3 (root + packages[''])
- src/cli/index.ts: program.version('1.4.1') -> '1.4.3'
- src/mcp/server.ts: McpServer version '1.4.0' -> '1.4.3'
The MCP server was inconsistently at 1.4.0 even when other surfaces
reported 1.4.1; reconciling all four to 1.4.3 closes that gap.
Scope rationale (from the v1.5.1 discussion): the work on this branch
is materially bug-fix oriented — confidence rendering (#7), topology
dedup (#9), prompt.md migration (#14), fatal tier reservation (#6),
JWT redaction opt-in (#11) — even though two additive features
landed alongside (multi-hop @flows chains, quoted refs in #5). Patch
bump rather than minor reflects the intent: this is the v1.4.x line
plus tight fixes, not a v1.5 product cut. The minor bump and broader
release notes will happen at the rebase against main and the formal
v1.5.0 cut.
Verified: 'guardlink --version' prints 1.4.3; npm build clean;
167/167 tests pass.
Fixes punch-list bug #12.
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.
Here you go:
What does this PR do?
Fixes the /gal annotation language reference (both TUI and CLI) to match the actual parser syntax. Every example in the previous /gal output used incorrect formats that would produce parse errors if a user or AI agent followed them. Also adds the missing /unannotated command to /help and fixes the CLI --version reporting stale 1.1.0.
Key syntax corrections:
Description format: : text → -- "quoted text" (parser regex: --\s*"...")
Severity format: severity:high → [high] / [P0] (parser regex: [...])
@flows connector: to → -> (parser regex: ->)
@validates preposition: on → for
@owns: added missing for preposition
@mitigates: documented using as primary keyword (with remains as v1 compat)
New documentation added to /gal:
External References section (cwe:, owasp:, capec:, attack:)
@boundary alternate syntaxes (between A and B, A | B) and (#id) support
Standalone @shield single-line marker
(#id) syntax on @threat and @control definitions
Tips updated with format reminders
Also bundled:
Minor annotation corrections (@comment → @Audit on launcher timeout, @Audit added to suggest module)
Two new workspace controls in definitions
Agent instruction files synced with current model
.gitignore cleanup for generated report files
Generated threat-dashboard.html and STRIDE threat report added to repo
Type
Bug fix
New feature
Annotation spec change
Documentation
CI / tooling
Checklist
npm run build passes
npm test passes
guardlink validate . passes (if annotations changed)
CHANGELOG.md updated (for user-facing changes)
Spec changes
N/A — no parser or schema changes. The annotation syntax was already correct in the parser and templates (init/templates.ts); this PR fixes only the /gal display output and /help listing to match what already works.