Appearance
A finding you believe is wrong
A check fails on a line that you believe breaks no rule. A waiver on the line would make the build green. The cause would stay in place. These steps find the cause first. It lies in the type, in the rule, or in one line that is a real exception. At the end of the steps:
- the rule gives no wrong finding on the file;
- the one exception carries a waiver with its reason;
- each waiver left in the repository drops a finding.
The outputs below come from a repository whose main holds the law of Bring a law into an existing repository. In that law, the type library lists the enforced rule no-console. The branch main holds src/core/round.ts too. A waiver marker sits on line 2 of that file, inside a doc comment:
ts
/**
* lawcheck-waive no-console -- the example in this comment prints nothing
* Example: console.log(round(2.5)) prints 3.
*/
export function round(value: number): number {
return Math.round(value);
}On a branch made from main, you added src/core/format.ts:
ts
/**
* Formats cents as euros.
* Example: console.log(format(250)) prints 2.50.
*/
export function format(cents: number): string {
if (cents < 0) console.warn('a negative amount reached format');
return (cents / 100).toFixed(2);
}1. Read the finding
text
$ lawcheck check --base mainoutput
lawcheck: FAIL 2 errors in 1 changed file (against main)
src/core/format.ts:3 error[no-console] writes to the terminal with console.log
why: Only the command layer writes to the terminal.
src/core/format.ts:6 error[no-console] writes to the terminal with console.warn
next: fix src/core/format.ts:3The finding on line 3 points at a comment. Line 6 calls console.warn. The pricing team reads that warning.
2. Check the type
text
$ lawcheck explain src/core/format.tsoutput
src/core/format.ts
type: library (library) Code the commands call.
matched: library by "src/core/**"
may use: any file; no type on the way up has may_use
rules:
no-console script enforced from library Only the command layer writes to the terminal.
waivers: noneThe file holds code that the commands call. library is the right type for it. When a file has the wrong type, the fault lies in the law. Fix it in .lawcheck/law.yaml: change the paths of the type, add a ! pattern, or add a content expression (Types for an existing project).
3. Check the rule alone
text
$ lawcheck try no-console src/core/format.tsoutput
lawcheck: try no-console (script rule, enforced) 2 findings in 1 of 1 file
src/core/format.ts:3 error[no-console] writes to the terminal with console.log
why: Only the command layer writes to the terminal.
src/core/format.ts:6 error[no-console] writes to the terminal with console.warnlawcheck try runs one rule on the files you name and writes nothing. The rule no-console alone gives both findings, so the cause lies in the rule or in the code.
4. Choose the fix
| The finding is wrong because | Fix |
|---|---|
| the file has the wrong type | the law |
| the rule misreads lines like this one, in any file | the rule |
| the rule is right, and this one line is an agreed exception | a waiver on that line |
Each line needs its own fix:
- line 3 is a comment that the rule reads as a call, so the fix goes into the rule;
- line 6 is a real call that the team keeps on purpose, so it gets a waiver.
5. Fix the rule
Change .lawcheck/rules/no-console.mjs so that it skips the lines that start a comment:
js
export function check({ files }) {
const findings = [];
for (const file of files) {
file.lines.forEach((text, index) => {
if (/^\s*(\/\/|\/\*|\*)/.test(text)) return;
const call = text.match(/\bconsole\.(\w+)/);
if (call) findings.push({ line: index + 1, message: `writes to the terminal with console.${call[1]}` });
});
}
return findings;
}text
$ lawcheck try no-console src/core/format.tsoutput
lawcheck: try no-console (script rule, enforced) 1 finding in 1 of 1 file
src/core/format.ts:6 error[no-console] writes to the terminal with console.warn
why: Only the command layer writes to the terminal.6. Waive the one line
At the end of line 6, add the marker lawcheck-waive, the id of the rule, -- and the reason:
ts
/**
* Formats cents as euros.
* Example: console.log(format(250)) prints 2.50.
*/
export function format(cents: number): string {
if (cents < 0) console.warn('a negative amount reached format'); // lawcheck-waive no-console -- the pricing team reads this warning until 2.0
return (cents / 100).toFixed(2);
}text
$ lawcheck check --base mainoutput
lawcheck: PASS 2 changed files (against main), 1 waiver
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: changes .lawcheck/rules/no-console.mjs; adds a waiver of no-console in src/core/format.tsThe note names the waiver, so the person who reviews the change sees it. Waivers shows every form of the marker.
7. Find the waivers that waive nothing
text
$ lawcheck check --full --base mainoutput
lawcheck: PASS 2 changed files (against main), 1 waiver
note: this change edits the law that judges it: changes .lawcheck/rules/no-console.mjs; adds a waiver of no-console in src/core/format.ts
debt (outside this change): 1 finding in 1 file, 1 waiver
src/core/round.ts:2 warning[waiver-unused] the waiver of 'no-console' drops no finding
why: a waiver that drops nothing would hide the next finding on its lineThe older waiver in src/core/round.ts covers a comment line. The fixed rule finds nothing on that line, so Lawcheck reports the waiver as waiver-unused. src/core/round.ts lies outside the change, so Lawcheck lists that finding as a warning of debt.
lawcheck check --full --json lists every waiver of the repository in waivers, with its file, line, rule and reason. The field waived of a waiver counts the findings it dropped. On a waiver of a script rule, a waived of 0 marks a waiver that drops nothing (JSON documents).
8. Remove it
Delete line 2 of src/core/round.ts:
ts
/**
* Example: console.log(round(2.5)) prints 3.
*/
export function round(value: number): number {
return Math.round(value);
}text
$ lawcheck check --full --base mainoutput
lawcheck: PASS 3 changed files (against main), 1 waiver
note: this change edits the law that judges it: changes .lawcheck/rules/no-console.mjs; adds a waiver of no-console in src/core/format.ts
debt (outside this change): noneIf it goes wrong
- Lawcheck reports
waiver-unknown-rulefor a marker that names no rule of the law. It reportswaiver-without-reasonfor a marker with no reason after--. Such a waiver drops no finding. In the change, Lawcheck reports it as an error. - In a type with
waivers: false, Lawcheck reads the marker as plain text. The finding on that line stays. - A finding about the whole file has no line. A waiver drops the findings on its own line, so no waiver can drop this one. Fix the rule or the law instead.
- A reviewer rule failed a file you believe is right. Lawcheck caches that failure in
.lawcheck/.local/failures/and shows it again on each later check.lawcheck check --review --againsends the file to the reviewer once more. After you reword the rule file,lawcheck check --reviewreviews the file again without--again(Write a reviewer rule).
Next: A slow check