How-to guides › Understand existing code

How-to guides

Understanding code: who wrote it, what it does, what its architecture is

This page is about code that already exists. It may have been written by people, by archec gen, or by an AI assistant. archec reads it in three ways:

  • archec provenance says who wrote each line;
  • archec observe says what the code does, from its traces;
  • archec recover says what its architecture is, from its imports, and archec conform keeps the code true to that architecture.

A first look#

Three TypeScript files: src/main.ts imports src/core/engine.ts, which imports src/util/log.ts.

archec recover src -o recovered.arche
✓ recovered.arche — 3 files, 3 parts, 0 outside packages, 2 links, 0 cycle(s), 0 unresolved import(s)

recovered.arche has one part per folder, and one link per import between them:

system Src "src" {
  prop recovered = "archec recover src"
  part main: Main
  part core: Core
  part util: Util
  core.uses -> util.api "1 import"
  main.uses -> core.api "1 import"
}

archec conform checks that the code still matches this model:

archec conform recovered.arche
Src: 3 of 3 files mapped; 2 link(s) converge, 0 import(s) diverge, 0 link(s) absent
✓ every dependency of the code is in the model

Remove the line core.uses -> util.api and run it again. The import in engine.ts now has no link in the model, so it fails with exit code 1:

Divergences: imports the model has no link for (1, between 1 pair(s) of parts)
  error Src.core → Src.util: 1 import(s)
      src/core/engine.ts:1 imports '../util/log' (Src.util)

Src: 3 of 3 files mapped; 1 link(s) converge, 1 import(s) diverge, 0 link(s) absent
✗ the code does what the model does not say

Who wrote the code: the model, an AI assistant, or a person#

With AI writing code, a reviewer needs to know who wrote what. archec provenance main.arche (or archec audit main.arche --authors) gives each line of code one origin:

  • generated: archec gen wrote it, and it is unchanged. gen leaves .archegen.json beside its output, with a fingerprint per line.
  • AI: an AI assistant wrote it. archec knows this from one of these:
    • the commit has a Co-Authored-By: Claude…, Generated-by: or AI-assisted: trailer;
    • the commit has an assistant's address;
    • a marker in .arche/provenance.jsonl says so.
  • edited after gen: gen wrote the file, and a person changed the line.
  • human: the rest.

It reads git blame, so each line counts for the commit that last changed it.

What it reports:

  • the lines, summed by file and by part of the model. A part's files are the ones it names with source or code, and those of its parts.
  • the files an assistant wrote that no person has committed to since.

archec diagram main.arche Car --overlay provenance colours each block by who wrote most of its code. archec doc --html --provenance adds the tables to the specification.

For Claude Code, add this hook to .claude/settings.json. It marks the lines Claude writes, as it writes them.

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|MultiEdit|Write",
    "hooks": [ { "type": "command", "command": "archec provenance hook" } ] } ] } }

Other assistants can call archec provenance mark <file> --lines 10-40 --tool <name>. See the commands.

archec debt main.arche goes one step further: per part, the share of lines an assistant wrote that no person signed off (archec approve <Part> --code) or that are in a function no requirement leads to, and how many people know the part. See comprehension debt.

Behaviour from traces: what the code actually does#

Code written fast, or by an AI, does things nobody wrote down. archec observe reads what the code did and writes it as a model, to read and to draw.

It reads:

  • OpenTelemetry traces, as OTLP JSON. This is what the file exporter of the SDK or of the collector writes.
  • a Jaeger or Zipkin export.
cd test/fixtures/observe
archec observe shop.otlp.jsonl --states -o observed.arche
archec diagram observed.arche post-checkout-error      # a sequence diagram
archec diagram observed.arche Observed.orders.states   # a state diagram

What the model holds:

  • Each service is a part.
  • Each call from one service to another is a message on a link. The link says how many calls were seen, how long they took (p50, p95), and how many failed.
  • A database or a cache that is called but has no trace of its own is a part too.
  • Traces are grouped by the path they took: one scenario per shape, with how often it occurred.
  • Calls that overlap are drawn in a par. The same call repeated in a row is drawn in a loop.
