workproof 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,7 @@
 <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">
@@ -119,6 +121,7 @@ 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
@@ -127,7 +130,28 @@ workproof verify <report.json> [--repo <dir>]...
 --json                 print the JSON to stdout instead of writing files
 ```
 
-A `.mailmap` in the repository merges an author's several addresses.
+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.
+
+## 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

@@ -1,7 +1,7 @@
 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 { listCommits, listTags, rootCommit, headSha, remoteUrl, assertRepository } from "./git.js";
 import { resolveIdentity } from "./figures/identity.js";
 import { tenure, commitShare } from "./figures/commits.js";
 import { cadence } from "./figures/cadence.js";
@@ -22,8 +22,12 @@ const survivingVersion = () => {
         return "unknown";
     }
 };
-export async function analyseRepo(cwd, params) {
-    const all = await listCommits(cwd, {});
+export async function analyseRepo(cwd, params, hooks = {}) {
+    const say = hooks.progress ?? (() => { });
+    await assertRepository(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");
@@ -41,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/cli.js

@@ -13,6 +13,7 @@ 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)
@@ -52,6 +53,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")
@@ -78,7 +84,9 @@ export function parse(argv) {
     return { params, repos, out, json, doNarrate, verifyFile };
 }
 async function main() {
+    const started = Date.now();
     const { params, repos, out, json, doNarrate, 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 +101,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) {
@@ -110,7 +118,7 @@ async function main() {
     }
     await writeFile(`${out}.json`, JSON.stringify(report, null, 2));
     await writeFile(`${out}.md`, renderMarkdown(report, narrative));
-    console.log(`wrote ${out}.md and ${out}.json`);
+    console.log(`wrote ${out}.md and ${out}.json 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/identity.js

@@ -1,13 +1,15 @@
-import { configuredEmail } from "../git.js";
+import { configuredEmail, configuredName } 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);
+    const explicit = author && author.length ? author : [];
+    // Without --author, try the configured email, then the configured name.
+    const wanted = (explicit.length ? explicit : [await configuredEmail(cwd), await configuredName(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");
+        throw new Error(`no author given and git config has no user.email or user.name; pass --author. ${authorsHint(commits)}`);
     const emails = new Set();
     const names = new Set();
     for (const c of commits) {
@@ -17,7 +19,15 @@ export async function resolveIdentity(commits, author, cwd) {
         }
     }
     if (!emails.size)
-        throw new Error(`no commits by ${wanted.join(", ")} in this repository`);
+        throw new Error(`no commits by ${wanted.join(" or ")} in this repository. ${authorsHint(commits)}`);
     return { emails: [...emails].sort(), names: [...names].sort() };
 }
+/** The most frequent author names, so the error tells the user what to pass. */
+function authorsHint(commits) {
+    const counts = new Map();
+    for (const c of commits)
+        counts.set(c.name, (counts.get(c.name) ?? 0) + 1);
+    const top = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([name, n]) => `"${name}" (${n})`);
+    return top.length ? `Authors here: ${top.join(", ")}. Pass one with --author.` : "The repository has no commits.";
+}
 export const isMine = (c, id) => id.emails.includes(c.email);

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;
@@ -26,4 +27,7 @@ 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 configuredName(cwd: string): Promise<string>;
+/** Throws a plain sentence when the directory is not inside a git repository. */
+export declare function assertRepository(cwd: string): Promise<void>;
 export declare function configuredEmail(cwd: string): Promise<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")) {
@@ -66,6 +68,23 @@ export async function remoteUrl(cwd) {
         return "";
     }
 }
+export async function configuredName(cwd) {
+    try {
+        return (await git(["config", "--get", "user.name"], cwd)).trim();
+    }
+    catch {
+        return "";
+    }
+}
+/** Throws a plain sentence when the directory is not inside a git repository. */
+export async function assertRepository(cwd) {
+    try {
+        await git(["rev-parse", "--is-inside-work-tree"], cwd);
+    }
+    catch {
+        throw new Error(`${cwd} is not inside a git repository (use --repo to point at one)`);
+    }
+}
 export async function configuredEmail(cwd) {
     try {
         return (await git(["config", "--get", "user.email"], cwd)).trim().toLowerCase();

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workproof",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",