workproof 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Efe Genc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+<p align="center"><img src="assets/wordmark.svg" width="480" alt="workproof"></p>
+
+<p align="center"><em>Your best work is in private repos. Prove it anyway.</em></p>
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/workproof?style=flat-square&color=111111&label=npm" alt="npm">
+  <img src="https://img.shields.io/github/stars/Bubblegunn/workproof?style=flat-square&color=111111" alt="stars">
+  <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT">
+</p>
+
+workproof turns a git repository into a verifiable engineering report for one author,
+without showing any code. You run it in the repository you cannot share. The reader
+gets six figures, the exact command behind each one, what each one cannot show, and a
+hash. Anyone with the same repository can rerun `verify` and see whether the numbers
+reproduce.
+
+## 30 seconds
+
+```
+cd your-private-repo
+npx workproof
+```
+
+That writes `workproof-report.md` (paste it into a résumé, a portfolio, a visa application)
+and `workproof-report.json` (for tools, and for verification). To check someone's report:
+
+```
+npx workproof verify workproof-report.json
+```
+
+## What a report looks like
+
+This is real output for one maintainer of [langchain-ai/openwiki](https://github.com/langchain-ai/openwiki)
+at `1e6d54c`, run on 5 September 2026 with `--author "Colin Francis" --sample 5`, paths and
+emails hidden (the defaults):
+
+```
+## openwiki
+
+HEAD 1e6d54cdfeec · fingerprint 82aa401bbba056f1 · identities: Colin Francis
+
+### Tenure window
+2026-07-06 to 2026-09-03 (60 days)
+
+### Share of commits in tenure
+71 of 295 non-merge commits, 24.1%
+
+### Cadence
+9 active weeks of 9, 7.9 commits per active week, longest streak 9 weeks
+1 of 21 release tags in tenure
+
+### Footprint
+694 files touched
+16 directories with a commit share at or above the threshold (paths hidden; run with --paths)
+languages by lines added: TypeScript 80.4%, JSON 9.6%, Markdown 7.0%, JavaScript 1.6%, YAML 1.4%
+
+### Tests and documentation
+393 of 657 test-file changes, 59.8%
+116 documents authored
+
+### Surviving lines at HEAD
+23,317 of 33,038 surviving lines, 70.6% (files 123/548, sample 1 in 5)
+```
+
+Under every figure the report prints two more lines: `How:` with the git command that
+produced it, and `What this cannot show:`. The last section is `Integrity`: the report
+hash and the repository fingerprint.
+
+Read the two shares together. This person wrote 24.1% of the commits in their window and
+70.6% of the lines that are still alive. A commit count would have called them a minor
+contributor. That gap, in either direction, is usually the most honest thing a report can
+say about someone's work.
+
+## What it measures
+
+All six figures come from git and nothing else.
+
+| figure | what it is | what it cannot show |
+|---|---|---|
+| Tenure window | first to last commit by the author, or `--since/--until` | work before the first commit or after the last |
+| Share of commits | non-merge commits by the author over all non-merge commits in the window | what survived; a typo and a subsystem count the same |
+| Cadence | active weeks, commits per active week, longest streak, release tags in tenure and the author's | a week with one commit and a week with forty both count as active |
+| Footprint | files touched, directories at or above a commit-share threshold, languages by lines added | generated and vendored files inflate whoever committed them |
+| Tests and docs | share of test-file changes, documents authored | test cases, coverage, or the quality of a document |
+| Surviving lines | share of lines alive at HEAD, `git blame -w -M` over a deterministic file sample, via [surviving-lines](https://github.com/Bubblegunn/surviving-lines) | merit; code deleted on purpose counts for nobody |
+
+## How verification works
+
+- The JSON carries the repository's HEAD, a **fingerprint** (sha256 of the root commit and
+  the normalised remote URL, so the repository is identified without being named), the
+  identity names used, the `surviving-lines` version, every parameter, and a **hash** of
+  the parameters and figures.
+- `workproof verify report.json` recomputes every figure in the repository you point it at
+  and prints a match table. If HEAD moved since the report, it says so and shows which
+  figures changed.
+- A hiring manager needs two things: the report and read access to the repository (or a
+  colleague inside the company who will run one command). Nothing leaves the repository.
+
+## Privacy
+
+- No code content, ever. The tool reads `git log --numstat` and `git blame`, and emits
+  counts.
+- No file paths by default. `--paths` adds directory names at the configured `--depth`
+  (default 2), never files.
+- No email addresses by default. `--emails` adds them; without it, even the `--author`
+  you typed is replaced by `(email hidden)` in the stored parameters.
+- The optional narrative (`--narrate`) sends the figures, and only the figures, to a
+  model endpoint you choose (`WORKPROOF_API_URL`, `WORKPROOF_API_KEY`, `WORKPROOF_MODEL`;
+  OpenAI-compatible or Anthropic). The paragraph is appended under
+  "Generated narrative (not verified)" and is excluded from the hash.
+
+## Options
+
+```
+workproof [options] [--repo <dir>]...
+workproof verify <report.json> [--repo <dir>]...
+
+--author <email|name>  identity to report on (repeatable; default: git config user.email)
+--repo <dir>           repository to analyse (repeatable; several produce one combined report)
+--since / --until      override the tenure window
+--sample <n>           blame every n-th file (default: 1; 7 for very large repositories)
+--depth <n>            directory depth for ownership (default: 2)
+--paths                include directory paths
+--emails               include author emails
+--narrate              append a model-written paragraph
+--out <basename>       output basename (default: workproof-report)
+--json                 print the JSON to stdout instead of writing files
+```
+
+A `.mailmap` in the repository merges an author's several addresses.
+
+## For candidates
+
+Run it in each repository you are proud of and cannot show. Put the Markdown in your
+portfolio next to the sentence you would have written anyway ("I built the frontend"),
+and let the numbers carry the sentence. Keep the JSON; it is what a reviewer verifies.
+
+## For hiring managers
+
+Ask for the JSON and for someone inside the candidate's former company to run
+`npx workproof verify` on it. The table either reproduces or it does not. If the
+repository has moved on, the tool says which figures changed and why that is expected.
+
+## For visa and immigration evidence
+
+workproof was built for a UK Global Talent application, where the strongest work was in
+private repositories and "trust me" is not evidence. A report is a measurement with its
+method attached, not an endorsement; pair it with letters from people who were there.
+
+## What it does not do
+
+It measures survivorship and activity, not quality, review, design or mentoring. It does
+not rank people. It does not replace references. It is not a legal document.
+
+## Where it comes from
+
+The method is written up in
+[How to show engineering ownership when the repositories are private](https://efe-genc-portfolio.vercel.app/writing/showing-ownership-private-repositories/).
+The blame sampling is [surviving-lines](https://github.com/Bubblegunn/surviving-lines),
+workproof's only dependency.
+
+## Development
+
+```
+npm ci
+npm test        # tsc build, then node:test over the compiled tests (fixture repositories built in a temp dir)
+```
+
+MIT.

package/dist/src/analyse.d.ts

@@ -0,0 +1,26 @@
+import type { Figure } from "./figures/types.js";
+export interface Params {
+    author?: string[];
+    since?: string;
+    until?: string;
+    sample?: number;
+    depth: number;
+    threshold: number;
+    minCommits: number;
+    paths: boolean;
+    emails: boolean;
+}
+export interface RepoReport {
+    name: string;
+    head: string;
+    fingerprint: string;
+    identity: {
+        emails: string[];
+        names: string[];
+        count: number;
+    };
+    figures: Figure<any>[];
+}
+/** sha256 of the root commit and the normalised remote: identifies a repository without naming it. */
+export declare function fingerprint(root: string, remote: string): string;
+export declare function analyseRepo(cwd: string, params: Params): Promise<RepoReport>;

package/dist/src/analyse.js

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { createRequire } from "node:module";
+import { listCommits, listTags, rootCommit, headSha, remoteUrl } from "./git.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) {
+    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 require = createRequire(import.meta.url);
+const survivingVersion = () => {
+    try {
+        return require("surviving-lines/package.json").version;
+    }
+    catch {
+        return "unknown";
+    }
+};
+export async function analyseRepo(cwd, params) {
+    const all = await listCommits(cwd, {});
+    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);
+    const tags = await listTags(cwd);
+    const sample = params.sample ?? (all.reduce((n, c) => n + c.files.length, 0) > 50000 ? 7 : 1);
+    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)" })) };
+    }
+    const figures = [
+        t,
+        commitShare(inTenure, id),
+        cadence(inTenure, tags, id, { first: t.value.first, last: t.value.last }),
+        fp,
+        testsAndDocs(inTenure, id),
+        await survivingLines(cwd, id, { sample, version: survivingVersion() }),
+    ];
+    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 },
+        figures,
+    };
+}