// observed: 9 of 64 trace(s) went this way (14%)
scenario post-checkout-error "POST /checkout (payment declined)" {
  sequence post-checkout-error-steps "POST /checkout (payment declined)" {
    Observed.outside -> Observed.gateway : POST_CHECKOUT
    Observed.gateway -> Observed.orders : POST_ORDERS
    Observed.orders -> Observed.orders : validate_cart
    par {
      when "RESERVE" { … }
      when "CHARGE" {
        Observed.orders -> Observed.payments : CHARGE
        Observed.payments -> Observed.orders : CHARGE "error: card declined" { reply }
      }
    }
    Observed.orders -> Observed.inventory : RELEASE
    …

--states adds a state machine to each service that waits on another. Its states are the replies it waits for. A comment says in how many traces each transition was taken:

    // observed: in 9 of 64 trace(s)
    AwaitingCharge -> AwaitingRelease on CHARGE when "the reply is an error" / "sends RELEASE"

With --model main.arche, it compares the traces with your model instead. It reports:

  • services that are no part of the model;
  • calls the model has no link or message for;
  • links never seen;
  • a link's deadline against the time measured on the wire;
  • the checks of archec replay.

archec replay reads the same traces. See the commands.

From code to model#

The rest of arche-lang goes from the model to code. archec recover goes the other way. It is for code nobody drew, written over years or by an AI in an afternoon:

archec recover src -o recovered.arche      # TypeScript, JavaScript, Go, Python, C/C++, Rust
archec diagram recovered.arche --md        # see it

How it reads the code#

It reads each file's imports with a small scanner per language. It needs no compiler and nothing installed. It also reads what the file does with each name it imports: how often it uses it, and how. A use is a call, a new X (a struct literal in Go and Rust), a type, or another value.

Each import gets a weight:

  • an import used often weighs more: about 1 + log₂ of its uses;
  • an import that takes only types weighs half;
  • a re-export (export … from) weighs ½;
  • an import never used weighs ¼ to ½.

TypeScript and JavaScript are read with the TypeScript compiler's parser when it is available (archec's own, or the one in the working folder's node_modules). Otherwise they are read lexically, like the other languages. Lexical reading skips the file's strings and comments, and matches the remaining names with what each import binds:

  • import { a as b } binds b;
  • import x.y binds x.y;
  • in Go, the package name is used as pkg.Name;
  • a C header binds what it declares.

In Go, the files of one package use each other with no import at all. When a file uses a name that another file of its package declares, that is a reference between the two files. A reference is weighed the same way as an import.

How it groups files into parts#

  • It makes a part of each folder.
  • It cuts a folder of many files into groups. First come families of names that import one another (websim*, parser*). The other files are grouped by coupling, using the weights above. A file that many files import counts less towards where each of them goes. Each group is named after its stem, or after the file the others import most.
  • It writes one link per pair of parts, with the number of imports (and references).
  • A file that many import, and that imports at most two files of its folder, is a library. It is kept apart, as common.
  • A file that many import and that imports a lot (the centre of a program) is placed by coupling, like the others.
  • A file beside folders, that one of those folders uses and that has most of its links with it, joins that folder's part. A // recovered: comment says which.
  • Among sibling parts, one may be used by two thirds of the others, while it uses them a quarter as much or less. It is written kind library. What it imports back is noted on it and left out of the cycles. This way a cycle shows the knot of the design, not a helper imported back.
  • Cycles are broken at their lightest links, by weight. An import of types only goes first.
  • The standard library (Node's own modules, Python's, Go's, libc, Rust's std) is left out, because every part would link to it. --std keeps it.

Each part lists its files with source. The names that others import from it are its functions. What archec had to guess is a // recovered: comment:

/// 14 files, 3 996 lines.
component Importer "importer" {
  kind module
  source "src/importer/**"

  in api:   call
  out uses: call

  fn import_project "importProject"
  fn import_sysml "importSysml"
  …
  /// 4 files, 1 182 lines.
  component sysml "importer/sysml*" {
    kind module
    source "src/importer/sysml.ts"
    …
  }

  sysml.uses -> ir.api "8 imports"
}

system ArcheLang "arche-lang" {
  prop recovered = "archec recover src"
  …
  // recovered: a cycle: 25 parts import one another; 53 light links break it (archec recover --json lists them). To shrink it first, cut:
  // recovered:   what common imports from generics, libraries, parser (+2) (11 imports, src/program.ts:18…): 22 parts left in a cycle
  // recovered: 107 weak links (fewer than 3 imports) not drawn: weak_links lists them, archec conform allows them (--min-imports 1 draws all)
  prop weak_links = [
    "board -> gen: 1 import",
    …
  ]
  cli.uses -> importer.api "8 imports"
  …
}
Diagram: arche-lang
What archec draws from this code: arche-lang
  • In a block with more than 12 links, only links of 3 imports or more are kept as links. The weaker ones are listed in prop weak_links, so nothing is lost. --min-imports N sets the bar in every block; --min-imports 1 draws every link.
  • A cycle is described by the light links that break it, each with an import's file and line. (This is a feedback arc set, weighted by imports.) For a big cycle, archec says what to cut first.
  • archec diagram draws at most the 30 heaviest links of each block of a recovered model, heaviest first, and says how many it left out. prop recovered marks a model as recovered. --max-links N sets the number for any model whose links give their weight ("12 imports"). --max-links 0 draws all.

archec recover --json gives each link its imports, references, weight and uses.

To measure how close the grouping comes to a model drawn by hand, run node tools/recover-score.mjs. It compares archec recover src with arche-lang's own model (examples/arche-lang). It counts the pairs of files that both place together, as precision and recall.

Keeping the code true to the model#

Rename the parts, regroup them, and remove the links you do not want. The result is now the architecture you mean. archec conform keeps it true. It follows the reflexion model:

  • each import of the code between two parts must be a link of the model. Otherwise it is an error, at the import's file and line.
  • each link should have imports under it. Otherwise it is a warning.
  • each file should belong to a part.

A pair of parts listed in weak_links is allowed. Its imports are counted apart: they are neither convergences nor divergences. Remove the line to forbid them.

Divergences: imports the model has no link for (1, between 1 pair(s) of parts)
  error Code.core → Code.util: 1 import(s)
      src/core/engine.ts:1 imports '../util/log' (Code.util)

Code: 5 of 5 files mapped; 4 link(s) converge, 1 import(s) diverge, 0 link(s) absent
✗ the code does what the model does not say

archec ci runs it as a gate, when a source names a file of the code.

archec arch-diff src main..HEAD --md recovers two revisions from git. For the pull request, it writes:

  • the parts and links the branch added or removed;
  • the files it moved between parts;
  • with --model, the divergences it brought in.

The second revision is grouped as the first one was. A folder that grew past 12 files is cut into groups, or kept whole, as before. It is listed under Folders rather than as files moved.

Limits#

  • Imports are read, not types or calls. --graph gitnexus adds calls from a GitNexus index.
  • An import of a computed name is only reported.
  • The grouping is a first proposal, not a design.