workproof 0.1.2 → 0.2.0

package/dist/src/analyse.js

@@ -1,17 +1,35 @@
-import { createHash } from "node:crypto";
+import { createHash, createHmac, randomBytes } from "node:crypto";
 import { basename } from "node:path";
 import { createRequire } from "node:module";
-import { listCommits, listTags, rootCommit, headSha, remoteUrl, assertRepository } from "./git.js";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { listCommits, listTags, rootCommit, headSha, remoteUrl, assertRepository, gitVersion, checkAttr, listHeadFiles } from "./git.js";
+import { isBot, excludedSet } from "./exclusions.js";
+// surviving-lines ships plain ESM JavaScript without type declarations.
+// @ts-ignore
+import { globToRegExp } from "surviving-lines/bin/surviving-lines.js";
 import { resolveIdentity } from "./figures/identity.js";
 import { tenure, commitShare } from "./figures/commits.js";
 import { cadence } from "./figures/cadence.js";
 import { footprint, testsAndDocs } from "./figures/footprint.js";
-import { survivingLines } from "./figures/surviving.js";
-/** sha256 of the root commit and the normalised remote: identifies a repository without naming it. */
-export function fingerprint(root, remote) {
+import { survivingLines, blameFlags } from "./figures/surviving.js";
+import { filesAuthored, majorContributor, commitSize, coAuthored, absenceFactor, aiAssisted, survivalByCohort } from "./figures/authorship.js";
+/** A fresh 16-byte fingerprint key as hex. Printed once, stored nowhere. */
+export const newFingerprintKey = () => randomBytes(16).toString("hex");
+const NOREPLY = /@users\.noreply\.github\.com$/i;
+/** GitHub noreply addresses carry the login in the local part, so they are never written out. */
+export const publicEmail = (email) => (NOREPLY.test(email) ? "(github noreply)" : email);
+/**
+ * Identifies a repository without naming it. Keyed: HMAC-SHA256 under a per-report key of
+ * the root commit and the normalised remote, so a reader cannot look a public repository
+ * up from its fingerprint. Unkeyed (no key given): plain sha256, kept for callers that
+ * want a stable public identifier.
+ */
+export function fingerprint(root, remote, key) {
     let r = remote.trim().toLowerCase().replace(/\.git$/, "");
     r = r.replace(/^[a-z+]+:\/\//, "").replace(/^git@([^:]+):/, "$1/");
-    return createHash("sha256").update(`${root}\n${r}`).digest("hex");
+    const text = `${root}\n${r}`;
+    return key === undefined ? createHash("sha256").update(text).digest("hex") : createHmac("sha256", Buffer.from(key, "hex")).update(text).digest("hex");
 }
 const require = createRequire(import.meta.url);
 const survivingVersion = () => {
@@ -22,19 +40,70 @@ const survivingVersion = () => {
         return "unknown";
     }
 };
+async function ignoreRevsFor(cwd, params) {
+    if (params.ignoreRevsFile)
+        return params.ignoreRevsFile;
+    try {
+        await access(join(cwd, ".git-blame-ignore-revs"));
+        return ".git-blame-ignore-revs";
+    }
+    catch {
+        return null;
+    }
+}
+/** Bot commits out, excluded paths out of every commit's file list; the untouched copy stays for the share. */
+async function applyExclusions(cwd, all, params) {
+    const enabled = params.exclusions !== false;
+    const extra = (params.exclude ?? []).map((g) => globToRegExp(g));
+    const botCommits = enabled ? all.filter(isBot).length : 0;
+    const human = enabled ? all.filter((c) => !isBot(c)) : all;
+    const headFiles = await listHeadFiles(cwd);
+    const paths = new Set(headFiles);
+    for (const c of human)
+        for (const f of c.files)
+            paths.add(f.path);
+    const attrs = enabled ? await checkAttr(cwd, [...paths]) : new Map();
+    const excluded = excludedSet(paths, attrs, extra);
+    if (!enabled)
+        for (const p of [...excluded])
+            if (!extra.some((re) => re.test(p)))
+                excluded.delete(p);
+    const commits = human.map((c) => ({ ...c, files: c.files.filter((f) => !excluded.has(f.path)) }));
+    return { commits, raw: human, excluded, botCommits, enabled, headFiles: new Set(headFiles.filter((p) => !excluded.has(p))) };
+}
 export async function analyseRepo(cwd, params, hooks = {}) {
     const say = hooks.progress ?? (() => { });
     await assertRepository(cwd);
+    const key = params.fingerprintKey ?? newFingerprintKey();
+    if (!params.fingerprintKey)
+        say(`fingerprint key ${key} (keep it to compare reports; it is not stored)`);
     say(`${basename(cwd)}: reading history${params.maxCommits ? ` (newest ${params.maxCommits} commits)` : ""}...`);
-    const all = await listCommits(cwd, params.maxCommits ? { max: params.maxCommits } : {});
-    say(`${basename(cwd)}: ${all.length.toLocaleString("en-US")} commits read`);
+    const everything = await listCommits(cwd, params.maxCommits ? { max: params.maxCommits } : {});
+    say(`${basename(cwd)}: ${everything.length.toLocaleString("en-US")} commits read`);
+    const ex = await applyExclusions(cwd, everything, params);
+    const all = ex.commits;
     const id = await resolveIdentity(all, params.author, cwd);
     const t = tenure(all, id, { ...(params.since ? { since: params.since } : {}), ...(params.until ? { until: params.until } : {}) });
     const start = new Date(t.value.first + "T00:00:00Z");
     const end = new Date(t.value.last + "T23:59:59Z");
     const inTenure = all.filter((c) => c.date >= start && c.date <= end);
+    let addedAll = 0;
+    let addedExcluded = 0;
+    for (const c of ex.raw) {
+        if (c.date < start || c.date > end || c.parents > 1)
+            continue;
+        for (const f of c.files) {
+            if (f.added === null)
+                continue;
+            addedAll += f.added;
+            if (ex.excluded.has(f.path))
+                addedExcluded += f.added;
+        }
+    }
     const tags = await listTags(cwd);
     const sample = params.sample ?? (all.reduce((n, c) => n + c.files.length, 0) > 50000 ? 7 : 1);
+    const ignoreRevs = await ignoreRevsFor(cwd, params);
+    const blame = blameFlags(params.copies ?? false, ignoreRevs);
     const fp = footprint(inTenure, id, { depth: params.depth, threshold: params.threshold, minCommits: params.minCommits });
     if (!params.paths) {
         fp.value = { ...fp.value, ownedDirectories: fp.value.ownedDirectories.map((d) => ({ ...d, path: "(hidden; run with --paths)" })) };
@@ -45,16 +114,33 @@ export async function analyseRepo(cwd, params, hooks = {}) {
         cadence(inTenure, tags, id, { first: t.value.first, last: t.value.last }),
         fp,
         testsAndDocs(inTenure, id),
+        filesAuthored(all, id, ex.headFiles),
+        majorContributor(inTenure, id, params.depth),
+        commitSize(inTenure, id),
+        coAuthored(inTenure, id),
+        absenceFactor(inTenure, id),
+        aiAssisted(inTenure, id),
     ];
     say(`${basename(cwd)}: blaming files (1 in ${sample} sample)...`);
-    const surviving = await survivingLines(cwd, id, { sample, version: survivingVersion() });
+    const surviving = await survivingLines(cwd, id, {
+        sample,
+        seed: params.seed ?? "",
+        exclude: params.exclude ?? [],
+        copies: params.copies ?? false,
+        ignoreRevsFile: ignoreRevs,
+        excluded: ex.excluded,
+        version: survivingVersion(),
+    });
     say(`${basename(cwd)}: blamed ${surviving.value.filesSampled} of ${surviving.value.filesTotal} files`);
-    figures.push(surviving);
+    figures.push(surviving, survivalByCohort(surviving.value.byYear, sample));
     return {
         name: basename(cwd),
         head: await headSha(cwd),
-        fingerprint: fingerprint(await rootCommit(cwd), await remoteUrl(cwd)),
-        identity: { emails: params.emails ? id.emails : [], names: id.names, count: id.emails.length },
+        fingerprint: fingerprint(await rootCommit(cwd), await remoteUrl(cwd), key),
+        fingerprintKeyed: true,
+        identity: { emails: params.emails ? [...new Set(id.emails.map(publicEmail))] : [], names: id.names, count: id.emails.length },
+        environment: { git: await gitVersion(cwd), blame, ignoreRevs, seed: params.seed ?? "" },
+        excluded: { botCommits: ex.botCommits, files: ex.excluded.size, linesAddedShare: addedAll ? addedExcluded / addedAll : 0, enabled: ex.enabled },
         figures,
     };
 }

package/dist/src/attest.d.ts

@@ -0,0 +1,62 @@
+import type { Report } from "./report.js";
+export declare const STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+export declare const PREDICATE_TYPE = "https://workproof.dev/attestation/v1";
+export declare const PAYLOAD_TYPE = "application/vnd.in-toto+json";
+export interface InTotoStatement {
+    _type: typeof STATEMENT_TYPE;
+    subject: {
+        name: string;
+        digest: {
+            sha256: string;
+        };
+    }[];
+    predicateType: typeof PREDICATE_TYPE;
+    predicate: Predicate;
+}
+export interface Predicate {
+    tool: {
+        name: "workproof";
+        version: string;
+    };
+    generatedAt: string;
+    params: Record<string, unknown>;
+    repositories: {
+        head: string;
+        fingerprint: string;
+        fingerprintKeyed: boolean;
+        identity: {
+            names: string[];
+        };
+        environment: Report["repositories"][number]["environment"];
+        excluded: Report["repositories"][number]["excluded"];
+    }[];
+}
+/**
+ * The predicate says what was measured and under which environment, nothing more: no
+ * figures (they are behind the subject digest), no remote URL, no paths of any kind.
+ */
+export declare function predicateFor(report: Report): Predicate;
+/** An in-toto v1 Statement whose subject is the report's own hash. */
+export declare function statementFor(report: Report): InTotoStatement;
+/** Writes <basename>.intoto.json and <basename>.predicate.json next to the report. */
+export declare function writeStatement(reportPath: string): Promise<{
+    statement: string;
+    predicate: string;
+}>;
+export interface DsseEnvelope {
+    payloadType: typeof PAYLOAD_TYPE;
+    payload: string;
+    signatures: {
+        keyid: string;
+        sig: string;
+    }[];
+}
+/**
+ * Signs the statement with an SSH key (ssh-keygen -Y sign, namespace "workproof"), keeps
+ * the detached .sig ssh-keygen wrote, and wraps both in a DSSE envelope as
+ * <basename>.dsse.json. The signature covers the statement bytes as written.
+ */
+export declare function signLocal(statementPath: string, keyPath: string): Promise<{
+    signature: string;
+    envelope: string;
+}>;

package/dist/src/attest.js

@@ -0,0 +1,72 @@
+import { execFile } from "node:child_process";
+import { readFile, writeFile, rm } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { checkReport } from "./verify.js";
+/** ssh-keygen asks on stdin before overwriting a signature; stdin is closed so it can never wait. */
+const run = (cmd, args) => new Promise((resolve, reject) => {
+    const child = execFile(cmd, args, { encoding: "utf8" }, (err, stdout, stderr) => (err ? reject(new Error(`${cmd} ${args[0]} ${args[1]} failed: ${String(stderr || err.message).trim()}`)) : resolve(stdout)));
+    child.stdin?.end();
+});
+export const STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+export const PREDICATE_TYPE = "https://workproof.dev/attestation/v1";
+export const PAYLOAD_TYPE = "application/vnd.in-toto+json";
+/**
+ * The predicate says what was measured and under which environment, nothing more: no
+ * figures (they are behind the subject digest), no remote URL, no paths of any kind.
+ */
+export function predicateFor(report) {
+    const { ignoreRevsFile: _ignore, ...params } = report.params;
+    return {
+        tool: { name: "workproof", version: report.version },
+        generatedAt: report.generatedAt,
+        params,
+        repositories: report.repositories.map((r) => ({
+            head: r.head,
+            fingerprint: r.fingerprint,
+            fingerprintKeyed: r.fingerprintKeyed === true,
+            identity: { names: r.identity.names },
+            environment: r.environment,
+            excluded: r.excluded,
+        })),
+    };
+}
+/** An in-toto v1 Statement whose subject is the report's own hash. */
+export function statementFor(report) {
+    const integrity = checkReport(report);
+    if (!integrity.ok)
+        throw new Error(`refusing to attest a report that does not check: ${integrity.problems[0]}`);
+    return {
+        _type: STATEMENT_TYPE,
+        subject: [{ name: "workproof-report", digest: { sha256: report.hash } }],
+        predicateType: PREDICATE_TYPE,
+        predicate: predicateFor(report),
+    };
+}
+const stem = (reportPath) => join(dirname(reportPath), basename(reportPath).replace(/\.json$/, ""));
+/** Writes <basename>.intoto.json and <basename>.predicate.json next to the report. */
+export async function writeStatement(reportPath) {
+    const report = JSON.parse(await readFile(reportPath, "utf8"));
+    const statement = statementFor(report);
+    const paths = { statement: `${stem(reportPath)}.intoto.json`, predicate: `${stem(reportPath)}.predicate.json` };
+    await writeFile(paths.statement, JSON.stringify(statement, null, 2) + "\n");
+    await writeFile(paths.predicate, JSON.stringify(statement.predicate, null, 2) + "\n");
+    return paths;
+}
+/**
+ * Signs the statement with an SSH key (ssh-keygen -Y sign, namespace "workproof"), keeps
+ * the detached .sig ssh-keygen wrote, and wraps both in a DSSE envelope as
+ * <basename>.dsse.json. The signature covers the statement bytes as written.
+ */
+export async function signLocal(statementPath, keyPath) {
+    const signature = `${statementPath}.sig`;
+    await rm(signature, { force: true });
+    await run("ssh-keygen", ["-Y", "sign", "-f", keyPath, "-n", "workproof", statementPath]);
+    const envelope = {
+        payloadType: PAYLOAD_TYPE,
+        payload: (await readFile(statementPath)).toString("base64"),
+        signatures: [{ keyid: "ssh", sig: (await readFile(signature)).toString("base64") }],
+    };
+    const envelopePath = statementPath.replace(/\.intoto\.json$/, ".dsse.json");
+    await writeFile(envelopePath, JSON.stringify(envelope, null, 2) + "\n");
+    return { signature, envelope: envelopePath };
+}

package/dist/src/badge.d.ts

@@ -0,0 +1,13 @@
+import type { Report } from "./report.js";
+/** shields.io endpoint document: https://shields.io/badges/endpoint-badge */
+export interface Badge {
+    schemaVersion: 1;
+    label: string;
+    message: string;
+    color: string;
+}
+/**
+ * A badge for the first repository in the report. It is a claim, not evidence:
+ * the JSON report next to it is what a reader verifies.
+ */
+export declare function badgeFor(report: Report): Badge;

package/dist/src/badge.js

@@ -0,0 +1,20 @@
+const pct = (x) => `${(x * 100).toFixed(1)}%`;
+/**
+ * A badge for the first repository in the report. It is a claim, not evidence:
+ * the JSON report next to it is what a reader verifies.
+ */
+export function badgeFor(report) {
+    const repo = report.repositories[0];
+    if (!repo)
+        throw new Error("the report has no repositories");
+    const surviving = repo.figures.find((f) => f.id === "survivingLines");
+    const tenure = repo.figures.find((f) => f.id === "tenure");
+    if (!surviving || !tenure)
+        throw new Error("the report has no surviving-lines or tenure figure");
+    return {
+        schemaVersion: 1,
+        label: "workproof",
+        message: `${pct(surviving.value.share)} surviving lines · ${Number(tenure.value.days).toLocaleString("en-US")} days`,
+        color: "1f3fbf",
+    };
+}

package/dist/src/canonical.d.ts

@@ -0,0 +1,9 @@
+/**
+ * RFC 8785 (JSON Canonicalization Scheme) serialisation, without a dependency.
+ *
+ * Object keys are sorted by UTF-16 code units, numbers use the shortest round-trip
+ * form JSON.stringify already produces, strings are escaped as JSON.stringify does,
+ * and there is no whitespace. Properties whose value is undefined are skipped, as
+ * JSON.stringify skips them. Non-finite numbers have no JSON form and throw.
+ */
+export declare function canonicalize(value: unknown): string;

package/dist/src/canonical.js

@@ -0,0 +1,27 @@
+/**
+ * RFC 8785 (JSON Canonicalization Scheme) serialisation, without a dependency.
+ *
+ * Object keys are sorted by UTF-16 code units, numbers use the shortest round-trip
+ * form JSON.stringify already produces, strings are escaped as JSON.stringify does,
+ * and there is no whitespace. Properties whose value is undefined are skipped, as
+ * JSON.stringify skips them. Non-finite numbers have no JSON form and throw.
+ */
+export function canonicalize(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error(`cannot canonicalise a non-finite number (${value})`);
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map((v) => (v === undefined ? "null" : canonicalize(v))).join(",")}]`;
+    if (typeof value === "object") {
+        const record = value;
+        const keys = Object.keys(record)
+            .filter((k) => record[k] !== undefined)
+            .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(record[k])}`).join(",")}}`;
+    }
+    throw new Error(`cannot canonicalise a value of type ${typeof value}`);
+}

package/dist/src/cli.d.ts

@@ -1,12 +1,18 @@
 #!/usr/bin/env node
 import type { Params } from "./index.js";
+type OutputFormat = "both" | "markdown" | "json";
 interface Cli {
     params: Params;
     repos: string[];
     out: string;
+    format: OutputFormat;
     json: boolean;
     doNarrate: boolean;
+    badge: boolean;
     verifyFile: string | undefined;
+    checkFile: string | undefined;
+    attestFile: string | undefined;
+    localKey: string | undefined;
 }
 export declare function parse(argv: string[]): Cli;
 export {};

package/dist/src/cli.js

@@ -3,9 +3,11 @@ import { readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
-import { analyseRepo, buildReport, renderMarkdown, verifyReport, narrate } from "./index.js";
+import { analyseRepo, buildReport, renderMarkdown, verifyReport, checkReport, narrate, badgeFor, newFingerprintKey, writeStatement, signLocal } from "./index.js";
 const HELP = `usage: workproof [options] [--repo <dir>]...
