audit

Invocation#

lem-cli audit [--paper <id-or-title>] [--registry <file>] [--report <file>] [--no-report] [--force] [--transcripts] [--pangram-abstracts] [--resolve-overleaf-missing [--resolve-only] [--max-overleaf-phrases <n>] [--stop-on-overleaf-failure]]

Inputs and options#

• --paper <id-or-title> restricts the audit: a UUID becomes an id filter; any other value becomes the title filter passed to the auditor.
• --registry <file> audits another registry than the configured one; --report <file> writes the report there instead of the default path.
• --no-report runs without writing the report. --force refreshes provenance and rescans cached Overleaf phrases. --transcripts refreshes the transcript index. --pangram-abstracts also checks abstracts with Pangram.
• --resolve-overleaf-missing first scans the Overleaf version history for the evidence each selected paper is missing; --resolve-only stops after that scan; --max-overleaf-phrases <n> bounds how many phrases are scanned in all; --stop-on-overleaf-failure ends a paper's scan at its first failed phrase.

Output and state#

Runs LemProvenanceAuditor against the registry and prints report as JSON, or the same document with --plain. By default it writes the report and includes report_path; --no-report omits both the write and that field.

A manuscript line is attributed to a transcript event only when the line's whole normalized word sequence — as written or as plain text with its LaTeX rendered, and with a leading “Proof” or “Proposition” label dropped — appears in that event whole and in order. Lem chooses no window, gap or minimum word count, so a line that was only partly written in a session is not attributed to it.

Each paper's evidence_issues name the transcript-backed lines whose evidence does not prove them: missing_transcript_evidence, missing_match_text, or match_text_does_not_hold_line when the match text does not hold the line's whole word sequence (as written or as plain text) whole and in order. No length or word count decides a proof.

With --resolve-overleaf-missing the answer also carries overleaf_resolve: per selected paper the missing units before and after, the phrases scanned, each scan's state and message, and the rounds numbered from one. A round scans the phrases of the units still missing that no earlier round scanned; the scan ends when nothing is missing, no new phrase is left, the phrase budget is spent or, with --stop-on-overleaf-failure, a scan fails. Cached Overleaf evidence backs a line when the scanned phrase, the evidence's match text or its snapshot holds the line or is held by it, or the snapshot holds the line's words as one run; Lem chooses no gap, span or minimum word count.

Refusals#

• --paper, --registry, --report or --max-overleaf-phrases without a following value refuses with “audit: <option> needs a value”.
• --max-overleaf-phrases with anything but a whole number above zero refuses with “audit: --max-overleaf-phrases takes a whole number above zero, not <value>”.
• --resolve-only, --max-overleaf-phrases or --stop-on-overleaf-failure without --resolve-overleaf-missing refuses with “audit: --resolve-only, --max-overleaf-phrases and --stop-on-overleaf-failure shape the Overleaf scan and need --resolve-overleaf-missing”.
• Any unknown option refuses with “audit: unknown option <argument>”.
• An auditor error refuses with “audit failed: <detail>”.
• An audit that leaves any line's provenance unknown does not pass: after printing the report it exits nonzero with “audit: <n> line(s) have unknown provenance in <k> paper(s): <title> (<count>), …”, the papers with the most unknown lines first.