Skip to content

JSON documents ​

With --json, every command prints one JSON document to standard output and nothing else. The first field of every document is schema. It names the document and its version. The form of a document whose name ends in /0 may change between versions. lawcheck-error/1 is stable.

A field that holds no value is null and stays in the document. Two cases differ:

  • findings.line and runs.findings.line are absent for a finding about the whole file;
  • law_changes is present only when the check compared a base and the law differs.

A string holds the text as it is, a file name or a message included. A format character of Unicode is an invisible mark, such as a zero-width space or a mark that changes the direction of text. Lawcheck writes three kinds of character in a string as escapes, such as \n, \u001b and \u202e:

  • the control characters, below U+0020 and from U+007F to U+009F;
  • U+2028 and U+2029, which some programs read as line ends;
  • the format characters of Unicode, except the joiners U+200C and U+200D.

The printed document holds none of these characters raw. A program that parses the document gets the text unchanged. In the text output, Lawcheck writes the same characters as visible escapes, such as \x1b and \u202e (Codes). Lawcheck writes an API key of the reviewer as [key] in both outputs.

This page names a field of a list's items by its path. findings.code is the code of each item of findings.

lawcheck-check/0 ​

check prints this document, with exit 0 or 1. The repository of The commands has a file src/core/report.ts that calls console.log on its line 2. In that repository, lawcheck check --base main --json prints:

json
{
  "schema": "lawcheck-check/0",
  "result": "fail",
  "scope": {
    "mode": "change",
    "base": "main",
    "files": 1,
    "law_changed": false
  },
  "summary": {
    "errors": 1,
    "warnings": 0,
    "debt": 0,
    "waivers": 0,
    "unresolved": 0
  },
  "findings": [
    {
      "code": "no-console",
      "rule": "no-console",
      "severity": "error",
      "blocking": true,
      "debt": false,
      "file": "src/core/report.ts",
      "line": 2,
      "type": "library",
      "message": "writes to the terminal with console.log",
      "why": "Only the command layer writes to the terminal."
    }
  ],
  "waivers": [],
  "unresolved": [],
  "reviews": {
    "missing": 0,
    "calls_made": 0,
    "passes_recorded": 0
  },
  "next": {
    "command": null,
    "text": "fix src/core/report.ts:2"
  }
}
FieldValue
resultfail when a finding has severity error, else pass
scopewhat the check judged
scope.modechange for a plain check, full with --full, paths for named files
scope.basethe base as given, or null without one
scope.filesthe count of changed files, or under paths of the named files
scope.law_changedtrue when the change touches .lawcheck/law.yaml, .lawcheck/config.yaml or a rule file
scope.law_changespresent only when a base was compared and the law differs: a list of what the change does to the law, in words (What a check judges)
summarycounts over the change
summary.errorsfindings of the change with severity error
summary.warningsfindings of the change with severity warning
summary.debtfindings outside the change, under --full
summary.waiverswaivers in the files of the change
summary.unresolvedunresolved uses in the files of the change
findingsevery finding, those of the change first, then the debt
findings.codethe rule's id for a finding of a rule, or the code, such as forbidden-use (Codes)
findings.rulethe id of the rule the finding concerns, or null for a code that concerns none
findings.severityerror or warning
findings.blockingtrue for severity error
findings.debttrue for a file outside the change
findings.filethe path from the root
findings.linethe line, from 1; absent for a finding about the whole file
findings.typethe id of the file's type
findings.messagewhat is wrong
findings.whythe rule's why, or the line that explains the code
waiversevery waiver, in the change and in the debt
waivers.filethe file of the waiver
waivers.linethe line of its marker
waivers.rulethe rule it waives
waivers.debttrue for a file outside the change
waivers.waivedhow many findings it dropped
waivers.reasonthe text after --
unresolvedevery use the readers found and could not tie to one file
unresolved.filethe file that holds the use
unresolved.linethe line of the use
unresolved.whatthe name or path of the use as the reader reads it
unresolved.answerambiguous or none
unresolved.reasonfor none, unfollowed or unowned when the readers give one, else null
unresolved.candidatesthe files an ambiguous use could name, or for unowned the one file it names, else empty
unresolved.debttrue for a file outside the change
reviewsthe reviewer rules in this run
reviews.missingnot-reviewed findings
reviews.calls_madethe requests this run sent
reviews.passes_recordedthe new lines in .lawcheck/verdicts
nextthe next step, or null when the check passes
next.commandthe command alone, where the step is one command, else null
next.textthe step in words, as the next: line of the text output

lawcheck-error/1 ​

Every command but doctor prints this document when it ends with exit 2.

FieldValue
errorsevery error, sorted by file and line
errors.codethe code (Codes)
errors.filethe file, or null where there is no place
errors.linethe line, or null
errors.messagewhat is wrong
errors.whythe line that explains the code
nextthe next step for the first error
next.commandthe command alone, where the step is one command, else null
next.textthe step in words