-       workproof verify <report.json> [--repo <dir>]...
+       workproof check <report.json>
+       workproof verify <report.json> [--repo <dir>]... [--fingerprint-key <hex>]
+       workproof attest <report.json> [--local <ssh-key>]
 
 Turn a git repository into a verifiable engineering report for one author, without showing code.
 
@@ -15,20 +17,61 @@ Turn a git repository into a verifiable engineering report for one author, witho
   --sample <n>           blame every n-th file (default: 1, or 7 for very large repositories)
   --max-commits <n>      read only the newest n commits (escape hatch for enormous histories)
   --depth <n>            directory depth for ownership (default: 2)
+  --no-exclusions        count bot commits and generated, vendored, lock and snapshot files
+  --exclude <glob>       also drop files matching the glob (repeatable)
+  --seed <text>          salt for the blame file sample
+  --copies               pass -C to git blame so copied lines follow their origin
+  --ignore-revs-file <f> blame ignore-revs file (default: .git-blame-ignore-revs at the root)
+  --fingerprint-key <hex> reuse a fingerprint key so two reports of one repository match
   --paths                include directory paths in the report (off by default)
   --emails               include author emails in the report (off by default)
   --narrate              append a model-written paragraph; needs WORKPROOF_API_URL, WORKPROOF_API_KEY, WORKPROOF_MODEL
