Fix output modifier positioning and add arch health subcommands

[darko-mijic]

Summary

• Fix output modifier positioning bug — --names-only, --count, --fields, --full, and --format now work regardless of where they appear in the command (before or after the subcommand). Previously, placing modifiers after the subcommand (e.g., list --count) caused them to be silently ignored.
• Add three arch health subcommands — arch dangling, arch orphans, and arch blocking for detecting graph quality issues in the architecture relationship model.
• Remove redundant arch graph subcommand — superseded by the more comprehensive arch neighborhood command added in Replace 11 static recipe files with codec-driven reference generation #19.

Changes

Bug Fix: Output Modifier Position Independence

Moved output modifier parsing (--names-only, --count, --fields, --full, --format) out of the flag-only switch block to an earlier position-independent section in parseArgs(). This ensures modifiers work in natural command order:

# These now both work identically:
pnpm process:query -- --count list --status completed
pnpm process:query -- list --status completed --count

New Feature: Architecture Health Subcommands

Subcommand	Description	Data Source
arch dangling	Broken references (pattern names that don't exist)	ValidationSummary.danglingReferences
arch orphans	Patterns with no relationships (isolated nodes)	findOrphanPatterns() in arch-queries
arch blocking	Patterns blocked by incomplete dependencies	buildOverview().blocking

The pipeline now returns a ValidationSummary alongside the MasterDataset (via transformToMasterDatasetWithValidation) to power the arch dangling command without recomputation.

Removed: arch graph Subcommand

arch graph <pattern> returned raw dependency and relationship names but provided less value than arch neighborhood <pattern>, which returns uses, usedBy, and same-context siblings — a strictly superior view. Removed to reduce API surface area.

Files Changed

File	Change
src/api/arch-queries.ts	Add findOrphanPatterns() function and OrphanEntry interface
src/cli/process-api.ts	Fix modifier positioning, add health subcommands, remove arch graph, thread ValidationSummary
tests/features/cli/process-api.feature	Add Rules 15-16 (modifier position, health subcommands), remove arch graph scenario
tests/steps/cli/process-api.steps.ts	Step definitions for new scenarios + dangling reference fixture
docs/PROCESS-API.md	Update arch subcommand table
CLAUDE.md	Add health subcommands to Data API CLI reference

Test Plan

• All 6,815 tests pass (pnpm test)
• New Rule 15 scenarios verify modifiers work after subcommand (list --count, list --names-only, list --status completed --count)
• New Rule 16 scenarios verify arch dangling, arch orphans, and arch blocking return valid JSON arrays with expected fields
• Removed arch graph scenario to match CLI change
• TypeScript builds cleanly (pnpm build)

Summary by CodeRabbit

• New Features

  • Added arch subcommands: dangling, orphans, blocking, neighborhood, compare, and coverage.
  • Output modifiers now work when placed after subcommands.
  • Removed the legacy arch graph subcommand.

• Documentation

  • Updated arch subcommand reference and examples to reflect new commands and formats.

• Tests

  • Expanded tests for graph health subcommands and output modifier positioning.

[coderabbitai]

📝 Walkthrough

Walkthrough

Introduces arch "graph health" subcommands (dangling, orphans, blocking), adds orphan-detection logic, and threads a ValidationSummary through the CLI pipeline so handlers can return dataset validation alongside the master dataset.

Changes

Cohort / File(s)	Summary
Documentation docs/PROCESS-API.md	Removed graph subcommand; added neighborhood, compare, coverage, dangling, orphans, blocking; updated examples and help text.
Orphan Detection src/api/arch-queries.ts	Added OrphanEntry interface and findOrphanPatterns(dataset: MasterDataset): readonly OrphanEntry[] to detect patterns with no relationships.
CLI pipeline & routing src/cli/process-api.ts	Replaced transformToMasterDataset with transformToMasterDatasetWithValidation; introduced PipelineResult { dataset, validation }; extended RouteContext with validation; wired new arch subcommands (dangling, orphans, blocking) to validation-derived outputs; removed graph route.
Tests — features & steps tests/features/cli/process-api.feature, tests/steps/cli/process-api.steps.ts	Removed previous arch graph scenario; added fixtures for dangling refs (createDanglingRefFiles, writeDanglingRefFiles); added tests for output-modifier position independence and graph health subcommands (dangling, orphans, blocking).

Sequence Diagram

sequenceDiagram
    participant Client
    participant CLI
    participant Pipeline
    participant Transformer
    participant ArchHandler
    participant Dataset

    Client->>CLI: run arch <subcommand>
    CLI->>Pipeline: buildPipeline(config)
    Pipeline->>Transformer: transformToMasterDatasetWithValidation(...)
    Transformer->>Transformer: produce RuntimeMasterDataset + ValidationSummary
    Transformer-->>Pipeline: { dataset, validation }
    Pipeline-->>ArchHandler: RouteContext { dataset, validation }
    ArchHandler->>ArchHandler: dispatch subcommand
    alt dangling
        ArchHandler->>ArchHandler: return validation.danglingReferences
    else orphans
        ArchHandler->>Dataset: findOrphanPatterns(dataset)
    else blocking
        ArchHandler->>Dataset: buildOverview(dataset).blocking
    end
    ArchHandler-->>Client: JSON array result

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I nibble logs and chase stray refs tonight,

I sniff out orphans hidden out of sight,
Dangling threads I tug until they're found,
Pipelines hum and validation sings aloud,
Hooray — the graph grows tidy and bright!

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.77% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the two main changes: fixing output modifier positioning and adding arch health subcommands (dangling, orphans, blocking), both of which are central to the changeset.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/process-api-cli-small-issues

---

No actionable comments were generated in the recent review. 🎉

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Fix all issues with AI agents

In `@src/api/arch-queries.ts`:
- Around line 398-402: The OrphanEntry interface's file property can be an empty
string when findPatternByName returns undefined (see findPatternByName usage
around where file is set to ''), so add a brief JSDoc comment to
OrphanEntry.file clarifying that it will be an empty string if pattern metadata
is unavailable (e.g., "empty string if pattern metadata is unavailable") to make
downstream behavior explicit.

In `@src/cli/process-api.ts`:
- Around line 726-733: The early returns in handleArch are correct —
dangling/orphans/blocking must bypass the archIndex gate — but avoid recomputing
the full overview just to read .blocking: replace the direct call
buildOverview(ctx.dataset).blocking with a lightweight helper (e.g.,
getBlockingOverview(ctx.dataset) or buildOverview(ctx.dataset, { fields:
['blocking'] })) or add memoization/caching inside buildOverview so fetching
.blocking is cheap; keep the early return logic in handleArch and only change
how blocking is obtained to a cheaper path.

In `@tests/features/cli/process-api.feature`:
- Around line 320-375: The new Rule blocks for "Output Modifier Position
Independence" and "Graph Health Subcommands" are missing the structured metadata
and one scenario is asymmetric: add the standard sections (**Invariant:**,
**Rationale:**, **Verified by:**) to each new Rule block (the blocks beginning
with "Rule: Output modifiers work..." and "Rule: CLI arch health
subcommands...") and enhance the "Arch blocking" scenario (the scenario starting
"Arch blocking returns blocked patterns") to assert a known response field
(e.g., check that stdout JSON data contains an entry with a "pattern" or
"blockedBy" field) so it matches the stronger checks used in the "dangling" and
"orphans" scenarios.

In `@tests/steps/cli/process-api.steps.ts`:
- Around line 1049-1135: The 'Arch blocking returns blocked patterns'
RuleScenario sets up fixtures via writePatternFiles and runs the CLI via
runCLICommand but only asserts that parsed.data is an array; update that
scenario (the RuleScenario named "Arch blocking returns blocked patterns") to
mirror the other scenarios by parsing getResult().stdout into { data:
Array<Record<string, unknown>> }, asserting the array has length > 0, and
asserting the first entry has a specific expected field (use the same field name
used in the other scenarios' field check), e.g., check arr.length > 0 and
expect(arr[0]).toHaveProperty(<field>), so tests are consistent with
writePatternFiles and runCLICommand usage.