workproof 0.1.1 → 0.1.3

package/README.md

@@ -1,9 +1,14 @@
 <p align="center"><img src="assets/wordmark.svg" width="480" alt="workproof"></p>
 
+<p align="center">English | <a href="README.tr.md">Türkçe</a></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/npm/dm/workproof?style=flat-square&color=111111" alt="npm downloads">
+  <img src="https://img.shields.io/github/actions/workflow/status/Bubblegunn/workproof/ci.yml?style=flat-square&color=111111&label=ci" alt="ci">
+  <img src="https://img.shields.io/bundlephobia/minzip/workproof?style=flat-square&color=111111" alt="minzipped size">
   <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>
@@ -119,15 +124,91 @@ workproof verify <report.json> [--repo <dir>]...
 --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)
+--max-commits <n>      read only the newest n commits (escape hatch for enormous histories)
 --depth <n>            directory depth for ownership (default: 2)
 --paths                include directory paths
 --emails               include author emails
 --narrate              append a model-written paragraph
+--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
+--format <mode>        write markdown, json, or both (default: both); json prints to stdout
+--json                 same as --format json
+```
+
+A `.mailmap` in the repository merges an author's several addresses. Progress lines go to
+stderr while history is read and files are blamed, so a long run is visibly alive; on a
+history of hundreds of thousands of commits, `--max-commits` bounds the read and the report
+records that it did.
+
+## Badge
+
+`--badge` writes `workproof-report.badge.json` next to the report, in the
+[shields.io endpoint format](https://shields.io/badges/endpoint-badge):
+
+```json
+{ "schemaVersion": 1, "label": "workproof", "message": "70.6% surviving lines · 24.1% commits", "color": "1f3fbf" }
+```
+
+Commit it to a public repository (your portfolio, a gist) and point shields at the raw URL:
+
+```
+![workproof](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/<you>/<repo>/main/workproof-report.badge.json&style=flat-square)
+```
+
+A badge is a claim, not evidence. Keep the JSON report next to it; the report is what a
+reader verifies, the badge is only how they find it.
+
+## GitHub Action
+
+The repository ships a composite action that runs workproof on a checkout and posts one
+sticky comment on the pull request with the six figures. `fetch-depth: 0` is required, or
+the history the figures come from is missing; `author` is required because a GitHub login
+does not map reliably onto commit identities.
+
+```yaml
+name: workproof
+on:
+  pull_request:
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  report:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: Bubblegunn/workproof@main
+        with:
+          author: ada@example.com
+          sample: "1"
 ```
 
-A `.mailmap` in the repository merges an author's several addresses.
+The comment is updated in place on later pushes (it carries a marker), and the JSON report
+stays in the workspace as `workproof-report.json` for an `upload-artifact` step if you want
+the evidence kept with the run. Set `comment: "false"` to only produce the files.
+
+## Can it be gamed?
+
+Partly, and the report is built so the gaming shows.
+
+- Commit spam moves commit share and cadence, and nothing else. Surviving lines come from
+  `git blame` at HEAD, so a thousand empty commits add zero surviving lines, and the gap
+  between the two shares is printed side by side.
+- Vendoring a library inflates lines added. The languages figure and the owned-directory
+  list (with `--paths`) show where those lines landed, and a reviewer sees a directory
+  named `vendor` or `node_modules` owning most of them.
+- Rewriting history to change authorship changes the root commit or HEAD, so the
+  fingerprint and HEAD in an older report stop matching.
+- The verifier runs against the same repository. A report that does not reproduce is worse
+  than no report, which is the incentive the tool relies on.
+
+What it cannot catch: a genuinely large, low-value contribution. That is what references
+are for.
 
 ## For candidates
 

package/README.tr.md

@@ -0,0 +1,188 @@
+<p align="center"><img src="assets/wordmark.svg" width="480" alt="workproof"></p>
+
+<p align="center"><a href="README.md">English</a> | Türkçe</p>
+
+<p align="center"><em>En iyi işin özel repolarda. Yine de kanıtla.</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, bir git deposunu tek bir yazar için doğrulanabilir bir mühendislik raporuna
+çevirir; hiçbir kod göstermeden. Paylaşamadığınız depoda çalıştırırsınız. Okuyan kişi altı
+figür, her birinin arkasındaki tam komutu, her birinin neyi gösteremediğini ve bir hash alır.
+Aynı depoya sahip herkes `verify` çalıştırıp sayıların yeniden üretilip üretilmediğini görür.
+
+## 30 saniye
+
+```
+cd your-private-repo
+npx workproof
+```
+
+Bu, `workproof-report.md` (bir özgeçmişe, portfolyoya, vize başvurusuna yapıştırın) ve
+`workproof-report.json` (araçlar ve doğrulama için) dosyalarını yazar. Birinin raporunu
+kontrol etmek için:
+
+```
+npx workproof verify workproof-report.json
+```
+
+## Bir rapor neye benzer
+
+Bu, [langchain-ai/openwiki](https://github.com/langchain-ai/openwiki) deposunun `1e6d54c`
+sürümünde bir bakımcı için 5 Eylül 2026'da `--author "Colin Francis" --sample 5` ile alınan
+gerçek çıktıdır; yollar ve e-postalar gizli (varsayılanlar):
+
+```
+## 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)
+```
+
+Her figürün altında rapor iki satır daha basar: onu üreten git komutuyla `How:` ve
+`What this cannot show:`. Son bölüm `Integrity`: rapor hash'i ve depo parmak izi.
+
+İki payı birlikte okuyun. Bu kişi penceresindeki commit'lerin %24,1'ini ve hâlâ yaşayan
+satırların %70,6'sını yazmış. Bir commit sayısı onu küçük bir katkıcı olarak adlandırırdı. Bu
+boşluk, iki yönde de, bir raporun birinin işi hakkında söyleyebileceği en dürüst şeydir.
+
+## Ne ölçer
+
+Altı figürün hepsi git'ten gelir, başka hiçbir şeyden değil.
+
+| figür | ne | neyi gösteremez |
+|---|---|---|
+| Görev penceresi | yazarın ilk ve son commit'i, ya da `--since/--until` | ilk commit'ten önceki ya da sonuncudan sonraki iş |
+| Commit payı | penceredeki merge dışı commit'ler içinde yazarın merge dışı commit'leri | neyin sağ kaldığı; bir yazım hatası ile bir alt sistem aynı sayılır |
+| Tempo | aktif haftalar, aktif hafta başına commit, en uzun seri, penceredeki sürüm etiketleri ve yazarınkiler | bir commit'lik hafta ile kırk commit'lik hafta ikisi de aktif sayılır |
+| Ayak izi | dokunulan dosyalar, commit payı eşiğin üstündeki dizinler, eklenen satıra göre diller | üretilmiş ve vendored dosyalar commit'leyeni şişirir |
+| Testler ve dokümanlar | test dosyası değişikliklerinin payı, yazılan dokümanlar | test vakaları, kapsam ya da bir dokümanın kalitesi |
+| Hayatta kalan satırlar | HEAD'de yaşayan satırların payı, deterministik dosya örneği üzerinde `git blame -w -M`, [surviving-lines](https://github.com/Bubblegunn/surviving-lines) ile | liyakat; bilerek silinen kod kimseye sayılmaz |
+
+## Doğrulama nasıl çalışır
+
+- JSON deponun HEAD'ini, bir **parmak izi** (kök commit ve normalleştirilmiş remote adresinin
+  sha256'sı; depo adı verilmeden tanımlanır), kullanılan kimlik adlarını, `surviving-lines`
+  sürümünü, her parametreyi ve parametreler ile figürlerin bir **hash**'ini taşır.
+- `workproof verify report.json` her figürü gösterdiğiniz depoda yeniden hesaplar ve bir
+  eşleşme tablosu basar. HEAD rapordan beri ilerlediyse bunu söyler ve hangi figürlerin
+  değiştiğini gösterir.
+- Bir işe alım yöneticisinin iki şeye ihtiyacı vardır: rapor ve depoya okuma erişimi (ya da
+  şirket içinde tek komutu çalıştıracak bir çalışan). Depodan hiçbir şey çıkmaz.
+
+## Gizlilik
+
+- Kod içeriği, asla. Araç `git log --numstat` ve `git blame` okur ve sayılar üretir.
+- Varsayılan olarak dosya yolu yok. `--paths`, yapılandırılan `--depth` (varsayılan 2)
+  derinliğinde dizin adları ekler, dosya asla.
+- Varsayılan olarak e-posta adresi yok. `--emails` ekler; onsuz, yazdığınız `--author`
+  bile saklanan parametrelerde `(email hidden)` ile değiştirilir.
+- İsteğe bağlı anlatı (`--narrate`) figürleri, yalnızca figürleri, seçtiğiniz bir model uç
+  noktasına gönderir (`WORKPROOF_API_URL`, `WORKPROOF_API_KEY`, `WORKPROOF_MODEL`;
+  OpenAI uyumlu ya da Anthropic). Paragraf "Generated narrative (not verified)" başlığı
+  altına eklenir ve hash'in dışındadır.
+
+## Seçenekler
+
+```
+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)
+--max-commits <n>      read only the newest n commits (escape hatch for enormous histories)
+--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
+```
+
+Depodaki bir `.mailmap`, bir yazarın birden çok adresini birleştirir. Geçmiş okunurken ve
+dosyalar blame'lenirken ilerleme satırları stderr'e gider, uzun bir çalıştırma canlı
+görünür; yüz binlerce commit'lik bir geçmişte `--max-commits` okumayı sınırlar ve rapor bunu
+kaydeder.
+
+## Oyunlanabilir mi?
+
+Kısmen; rapor, oyunun görünmesi için tasarlandı.
+
+- Commit spam'i commit payını ve tempoyu oynatır, başka bir şeyi değil. Hayatta kalan satırlar
+  HEAD'deki `git blame`'den gelir; bin boş commit sıfır hayatta kalan satır ekler ve iki pay
+  yan yana basılır.
+- Bir kütüphaneyi vendor'lamak eklenen satırları şişirir. Diller figürü ve (`--paths` ile)
+  sahiplenilen dizin listesi o satırların nereye düştüğünü gösterir; inceleyen, satırların
+  çoğunu `vendor` ya da `node_modules` adlı bir dizinin sahiplendiğini görür.
+- Yazarlığı değiştirmek için geçmişi yeniden yazmak kök commit'i ya da HEAD'i değiştirir;
+  eski bir rapordaki parmak izi ve HEAD eşleşmez olur.
+- Doğrulayıcı aynı depoya karşı çalışır. Yeniden üretilemeyen bir rapor, hiç rapor
+  olmamasından kötüdür; aracın dayandığı teşvik budur.
+
+Yakalayamadığı: gerçekten büyük ama düşük değerli bir katkı. Referanslar bunun içindir.
+
+## Adaylar için
+
+Gurur duyduğunuz ve gösteremediğiniz her depoda çalıştırın. Markdown'ı portfolyonuza, zaten
+yazacağınız cümlenin ("frontend'i ben yaptım") yanına koyun ve sayılar cümleyi taşısın. JSON'u
+saklayın; inceleyenin doğruladığı odur.
+
+## İşe alanlar için
+
+JSON'u ve adayın eski şirketinden birinin üzerinde `npx workproof verify` çalıştırmasını
+isteyin. Tablo ya yeniden üretilir ya üretilmez. Depo ilerlediyse araç hangi figürlerin
+değiştiğini ve bunun neden beklendiğini söyler.
+
+## Vize ve göç kanıtı için
+
+workproof, en güçlü işin özel depolarda olduğu ve "bana güven"in kanıt sayılmadığı bir
+Birleşik Krallık Global Talent başvurusu için yapıldı. Bir rapor, yöntemi ekli bir ölçümdür,
+bir tavsiye değil; orada bulunmuş insanların mektuplarıyla birlikte kullanın.
+
+## Bunu yapmaz
+
+Hayatta kalmayı ve etkinliği ölçer; kaliteyi, incelemeyi, tasarımı ya da mentorluğu değil.
+İnsanları sıralamaz. Referansların yerine geçmez. Hukuki bir belge değildir.
+
+## Nereden geliyor
+
+Yöntem
+[How to show engineering ownership when the repositories are private](https://efe-genc-portfolio.vercel.app/writing/showing-ownership-private-repositories/)
+yazısında anlatılıyor. Blame örneklemesi workproof'un tek bağımlılığı olan
+[surviving-lines](https://github.com/Bubblegunn/surviving-lines) paketidir.
+
+## Geliştirme
+
+```
+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