+  --badge                also write <out>.badge.json, a shields.io endpoint document
   --out <basename>       output basename (default: workproof-report)
-  --json                 print the JSON to stdout instead of writing files
-  -h, --help             this text`;
+  --format <mode>        output markdown, json, or both (default: both)
+  --json                 print the JSON to stdout instead of writing files (legacy alias)
+  -h, --help             this text
+  --version              print the version
+
+check validates the document and recomputes its hash offline; verify does that, then
+compares the fingerprint and HEAD and recomputes every figure in the repository; attest
+writes an in-toto statement whose subject is the report hash, and with --local signs it
+with ssh-keygen -Y sign (namespace workproof) into a DSSE envelope.`;
 export function parse(argv) {
-    const params = { depth: 2, threshold: 0.5, minCommits: 5, paths: false, emails: false };
+    const params = { depth: 2, threshold: 0.5, minCommits: 5, paths: false, emails: false, exclusions: true, exclude: [], seed: "", copies: false };
     const repos = [];
     const authors = [];
     let out = "workproof-report";
+    let format = "both";
     let json = false;
     let doNarrate = false;
+    let badge = false;
     let verifyFile;
+    let checkFile;
+    let attestFile;
+    let localKey;
+    if (argv[0] === "attest") {
+        attestFile = argv[1];
+        if (!attestFile)
+            throw new Error("attest needs a report.json");
+        argv = argv.slice(2);
+        if (argv[0] === "--local") {
+            localKey = argv[1];
+            if (!localKey)
+                throw new Error("--local needs an ssh private key path");
+            argv = argv.slice(2);
+        }
+        if (argv.length)
+            throw new Error(`unknown option ${argv[0]} (attest takes only --local <ssh-key>)`);
+    }
+    if (argv[0] === "check") {
+        checkFile = argv[1];
+        if (!checkFile)
+            throw new Error("check needs a report.json");
+        if (argv.length > 2)
+            throw new Error("check takes only the report; it never reads a repository");
+        argv = [];
+    }
     if (argv[0] === "verify") {
         verifyFile = argv[1];
         if (!verifyFile)
@@ -60,16 +103,38 @@ export function parse(argv) {
         }
         else if (a === "--depth")
             params.depth = Number(next());
+        else if (a === "--no-exclusions")
+            params.exclusions = false;
+        else if (a === "--exclude")
+            params.exclude.push(next());
+        else if (a === "--seed")
+            params.seed = next();
+        else if (a === "--copies")
+            params.copies = true;
+        else if (a === "--ignore-revs-file")
+            params.ignoreRevsFile = next();
+        else if (a === "--fingerprint-key")
+            params.fingerprintKey = next();
         else if (a === "--paths")
             params.paths = true;
         else if (a === "--emails")
             params.emails = true;
         else if (a === "--narrate")
             doNarrate = true;
+        else if (a === "--badge")
+            badge = true;
         else if (a === "--out")
             out = next();
-        else if (a === "--json")
+        else if (a === "--format") {
+            const value = next();
+            if (value !== "both" && value !== "markdown" && value !== "json")
+                throw new Error("--format must be markdown, json, or both");
+            format = value;
+        }
+        else if (a === "--json") {
             json = true;
+            format = "json";
+        }
         else if (a === "-h" || a === "--help") {
             console.log(HELP);
             process.exit(0);
@@ -81,24 +146,75 @@ export function parse(argv) {
         params.author = authors;
     if (!repos.length)
         repos.push(process.cwd());
-    return { params, repos, out, json, doNarrate, verifyFile };
+    return { params, repos, out, format, json, doNarrate, badge, verifyFile, checkFile, attestFile, localKey };
 }
 async function main() {
+    if (process.argv.includes("--version")) {
+        console.log(createRequire(import.meta.url)("../../package.json").version);
+        return;
+    }
     const started = Date.now();
-    const { params, repos, out, json, doNarrate, verifyFile } = parse(process.argv.slice(2));
+    const { params, repos, out, format, json, doNarrate, badge, verifyFile, checkFile, attestFile, localKey } = parse(process.argv.slice(2));
     const progress = (m) => process.stderr.write(`${m}\n`);
+    const printIntegrity = (i) => {
+        const schemaProblems = i.problems.filter((p) => !p.startsWith("hash mismatch"));
+        console.log(schemaProblems.length ? `schema: ${schemaProblems.length} problem${schemaProblems.length === 1 ? "" : "s"}` : "schema ok");
+        for (const p of schemaProblems)
+            console.log(`  ${p}`);
+        if (!schemaProblems.length)
+            console.log(i.ok ? `hash ok ${i.hash.computed}` : i.problems.find((p) => p.startsWith("hash mismatch")));
+    };
+    if (attestFile) {
+        const { statement, predicate } = await writeStatement(attestFile);
+        const files = [statement, predicate];
+        if (localKey) {
+            const { signature, envelope } = await signLocal(statement, localKey);
+            files.push(signature, envelope);
+        }
+        console.log(`wrote ${files.slice(0, -1).join(", ")} and ${files[files.length - 1]}`);
+        return;
+    }
+    if (checkFile) {
+        const result = checkReport(JSON.parse(await readFile(checkFile, "utf8")));
+        printIntegrity(result);
+        process.exit(result.ok ? 0 : 1);
+    }
     if (verifyFile) {
         const report = JSON.parse(await readFile(verifyFile, "utf8"));
-        const result = await verifyReport(report, repos);
+        const result = await verifyReport(report, repos, params.fingerprintKey ? { fingerprintKey: params.fingerprintKey } : {});
+        printIntegrity(result.integrity);
+        if (!result.integrity.ok) {
+            console.log("the report was edited or damaged after it was written; figures were not recomputed");
+            process.exit(1);
+        }
+        for (const f of result.fingerprints) {
+            if (!f.compared)
+                console.log(`${f.repo}: fingerprint not compared (pass --fingerprint-key)`);
+            else if (!f.match)
+                console.log(`${f.repo}: fingerprint differs; this is a different repository, figures were not recomputed`);
+            else
+                console.log(`${f.repo}: fingerprint ok`);
+        }
         for (const h of result.headMoved)
             console.log(`HEAD moved: ${h}`);
         for (const r of result.rows)
             if (!r.match)
                 console.log(`mismatch ${r.repo}/${r.figure}\n  report:     ${r.expected}\n  repository: ${r.actual}`);
-        console.log(result.ok ? "all figures reproduce" : `${result.rows.filter((r) => !r.match).length} figures differ`);
+        const differ = result.rows.filter((r) => !r.match).length;
+        if (result.fingerprints.some((f) => f.compared && !f.match))
+            process.exit(1);
+        console.log(result.ok ? "all figures reproduce" : `${differ} figures differ`);
+        console.log(result.ok
+            ? "\nWhat this proves: every figure in the report was recomputed from this repository just now and came out the same, and the document has not been edited since it was written.\nWhat it does not prove: that the repository itself is honest history, that the figures measure anything worth measuring, or that the work was good. A repository whose history was rewritten before the report was made reproduces perfectly."
+            : "\nA figure that differs is not proof of dishonesty. HEAD moves, and every figure except tenure is computed at HEAD; check the HEAD line above before concluding anything.");
         process.exit(result.ok ? 0 : 1);
     }
     const version = createRequire(import.meta.url)("../../package.json").version;
+    if (!params.fingerprintKey) {
+        // One key per report, so the repositories in a combined report share it; printed once, stored nowhere.
+        params.fingerprintKey = newFingerprintKey();
+        progress(`fingerprint key ${params.fingerprintKey} (keep it to compare reports or to verify the fingerprint; it is not stored)`);
+    }
     const repositories = [];
     for (const dir of repos)
         repositories.push(await analyseRepo(dir, params, { progress }));
@@ -112,13 +228,24 @@ async function main() {
             throw new Error("--narrate needs WORKPROOF_API_URL, WORKPROOF_API_KEY and WORKPROOF_MODEL");
         narrative = await narrate(report, { url, key, model });
     }
-    if (json) {
+    if (format === "json") {
         console.log(JSON.stringify(report, null, 2));
         return;
     }
-    await writeFile(`${out}.json`, JSON.stringify(report, null, 2));
-    await writeFile(`${out}.md`, renderMarkdown(report, narrative));
-    console.log(`wrote ${out}.md and ${out}.json in ${((Date.now() - started) / 1000).toFixed(1)}s`);
+    const written = [];
+    if (format === "markdown" || format === "both") {
+        await writeFile(`${out}.md`, renderMarkdown(report, narrative));
+        written.push(`${out}.md`);
+    }
+    if (format === "both") {
+        await writeFile(`${out}.json`, JSON.stringify(report, null, 2));
+        written.push(`${out}.json`);
+    }
+    if (badge) {
+        await writeFile(`${out}.badge.json`, JSON.stringify(badgeFor(report), null, 2));
+        written.push(`${out}.badge.json`);
+    }
+    console.log(`wrote ${written.join(" and ")} in ${((Date.now() - started) / 1000).toFixed(1)}s`);
 }
 const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
 if (entry === import.meta.url || entry.endsWith("/workproof")) {

package/dist/src/exclusions.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What leaves every denominator before a figure is computed.
+ *
+ * Bots are recognised by the two patterns GitHub uses for app identities, nothing
+ * cleverer: a name ending in "[bot]" or the "<id>+<name>[bot]@users.noreply.github.com"
+ * address. Generated, vendored, lock and snapshot files follow the subset of
+ * github-linguist's generated.rb and vendor.yml that moves line counts, plus whatever a
+ * repository marks with linguist-generated or linguist-vendored in .gitattributes.
+ */
+export declare const isBot: (c: {
+    name: string;
+    email: string;
+}) => boolean;
+/** True for paths the built-in lists treat as generated, vendored, lock or snapshot files. */
+export declare function isExcludedPath(path: string): boolean;
+export interface PathAttributes {
+    generated: boolean;
+    vendored: boolean;
+}
+/**
+ * The set of paths to drop, from the built-in lists, the repository's .gitattributes,
+ * and the user's --exclude globs (already compiled to RegExp).
+ */
+export declare function excludedSet(paths: Iterable<string>, attrs: Map<string, PathAttributes>, extra: RegExp[]): Set<string>;