GitHub

The check commands

Hold the model to its vocabulary, its code and the pictures that embed it. A check fails while a finding remains.

On this page

Every command below comes from the CLI's own contract in release 0.5.0. Run archboard help <command> for the same words at your terminal.

Command What it does
check Run every check of the vault: semantics, code, then embeds
check all Run every check of the vault: semantics, code, then embeds
check semantics Check the canonical model, active proposals, and vocabulary
check code Inspect the source that canonical bindings and evidence anchors name
check embeds Check the reproducible architecture artifacts that this checkout embeds

check #

Run every check of the vault: semantics, code, then embeds

Without a subcommand, archboard check runs archboard check all, and the options before the subcommand go to it.

Examples

Terminal window
archboard check
archboard check semantics
archboard check code
archboard check embeds

check all #

Run every check of the vault: semantics, code, then embeds

  • Needs the server
  • Writes files

Synopsis

archboard check all [--state <draft>] [--every-draft] [--plan <file>] [--fix] [--url <url>] [-C <dir>]

Runs the semantics check, the code check and the embeds check, in that order, and answers with one part for each (ADR 0057).

These options set what the checks read

  • --state names the draft that the semantics check and the code check read.
  • --every-draft and --plan say what the code check reads, as check code describes.
  • --fix draws outdated embeds again, as check embeds describes. The other checks still run and report.

In a Git checkout without a vault, only the embeds check runs. The result identifies skipped semantic and code checks, names no vault, and uses the embed result for its exit status.

Exit 1 means a semantic diagnostic or a warning remains in any check. Information never changes the exit status. No architecture input changes.

Arguments

Argument What it does
--state <draft> Read the canonical state identified by this ID or unique name
--every-draft Inspect each independent active proposal instead of current architecture
--plan <file> repeatable Read this plan JSON, from terraform show -json or tofu show -json, for the root module of its directory. The check reads only its addresses and references, for the modules it does not read itself. The file must be in the checkout that holds the vault or in the chosen checkout of another repository
--fix Redraw changed local SVG and PNG artifacts from their exact canonical recipes. Refresh metadata when the picture stays current. Preserve cached sources and original legacy artifacts. Report every completed repair.
--url <url> The Archboard server to talk to; overrides ARCHBOARD_URL Default http://127.0.0.1:4242.
-C <dir> Find the vault from this directory instead of the working directory, the way git -C finds a repository; other relative paths still resolve against the working directory

Examples

Terminal window
archboard check
archboard check all --state TASK-123
archboard check --every-draft
archboard check --fix

Output

  • One part for each check that ran: semantics, code, embeds

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
1 issues The semantics part has a diagnostic, or the code part or the embeds part a warning. Information never changes the exit status

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 STATE_NOT_FOUND --state names no state of the model. Name one by its identity or exact name. archboard model proposals lists the drafts.
2 STATE_AMBIGUOUS --state names several states of the model. Name one by its identity, which archboard model proposals lists.
2 PLAN_REFUSED --plan names a file outside the checkout that holds the vault and the chosen checkout of every other repository, Terraform state, a variable file or a file under .terraform, or a file that is not a plan JSON. The refusal names the plan and why.
2 VAULT_NOT_FOUND The working directory, or the directory -C names, is in no Git checkout. No enclosing <dir>/.archboard/vault exists. In a Git checkout that holds no vault, this command runs without one and is not refused. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

check semantics #

Check the canonical model, active proposals, and vocabulary

  • Needs the server
  • Reads only

Synopsis

archboard check semantics [--url <url>] [-C <dir>]

Reports invalid configuration, incoherent model content, and removed vocabulary references. It changes no authored input.

