workproof 0.1.2 → 0.2.0

package/dist/src/git.js

@@ -1,13 +1,37 @@
 import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-const execFileP = promisify(execFile);
-export async function git(args, cwd) {
-    const { stdout } = await execFileP("git", args, { cwd, encoding: "utf8", maxBuffer: 1024 * 1024 * 512 });
-    return stdout;
+/**
+ * Settings that change what diff and blame attribute, pinned so two machines with different
+ * defaults produce the same figures. indentHeuristic became the default in git 2.14 and
+ * rename detection in 2.9; a report records the git version it ran under as well.
+ */
+export const PINNED_CONFIG = ["-c", "diff.renames=true", "-c", "diff.algorithm=myers", "-c", "diff.indentHeuristic=true", "-c", "core.autocrlf=false"];
+export function git(args, cwd, input) {
+    return new Promise((resolve, reject) => {
+        const child = execFile("git", [...PINNED_CONFIG, ...args], { cwd, encoding: "utf8", maxBuffer: 1024 * 1024 * 512 }, (err, stdout) => {
+            if (err)
+                reject(err);
+            else
+                resolve(stdout);
+        });
+        if (input !== undefined)
+            child.stdin?.end(input);
+    });
+}
+export const gitVersion = async (cwd) => (await git(["--version"], cwd)).trim();
+const RS = "\x1e";
+const US = "\x1f";
+const GS = "\x1d";
+function splitTrailers(field) {
+    return (field ?? "").split(GS).map((s) => s.trim()).filter(Boolean);
 }
-/** All commits reachable from HEAD, newest first, with per-file numstat. One git call. */
+/** All commits reachable from HEAD, newest first, with per-file numstat and trailers. One git call. */
 export async function listCommits(cwd, opts) {
-    const args = ["log", "--numstat", "--format=%x1e%H%x1f%aE%x1f%aN%x1f%aI%x1f%P", "-M"];
+    const args = [
+        "log",
+        "--numstat",
+        "--format=%x1e%H%x1f%aE%x1f%aN%x1f%aI%x1f%P%x1f%(trailers:key=Co-authored-by,valueonly,separator=%x1d)%x1f%(trailers:key=Assisted-by,valueonly,separator=%x1d)",
+        "-M",
+    ];
     if (opts.since)
         args.push(`--since=${opts.since}`);
     if (opts.until)
@@ -16,24 +40,30 @@ export async function listCommits(cwd, opts) {
         args.push(`--max-count=${opts.max}`);
     const out = await git(args, cwd);
     const commits = [];
-    for (const block of out.split("\x1e")) {
+    for (const block of out.split(RS)) {
         if (!block.trim())
             continue;
+        // Trailer values may contain newlines only if a trailer does, which git folds; the header ends at the first newline.
         const [header, ...rest] = block.split("\n");
-        const [sha, email, name, iso, parents] = header.split("\x1f");
+        const [sha, email, name, iso, parents, coAuthorField, assistedField] = header.split(US);
+        const coAuthorValues = splitTrailers(coAuthorField);
         const files = [];
         for (const line of rest) {
             if (!line.trim())
                 continue;
             const [a, d, ...pathParts] = line.split("\t");
             let path = pathParts.join("\t");
+            let from;
             // rename entries look like "old => new" or "dir/{old => new}/file"
             const brace = path.match(/^(.*)\{(.*) => (.*)\}(.*)$/);
-            if (brace)
+            if (brace) {
+                from = `${brace[1]}${brace[2]}${brace[4]}`;
                 path = `${brace[1]}${brace[3]}${brace[4]}`;
-            else if (path.includes(" => "))
-                path = path.split(" => ")[1];
-            files.push({ path, added: a === "-" ? null : Number(a), deleted: d === "-" ? null : Number(d) });
+            }
+            else if (path.includes(" => ")) {
+                [from, path] = path.split(" => ");
+            }
+            files.push({ path, added: a === "-" ? null : Number(a), deleted: d === "-" ? null : Number(d), ...(from ? { from } : {}) });
         }
         commits.push({
             sha: sha,
@@ -42,6 +72,9 @@ export async function listCommits(cwd, opts) {
             date: new Date(iso),
             parents: parents ? parents.trim().split(" ").filter(Boolean).length : 0,
             files,
+            coAuthors: coAuthorValues.map((v) => (v.match(/<([^>]+)>/)?.[1] ?? "").toLowerCase()).filter(Boolean),
+            coAuthorNames: coAuthorValues.map((v) => v.replace(/\s*<[^>]*>\s*$/, "").trim()).filter(Boolean),
+            assistedBy: splitTrailers(assistedField),
         });
     }
     return commits;
@@ -58,6 +91,11 @@ export async function listTags(cwd) {
     }
     return tags.sort((a, b) => a.date.getTime() - b.date.getTime());
 }
+/** Every path in the HEAD tree. */
+export async function listHeadFiles(cwd) {
+    const out = await git(["ls-tree", "-r", "-z", "--name-only", "HEAD"], cwd);
+    return out.split("\0").filter(Boolean);
+}
 export const rootCommit = async (cwd) => (await git(["rev-list", "--max-parents=0", "HEAD"], cwd)).trim().split("\n").pop();
 export const headSha = async (cwd) => (await git(["rev-parse", "HEAD"], cwd)).trim();
 export async function remoteUrl(cwd) {
@@ -85,6 +123,25 @@ export async function assertRepository(cwd) {
         throw new Error(`${cwd} is not inside a git repository (use --repo to point at one)`);
     }
 }
+/** linguist-generated and linguist-vendored from .gitattributes, for the given paths. */
+export async function checkAttr(cwd, paths) {
+    const out = new Map();
+    if (!paths.length)
+        return out;
+    const raw = await git(["check-attr", "-z", "--stdin", "linguist-generated", "linguist-vendored"], cwd, paths.join("\0") + "\0");
+    const parts = raw.split("\0");
+    for (let i = 0; i + 2 < parts.length; i += 3) {
+        const [path, attr, value] = [parts[i], parts[i + 1], parts[i + 2]];
+        const entry = out.get(path) ?? { generated: false, vendored: false };
+        const set = value === "set" || value === "true";
+        if (attr === "linguist-generated")
+            entry.generated = set;
+        if (attr === "linguist-vendored")
+            entry.vendored = set;
+        out.set(path, entry);
+    }
+    return out;
+}
 export async function configuredEmail(cwd) {
     try {
         return (await git(["config", "--get", "user.email"], cwd)).trim().toLowerCase();

package/dist/src/index.d.ts

@@ -1,8 +1,14 @@
-export { analyseRepo, fingerprint } from "./analyse.js";
+export { analyseRepo, fingerprint, newFingerprintKey, publicEmail } from "./analyse.js";
 export type { Params, RepoReport, AnalyseHooks } from "./analyse.js";
-export { buildReport, renderMarkdown } from "./report.js";
+export { buildReport, renderMarkdown, hashOf } from "./report.js";
+export { canonicalize } from "./canonical.js";
+export { validateReport } from "./schema.js";
 export type { Report } from "./report.js";
-export { verifyReport } from "./verify.js";
-export type { VerifyRow } from "./verify.js";
+export { verifyReport, checkReport } from "./verify.js";
+export type { VerifyRow, VerifyResult, Integrity } from "./verify.js";
 export { narrate } from "./narrate.js";
 export type { Figure, Identity } from "./figures/types.js";
+export { badgeFor } from "./badge.js";
+export type { Badge } from "./badge.js";
+export { statementFor, predicateFor, writeStatement, signLocal, PREDICATE_TYPE, STATEMENT_TYPE } from "./attest.js";
+export type { InTotoStatement, Predicate, DsseEnvelope } from "./attest.js";

package/dist/src/index.js

@@ -1,4 +1,8 @@
-export { analyseRepo, fingerprint } from "./analyse.js";
-export { buildReport, renderMarkdown } from "./report.js";
-export { verifyReport } from "./verify.js";
+export { analyseRepo, fingerprint, newFingerprintKey, publicEmail } from "./analyse.js";
+export { buildReport, renderMarkdown, hashOf } from "./report.js";
+export { canonicalize } from "./canonical.js";
+export { validateReport } from "./schema.js";
+export { verifyReport, checkReport } from "./verify.js";
 export { narrate } from "./narrate.js";
+export { badgeFor } from "./badge.js";
+export { statementFor, predicateFor, writeStatement, signLocal, PREDICATE_TYPE, STATEMENT_TYPE } from "./attest.js";

package/dist/src/report.d.ts

@@ -1,13 +1,17 @@
 import type { Params, RepoReport } from "./analyse.js";
 export interface Report {
     tool: "workproof";
+    /** Shape of the document; check and verify refuse other versions. */
+    schemaVersion: 2;
     version: string;
     generatedAt: string;
     params: Params;
     repositories: RepoReport[];
-    /** sha256 of the canonical JSON of { params, repositories }. */
+    /** sha256 of the RFC 8785 canonical JSON of { params, repositories }. */
     hash: string;
 }
+/** The hash a report with these parameters and repositories must carry. */
+export declare const hashOf: (params: unknown, repositories: unknown) => string;
 export declare function buildReport(repositories: RepoReport[], params: Params, meta: {
     version: string;
     generatedAt: string;

package/dist/src/report.js

@@ -1,20 +1,26 @@
 import { createHash } from "node:crypto";
-const canonical = (v) => JSON.stringify(v, (_k, val) => val && typeof val === "object" && !Array.isArray(val)
-    ? Object.fromEntries(Object.keys(val).sort().map((k) => [k, val[k]]))
-    : val);
-/** Without --emails, an author given as an email address is not echoed into the report. */
+import { canonicalize } from "./canonical.js";
+import { publicEmail } from "./analyse.js";
+import { plainSummary } from "./summary.js";
+/** The hash a report with these parameters and repositories must carry. */
+export const hashOf = (params, repositories) => createHash("sha256").update(canonicalize({ params, repositories })).digest("hex");
+/**
+ * What of the parameters the report may carry: never the fingerprint key, never a GitHub
+ * noreply login, and without --emails no author given as an email address.
+ */
 function publicParams(params) {
-    if (params.emails || !params.author)
-        return params;
-    return { ...params, author: params.author.map((a) => (a.includes("@") ? "(email hidden)" : a)) };
+    const { fingerprintKey: _key, ...rest } = params;
+    if (!rest.author)
+        return rest;
+    return { ...rest, author: rest.author.map((a) => (a.includes("@") ? (params.emails ? publicEmail(a) : "(email hidden)") : a)) };
 }
 export function buildReport(repositories, params, meta) {
     const shown = publicParams(params);
-    const hash = createHash("sha256").update(canonical({ params: shown, repositories })).digest("hex");
-    return { tool: "workproof", version: meta.version, generatedAt: meta.generatedAt, params: shown, repositories, hash };
+    return { tool: "workproof", schemaVersion: 2, version: meta.version, generatedAt: meta.generatedAt, params: shown, repositories, hash: hashOf(shown, repositories) };
 }
 const pct = (x) => `${(x * 100).toFixed(1)}%`;
 const n = (x) => x.toLocaleString("en-US");
+const plural = (x, one, many) => `${n(x)} ${x === 1 ? one : many}`;
 function figureLines(f) {
     const v = f.value;
     switch (f.id) {
@@ -37,9 +43,23 @@ function figureLines(f) {
             ];
         }
         case "testsAndDocs":
-            return [`${n(v.testChangesAuthor)} of ${n(v.testChangesTotal)} test-file changes, ${pct(v.testShare)}`, `${n(v.docsAuthored)} documents authored`];
+            return [`${n(v.testChangesAuthor)} of ${n(v.testChangesTotal)} test-file changes, ${pct(v.testShare)}`, `${n(v.docsCreated)} documents created`];
+        case "filesAuthored":
+            return [`${n(v.authored)} of ${n(v.total)} files alive at HEAD, ${pct(v.share)} (degree of authorship)`];
+        case "majorContributor":
+            return [`major contributor in ${n(v.major)} of ${n(v.dirs)} directories (at least ${v.threshold * 100}% of commits)`];
+        case "commitSize":
+            return [`median ${n(v.median)} lines, 90th percentile ${n(v.p90)}, ${plural(v.huge, "commit", "commits")} over 10,000 lines`];
+        case "coAuthored":
+            return [`${plural(v.trailerCommits, "commit", "commits")} by others naming the author in a Co-authored-by trailer`];
+        case "absenceFactor":
+            return [`${n(v.authorsToHalf)} author${v.authorsToHalf === 1 ? "" : "s"} cover half the commits; the author ranks ${n(v.authorRank)} of ${n(v.authors)} by commit count`];
+        case "aiAssisted":
+            return [`${plural(v.commits, "commit declares", "commits declare")} an AI tool in a trailer, ${pct(v.share)} of the author's commits`];
+        case "survivalByCohort":
+            return v.length ? v.map((c) => `${c.year}: ${n(c.lines)} lines`) : ["no surviving lines in the sample"];
         case "survivingLines":
-            return [`${n(v.lines)} of ${n(v.linesAttributed)} surviving lines, ${pct(v.share)} (files ${v.filesSampled}/${v.filesTotal}, sample 1 in ${v.sample})`];
+            return [`${n(v.lines)} of ${n(v.linesAttributed)} surviving lines, ${pct(v.share)} (files ${v.filesSampled}/${v.filesTotal}, sample 1 in ${v.sample}${v.seed ? `, seed "${v.seed}"` : ""})`];
         default:
             return [JSON.stringify(v)];
     }
@@ -52,7 +72,9 @@ export function renderMarkdown(report, narrative) {
         ``,
     ];
     for (const repo of report.repositories) {
-        out.push(`## ${repo.name}`, ``, `HEAD \`${repo.head.slice(0, 12)}\` · fingerprint \`${repo.fingerprint.slice(0, 16)}\` · identities: ${repo.identity.names.join(", ")}${repo.identity.emails.length ? ` (${repo.identity.emails.join(", ")})` : ""}`, ``);
+        out.push(`## ${repo.name}`, ``, `HEAD \`${repo.head.slice(0, 12)}\` · fingerprint \`${repo.fingerprint.slice(0, 16)}\` · identities: ${repo.identity.names.join(", ")}${repo.identity.emails.length ? ` (${repo.identity.emails.join(", ")})` : ""}`, ``, repo.excluded.enabled
+            ? `excluded ${plural(repo.excluded.botCommits, "bot commit", "bot commits")} and ${plural(repo.excluded.files, "generated, vendored or lock file", "generated, vendored or lock files")} (${pct(repo.excluded.linesAddedShare)} of lines added)`
+            : `exclusions off (--no-exclusions): bot commits and generated files are counted`, ``, `### In plain language`, ``, plainSummary(repo), ``, `That paragraph is assembled from the figures below by a fixed rule, with no model involved, so it says nothing the numbers do not.`, ``);
         for (const f of repo.figures) {
             out.push(`### ${f.title}`, ``);
             for (const line of figureLines(f))
@@ -60,7 +82,7 @@ export function renderMarkdown(report, narrative) {
             out.push(``, `How: \`${f.command}\``, ``, `What this cannot show: ${f.limits.join(" ")}`, ``);
         }
     }
-    out.push(`## Integrity`, ``, `Report hash \`${report.hash}\` (sha256 of parameters and figures). Repository fingerprints are hashes of the root commit and remote; they identify a repository without naming it.`, ``);
+    out.push(`## Integrity`, ``, `Report hash \`${report.hash}\` (sha256 over the RFC 8785 canonical JSON of parameters and figures; \`npx workproof check\` recomputes it offline). Repository fingerprints are keyed hashes of the root commit and remote; they identify a repository without naming it, and only someone holding the key printed when the report was made can compare them.`, ``);
     if (narrative) {
         out.push(`## Generated narrative (not verified)`, ``, `The paragraph below was produced by a language model from the figures above and is not part of the hash.`, ``, narrative.trim(), ``);
     }

package/dist/src/schema.d.ts

@@ -0,0 +1,4 @@
+type Problem = string;
+/** Returns the list of problems; an empty list means the report has the 0.2 shape. */
+export declare function validateReport(value: unknown): Problem[];
+export {};

package/dist/src/schema.js

@@ -0,0 +1,66 @@
+/**
+ * Shape check for a report, done by hand so `check` needs no dependency. The same shape
+ * is published as JSON Schema in schema/report.schema.json for other tools.
+ */
+const hex = (n) => new RegExp(`^[0-9a-f]{${n}}$`);
+const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function expect(problems, path, ok, what) {
+    if (!ok)
+        problems.push(`${path}: expected ${what}`);
+    return ok;
+}
+function checkFigure(problems, path, f) {
+    if (!expect(problems, path, isObject(f), "object"))
+        return;
+    const fig = f;
+    expect(problems, `${path}.id`, typeof fig.id === "string" && fig.id.length > 0, "non-empty string");
+    expect(problems, `${path}.title`, typeof fig.title === "string", "string");
+    expect(problems, `${path}.value`, fig.value !== undefined, "a value");
+    expect(problems, `${path}.command`, typeof fig.command === "string", "string");
+    expect(problems, `${path}.limits`, Array.isArray(fig.limits) && fig.limits.every((l) => typeof l === "string"), "array of strings");
+}
+function checkRepository(problems, path, r) {
+    if (!expect(problems, path, isObject(r), "object"))
+        return;
+    const repo = r;
+    expect(problems, `${path}.name`, typeof repo.name === "string", "string");
+    expect(problems, `${path}.head`, typeof repo.head === "string" && hex(40).test(repo.head), "40 hex characters");
+    expect(problems, `${path}.fingerprint`, typeof repo.fingerprint === "string" && hex(64).test(repo.fingerprint), "64 hex characters");
+    if (expect(problems, `${path}.identity`, isObject(repo.identity), "object")) {
+        const id = repo.identity;
+        expect(problems, `${path}.identity.emails`, Array.isArray(id.emails), "array");
+        expect(problems, `${path}.identity.names`, Array.isArray(id.names), "array");
+        expect(problems, `${path}.identity.count`, typeof id.count === "number", "number");
+    }
+    if (expect(problems, `${path}.environment`, isObject(repo.environment), "object")) {
+        const env = repo.environment;
+        expect(problems, `${path}.environment.git`, typeof env.git === "string", "string");
+        expect(problems, `${path}.environment.blame`, Array.isArray(env.blame), "array");
+    }
+    if (expect(problems, `${path}.excluded`, isObject(repo.excluded), "object")) {
+        const ex = repo.excluded;
+        expect(problems, `${path}.excluded.botCommits`, typeof ex.botCommits === "number", "number");
+        expect(problems, `${path}.excluded.files`, typeof ex.files === "number", "number");
+        expect(problems, `${path}.excluded.linesAddedShare`, typeof ex.linesAddedShare === "number", "number");
+    }
+    if (expect(problems, `${path}.figures`, Array.isArray(repo.figures) && repo.figures.length > 0, "non-empty array")) {
+        repo.figures.forEach((f, i) => checkFigure(problems, `${path}.figures[${i}]`, f));
+    }
+}
+/** Returns the list of problems; an empty list means the report has the 0.2 shape. */
+export function validateReport(value) {
+    const problems = [];
+    if (!expect(problems, "report", isObject(value), "object"))
+        return problems;
+    const r = value;
+    expect(problems, "tool", r.tool === "workproof", '"workproof"');
+    expect(problems, "schemaVersion", r.schemaVersion === 2, "2");
+    expect(problems, "version", typeof r.version === "string", "string");
+    expect(problems, "generatedAt", typeof r.generatedAt === "string" && !Number.isNaN(Date.parse(r.generatedAt)), "ISO date");
+    expect(problems, "params", isObject(r.params), "object");
+    expect(problems, "hash", typeof r.hash === "string" && hex(64).test(r.hash), "64 hex characters");
+    if (expect(problems, "repositories", Array.isArray(r.repositories) && r.repositories.length > 0, "non-empty array")) {
+        r.repositories.forEach((repo, i) => checkRepository(problems, `repositories[${i}]`, repo));
+    }
+    return problems;
+}

package/dist/src/summary.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The report in plain language, for the person who will read it and does not
+ * write software: a recruiter, a hiring manager, a caseworker.
+ *
+ * Built from the figures with no model call, so it is deterministic and adds
+ * nothing that is not already in the numbers above it. It states no opinion
+ * about quality, keeps the two shares apart, and ends with how to check it.
+ * The paragraph is derived from the hashed figures, not part of the hash.
+ */
+import type { RepoReport } from "./analyse.js";
+export declare function plainSummary(repo: RepoReport): string;

package/dist/src/summary.js

@@ -0,0 +1,47 @@
+const pct = (x) => `${Math.round(x * 100)}%`;
+const n = (x) => x.toLocaleString("en-US");
+const value = (repo, id) => repo.figures.find((f) => f.id === id)?.value;
+const MONTHS = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+/** "2026-01-05" to "5 January 2026". Dates only; the report carries no times. */
+function longDate(iso) {
+    const [y, m, d] = iso.split("-").map(Number);
+    if (!y || !m || !d)
+        return iso;
+    return `${d} ${MONTHS[m - 1]} ${y}`;
+}
+export function plainSummary(repo) {
+    const who = repo.identity.names[0] ?? "This author";
+    const tenure = value(repo, "tenure");
+    const commits = value(repo, "commitShare");
+    const surviving = value(repo, "survivingLines");
+    const cadence = value(repo, "cadence");
+    const files = value(repo, "filesAuthored");
+    const absence = value(repo, "absenceFactor");
+    const sentences = [];
+    if (tenure) {
+        sentences.push(`${who} worked in ${repo.name} from ${longDate(tenure.first)} to ${longDate(tenure.last)}, a span of ${n(tenure.days)} days.`);
+    }
+    if (commits && surviving) {
+        sentences.push(`They made ${n(commits.author)} of the ${n(commits.total)} changes recorded in that period (${pct(commits.share)}), and ${n(surviving.lines)} of the ${n(surviving.linesAttributed)} lines of code still in the project today are theirs (${pct(surviving.share)}).`);
+        sentences.push(commits.share >= surviving.share
+            ? `The second number is the one that lasts: it counts the work that survived everything written since.`
+            : `The second number is the one that lasts, and here it is the higher of the two: their work survived everything written since better than the count of changes suggests.`);
+    }
+    if (files) {
+        sentences.push(`${n(files.authored)} of the ${n(files.total)} files in the project were started by them (${pct(files.share)}).`);
+    }
+    if (cadence) {
+        sentences.push(`They were active in ${n(cadence.activeWeeks)} of the ${n(cadence.weeksInTenure)} weeks in that period.`);
+    }
+    if (absence && absence.authors > 1) {
+        sentences.push(`${n(absence.authors)} people wrote code in this project; by share of surviving lines they rank ${n(absence.authorRank)}.`);
+    }
+    if (repo.excluded.enabled) {
+        sentences.push(`Before any of this was counted, ${n(repo.excluded.botCommits)} automated ${repo.excluded.botCommits === 1 ? "change" : "changes"} and ${n(repo.excluded.files)} machine-written or copied ${repo.excluded.files === 1 ? "file" : "files"} were removed, so none of them inflate the figures.`);
+    }
+    sentences.push(surviving && surviving.sample > 1
+        ? `The line figures come from a fixed sample of one file in ${n(surviving.sample)}, chosen by a rule that anyone re-running this gets the same way.`
+        : `Every figure above names the exact command that produced it.`);
+    sentences.push(`Anyone with a copy of this project can recompute all of it with \`npx workproof verify\`, and the report will not match if a number was edited.`);
+    return sentences.join(" ");
+}

package/dist/src/verify.d.ts

@@ -6,9 +6,35 @@ export interface VerifyRow {
     expected: string;
     actual: string;
 }
-/** Recompute every figure in the given repositories and compare with the report. */
-export declare function verifyReport(report: Report, repoDirs: string[]): Promise<{
+export interface Integrity {
     ok: boolean;
+    problems: string[];
+    hash: {
+        stated: string;
+        computed: string;
+    };
+}
+/**
+ * Offline: does the document have the 0.2 shape, and does its content hash to the hash it
+ * states? No git, no repository. An edited report fails here before anything is recomputed.
+ */
+export declare function checkReport(report: unknown): Integrity;
+export interface VerifyResult {
+    ok: boolean;
+    integrity: Integrity;
+    /** Per repository: whether the fingerprint was compared, and whether it matched. */
+    fingerprints: {
+        repo: string;
+        compared: boolean;
+        match: boolean;
+    }[];
     rows: VerifyRow[];
     headMoved: string[];
-}>;
+}
+/**
+ * check first, then the repository: fingerprint and HEAD, then every figure recomputed
+ * and compared. A fingerprint mismatch is a different repository and stops before figures.
+ */
+export declare function verifyReport(report: Report, repoDirs: string[], opts?: {
+    fingerprintKey?: string;
+}): Promise<VerifyResult>;

package/dist/src/verify.js

@@ -1,18 +1,49 @@
-import { analyseRepo } from "./analyse.js";
-import { headSha } from "./git.js";
+import { analyseRepo, fingerprint } from "./analyse.js";
+import { headSha, rootCommit, remoteUrl } from "./git.js";
+import { hashOf } from "./report.js";
+import { validateReport } from "./schema.js";
 const show = (v) => JSON.stringify(v);
-/** Recompute every figure in the given repositories and compare with the report. */
-export async function verifyReport(report, repoDirs) {
+/**
+ * Offline: does the document have the 0.2 shape, and does its content hash to the hash it
+ * states? No git, no repository. An edited report fails here before anything is recomputed.
+ */
+export function checkReport(report) {
+    const problems = validateReport(report);
+    const r = report;
+    const stated = typeof r?.hash === "string" ? r.hash : "";
+    let computed = "";
+    if (problems.length === 0) {
+        computed = hashOf(r.params, r.repositories);
+        if (computed !== stated)
+            problems.push(`hash mismatch: report says ${stated}, content hashes to ${computed}`);
+    }
+    return { ok: problems.length === 0, problems, hash: { stated, computed } };
+}
+/**
+ * check first, then the repository: fingerprint and HEAD, then every figure recomputed
+ * and compared. A fingerprint mismatch is a different repository and stops before figures.
+ */
+export async function verifyReport(report, repoDirs, opts = {}) {
+    const integrity = checkReport(report);
     const rows = [];
     const headMoved = [];
+    const fingerprints = [];
+    if (!integrity.ok)
+        return { ok: false, integrity, fingerprints, rows, headMoved };
     for (const [i, expected] of report.repositories.entries()) {
         const dir = repoDirs[i] ?? repoDirs[0] ?? process.cwd();
+        const key = opts.fingerprintKey ?? report.params.fingerprintKey;
+        const compared = !expected.fingerprintKeyed || key !== undefined;
+        const match = compared ? fingerprint(await rootCommit(dir), await remoteUrl(dir), expected.fingerprintKeyed ? key : undefined) === expected.fingerprint : false;
+        fingerprints.push({ repo: expected.name, compared, match });
+        if (compared && !match)
+            continue;
         const head = await headSha(dir);
         if (head !== expected.head)
             headMoved.push(`${expected.name}: report at ${expected.head.slice(0, 12)}, repository at ${head.slice(0, 12)}`);
         // Emails are hidden from the report by default, so resolve the identity from what it does carry.
         const author = expected.identity.emails.length ? expected.identity.emails : expected.identity.names;
-        const actual = await analyseRepo(dir, { ...report.params, author });
+        const actual = await analyseRepo(dir, { ...report.params, author, ...(key ? { fingerprintKey: key } : {}) });
         for (const f of expected.figures) {
             const a = actual.figures.find((x) => x.id === f.id);
             const e = show(f.value);
@@ -20,5 +51,6 @@ export async function verifyReport(report, repoDirs) {
             rows.push({ repo: expected.name, figure: f.id, match: e === g, expected: e, actual: g });
         }
     }
-    return { ok: rows.every((r) => r.match) && headMoved.length === 0, rows, headMoved };
+    const ok = fingerprints.every((f) => !f.compared || f.match) && rows.every((r) => r.match) && headMoved.length === 0;
+    return { ok, integrity, fingerprints, rows, headMoved };
 }

package/package.json

@@ -1,25 +1,80 @@
 {
   "name": "workproof",
-  "version": "0.1.2",
-  "description": "Turn a private git repository into a verifiable engineering report for one author, without showing any code.",
+  "version": "0.2.0",
+  "description": "Turn a private git repository into a verifiable engineering report for one author, without showing any code: thirteen figures from git, a hash anyone can recompute offline, verify, and an in-toto attestation.",
   "type": "module",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
-  "exports": { ".": { "types": "./dist/src/index.d.ts", "import": "./dist/src/index.js" } },
-  "bin": { "workproof": "./dist/src/cli.js" },
-  "files": ["dist/src", "README.md", "LICENSE"],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "workproof": "dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "schema",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node --test dist/test/figures.test.js dist/test/report.test.js dist/test/cli.test.js",
-    "prepublishOnly": "npm test"
+    "test": "npm run build && node --test dist/test/figures.test.js dist/test/exclusions.test.js dist/test/adversarial.test.js dist/test/integrity.test.js dist/test/attest.test.js dist/test/report.test.js dist/test/summary.test.js dist/test/cli.test.js dist/test/action.test.js test/release.test.mjs",
+    "prepublishOnly": "npm test",
+    "examples": "npm run build && node examples/basic.mjs",
+    "release": "node scripts/release.mjs",
+    "release-gate": "npm run build && node scripts/release-gate.mjs",
+    "bench:adversarial": "npm run build && node bench/adversarial.mjs"
   },
-  "engines": { "node": ">=20" },
-  "keywords": ["git", "portfolio", "proof-of-work", "career", "blame", "engineering-evidence"],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "git",
+    "git-blame",
+    "engineering-report",
+    "verifiable",
+    "proof-of-work",
+    "portfolio",
+    "resume",
+    "hiring",
+    "career",
+    "authorship",
+    "code-ownership",
+    "surviving-lines",
+    "engineering-evidence",
+    "in-toto",
+    "sigstore",
+    "attestation",
+    "github-action",
+    "cli"
+  ],
   "author": "Efe Genc",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/Bubblegunn/workproof.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bubblegunn/workproof.git"
+  },
   "homepage": "https://github.com/Bubblegunn/workproof#readme",
-  "dependencies": { "surviving-lines": "^0.1.1" },
-  "devDependencies": { "@types/node": "^22.15.0", "typescript": "^5.8.0" }
+  "bugs": {
+    "url": "https://github.com/Bubblegunn/workproof/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "surviving-lines": "^0.1.1"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@types/node": "^26.4.1",
+    "publint": "^0.3.24",
+    "typescript": "^7.0.2"
+  }
 }