package/dist/src/cli.d.ts

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

package/dist/src/cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+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";
+const HELP = `usage: workproof [options] [--repo <dir>]...
+       workproof verify <report.json> [--repo <dir>]...
+
+Turn a git repository into a verifiable engineering report for one author, without showing code.
+
+  --author <email|name>  identity to report on (repeatable; default: git config user.email)
+  --repo <dir>           repository to analyse (repeatable; default: current directory)
+  --since / --until      override the tenure window (dates git understands)
+  --sample <n>           blame every n-th file (default: 1, or 7 for very large repositories)
+  --depth <n>            directory depth for ownership (default: 2)
+  --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
+  --out <basename>       output basename (default: workproof-report)
+  --json                 print the JSON to stdout instead of writing files
+  -h, --help             this text`;
+export function parse(argv) {
+    const params = { depth: 2, threshold: 0.5, minCommits: 5, paths: false, emails: false };
+    const repos = [];
+    const authors = [];
+    let out = "workproof-report";
+    let json = false;
+    let doNarrate = false;
+    let verifyFile;
+    if (argv[0] === "verify") {
+        verifyFile = argv[1];
+        if (!verifyFile)
+            throw new Error("verify needs a report.json");
+        argv = argv.slice(2);
+    }
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = () => {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Error(`${a} needs a value`);
+            return v;
+        };
+        if (a === "--author")
+            authors.push(next());
+        else if (a === "--repo")
+            repos.push(resolve(next()));
+        else if (a === "--since")
+            params.since = next();
+        else if (a === "--until")
+            params.until = next();
+        else if (a === "--sample")
+            params.sample = Number(next());
+        else if (a === "--depth")
+            params.depth = Number(next());
+        else if (a === "--paths")
+            params.paths = true;
+        else if (a === "--emails")
+            params.emails = true;
+        else if (a === "--narrate")
+            doNarrate = true;
+        else if (a === "--out")
+            out = next();
+        else if (a === "--json")
+            json = true;
+        else if (a === "-h" || a === "--help") {
+            console.log(HELP);
+            process.exit(0);
+        }
+        else
+            throw new Error(`unknown option ${a} (see --help)`);
+    }
+    if (authors.length)
+        params.author = authors;
+    if (!repos.length)
+        repos.push(process.cwd());
+    return { params, repos, out, json, doNarrate, verifyFile };
+}
+async function main() {
+    const { params, repos, out, json, doNarrate, verifyFile } = parse(process.argv.slice(2));
+    if (verifyFile) {
+        const report = JSON.parse(await readFile(verifyFile, "utf8"));
+        const result = await verifyReport(report, repos);
+        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`);
+        process.exit(result.ok ? 0 : 1);
+    }
+    const version = createRequire(import.meta.url)("../../package.json").version;
+    const repositories = [];
+    for (const dir of repos)
+        repositories.push(await analyseRepo(dir, params));
+    const report = buildReport(repositories, params, { version, generatedAt: new Date().toISOString() });
+    let narrative;
+    if (doNarrate) {
+        const url = process.env.WORKPROOF_API_URL;
+        const key = process.env.WORKPROOF_API_KEY;
+        const model = process.env.WORKPROOF_MODEL;
+        if (!url || !key || !model)
+            throw new Error("--narrate needs WORKPROOF_API_URL, WORKPROOF_API_KEY and WORKPROOF_MODEL");
+        narrative = await narrate(report, { url, key, model });
+    }
+    if (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`);
+}
+const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (entry === import.meta.url || entry.endsWith("/workproof")) {
+    main().catch((err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+}

package/dist/src/figures/cadence.d.ts

@@ -0,0 +1,15 @@
+import type { Commit, Tag } from "../git.js";
+import type { Figure, Identity } from "./types.js";
+/** ISO 8601 week key, e.g. 2026-W02. */
+export declare function isoWeek(d: Date): string;
+export declare function cadence(commits: Commit[], tags: Tag[], id: Identity, window: {
+    first: string;
+    last: string;
+}): Figure<{
+    activeWeeks: number;
+    weeksInTenure: number;
+    commitsPerActiveWeek: number;
+    longestStreakWeeks: number;
+    tagsInTenure: number;
+    authorTags: number;
+}>;

package/dist/src/figures/cadence.js

@@ -0,0 +1,59 @@
+import { isMine } from "./identity.js";
+/** ISO 8601 week key, e.g. 2026-W02. */
+export function isoWeek(d) {
+    const t = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+    const dayNum = t.getUTCDay() || 7;
+    t.setUTCDate(t.getUTCDate() + 4 - dayNum);
+    const yearStart = new Date(Date.UTC(t.getUTCFullYear(), 0, 1));
+    const week = Math.ceil(((t.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+    return `${t.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+}
+function weeksBetween(first, last) {
+    const out = [];
+    const d = new Date(first + "T00:00:00Z");
+    const end = new Date(last + "T00:00:00Z");
+    while (d <= end) {
+        const w = isoWeek(d);
+        if (out[out.length - 1] !== w)
+            out.push(w);
+        d.setUTCDate(d.getUTCDate() + 1);
+    }
+    return out;
+}
+export function cadence(commits, tags, id, window) {
+    const mine = commits.filter((c) => isMine(c, id) && c.parents <= 1);
+    const perWeek = new Map();
+    for (const c of mine)
+        perWeek.set(isoWeek(c.date), (perWeek.get(isoWeek(c.date)) ?? 0) + 1);
+    const weeks = weeksBetween(window.first, window.last);
+    let streak = 0;
+    let longest = 0;
+    for (const w of weeks) {
+        if (perWeek.has(w)) {
+            streak++;
+            longest = Math.max(longest, streak);
+        }
+        else
+            streak = 0;
+    }
+    const activeWeeks = perWeek.size;
+    const start = new Date(window.first + "T00:00:00Z");
+    const end = new Date(window.last + "T23:59:59Z");
+    const inTenure = tags.filter((t) => t.date >= start && t.date <= end);
+    const value = {
+        activeWeeks,
+        weeksInTenure: weeks.length,
+        commitsPerActiveWeek: activeWeeks ? Math.round((mine.length / activeWeeks) * 10) / 10 : 0,
+        longestStreakWeeks: longest,
+        tagsInTenure: inTenure.length,
+        authorTags: inTenure.filter((t) => id.emails.includes(t.email)).length,
+    };
+    const figure = {
+        id: "cadence",
+        title: "Cadence",
+        value,
+        command: "git log --no-merges --format=%aI --author=<identity>; ISO weeks; git for-each-ref refs/tags with creatordate",
+        limits: ["A week with one commit and a week with forty both count as active.", "Tags are releases only if the project tags releases."],
+    };
+    return figure;
+}

package/dist/src/figures/commits.d.ts

@@ -0,0 +1,15 @@
+import type { Commit } from "../git.js";
+import type { Figure, Identity } from "./types.js";
+export declare function tenure(commits: Commit[], id: Identity, override: {
+    since?: string;
+    until?: string;
+}): Figure<{
+    first: string;
+    last: string;
+    days: number;
+}>;
+export declare function commitShare(commits: Commit[], id: Identity): Figure<{
+    author: number;
+    total: number;
+    share: number;
+}>;

package/dist/src/figures/commits.js

@@ -0,0 +1,30 @@
+import { isMine } from "./identity.js";
+const day = (d) => d.toISOString().slice(0, 10);
+export function tenure(commits, id, override) {
+    const mine = commits.filter((c) => isMine(c, id)).map((c) => c.date).sort((a, b) => a.getTime() - b.getTime());
+    const first = override.since ? new Date(override.since) : mine[0];
+    const last = override.until ? new Date(override.until) : mine[mine.length - 1];
+    const days = Math.round((last.getTime() - first.getTime()) / 86400000) + 1;
+    return {
+        id: "tenure",
+        title: "Tenure window",
+        value: { first: day(first), last: day(last), days },
+        command: override.since || override.until ? "--since/--until as given" : "git log --format=%aI --author=<identity>; first and last commit dates",
+        limits: ["Tenure is measured from commits, so work before the first commit or after the last is invisible."],
+    };
+}
+export function commitShare(commits, id) {
+    const nonMerge = commits.filter((c) => c.parents <= 1);
+    const author = nonMerge.filter((c) => isMine(c, id)).length;
+    const total = nonMerge.length;
+    return {
+        id: "commitShare",
+        title: "Share of commits in tenure",
+        value: { author, total, share: total ? author / total : 0 },
+        command: "git log --no-merges --format=%aE --since=<first> --until=<last>; count by author over all",
+        limits: [
+            "Commits measure activity, not what survived. One commit can be a typo or a subsystem.",
+            "Squash-merged branches count once regardless of size.",
+        ],
+    };
+}

package/dist/src/figures/footprint.d.ts

@@ -0,0 +1,28 @@
+import type { Commit } from "../git.js";
+import type { Figure, Identity } from "./types.js";
+export declare function languageOf(path: string): string | null;
+export interface OwnedDirectory {
+    path: string;
+    author: number;
+    total: number;
+    share: number;
+}
+export declare function footprint(commits: Commit[], id: Identity, opts: {
+    depth: number;
+    threshold: number;
+    minCommits: number;
+}): Figure<{
+    filesTouched: number;
+    ownedDirectories: OwnedDirectory[];
+    languages: {
+        language: string;
+        lines: number;
+        share: number;
+    }[];
+}>;
+export declare function testsAndDocs(commits: Commit[], id: Identity): Figure<{
+    testChangesAuthor: number;
+    testChangesTotal: number;
+    testShare: number;
+    docsAuthored: number;
+}>;

package/dist/src/figures/footprint.js

@@ -0,0 +1,95 @@
+import { isMine } from "./identity.js";
+const LANG = {
+    ts: "TypeScript", tsx: "TypeScript", js: "JavaScript", jsx: "JavaScript", mjs: "JavaScript", cjs: "JavaScript",
+    py: "Python", cs: "C#", go: "Go", rs: "Rust", java: "Java", kt: "Kotlin", swift: "Swift", rb: "Ruby", php: "PHP",
+    c: "C", h: "C", cpp: "C++", hpp: "C++", css: "CSS", scss: "CSS", html: "HTML", vue: "Vue", svelte: "Svelte",
+    sql: "SQL", sh: "Shell", yml: "YAML", yaml: "YAML", json: "JSON", md: "Markdown", mdx: "Markdown", tf: "Terraform", dart: "Dart",
+};
+export function languageOf(path) {
+    const ext = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
+    return path.includes(".") ? LANG[ext] ?? null : null;
+}
+const isTest = (p) => /(^|\/)(__tests__|tests?|spec|e2e)\//i.test(p) || /\.(test|spec)\.[a-z]+$/i.test(p);
+const isDoc = (p) => /\.(md|mdx|rst)$/i.test(p);
+function dirAt(path, depth) {
+    const parts = path.split("/");
+    if (parts.length <= 1)
+        return null;
+    return parts.slice(0, Math.min(depth, parts.length - 1)).join("/");
+}
+export function footprint(commits, id, opts) {
+    const nonMerge = commits.filter((c) => c.parents <= 1);
+    const touched = new Set();
+    const dirs = new Map();
+    const langLines = new Map();
+    for (const c of nonMerge) {
+        const mine = isMine(c, id);
+        const seenDirs = new Set();
+        for (const f of c.files) {
+            if (mine) {
+                touched.add(f.path);
+                const lang = languageOf(f.path);
+                if (lang && f.added !== null)
+                    langLines.set(lang, (langLines.get(lang) ?? 0) + f.added);
+            }
+            const d = dirAt(f.path, opts.depth);
+            if (d)
+                seenDirs.add(d);
+        }
+        for (const d of seenDirs) {
+            const e = dirs.get(d) ?? { author: 0, total: 0 };
+            e.total++;
+            if (mine)
+                e.author++;
+            dirs.set(d, e);
+        }
+    }
+    const ownedDirectories = [...dirs.entries()]
+        .map(([path, e]) => ({ path, author: e.author, total: e.total, share: e.total ? e.author / e.total : 0 }))
+        .filter((d) => d.total >= opts.minCommits && d.share >= opts.threshold)
+        .sort((a, b) => b.share - a.share || b.total - a.total);
+    const totalLines = [...langLines.values()].reduce((s, n) => s + n, 0);
+    const languages = [...langLines.entries()]
+        .map(([language, lines]) => ({ language, lines, share: totalLines ? lines / totalLines : 0 }))
+        .sort((a, b) => b.lines - a.lines)
+        .slice(0, 8);
+    const value = { filesTouched: touched.size, ownedDirectories, languages };
+    const figure = {
+        id: "footprint",
+        title: "Footprint",
+        value,
+        command: `git log --no-merges --numstat -M; directories at depth ${opts.depth} where the author's commit share is at least ${Math.round(opts.threshold * 100)}% over at least ${opts.minCommits} commits; languages by lines added, extension map`,
+        limits: [
+            "Lines added include generated and vendored files unless they were excluded upstream.",
+            "A directory owned by commit count may still contain other people's surviving code; see the blame figure.",
+        ],
+    };
+    return figure;
+}
+export function testsAndDocs(commits, id) {
+    const nonMerge = commits.filter((c) => c.parents <= 1);
+    let testChangesAuthor = 0;
+    let testChangesTotal = 0;
+    const docs = new Set();
+    for (const c of nonMerge) {
+        const mine = isMine(c, id);
+        for (const f of c.files) {
+            if (isTest(f.path)) {
+                testChangesTotal++;
+                if (mine)
+                    testChangesAuthor++;
+            }
+            if (mine && isDoc(f.path))
+                docs.add(f.path);
+        }
+    }
+    const value = { testChangesAuthor, testChangesTotal, testShare: testChangesTotal ? testChangesAuthor / testChangesTotal : 0, docsAuthored: docs.size };
+    const figure = {
+        id: "testsAndDocs",
+        title: "Tests and documentation",
+        value,
+        command: "git log --no-merges --numstat; test paths match __tests__/, test/, tests/, spec/, e2e/ or *.test.* / *.spec.*; docs are .md, .mdx, .rst",
+        limits: ["Test file changes are counted, not test cases or coverage.", "A README edit and a design document count the same."],
+    };
+    return figure;
+}

package/dist/src/figures/identity.d.ts

@@ -0,0 +1,9 @@
+import type { Commit } from "../git.js";
+import type { Identity } from "./types.js";
+/**
+ * Resolve the author to report on. `author` entries match mailmapped emails or
+ * names, case-insensitively; with none given, the repository's configured
+ * user.email is used.
+ */
+export declare function resolveIdentity(commits: Commit[], author: string[] | undefined, cwd: string): Promise<Identity>;
+export declare const isMine: (c: Commit, id: Identity) => boolean;

package/dist/src/figures/identity.js

@@ -0,0 +1,23 @@
+import { configuredEmail } from "../git.js";
+/**
+ * Resolve the author to report on. `author` entries match mailmapped emails or
+ * names, case-insensitively; with none given, the repository's configured
+ * user.email is used.
+ */
+export async function resolveIdentity(commits, author, cwd) {
+    const wanted = (author && author.length ? author : [await configuredEmail(cwd)]).map((a) => a.toLowerCase()).filter(Boolean);
+    if (!wanted.length)
+        throw new Error("no author given and git config user.email is empty; pass --author");
+    const emails = new Set();
+    const names = new Set();
+    for (const c of commits) {
+        if (wanted.includes(c.email) || wanted.includes(c.name.toLowerCase())) {
+            emails.add(c.email);
+            names.add(c.name);
+        }
+    }
+    if (!emails.size)
+        throw new Error(`no commits by ${wanted.join(", ")} in this repository`);
+    return { emails: [...emails].sort(), names: [...names].sort() };
+}
+export const isMine = (c, id) => id.emails.includes(c.email);

package/dist/src/figures/surviving.d.ts

@@ -0,0 +1,12 @@
+import type { Figure, Identity } from "./types.js";
+export declare function survivingLines(cwd: string, id: Identity, opts: {
+    sample: number;
+    version: string;
+}): Promise<Figure<{
+    lines: number;
+    linesAttributed: number;
+    share: number;
+    filesSampled: number;
+    filesTotal: number;
+    sample: number;
+}>>;

package/dist/src/figures/surviving.js

@@ -0,0 +1,27 @@
+// surviving-lines ships plain ESM JavaScript without type declarations.
+// @ts-ignore
+import { analyse, parseArgs } from "surviving-lines/bin/surviving-lines.js";
+export async function survivingLines(cwd, id, opts) {
+    const result = await analyse(parseArgs(["--cwd", cwd, "--sample", String(opts.sample)]));
+    const mine = result.authors.filter((a) => id.emails.includes(a.mail));
+    const lines = mine.reduce((s, a) => s + a.lines, 0);
+    const value = {
+        lines,
+        linesAttributed: result.sample.linesAttributed,
+        share: result.sample.linesAttributed ? lines / result.sample.linesAttributed : 0,
+        filesSampled: result.sample.filesSampled,
+        filesTotal: result.sample.filesTotal,
+        sample: opts.sample,
+    };
+    const figure = {
+        id: "survivingLines",
+        title: "Surviving lines at HEAD",
+        value,
+        command: `surviving-lines ${opts.version}: git blame -w -M --line-porcelain over a deterministic 1-in-${opts.sample} file sample (FNV-1a on path)`,
+        limits: [
+            "Survivorship, not merit: code deleted on purpose counts for nobody.",
+            "Whitespace and moved lines keep their original author; copied lines do not unless --copies is used upstream.",
+        ],
+    };
+    return figure;
+}

package/dist/src/figures/types.d.ts

@@ -0,0 +1,13 @@
+export interface Figure<T> {
+    id: string;
+    title: string;
+    value: T;
+    /** The git command (or method) that produced the value, so a reader can rerun it. */
+    command: string;
+    /** What the figure cannot show. Printed under every figure. */
+    limits: string[];
+}
+export interface Identity {
+    emails: string[];
+    names: string[];
+}

package/dist/src/figures/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/git.d.ts

@@ -0,0 +1,29 @@
+export declare function git(args: string[], cwd: string): Promise<string>;
+export interface FileChange {
+    path: string;
+    added: number | null;
+    deleted: number | null;
+}
+export interface Commit {
+    sha: string;
+    email: string;
+    name: string;
+    date: Date;
+    parents: number;
+    files: FileChange[];
+}
+/** All commits reachable from HEAD, newest first, with per-file numstat. One git call. */
+export declare function listCommits(cwd: string, opts: {
+    since?: string;
+    until?: string;
+}): Promise<Commit[]>;
+export interface Tag {
+    name: string;
+    date: Date;
+    email: string;
+}
+export declare function listTags(cwd: string): Promise<Tag[]>;
+export declare const rootCommit: (cwd: string) => Promise<string>;
+export declare const headSha: (cwd: string) => Promise<string>;
+export declare function remoteUrl(cwd: string): Promise<string>;
+export declare function configuredEmail(cwd: string): Promise<string>;

package/dist/src/git.js

@@ -0,0 +1,76 @@
+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;
+}
+/** All commits reachable from HEAD, newest first, with per-file numstat. 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"];
+    if (opts.since)
+        args.push(`--since=${opts.since}`);
+    if (opts.until)
+        args.push(`--until=${opts.until}`);
+    const out = await git(args, cwd);
+    const commits = [];
+    for (const block of out.split("\x1e")) {
+        if (!block.trim())
+            continue;
+        const [header, ...rest] = block.split("\n");
+        const [sha, email, name, iso, parents] = header.split("\x1f");
+        const files = [];
+        for (const line of rest) {
+            if (!line.trim())
+                continue;
+            const [a, d, ...pathParts] = line.split("\t");
+            let path = pathParts.join("\t");
+            // rename entries look like "old => new" or "dir/{old => new}/file"
+            const brace = path.match(/^(.*)\{(.*) => (.*)\}(.*)$/);
+            if (brace)
+                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) });
+        }
+        commits.push({
+            sha: sha,
+            email: email.toLowerCase(),
+            name: name,
+            date: new Date(iso),
+            parents: parents ? parents.trim().split(" ").filter(Boolean).length : 0,
+            files,
+        });
+    }
+    return commits;
+}
+export async function listTags(cwd) {
+    const out = await git(["for-each-ref", "--format=%(refname:short)%09%(creatordate:iso-strict)%09%(taggeremail)%09%(*authoremail)%09%(authoremail)", "refs/tags"], cwd);
+    const tags = [];
+    for (const line of out.split("\n")) {
+        if (!line.trim())
+            continue;
+        const [name, iso, tagger, tagged, direct] = line.split("\t");
+        const email = (tagger || tagged || direct || "").replace(/^<|>$/g, "").toLowerCase();
+        tags.push({ name: name, date: new Date(iso), email });
+    }
+    return tags.sort((a, b) => a.date.getTime() - b.date.getTime());
+}
+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) {
+    try {
+        return (await git(["config", "--get", "remote.origin.url"], cwd)).trim();
+    }
+    catch {
+        return "";
+    }
+}
+export async function configuredEmail(cwd) {
+    try {
+        return (await git(["config", "--get", "user.email"], cwd)).trim().toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+export { analyseRepo, fingerprint } from "./analyse.js";
+export type { Params, RepoReport } from "./analyse.js";
+export { buildReport, renderMarkdown } from "./report.js";
+export type { Report } from "./report.js";
+export { verifyReport } from "./verify.js";
+export type { VerifyRow } from "./verify.js";
+export { narrate } from "./narrate.js";
+export type { Figure, Identity } from "./figures/types.js";

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export { analyseRepo, fingerprint } from "./analyse.js";
+export { buildReport, renderMarkdown } from "./report.js";
+export { verifyReport } from "./verify.js";
+export { narrate } from "./narrate.js";

package/dist/src/narrate.d.ts

@@ -0,0 +1,10 @@
+import type { Report } from "./report.js";
+/**
+ * Ask a model for one sober paragraph built only from the figures. Nothing
+ * but figure ids, titles and values leaves the machine: no paths, no code.
+ */
+export declare function narrate(report: Report, env: {
+    url: string;
+    key: string;
+    model: string;
+}, fetchImpl?: typeof fetch): Promise<string>;

package/dist/src/narrate.js

@@ -0,0 +1,27 @@
+/**
+ * Ask a model for one sober paragraph built only from the figures. Nothing
+ * but figure ids, titles and values leaves the machine: no paths, no code.
+ */
+export async function narrate(report, env, fetchImpl = fetch) {
+    const figures = report.repositories.map((r) => ({ repository: r.name, figures: r.figures.map((f) => ({ id: f.id, title: f.title, value: f.value })) }));
+    const prompt = `You are writing a short, sober paragraph for an engineering résumé. Use only the numbers below; add nothing, round nothing up, and treat "commit share" and "surviving lines" as separate things. No adjectives like "impressive". Figures:\n${JSON.stringify(figures)}`;
+    const anthropic = /anthropic\.com/.test(env.url);
+    const body = anthropic
+        ? { model: env.model, max_tokens: 400, messages: [{ role: "user", content: prompt }] }
+        : { model: env.model, messages: [{ role: "user", content: prompt }], temperature: 0.2 };
+    const headers = { "content-type": "application/json" };
+    if (anthropic) {
+        headers["x-api-key"] = env.key;
+        headers["anthropic-version"] = "2023-06-01";
+    }
+    else
+        headers.authorization = `Bearer ${env.key}`;
+    const res = await fetchImpl(env.url, { method: "POST", headers, body: JSON.stringify(body) });
+    if (!res.ok)
+        throw new Error(`narrative request failed: ${res.status} ${await res.text()}`);
+    const data = (await res.json());
+    const text = anthropic ? data.content?.[0]?.text : data.choices?.[0]?.message?.content;
+    if (typeof text !== "string")
+        throw new Error("narrative response had no text");
+    return text;
+}

package/dist/src/report.d.ts

@@ -0,0 +1,15 @@
+import type { Params, RepoReport } from "./analyse.js";
+export interface Report {
+    tool: "workproof";
+    version: string;
+    generatedAt: string;
+    params: Params;
+    repositories: RepoReport[];
+    /** sha256 of the canonical JSON of { params, repositories }. */
+    hash: string;
+}
+export declare function buildReport(repositories: RepoReport[], params: Params, meta: {
+    version: string;
+    generatedAt: string;
+}): Report;
+export declare function renderMarkdown(report: Report, narrative?: string): string;

package/dist/src/report.js

@@ -0,0 +1,68 @@
+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. */
+function publicParams(params) {
+    if (params.emails || !params.author)
+        return params;
+    return { ...params, author: params.author.map((a) => (a.includes("@") ? "(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 };
+}
+const pct = (x) => `${(x * 100).toFixed(1)}%`;
+const n = (x) => x.toLocaleString("en-US");
+function figureLines(f) {
+    const v = f.value;
+    switch (f.id) {
+        case "tenure":
+            return [`${v.first} to ${v.last} (${n(v.days)} days)`];
+        case "commitShare":
+            return [`${n(v.author)} of ${n(v.total)} non-merge commits, ${pct(v.share)}`];
+        case "cadence":
+            return [
+                `${v.activeWeeks} active weeks of ${v.weeksInTenure}, ${v.commitsPerActiveWeek} commits per active week, longest streak ${v.longestStreakWeeks} weeks`,
+                `${v.authorTags} of ${v.tagsInTenure} release tags in tenure`,
+            ];
+        case "footprint": {
+            const hidden = v.ownedDirectories.length > 0 && String(v.ownedDirectories[0].path).startsWith("(hidden");
+            return [
+                `${n(v.filesTouched)} files touched`,
+                `${v.ownedDirectories.length} directories with a commit share at or above the threshold${hidden ? " (paths hidden; run with --paths)" : ""}`,
+                ...(hidden ? [] : v.ownedDirectories.slice(0, 12).map((d) => `  ${d.path}: ${d.author} of ${d.total} commits, ${pct(d.share)}`)),
+                "languages by lines added: " + (v.languages.length ? v.languages.map((l) => `${l.language} ${pct(l.share)}`).join(", ") : "none recognised"),
+            ];
+        }
+        case "testsAndDocs":
+            return [`${n(v.testChangesAuthor)} of ${n(v.testChangesTotal)} test-file changes, ${pct(v.testShare)}`, `${n(v.docsAuthored)} documents authored`];
+        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})`];
+        default:
+            return [JSON.stringify(v)];
+    }
+}
+export function renderMarkdown(report, narrative) {
+    const out = [
+        `# Engineering report`,
+        ``,
+        `Generated by workproof ${report.version} on ${report.generatedAt}. Every figure below names the command that produced it and what it cannot show. Verify with \`npx workproof verify <this report>.json\` in the same repository.`,
+        ``,
+    ];
+    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(", ")})` : ""}`, ``);
+        for (const f of repo.figures) {
+            out.push(`### ${f.title}`, ``);
+            for (const line of figureLines(f))
+                out.push(line.startsWith("  ") ? `- ${line.trim()}` : line);
+            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.`, ``);
+    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(), ``);
+    }
+    return out.join("\n");
+}

package/dist/src/verify.d.ts

@@ -0,0 +1,14 @@
+import type { Report } from "./report.js";
+export interface VerifyRow {
+    repo: string;
+    figure: string;
+    match: boolean;
+    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<{
+    ok: boolean;
+    rows: VerifyRow[];
+    headMoved: string[];
+}>;

package/dist/src/verify.js

@@ -0,0 +1,24 @@
+import { analyseRepo } from "./analyse.js";
+import { headSha } from "./git.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) {
+    const rows = [];
+    const headMoved = [];
+    for (const [i, expected] of report.repositories.entries()) {
+        const dir = repoDirs[i] ?? repoDirs[0] ?? process.cwd();
+        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 });
+        for (const f of expected.figures) {
+            const a = actual.figures.find((x) => x.id === f.id);
+            const e = show(f.value);
+            const g = show(a?.value);
+            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 };
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "workproof",
+  "version": "0.1.0",
+  "description": "Turn a private git repository into a verifiable engineering report for one author, without showing any code.",
+  "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"],
+  "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"
+  },
+  "engines": { "node": ">=20" },
+  "keywords": ["git", "portfolio", "proof-of-work", "career", "blame", "engineering-evidence"],
+  "author": "Efe Genc",
+  "license": "MIT",
+  "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" }
+}