Appearance
The first type and the first rule
You end with a law of one type and one script rule. A script rule is a JavaScript file of your repository. For each line of your files that breaks the rule, the script returns a finding. Three steps after lawcheck init, lawcheck check fails on the line of src/report.ts that calls console.log.
The outputs below come from a repository with two files on main:
src/price.tswrites nothing;- the first line of
src/report.tscallsconsole.log.
Its .gitignore names node_modules/. You work on a branch made from main.
1. Start the law
Run this in the folder of the code you want checked, inside a git work tree. That folder becomes the root of the law:
text
$ lawcheck initoutput
lawcheck: created .lawcheck/law.yaml and .lawcheck/.gitignore
Nothing is checked yet: the law has no types.
next: describe your first file type in .lawcheck/law.yaml (lawcheck docs first-law shows how)init writes these two files and nothing else.
2. Write the rule file
The rule file goes in .lawcheck/rules/. init makes no rules/ folder, so you create it in this step:
text
$ mkdir -p .lawcheck/rulesIn that folder, write no-console.mjs. The name of the file, without .mjs, is the id of the rule. Lawcheck calls the exported function check once for each file it judges. check returns the findings of the file it was given:
js
export function check({ files }) {
const findings = [];
for (const file of files) {
file.lines.forEach((text, index) => {
const call = text.match(/\bconsole\.(\w+)/);
if (call) findings.push({ line: index + 1, message: `writes to the terminal with console.${call[1]}` });
});
}
return findings;
}The rule reads lines as text. It parses no comments. It finds console.log inside a comment or a string, such as a code example in a doc comment. To skip those, a rule removes the comments from the text first. Script rules has the whole contract.
Until you add the rule to the law in Write the law, a command that reads the law stops with rule-file-without-entry and exit 2.
3. Write the law
Replace the text that init put in .lawcheck/law.yaml with the whole law, in one edit:
yaml
lawcheck: 0.1.0
rules:
no-console:
why: Only the command layer writes to the terminal.
types:
source:
about: Everything that ships.
paths: ["src/**/*.ts"]
rules: [no-console]A rule has an entry in the law and one file. The entry of no-console, under rules, holds the why that Lawcheck prints under every finding of the rule.
A type names the files of one kind. The type source has three keys:
aboutsays what its files are;pathstakes its files, here every.tsfile belowsrc/;ruleslists the rules that Lawcheck judges its files against.
A type matches only the files git lists. Lawcheck never judges a folder that .gitignore names, such as node_modules/ or a build folder. It would judge the same folder if git did not ignore it.
4. Check the file that breaks the rule
lawcheck check judges the files of the type source against the rule. With a path, it judges the files you name, changed or not:
text
$ lawcheck check src/report.tsoutput
lawcheck: FAIL 1 error in 1 named file
src/report.ts:1 error[no-console] writes to the terminal with console.log
why: Only the command layer writes to the terminal.
next: fix src/report.ts:1The check fails and exits 1. Without a path, lawcheck check judges the files that differ from the base. A check against main with no path passes, because src/report.ts is the same as on main. A check with --full lists the finding of that file as debt (See the debt).
5. See what a file gets
lawcheck explain shows the type of a file and the rules that judge it:
text
$ lawcheck explain src/price.tsoutput
src/price.ts
type: source (source) Everything that ships.
matched: source by "src/**/*.ts"
may use: any file; no type on the way up has may_use
rules:
no-console script enforced from source Only the command layer writes to the terminal.
waivers: nonesrc/price.ts has the type source. Under rules, the line of no-console gives its kind, its status, the type it comes from and its why.
6. See the debt
Without a path, a check judges only the files that differ from the base. The files you did not touch may already break the new rule. With --full, Lawcheck judges them too:
text
$ lawcheck check --full --base mainoutput
lawcheck: PASS 3 changed files (against main)
note: this change edits the law that judges it: adds .lawcheck/law.yaml; adds .lawcheck/rules/no-console.mjs
debt (outside this change): 1 finding in 1 file
src/report.ts:1 warning[no-console] writes to the terminal with console.log
why: Only the command layer writes to the terminal.The three changed files are the new files of .lawcheck/. Lawcheck counts them like any other file git lists. The note line says the change edits the law (What a check judges). Lawcheck lists a finding outside the change as debt. A finding of debt never fails the run, because Lawcheck prints it as a warning.
7. Try the rule on one file
lawcheck try runs one rule on the files you name, with no base. It writes nothing in the repository. Try no-console on src/price.ts:
text
$ lawcheck try no-console src/price.tsoutput
lawcheck: try no-console (script rule, enforced) nothing found in 1 filesrc/price.ts writes nothing to the terminal. try exits 0.
You can run try while you write a rule, before any type lists the rule. Until a type lists it, try needs a path. Without one, it stops with the error usage. The message says that no file has a type that lists the rule.
8. Try it on a file that breaks it
text
$ lawcheck try no-console src/report.tsoutput
lawcheck: try no-console (script rule, enforced) 1 finding in 1 of 1 file
src/report.ts:1 error[no-console] writes to the terminal with console.log
why: Only the command layer writes to the terminal.The finding names the file, the line, the rule and its why. try exits 1.
9. Try it on a whole folder
A pattern selects every file it matches. Put the pattern in quotes, so that the shell passes it to Lawcheck as written:
text
$ lawcheck try no-console 'src/**/*.ts'output
lawcheck: try no-console (script rule, enforced) 1 finding in 1 of 2 files
src/report.ts:1 error[no-console] writes to the terminal with console.log
why: Only the command layer writes to the terminal.10. Fix the debt, or start the rule advisory
Fix src/report.ts: take out its call of console.log. After the fix, the rule needs no status line, because its default status is enforced. If the debt is too large to fix now, give the rule status: advisory instead. Lawcheck then prints its findings as warnings in every file. The run passes:
yaml
lawcheck: 0.1.0
rules:
no-console:
why: Only the command layer writes to the terminal.
status: advisoryAfter you fix the debt, delete the status line. The rule is then enforced again. The law file describes every key of the law.
If it goes wrong
lawcheck checkpasses, and you expected the finding insrc/report.ts: without a path, a check judges only the changed files. Add--full, as in See the debt.- Lawcheck prints
law-invalid: the law misspells a key, such aspathforpaths. The message names the line and ends with the nearest known key,(did you mean 'paths'?). - Lawcheck prints
rule-missing-file: the law names a rule, and.lawcheck/rules/holds no file of that name. The file name must be the rule id followed by.mjs. - Lawcheck prints
rule-file-without-entry: a file in.lawcheck/rules/names no rule of the law, as between Write the rule file and Write the law. Give the file the rule id as its name, or add an entry for it. - Lawcheck prints
rule-crashed: the rule threw an error or returned something other than a list of findings. Write a script rule shows how to find the cause. lawcheck explainanswersnone: git ignores it, so Lawcheck never sees it:.gitignorenames the file. No type takes a file that git ignores.lawcheck try no-consolewithout a path stops withusage: no file has a type that lists the rule yet. Name a file, as in Try the rule on one file.