feat(c4): relationship validation + @c4 system + @c4 code levels by nightscape · Pull Request #1 · nightscape/archidoc

nightscape · 2026-06-14T11:37:32Z

Three independent enhancements that make @c4 richer and keep its diagrams honest. Each is a separate commit and could be split into its own PR on request.

1. `ir check-deps` — validate `@c4 uses` against real crate deps

Validates the @c4 uses arrows in a compiled IR against the real crate→crate graph from cargo metadata (no extra tooling).

archidoc ir check-deps <ir.json> --manifest-dir <dir> [--ignore NAME] [--strict]

Reports missing (real dep, no arrow — prints a paste-ready @c4 uses line) and stale (declared arrow, no real dep). --strict exits 1 (CI gate). workspace-hack ignored by default.

This revives the previously dead cargo_modules.rs machinery (ImportGraph / validate_relationships / detect_orphans — never CLI-wired, and dependent on the external cargo-modules tool) by giving it a workspace-native, tool-free, crate-level edge source and a CLI entry point.

2. `@c4 system` level — system-context diagram

C4Level had only Container/Component/Unknown — no way to declare the system in focus or external systems. Adds C4Level::System, parses @c4 system, and renders c4-context.puml (one System() per node + its @c4 uses arrows). Container diagram now renders system nodes as System_Ext() so container→system arrows resolve.

3. `@c4 code` level — code diagram

