Status: implemented; acceptance tests and live dogfood verification recorded in
SMOKE_TESTS.md.
Goal: CodeTwin analyzes its own Rust workspace and produces a useful, accurate Markdown
overview with linked crate detail pages. Baseline is 9c41fbc.
| Command | Result |
|---|---|
codetwin inspect [REPOSITORY] --json |
The extracted Code Model on stdout; diagnostics on stderr; no visualization files |
codetwin inspect [REPOSITORY] |
A concise human-readable workspace inventory |
codetwin visualize [REPOSITORY] --output <DIR> |
index.md and linked crate detail pages in the chosen directory |
Repository defaults to the current directory. Analyze the selected repository without changing
the process working directory. On new commands, global -C changes the path-resolution base;
resolve an explicit repository path against that base. Relative output directories resolve from its Cargo workspace root;
the default is docs/code. The JSON model stores repository-relative paths with /
separators, not absolute Cargo package IDs or machine-specific paths.
The existing gen, init, list, snapshot, and diff routes remain intact for this slice.
Their existing flags and default invocation behavior remain compatibility concerns handled by
the legacy route. New commands use explicit repository paths and the new analysis service.
On visualize, reject --json with a usage error pointing to inspect --json; it must not
silently bypass visualization. This keeps the first command contract small.
The first detail page shows package metadata, binary/library targets, manifest and target-source links, local dependencies and dependents. The deeper module/type/function view in the dogfood target is a later slice, not an acceptance requirement here.
Expected artifact layout:
docs/code/
index.md
crates/
<stable-artifact-id>.md
crates/codetwin/tests/; execute the compiled
binary rather than changing the test process’s working directory.app, a library
package model, and an isolated library unused. Declare app → model.Expected test result: new tests fail because the commands do not exist; existing tests pass. The fixture’s expected graph is three packages and one edge, including the isolated package.
codetwin-ir as the existing shared model boundary. Add explicit package records and
package-dependency records rather than pretending a Cargo package is a source module.CodeModel; default missing collections during deserialization
so existing stored models remain readable. Preserve existing module and symbol fields.Expected test result: old JSON still loads; the extended model round-trips; packages with no edges remain represented; equivalent inputs serialize in the same order. Existing IR and legacy consumers continue to compile and pass their tests.
codetwin crate, exposed through src/lib.rs for
meaningful library tests. Reuse the root’s existing cargo_metadata dependency declaration.--no-deps --offline --locked, using an explicit manifest path.
This inventories members without compiling the analyzed repository or fetching dependencies.
Rust/Cargo must be installed for this first analyzer.Expected test result: the fixture produces the exact three-package graph; renamed and inherited workspace dependencies resolve to their actual packages; dev/build/conditional relationships retain their qualifications. Malformed manifests fail with a nonzero exit status and an error on stderr. Inspection leaves repository inputs, including the lockfile, unchanged.
inspect through a shared analysis serviceinspect --json serializes the canonical model; ordinary inspect prints the inventory.Expected test result: JSON parses without log prefixes; running from another directory with an explicit repository path gives the same model. Inspection creates no output directory. Legacy command parsing and help still work.
codetwin; consume the model without reparsing manifests.Expected test result: exact fixture nodes and edges appear; every overview/detail/source link resolves; all packages have detail pages; an isolated package remains visible. Two runs produce byte-identical artifact contents. Different names that sanitize similarly do not collide.
Historical planning expectation at 9c41fbc before implementation: nine workspace packages, ten distinct local
dependency pairs, and nine crate detail pages. The graph contains
codetwin → codetwin-legacy → codetwin-ir and the dependencies of the five successor crates.
xtask is included as a separate workspace package with no local dependencies. The implemented slice adds the direct codetwin → codetwin-ir edge, giving eleven
local dependency declarations; see SMOKE_TESTS.md. These baseline counts
describe the planning input; tests must follow manifest changes rather than freeze this architecture.
| Scenario | Expected outcome |
|---|---|
| Three-package fixture | All three packages, exactly app → model, no invented edges |
| Renamed/inherited local dependency | Points to the real package while preserving alias metadata |
| Dev/build/optional/conditional declarations | Visible qualifications; graph is declared dependencies, not a feature-resolved build or runtime trace |
| No local dependencies | Valid inventory and standalone diagram nodes |
| Invalid path or malformed manifest | Nonzero exit, useful stderr, no generated artifacts |
| Missing Cargo executable | Contextual error; no fallback to a fabricated empty model |
inspect --json |
Valid JSON only on stdout; no filesystem output or input changes |
| Explicit repository from another directory | Same model and correctly resolved repository-relative output |
| Repeated generation | Same paths and bytes; existing generated pages refresh |
| Copied repository | No absolute paths leak into stable model or presentation |
| Dependency changed in fixture | The precise changed relationship appears in JSON and Markdown |
| Artifact and diagram identifiers | Distinct packages cannot overwrite pages or merge diagram nodes |
| Unrelated file in output directory | File remains untouched |
| User-owned file at a planned destination | Refuse replacement before writing any artifacts |
| Legacy command surface | Existing tests and help checks remain green |
Use focused tests during iteration, then cargo xtask ci for the completed slice; it includes
formatting, workspace compilation, Clippy, tests and documentation. Run the existing ignored
generation test explicitly if compatibility changes touch that path. Finish with git diff --check
and review the generated output. No redundant check/test/build sequence is needed.
No new product crate is necessary for this slice. Product responsibilities begin as modules
in codetwin, with the existing codetwin-ir dependency. Keep private automation in tools/xtask
and share external dependency requirements through root [workspace.dependencies].
Verified planning probe: cargo xtask scaffold cli --entrypoint primary --dry-run refuses the
existing codetwin-cli workspace dependency because it differs from the generated declaration.
Adapt the existing files deliberately; do not delete them or force the scaffold. For later
roadmap changes requiring new crates, preview and apply the template scaffold commands.
This slice does not implement deeper language parsing, runtime call graphs, other languages, watching, snapshots, comparison, browser serving, release changes or automatic CI commits of generated artifacts. The existing packaging problem remains a separate release decision.