Code and model
The commands that compare existing code with the model.
Commands: archec recover · archec conform · archec arch-diff · archec impact · archec brief · archec agent-context
| Command | What it does |
|---|---|
archec recover <src-dir> [-o recovered.arche] [--lang ts,js,go,py,c,rust] [--depth N] [--min-imports N] [--std] [--json] [--graph gitnexus] |
The architecture of code as arche-lang, for code nobody drew (or an AI wrote). Each file's imports are read by a small scanner per language: TS/JS import, export … from, require, import(); Go import with the module path of go.mod; Python import and from … import, relative or by package; C/C++ #include "…" (folder, include/, then name); Rust mod, use crate::/super::/self::. Folders of dependencies and builds (node_modules, vendor, dist, build, target…) and files that say they are generated are left out. A part is a folder; folders nest down to --depth levels (2); a folder's own files, when there are more than 12, are cut into groups: the files most of them import kept apart (common), then families of names that import one another (websim*, parser*: a stem of 4 letters or more), then the rest placed by coupling (modularity, a family never joining another), a group of more than 20 cut again; files that import only the common ones are each alone at the top, together (others) in a folder; a group is named after its stem, else the file others import most; a folder of one or two files that only one sibling imports, where siblings are many, is merged into it. Each outside package is a part of kind external (prop package); the standard libraries (Node's own modules, Python's, Go's, libc, Rust's std) are left out and counted in a note, --std keeps them, one part each (node, python, go, libc, std). Each part says its files with source (a folder src/gen/**, or files); its api port's functions are the names others import from it; one link per pair of parts, with the number of imports; in a block of more than 12 links, those of fewer than 3 imports are weak: listed in the block's prop weak_links and not drawn (--min-imports N: the bar, in every block; 1 draws all). A cycle is said by the light links whose imports, removed, break it (a feedback arc set weighted by imports), each with an import's file and line, or for a big one by what to cut first; unresolved imports and imports of a computed name are // recovered: comments too, and past a part's ten fns eight more names. The system says prop recovered (the command): archec diagram then draws its 30 heaviest links. The result checks clean and archec diagram draws it. --json: the parts, their files, the links with each import's file and line, the cycles and their cuts. --graph gitnexus: the calls between files from a GitNexus index, counted on the links (without the program or an index, a note says why and the imports alone are used). |
archec conform <main.arche> [--src dir] [--lang …] [--system S] [--directed] [--json] [--junit file] |
The model against the code: the reflexion model (Murphy and Notkin). Each part's files are those its source names (the most specific source wins: a file before a glob, a longer folder before a shorter); the code's imports, lifted to the two parts under their nearest common part, are a convergence (a link of the model between them), a divergence (no link: an error at the import's file and line) or, for a link with no import under it, an absence (a warning at the link). A link allows imports both ways (data and imports often go opposite ways); --directed asks them to go its way. Files no part names, and files two parts name, are warnings. An outside package is compared when a part says it is that package (prop package = "yaml"). A pair of parts a block lists in prop weak_links ("a -> b: 1 import", as archec recover writes them) is allowed, its imports counted apart (--directed: its way only). The code is read from the main file's folder, or --src. Exit 1 on a divergence. archec ci runs it as its conform gate when a source names a file of the code. |
archec arch-diff <src-dir> <rev-a>[..<rev-b>] [<rev-b>] [--model main.arche] [--lang …] [--depth N] [--std] [--json] [--md] |
The architecture of two git revisions compared: each recovered from git's blobs (nothing checked out), the second grouped as the first was so a file stays in its group, and a folder cut into groups or kept whole as in the first (one that crossed 12 files is said under Folders, not as files moved); without a second revision, the working tree. Parts added, removed and renamed, files moved from one part to another, file counts, links added, removed or with more or fewer imports, cycles new and gone. --model: the divergences at each revision against that model, and the new ones (then exit 1). --md: Markdown for a pull request comment. |
archec impact <rev-a>..<rev-b> | <rev-a> <rev-b> | --staged [--model main.arche] [--src dir] [--md|--json] [--no-arch] |
Why each part of a diff exists. Each hunk of the range (or of what is staged) is placed in its part, by the parts' source (as archec conform places files). Then in the functions it touches: added, changed or removed, read lexically in TS/JS, Go, Python, C/C++ and Rust (a method is Class.name). Then in the requirements traced to them: satisfies on the part's fn of that name (or label), else on the part or a part above it. Each requirement lists the tests that verify it. Hunks in files no part names are listed apart, and so are files that are not code. Functions no requirement leads to are listed. The architecture change follows, as archec arch-diff gives it, over the folders the parts' source name (--no-arch: left out). The model is --model, else main.arche here; without one, only the files and functions. Nothing is sent anywhere. --md: Markdown for a pull request. |
archec brief <main.arche> <System.part> [--md|--json] [--task] [--src dir] [-o file] |
One part's context, for an AI assistant (or a colleague) about to change it, from the model and the files beside it, offline. Its interface (ports and functions, as written); its neighbours, the parts linked to it in its block, by their interface and never their code; the requirements traced to it (to the part, its definition, a port or function of them) and the cases that verify each, or that none does yet; the parts it may depend on, as archec conform lifts an import: a link of its own block, or of a part it is in, and weak_links; the files it owns (source, the most specific one winning, as archec conform maps them); in the folders archec gen wrote (their .archec/genmap.json), its generated files and the USER CODE regions it may edit; the budgets of the parts it is in and what it draws, the chains through it; the project's rules on what it has; what check and vet say about its declarations now; its approvals. Last, a model fingerprint: what the model says about the part (not lines, files or findings), so a brief that changed under a task is seen. A part is named by its path (Car.brakes, Toolchain.compiler.parser), or by a name only one part has. Markdown by default; --json the same as data. --task also writes .arche/task beside the model, { "part", "fingerprint", "files" } (files relative to the model's folder), which archec guard reads; --clear-task removes it. The MCP tool brief of archec mcp is the same. Exit 1 when the model has errors or names no such part. |
archec agent-context <main.arche> [-o CLAUDE.md|AGENTS.md] [--check] |
The project's context for an AI assistant, from the model alone: the architecture (each system's parts, three levels deep, with their purpose and source), the allowed dependencies (the links of each block, and its weak_links), where hand-written code goes (a part's own files; generated code only between USER CODE markers), and the conventions (archec brief … --task before changing a part, requirement and test first, archec check and archec conform after each edit, an approved element's approval stales when it changes, explain each part of a diff), with a fingerprint. Written between two markers, <!-- archec agent-context: begin --> and <!-- archec agent-context: end -->: the text around them is yours and kept; without markers the block goes after your text. Without -o, printed. --check: exit 1 when the file's block is not what the model says now. archec ci runs it as its agent-context gate on CLAUDE.md and AGENTS.md beside the model. |