Warnings on current architecture, which refuse no write

  • CONTAINER_PASS_THROUGH: in a model that binds code, a module with parts and no binding, which no relationship or flow names, and whose parts no relationship or flow joins. Bind it to the code it owns, or author the relationship or flow that gives it a job. If it has neither, move its parts to its parent and remove it. A configured group gathers parts without a container.
  • CONTAINER_UNBOUND: in a model that binds code, a module with bound parts and no binding, so the code of its folder that no part binds belongs to no module. suggestedBinding names the one directory that holds every part and no other module's code, when one does. Bind the module there with an edit-module change that sets binding. If no directory holds every part, the parts are spread. Move a part that does another module's job, or tell the user that the code layout splits one job over several folders.
  • CONTAINER_PARTS_OUTSIDE: a bound module with a part bound outside its binding. suggestedBinding names the directory that holds them all, when one does. If the module owns that directory, bind the module there with an edit-module change that sets binding. If no directory holds every part, the parts are spread. Move a part that does another module's job, or tell the user that the code layout splits one job over several folders.
  • ROOT_UNCONNECTED: in a model with several roots, a root with no relationship to another root. A relationship of a part inside it counts. Author the relationship that the code establishes, or move the module into the module that uses it.
  • BINDING_SHARED: a module bound to the same repository, path and symbol as an earlier module. Read the code. If it does one job, keep the module that sits where the code sits and merge the other into it.
  • RELATIONSHIP_REPEATED: a relationship with the same source, target and anchor as an earlier one. Keep the one whose kind and label say what the anchored code does, and remove the other.
  • CONTAINER_LINE_TO_OWN_PART: a relationship between a module and a part that it holds, at any depth. The nesting already shows it. So a reading that opens the module draws no line for it, and the panel still lists it. Start or end it at the part that makes or answers the call.

A shape is a signal, so read the source before you act on one.

Errors on current architecture, which a reader can still read

  • FLOW_SUMMARY_MISSING: a flow with no summary. A write that touches the flow refuses. Read its code, then set the summary through model edit with an edit-flow change.
  • RELATIONSHIP_ON_CONTAINER: a relationship with an end on a module with parts, and neither end holds the other. A module cannot point at anything, so end it on the part that owns the code. If no part owns it, add one for what the module does at this seam.

Exit 1 means that a diagnostic or warning remains.

Arguments

Argument What it does
--url <url> The Archboard server to talk to; overrides ARCHBOARD_URL Default http://127.0.0.1:4242.
-C <dir> Find the vault from this directory instead of the working directory, the way git -C finds a repository; other relative paths still resolve against the working directory

Examples

Terminal window
archboard check semantics

Output

  • One part, semantics: the vault policy, its diagnostics and the timings

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
1 issues The semantics part has a diagnostic: a warning or an error

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

check code #

Inspect the source that canonical bindings and evidence anchors name

  • Needs the server
  • Reads only

Synopsis

archboard check code [--state <draft>] [--every-draft] [--plan <file>] [--url <url>] [-C <dir>]

Compares canonical modules and relationships with their bound source and evidence anchors.

It reads current architecture, the state named by --state, or proposals selected by --every-draft.

Source comes from the vault's checkout or another repository's chosen checkout. Git-ignored files are excluded.

Warnings

  • ANCHOR_PATH_MISSING, ANCHOR_SYMBOL_MISSING: an anchor whose file is not in its checkout, or does not hold its symbol. Cite the file or symbol that proves it now. If the code is gone, remove the anchor or change the model to what the code does.
  • BINDING_PATH_MISSING, BINDING_SYMBOL_MISSING: a bound path that is not in its checkout, or a bound symbol that the bound file or directory does not define. For a missing path, correct the binding or create the source before you accept the state. For a missing symbol, bind the part to the definition it stands for now. To bind the whole file or directory, leave out the symbol.
  • ANCHOR_MISMATCH: an anchor whose symbol is outside the bound code of both ends, or that the file uses only as evidence that the relationship's kind does not accept. Cite a symbol or use in the code of an end that proves the relationship. Bind the part whose code holds that definition. Or change the relationship or its kind to what the code does.
  • RELATIONSHIP_UNDRAWN: a bound part whose code other bound parts call or construct, with no relationship between them. Evidence that only matches by name makes it information. So does a relationship between the two sides where they meet: the children of their nearest holder. Add the relationship between the parts that make and answer the call. If the call reaches code that no part of the module binds, add a part bound to that code and end the relationship on the part. If the dependency is unintended, change the code.
  • ENTRY_POINT_UNEXPOSED: in a container bound to a module, an entry point that owns nothing the module exposes, while a caller drawn to it reaches it from outside the module. Make the callers use what the module exposes, or expose what they use from a root file.
  • TEST_IMPORT_UNEXPOSED: a test outside a module that imports a private file of the module. A test inside the module can use its private files. Import a public entry file of the module, or move the test inside it.
  • CALLER_UNDRAWN: a hidden part whose exposed code a file outside the module runs, and no part binds that file. Add the callers and their relationships outside the module. If the use is unintended, stop exporting that code.
  • DOCUMENT_PATH_MISSING: a document reference whose file is not at the branch or commit that the reference names (ADR 0054). Name the file where the document is now, pin the reference to a commit that holds it, or remove the reference.
  • INHERITED_PART_DROPPED: a proposal removes a bound part from its predecessor, while that source path or symbol still exists. The dropped field identifies the predecessor and source evidence. To keep the part, bring it back into the proposal with the same id. If the change removes the part, remove its code.

