polish: align JSON digest with machine-orientation principle#3
Merged
Conversation
Vectis digests are consumed by agents; the markdown surface was the only fully human-oriented format and duplicates information already covered by slim/full JSON and `vectis explain`. Drops ~190 lines of build_markdown plus its four tests, removes --format md from the CLI parser, and leaves the JSON paths unchanged. Also takes a copy-by-ref in Export_WritesFileAtDefaultLocation that clang-tidy flagged once the surrounding markdown tests went away. Co-Authored-By: Rooty
Vectis digests are agent-consumed: same input + same binary should yield byte-identical output so cache invalidation, diffing, and content-hash comparisons stay sound. The generated_at timestamp killed that property silently. The vectis_version field carries the schema-pinning value; runtime time has no use to a downstream agent. Drops the helper, the chrono/ctime includes, and updates the test to guard against regression. Co-Authored-By: Rooty
Adds a `signals` field to ArchitectureDescription carrying a flat list of `category:value` tokens (`workspace:cargo`, `dir:controllers`, `runtime:Java`, `manifest:pyproject.toml`, ...). JSON exporter emits the array; agents can grep / pattern-match it directly without parsing the prose `reasoning` string. `reasoning` is now human-only and stops being emitted in JSON. Workspace and library helper return shapes grew a sibling `signals` member so each detection branch publishes its own evidence rather than reconstructing it at the call site. Three small helpers (`dir_signal`, `push_matching_dir_signals`, `push_manifest_signals`) collapse the repeated `dir:<name>` loops and the `runtime:/manifest:` pairs each branch needs. Co-Authored-By: Rooty
Slim previously filtered unresolved (external) dependency edges out of the edges array but left them counted in stats.external_edges, so edges[].size() < stats.total_edges in slim — an inconsistent schema for an agent that compares the two. Slim now emits external edges with target=null and target_external=<raw import string>, matching the full format. Cycles remain full-only. Net effect on a real ~84k-edge digest: slim grows ~10% but its dep graph is now self-consistent and gives agents the third-party landscape they need without parsing the full format. Co-Authored-By: Rooty
A single-file run printed `1 files, 1 symbols, 1 deps`. Replaces the duplicated fprintf in run_explain and compute_digest_body with one formatter (count_word + scan_summary_line) so both CLI entry points emit the same line and 1-of-anything reads grammatically. Co-Authored-By: Rooty
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.
Summary
Five focused commits aligning every Vectis output surface with the machine-orientation principle (agents primary; humans only via
vectis explain).generated_atfrom JSON — same input + same binary now produce byte-identical outputarchitecture.signals: ["workspace:cargo", "dir:controllers", "runtime:Java", ...]replaces the prosereasoningstring in JSON;reasoningstays on the struct forvectis explain(humans)dependency_graph.edges[]now matchesstats.total_edges; agents see the third-party landscape without falling back to--format json-vsummary —1 filenot1 filesSchema breaks (intentional, v0.1.0)
architecture.reasoningremoved →architecture.signalsarray addedgenerated_atremoved (was a timestamp; now bit-identical reproducibility)dependency_graph.edgesnow includes external edges (target=null,target_external=<raw>)--format mdremoved;vectis-digest.mdno longer producedVerification
tests/fixtures/code/sample-multimodule:architecture.signalsnow reads["layout:monolith", "partial-layering", "dir:service", "dir:dao"]; slim emits external edges withtarget=nullshape