Appearance
What a check judges
A law written for code that already breaks it would fail every build on the first day. lawcheck check judges the files of the change. Old code fails nothing until someone changes it.
The base
Lawcheck compares the change with a base. A ref is a name that git resolves to a commit, such as a branch, a tag or a commit hash. Lawcheck takes the base from the first of these three that you give:
--base <ref>on the command line;- the variable
LAWCHECK_BASE, when it is not empty; origin/HEAD, where the clone has it.
text
$ lawcheck check --base mainLawcheck stops with base-unreachable and exit 2 in four cases:
- the base names no commit;
- the base shares no history with
HEAD; - the repository has no commit yet;
- the base is a commit id of forty zeros, which CI gives as the commit before the push of a new branch.
A shallow clone holds part of the history. In a shallow clone, or in a clone that did not fetch the base's branch, the message names the git fetch command that fetches the base.
With no base, a check on a machine counts every file as changed. Its first line says so. In a CI job, a plain check with no base stops with base-unreachable, because without a base it cannot tell the change from debt. The next: line of that error names --base, LAWCHECK_BASE and --full (lawcheck docs ci).
The change
The merge base of two commits is the newest commit that both histories hold. Lawcheck finds the merge base of HEAD and the base. The change is every file of the working tree that differs from that merge base:
- a file committed on this branch, staged, modified, or new and not ignored, is in the change;
- a deleted file is not;
- a renamed file counts as changed under its new path;
- a change of mode alone counts;
- an edit of a file that you marked
assume-unchangedorskip-worktreein git counts.git diffdoes not show such an edit.
Lawcheck judges each changed file against the rules that bind it. A rule binds a file when the file's type, or a type above it, lists the rule. Lawcheck judges the whole file. An error on a line you did not touch fails the run too.
The git settings of a repository can name programs that git starts while it reads the files. Lawcheck runs git with these programs turned off:
- a
core.fsmonitorprogram, which watches the work tree for changes; - the hooks that git runs at an event such as a commit;
- an external diff program;
- a
textconvprogram, which turns a file into text forgit diff; - a filter, which changes a file on its way into or out of git.
Settings you pass to git yourself, through GIT_CONFIG_PARAMETERS or git -c in an alias, take effect. If one of your own settings names a program, git can start that program.
Git reads some files through a filter, such as the files of Git LFS. Lawcheck compares such a file as its bytes on disk. If the file's time no longer matches git's index, the file can count as changed.
--full and debt
text
$ lawcheck check --full --base mainWith --full, Lawcheck judges every other file as well. The findings in those other files are debt. Debt never changes the exit code, because each of its findings is a warning, whatever the status of its rule.
Lawcheck prints the debt block after the findings of the change. The block has its own count of findings, files, waivers and unresolved uses. In --json each finding of debt has debt: true.
The limits of a plain check
A plain check judges only the files that differ from the base. Three kinds of change can alter a judgment without changing the file judged:
- a change of the law:
.lawcheck/law.yaml,.lawcheck/config.yamlor a rule file; - a file whose new text gives it another type: the judgment of each file that uses it can change;
- a file that the language readers consult, such as
tsconfig.json,package.json,go.mod,Cargo.toml,composer.jsonor a C# project file.
Each of these passes a plain check. Lawcheck judges the files they affect the next time those files change. A file outside the change never fails a plain check.
To judge every file after such a change, run lawcheck check --full. Lawcheck lists what it finds outside the change as debt. Debt blocks nothing. check and doctor say when the change touches the law.
check prints these lines when the change touches the law: .lawcheck/law.yaml, .lawcheck/config.yaml or a file in .lawcheck/rules/. It prints the first line only without --full:
text
note: the law changed in this change; lawcheck check --full --base main shows what it finds in the rest of the code
note: this change edits the law that judges it: takes the rule no-console off the type libraryThe second line says what the change does to the law that judges it. A pull request can change that law. It can take a rule off a type, or make a rule script return nothing. Then the same pull request passes its own check. The line names each change that Lawcheck finds when it compares the law with the base:
- a type or a rule added or removed;
- a rule made advisory or enforced, taken off a type or put on one;
- a changed
why,context,about,paths,content,may_useorwaivers; - a waiver the change adds;
- a file of
.lawcheck/rules/, or.lawcheck/config.yaml, added, removed or changed. The line names such a file by its path and not by what it does.
The line shows five items and the count of the rest. In --json, scope.law_changes lists every item. The line never changes the exit code of the run, whatever it lists. lawcheck docs ci gives a job that checks the change a second time with the law of the base.
lawcheck doctor reports the same in its law-change check. No line of check or doctor reports the other two kinds of change.
Files you name
lawcheck check <path or pattern>... judges the files you name, changed or not, and no others. This form needs no base. It runs in CI, and in a repository with no commit.
Lawcheck reads each path and pattern from the folder you run it in. A folder selects its files at any depth. A path that selects nothing, such as a missing file, a file git ignores or a binary file, adds nothing to the run. The root is the folder that holds .lawcheck/. A path outside the root stops the run with the error usage. Write a file whose name starts with - with ./ before it, as in ./-x.ts.
This form prints neither debt nor the note of a law change. It takes one flag, --json. A missing review never makes this form exit 1, because not-reviewed and too-large-to-review are warnings in it. The Claude Code plugin checks files this way (lawcheck docs plugin).
Exit codes
| Exit | Meaning |
|---|---|
| 0 | nothing blocks; warnings are advisory |
| 1 | an error: the code breaks the law |
| 2 | no conclusion: Lawcheck, the law or the setup is broken, and the output names what to fix |
Lawcheck reports a finding of an enforced rule in the change as an error. An error makes the run exit 1. Two kinds of finding are warnings: a finding of an advisory rule, and each finding of debt. A failing run ends with one next: line that says what to do next.
Next: JSON documents