Information, which never changes the exit status

  • RELATIONSHIP_BACKWARDS: a relationship with no anchor whose evidence runs only the other way. Turn the relationship around if the code runs that way. If the direction is the convention of its kind, anchor it to the code that proves it.
  • RELATIONSHIP_UNSUPPORTED: a relationship with no anchor whose evidence does not join its ends. Its missing field names the side with no evidence, code or infrastructure. The evidence list of each relationship kind in the vault configuration says what it accepts. Anchor it to the code that proves it, or change it to what the code does.
  • EXPOSED_UNUSED: the names that a module exposes and no file outside it uses. Stop exposing the names that no caller needs, unless a caller outside this checkout uses them.
  • VARIABLE_PASSED_THROUGH: a Terraform or OpenTofu module that passes a variable unchanged to one argument of a resource. Let the module decide or hide the value, so that its callers need not.
  • MODULE_SHALLOW: a Terraform or OpenTofu module that wraps one resource and passes every variable through. Let callers declare the resource, or let the module decide what its callers need not.

What it reads

  • The languages and formats it knows by their syntax, such as TypeScript, Python, C#, Swift, Rust, Go, docker-compose files and Terraform, and every other file as text.
  • The language server that repo language-server configures for a checkout and a language. It runs that repository's code, as an editor does.
  • A module's interface: a directory, or the index.ts or __init__.py that stands for it. A Terraform or OpenTofu module exposes its variables and outputs.
  • A binding that names a branch or commit that its checkout does not have checked out. It is read at that ref from Git, without a checkout.

What it reads across a network hop

An environment value that bound code reads, joined with the compose service, Kubernetes workload or Terraform resource. That service, workload or resource runs that code and sets the value to another part's address. This is configured-path evidence.

A compose service runs the directory it builds, and each of them runs the code drawn inside the part bound to it. Where the infrastructure leaves a choice, the evidence is a candidate.

What it reads of Terraform and OpenTofu

A root module and the local modules it calls. A part bound to a root module names an address there as its symbol, such as module.queue.aws_sqs_queue.this.

The check never reads state, a variable file or .terraform, and never runs terraform or tofu. A reference that joins two such parts is configured-path evidence. --plan names a plan for the addresses inside remote modules.