lawcheck-init/0 ​

init prints this document, with exit 0.

FieldValue
rootthe path of the new root below the top of the git work tree, "" at the top
createdthe files init wrote, from the new root
keptthe files that were there and stay as they were
nextthe next step
next.commandnull
next.textthe step in words

lawcheck-prime/0 ​

prime prints this document, with exit 0.

FieldValue
textthe whole text output
step1 to 4, the step of shortening that fit within 8,000 characters, or null without a law
charactersthe length of text in code points

lawcheck-explain/0 ​

explain prints this document, with exit 0. subject says which of the four forms follows: file, directory, type or rule.

FieldValue
subjectfile, directory, type or rule

For a file, these fields follow schema and subject:

FieldValue
paththe path from the root
existsfalse for a file that does not exist yet
typethe id of its type, or null
chainthe ids from the root type down to its type
aboutthe about of its type, or null
nonethe reason it has no type, or null
matchedone item per type of the chain
matched.typethe type
matched.patternthe first pattern of the type that matches the path
matched.contentthe type's content, or null
not_matchedthe subtypes whose paths match and whose content does not
not_matched.typethe subtype
not_matched.contentits content
thenfor a path whose type depends on its text, which type each text would give, or null
may_usethe list in force, or null when no type on the way up has may_use
may_use.typesthe types its files may use
may_use.fromthe type above whose list holds, or null for the file's own type
useswhether its uses are read, or null when no list is in force
uses.readtrue when a reader reads the file
uses.languagethe reader's language, or null
rulesevery rule of the chain
rules.idthe rule
rules.kindscript or reviewer
rules.statusenforced or advisory
rules.whythe rule's why
rules.fromthe type that lists it
rules.reviewreviewed, failed, too-large or not-reviewed, or null for a script rule or a file that does not exist
waiversthe waivers in the file
waivers.linethe line of the marker
waivers.rulethe rule it waives
waivers.reasonthe text after --

For a directory, these fields follow schema and subject:

FieldValue
paththe folder, with a trailing /
filesthe count of files git lists below it
typesone item per type that has files there, and one with type null for the files with no type
types.typethe type, or null
types.filesits count of files

For a type, the document holds chain, about, may_use, rules (without review) and files after schema and subject, with the meanings above. It holds four fields of its own:

FieldValue
idthe type
pathsits patterns, as the law writes them
contentits content, or null
subtypesthe ids of its subtypes

waivers is false when the type's files take no waivers, else true. files lists the paths of the type's files.

For a rule, these fields follow schema and subject:

FieldValue
kindscript or reviewer
statusenforced or advisory
whythe rule's why
filethe rule file, such as .lawcheck/rules/no-console.mjs
contextthe paths of its context, or null
reviewedfor a reviewer rule, how many of its files have a verdict; null for a script rule

id is the rule. types names each type that lists it. files names the files it binds: each file whose type, or a type above it, lists the rule.

lawcheck-try/0 ​

try prints this document, with exit 0 or 1.

FieldValue
rulethe rule's id
filesthe count of chosen files
summarycounts over every answer
summary.findingsthe findings left after waivers
summary.files_with_findingsthe files with at least one
summary.waivedthe findings that waivers dropped
summary.calls_madethe requests this run sent
runsone item per file and answer
runs.filethe file
runs.attemptthe answer's number, from 1; 1 for a script rule
runs.verdictpass or fail, or null for a script rule and in a dry run
runs.findingsthe findings after waivers; empty in a dry run
runs.findings.linethe line, or absent for the whole file
runs.findings.messagewhat is wrong
runs.findings.severityerror for an enforced rule, warning for an advisory one
runs.waivedthe findings that waivers dropped
runs.answerthe reviewer's answer as it came, or null for a script rule and in a dry run
runs.prompt_charsthe size of the prompt in characters, or null for a script rule
nextnull

lawcheck-docs/0 ​

docs prints this document, with exit 0. Without a topic, the document holds these fields:

FieldValue
topicsevery page, in reading order
topics.idthe id lawcheck docs takes
topics.titlethe title

With a topic, the document holds id, title and text. text holds the Markdown of the page, with its links unchanged.

FieldValue
idthe page's id
titleits title
textthe page

lawcheck-doctor/0 ​

doctor prints this document, with exit 0 or 2.

FieldValue
resultpass when no check failed, else fail
checksthe nine checks, in their order (The commands)
checks.idthe check, such as node
checks.stateok, note, fail or skip
checks.messagewhat the check found
checks.nextthe next step for a note or fail, or null
checks.next.commandthe command alone, such as lawcheck init, where the step is one, else null
checks.next.textthe step in words

Next: The Claude Code plugin