Completes C4 downward. Item-level @c4 code doc markers on struct/enum/trait/fn (parsed via syn — the adapter previously read only module //! docs) become curated code-level nodes under their component. Unmarked items are ignored (curated, not a dump). Renders c4-code.puml; intra-component @c4 uses resolve to qualified ids.

Notes

All three are independent of the three dev feature branches (no file overlap); based on dev only for a clean diff. Portable to upstream main.
New IR fields are serde-default, so existing IR JSON stays valid.
Tests added for each; validated end-to-end against real projects (a 20+ crate workspace for feat(c4): relationship validation + @c4 system + @c4 code levels #1; scratch fixtures for Default output to _context/ GitSmart86/archidoc#2/Feature: Surface Health column in Component Index output GitSmart86/archidoc#3). Pre-existing polyglot_detection_test failures on dev are unrelated.

🤖 Generated with Claude Code

@C4

Add a workspace-native dependency source and a `ir check-deps` CLI command that diffs declared `@c4 uses` arrows against the real crate→crate graph. - adapters/archidoc-rust/cargo_metadata.rs: workspace_import_graph() reads `cargo metadata --no-deps` (no external tooling, unlike the cargo-modules path) into the existing ImportGraph; validate_ir_relationships() diffs a compiled IR's relationships against it, reusing RelationshipWarning. - archidoc ir check-deps <ir> --manifest-dir <dir> [--ignore N] [--strict]: reports `missing` (real dep, no @C4 uses — prints paste-ready line) and `stale` (declared @C4 uses, no real dep). --strict exits 1 for CI. - Revives the previously dead validate_relationships/ImportGraph machinery by giving it a tool-free, crate-level edge source and a CLI entry point. - workspace-hack ignored by default. 3 unit tests. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Adds the top of the C4 model (previously C4Level had only Container/ Component/Unknown — no way to declare the system in focus or external systems). - archidoc-types: C4Level::System variant (+ Display "system"). - archidoc-rust: extract_c4_level() parses `@c4 system`. - archidoc-engine/plantuml: generate_context() renders one System() per `@c4 system` node plus its `@c4 uses` relationships → c4-context.puml (emitted only when a system node exists). Container diagram now renders system nodes as System_Ext() so container→system arrows resolve. - CLI render plantuml emits the context diagram alongside container/component. - Tests: extract_c4_level covers all four levels. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Adds a new CLI workflow to validate compiled IR @c4 uses relationships against the actual Rust workspace crate dependency graph derived from cargo metadata, enabling detection of missing and stale dependency arrows without relying on external tooling.

Changes:

Introduces archidoc ir check-deps in archidoc-cli to compare IR relationships vs workspace crate deps, with --ignore and --strict support.
Adds a new archidoc_rust::cargo_metadata module that builds an ImportGraph from cargo metadata and diffs it against IR relationships.
Adds serde_json as a dependency of archidoc-rust to parse cargo metadata output.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
core/archidoc-cli/src/main.rs	Adds the `ir check-deps` subcommand and prints drift output / exit codes.
adapters/archidoc-rust/src/cargo_metadata.rs	New implementation to build crate-level dependency graph from `cargo metadata` and validate IR relationships.
adapters/archidoc-rust/src/lib.rs	Exposes the new `cargo_metadata` module publicly.
adapters/archidoc-rust/Cargo.toml	Adds `serde_json` dependency needed for parsing `cargo metadata` JSON.
Cargo.lock	Lockfile update reflecting the new dependency.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+            let to = match dep["name"].as_str() {
+                Some(n) if members.contains(n) && n != from => n.to_string(),
+                _ => continue,
+            };


+        let declared: HashSet<String> = dir
+            .relationships
+            .iter()
+            .map(|r| r.target.clone())
+            .filter(|t| !ignore.contains(t))
+            .collect();
+        let actual: HashSet<String> = graph
+            .get_dependencies(&crate_name)
+            .into_iter()
+            .filter(|t| !ignore.contains(t))
+            .collect();


 //! | `promote.rs` | -- | Auto-promote planned to verified | planned |
 //! | `cargo_modules.rs` | -- | cargo-modules integration (optional) | planned |

+pub mod cargo_metadata;
 pub mod cargo_modules;


+    /// Examples:
+    ///   archidoc ir check-deps _context/current.json --manifest-dir crates
+    ///   archidoc ir check-deps _context/current.json --manifest-dir . --strict


Completes the C4 model downward. Item-level `@c4 code` doc markers turn a curated set of load-bearing types into code-level nodes under their component — the rust adapter previously parsed only module `//!` docs. - archidoc-types: CodeElement on ModuleDoc + ir::CodeElement on DirNode (serde-default; existing IR JSON stays valid). - archidoc-rust/parser: extract_code_elements() uses syn to find struct/enum/trait/fn items whose doc contains `@c4 code`; captures kind, description, and `@c4 uses` relationships. Unmarked items are ignored (curated, not a dump). - archidoc-rust/walker: aggregates a module's code elements from its directory's source files onto the component's ModuleDoc. - archidoc-engine: ir_builder propagates code_elements; plantuml generate_code() renders c4-code.puml (Component per element, kind as the tech tag, intra-component `@c4 uses` resolved to qualified ids). Emitted only when a code element exists. - Tests: extract_code_elements curation + typing + relationships. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

nightscape · 2026-06-14T11:58:50Z

Superseded by three focused PRs against upstream GitSmart86/archidoc: GitSmart86#7 (relationship validation), GitSmart86#8 (@C4 system), GitSmart86#9 (@C4 code). dev will octo-merge those branches.

Copilot AI review requested due to automatic review settings June 14, 2026 11:37

Copilot started reviewing on behalf of nightscape June 14, 2026 11:37 View session

Copilot AI reviewed Jun 14, 2026

View reviewed changes

nightscape changed the title ~~feat(rust): validate @c4 uses against real crate deps via cargo metadata~~ feat(c4): relationship validation + @c4 system + @c4 code levels Jun 14, 2026

nightscape closed this Jun 14, 2026

nightscape deleted the feat/cargo-metadata-relationships branch June 14, 2026 11:58

Navigation Menu

feat(c4): relationship validation + @c4 system + @c4 code levels - #1

feat(c4): relationship validation + @c4 system + @c4 code levels#1
nightscape wants to merge 3 commits into
devfrom
feat/cargo-metadata-relationships

nightscape commented Jun 14, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

nightscape commented Jun 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

nightscape commented Jun 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1. ir check-deps — validate @c4 uses against real crate deps

2. @c4 system level — system-context diagram

3. @c4 code level — code diagram

Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

nightscape commented Jun 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nightscape commented Jun 14, 2026 •

edited

Loading

1. `ir check-deps` — validate `@c4 uses` against real crate deps

2. `@c4 system` level — system-context diagram

3. `@c4 code` level — code diagram