What it skips, each named in skipped with the reason

  • unbound: a part with no binding, so it has no code to read. Bind it once its code exists.
  • repository-unregistered: a binding or anchor in a repository that this machine has not registered. Check out that repository and register it with archboard repo add, then run the check again.
  • checkout-unavailable: a registered checkout that is gone, is no longer a Git checkout, or no longer identifies as its repository. Register the checkout again with archboard repo add.
  • path-ignored: a bound or anchored path that Git ignores. Bind code that Git tracks.
  • path-never-read: Terraform state, a variable file or the .terraform directory, which can hold secrets in plain text. The check never reads them.
  • text-only: files that no grammar reads. The check judges their anchors and bound symbols by name only. Its detail names the kinds of file.
  • expression-not-followed: a symbol that can lie below a Nix expression that the check cannot follow, such as an import, or in a Helm template, whose names only Helm gives. Its detail names the file and the lines.
  • ends-overlap: a relationship with no anchor whose ends hold one another or bind the same code. Evidence never joins such parts. Anchor the relationship, or join parts that do not overlap.
  • no-current-variant, model-unreadable: a model document whose named variant has no current state and no draft, or a vault file that is not a model document.
  • symbol-unparsed: a symbol found only in code that did not parse.
  • language-server-missing: a checkout and language with no configured language server, named once. Its detail names the command that configures one: run archboard repo language-server with the language and the server's command, and install that command.
  • language-server-unready: a project that its server cannot answer about. Examples are a Swift directory with no Package.swift, a C# checkout with no solution or project file, a C, C++ or Objective-C file with no compile_commands.json, a Rust file that no Cargo.toml holds, and a Go file that no go.mod holds. Add the file that the project lacks. Build a Swift package once, because the check never builds, and its server answers only from a build's index.
  • language-server-failed: a checkout where its server did not start, did not answer in time, or ended. Its detail names the program and what it did. Run that program by hand in the checkout to see why, then run the check again.
  • exposure-unknown: a module whose root files it cannot read. No language that the check reads has a root file in its directory, or its package.json exports name no file of the checkout. Bind the module to the directory that holds its root files, or make its exports name them.
  • module-not-read: an address inside a remote module, unless --plan names a plan for that root. To read it, pass the plan JSON of that root with --plan.
  • ref-without-language-server: code read at a ref. A language server reads the files on disk, so a use that no import resolves there stays as the code facts read it.
  • refs-differ: a relationship whose ends are read at different refs.
  • ref-not-checked-out: a ref that the checkout cannot resolve. It names the ref. Fetch that ref into the checkout, then run the check again.
  • draft-ref-missing, draft-refs-ambiguous: a draft whose ref the checkout does not have, or whose bindings name several refs. Fetch the missing ref, or give the bindings of the draft one ref in each repository.

Drafts

  • --state reads one exact canonical state by identity or unique name. It also warns about a bound path that the draft names and its checkout does not hold.
  • --every-draft reads each independent canonical proposal by identity.
  • Source bindings with explicit refs read Git objects without changing the checkout. Unpinned bindings read the selected checkout's files. Unavailable source stays explicit.

Exit 1 means the code check has a warning. No architecture input changes.

Arguments

Argument What it does
--state <draft> Read the canonical state identified by this ID or unique name
--every-draft Inspect each independent active proposal instead of current architecture
--plan <file> repeatable Read this plan JSON, from terraform show -json or tofu show -json, for the root module of its directory. The check reads only its addresses and references, for the modules it does not read itself. The file must be in the checkout that holds the vault or in the chosen checkout of another repository
--url <url> The Archboard server to talk to; overrides ARCHBOARD_URL Default http://127.0.0.1:4242.
-C <dir> Find the vault from this directory instead of the working directory, the way git -C finds a repository; other relative paths still resolve against the working directory

Examples

Terminal window
archboard check code
archboard check code --state TASK-123
archboard check code --every-draft
archboard check code --plan infra/plan.json

Output

  • One part, code: the findings, the skipped reads and the timings

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
1 issues The code part has a warning. Information and skips never change the exit status

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 STATE_NOT_FOUND --state names no state of the model. Name one by its identity or exact name. archboard model proposals lists the drafts.
2 STATE_AMBIGUOUS --state names several states of the model. Name one by its identity, which archboard model proposals lists.
2 PLAN_REFUSED --plan names a file outside the checkout that holds the vault and the chosen checkout of every other repository, Terraform state, a variable file or a file under .terraform, or a file that is not a plan JSON. The refusal names the plan and why.
2 VAULT_NOT_FOUND The command found no vault from the working directory or the directory -C names. Inside a checkout, only <root>/.archboard/vault counts. Outside one, the nearest enclosing <dir>/.archboard/vault counts. In a checkout with no vault, the refusal names each known vault whose models bind the checkout's repository, as the -C to give. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.