@@ -9,6 +9,12 @@ export interface Params {
     minCommits: number;
     paths: boolean;
     emails: boolean;
+    /** Escape hatch for enormous histories: read only the newest n commits. */
+    maxCommits?: number;
+}
+export interface AnalyseHooks {
+    /** Called with short status lines while history is read and files are blamed. */
+    progress?: (message: string) => void;
 }
 export interface RepoReport {
     name: string;
@@ -23,4 +29,4 @@ export interface RepoReport {
 }
 /** 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>;
+export declare function analyseRepo(cwd: string, params: Params, hooks?: AnalyseHooks): Promise<RepoReport>;

package/dist/src/analyse.js

@@ -22,9 +22,12 @@ const survivingVersion = () => {
         return "unknown";
     }
 };
-export async function analyseRepo(cwd, params) {
+export async function analyseRepo(cwd, params, hooks = {}) {
+    const say = hooks.progress ?? (() => { });
     await assertRepository(cwd);
-    const all = await listCommits(cwd, {});
+    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 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");
@@ -42,8 +45,11 @@ export async function analyseRepo(cwd, params) {
         cadence(inTenure, tags, id, { first: t.value.first, last: t.value.last }),
         fp,
         testsAndDocs(inTenure, id),
-        await survivingLines(cwd, id, { sample, version: survivingVersion() }),
     ];
+    say(`${basename(cwd)}: blaming files (1 in ${sample} sample)...`);
+    const surviving = await survivingLines(cwd, id, { sample, version: survivingVersion() });
+    say(`${basename(cwd)}: blamed ${surviving.value.filesSampled} of ${surviving.value.filesTotal} files`);
+    figures.push(surviving);
     return {
         name: basename(cwd),
         head: await headSha(cwd),

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 commits = repo.figures.find((f) => f.id === "commitShare");
+    if (!surviving || !commits)
+        throw new Error("the report has no surviving-lines or commit-share figure");
+    return {
+        schemaVersion: 1,
+        label: "workproof",
+        message: `${pct(surviving.value.share)} surviving lines · ${pct(commits.value.share)} commits`,
+        color: "1f3fbf",
+    };
+}

package/dist/src/cli.d.ts

@@ -1,11 +1,14 @@
 #!/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;
 }
 export declare function parse(argv: string[]): Cli;

package/dist/src/cli.js

@@ -3,7 +3,7 @@ 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, narrate, badgeFor } from "./index.js";
 const HELP = `usage: workproof [options] [--repo <dir>]...
        workproof verify <report.json> [--repo <dir>]...
 
@@ -13,20 +13,25 @@ Turn a git repository into a verifiable engineering report for one author, witho
   --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)
+  --max-commits <n>      read only the newest n commits (escape hatch for enormous histories)
   --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
+  --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
+  --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`;
 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 format = "both";
     let json = false;
     let doNarrate = false;
+    let badge = false;
     let verifyFile;
     if (argv[0] === "verify") {
         verifyFile = argv[1];
@@ -52,6 +57,11 @@ export function parse(argv) {
             params.until = next();
         else if (a === "--sample")
             params.sample = Number(next());
+        else if (a === "--max-commits") {
+            params.maxCommits = Number(next());
+            if (!Number.isInteger(params.maxCommits) || params.maxCommits < 1)
+                throw new Error("--max-commits must be an integer >= 1");
+        }
         else if (a === "--depth")
             params.depth = Number(next());
         else if (a === "--paths")
@@ -60,10 +70,20 @@ export function parse(argv) {
             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);
@@ -75,10 +95,12 @@ 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 };
 }
 async function main() {
-    const { params, repos, out, json, doNarrate, verifyFile } = parse(process.argv.slice(2));
+    const started = Date.now();
+    const { params, repos, out, format, json, doNarrate, badge, verifyFile } = parse(process.argv.slice(2));
+    const progress = (m) => process.stderr.write(`${m}\n`);
     if (verifyFile) {
         const report = JSON.parse(await readFile(verifyFile, "utf8"));
         const result = await verifyReport(report, repos);
@@ -93,7 +115,7 @@ async function main() {
     const version = createRequire(import.meta.url)("../../package.json").version;
     const repositories = [];
     for (const dir of repos)
-        repositories.push(await analyseRepo(dir, params));
+        repositories.push(await analyseRepo(dir, params, { progress }));
     const report = buildReport(repositories, params, { version, generatedAt: new Date().toISOString() });
     let narrative;
     if (doNarrate) {
@@ -104,13 +126,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`);
+    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/figures/footprint.js

@@ -2,7 +2,8 @@ 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",
+    c: "C", h: "C", cpp: "C++", hpp: "C++", ex: "Elixir", exs: "Elixir", scala: "Scala", sc: "Scala", hs: "Haskell", lhs: "Haskell", lua: "Lua", r: "R", m: "Objective-C", mm: "Objective-C", zig: "Zig",
+    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) {

package/dist/src/git.d.ts

@@ -16,6 +16,7 @@ export interface Commit {
 export declare function listCommits(cwd: string, opts: {
     since?: string;
     until?: string;
+    max?: number;
 }): Promise<Commit[]>;
 export interface Tag {
     name: string;

package/dist/src/git.js

@@ -12,6 +12,8 @@ export async function listCommits(cwd, opts) {
         args.push(`--since=${opts.since}`);
     if (opts.until)
         args.push(`--until=${opts.until}`);
+    if (opts.max)
+        args.push(`--max-count=${opts.max}`);
     const out = await git(args, cwd);
     const commits = [];
     for (const block of out.split("\x1e")) {

package/dist/src/index.d.ts

@@ -1,8 +1,10 @@
 export { analyseRepo, fingerprint } from "./analyse.js";
-export type { Params, RepoReport } from "./analyse.js";
+export type { Params, RepoReport, AnalyseHooks } 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";
+export { badgeFor } from "./badge.js";
+export type { Badge } from "./badge.js";

package/dist/src/index.js

@@ -2,3 +2,4 @@ export { analyseRepo, fingerprint } from "./analyse.js";
 export { buildReport, renderMarkdown } from "./report.js";
 export { verifyReport } from "./verify.js";
 export { narrate } from "./narrate.js";
+export { badgeFor } from "./badge.js";

package/package.json

@@ -1,25 +1,56 @@
 {
   "name": "workproof",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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"],
+  "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"
+    "prepublishOnly": "npm test",
+    "examples": "npm run build && node examples/basic.mjs"
+  },
+  "engines": {
+    "node": ">=20"
   },
-  "engines": { "node": ">=20" },
-  "keywords": ["git", "portfolio", "proof-of-work", "career", "blame", "engineering-evidence"],
+  "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" },
+  "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" }
+  "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"
+  }
 }