check embeds #

Check the reproducible architecture artifacts that this checkout embeds

  • Needs the server
  • Writes files

Synopsis

archboard check embeds [--fix] [--url <url>] [-C <dir>]

An embed is an SVG or PNG file that Archboard drew and Git tracks. It carries its recipe: the model, the state and the view that it shows.

The check works in these steps

  • Find each embed in the files that Git tracks.
  • Find the vault that its recipe names: in this checkout, in the checkout of that repository that this machine chose, or in a copy that an earlier fetch cached.
  • Draw the picture again from that model, state and view.
  • Compare the new picture with the file, and the model that drew each.

A picture of a model that says something new is EMBED_OUTDATED. A picture that only the renderer draws differently is information. An unchanged picture needs nothing.

Use --fix to write the new pictures over the files in this checkout. A PNG keeps its scale and its region.

A cached vault is only read. A recipe of an older format needs archboard model migrate, then a picture drawn again from the migrated model. The check leaves that file as it is.

The result lists every embed that it read, each vault, each finding and each file that --fix wrote. An interrupted --fix lists every file that it already wrote.

A recipe never substitutes another model by name. The check writes no architecture content.

Exit 1 means a warning remains. Information never changes the exit status.

Warnings

  • EMBED_OUTDATED: the model says something new since the picture was drawn. Draw it again with --fix, then commit it.
  • EMBED_SOURCE_MISSING: the model, the state or the view that the recipe names is gone, or what it names draws nothing now. Draw the picture from a reading that exists, or remove it.
  • EMBED_VAULT_FETCH_FAILED: no checkout on this machine holds the vault that the recipe names, fetching it failed, and no copy is cached. So the picture was not checked. Register a checkout of that repository with repo add.
  • EMBED_RECIPE_UNREADABLE: the file carries a recipe that cannot be read, so nothing can draw it again. Draw the picture again from the model, or remove it.

Information, which never changes the exit status

  • EMBED_RENDERER_CHANGED: only the picture differs, because the renderer draws the same model differently. The model says nothing new.
  • EMBED_VAULT_UNAVAILABLE: the vault that the recipe names cannot be read, so the picture was not checked: it is in no repository, its checkout holds none, its identity names no remote, the commit fetched or cached holds none, or the server refuses it.
  • EMBED_VAULT_CACHED: fetching the vault failed, and the check read the newest cached copy, which can be behind the default branch. Every finding against it is information, and --fix draws nothing from it.

A finding about a file of another repository is information, whatever its code. That repository draws the file again only after the vault's change merges.

Arguments

Argument What it does
--fix Redraw changed local SVG and PNG artifacts from their exact canonical recipes. Refresh metadata when the picture stays current. Preserve cached sources and original legacy artifacts. Report every completed repair.
--url <url> The Archboard server to talk to; overrides ARCHBOARD_URL Default http://127.0.0.1:4242.
-C <dir> Find the vault from this directory instead of the working directory, the way git -C finds a repository; other relative paths still resolve against the working directory

Examples

Terminal window
archboard check embeds
archboard check embeds --fix

Output

  • One part, embeds: the artifacts it inspected, the source vaults, the findings and the repairs in fixed

Exit codes

Exit When
0 Success The command did what it said. Its output is above.
1 issues The embeds part has a warning. Information never changes the exit status

Refusals

Exit Refusal
3 SERVER_UNREACHABLE The Archboard server could not be reached or started.
2 VAULT_NOT_FOUND The working directory, or the directory -C names, is in no Git checkout. No enclosing <dir>/.archboard/vault exists. In a Git checkout that holds no vault, this command runs without one and is not refused. The command changed nothing.
2 VAULT_REQUIRED A server call named no vault. A command names the vault it finds from the working directory or -C <dir>.
2 VAULT_UNREADABLE The vault the command found is not a directory the server can read. Nothing was created.
Docs

Type to search every page, command and schema.