workproof 0.1.2 → 0.2.0

package/dist/src/exclusions.js

@@ -0,0 +1,80 @@
+/**
+ * What leaves every denominator before a figure is computed.
+ *
+ * Bots are recognised by the two patterns GitHub uses for app identities, nothing
+ * cleverer: a name ending in "[bot]" or the "<id>+<name>[bot]@users.noreply.github.com"
+ * address. Generated, vendored, lock and snapshot files follow the subset of
+ * github-linguist's generated.rb and vendor.yml that moves line counts, plus whatever a
+ * repository marks with linguist-generated or linguist-vendored in .gitattributes.
+ */
+export const isBot = (c) => /\[bot\]$/.test(c.name) || /^\d+\+.*\[bot\]@users\.noreply\.github\.com$/i.test(c.email);
+const LOCK_FILES = new Set([
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "bun.lockb",
+    "bun.lock",
+    "cargo.lock",
+    "poetry.lock",
+    "uv.lock",
+    "pdm.lock",
+    "pipfile.lock",
+    "gemfile.lock",
+    "composer.lock",
+    "go.sum",
+    "packages.lock.json",
+    "flake.lock",
+    "mix.lock",
+    "pubspec.lock",
+    "gradle.lockfile",
+    "podfile.lock",
+    "deno.lock",
+]);
+const VENDORED_DIRS = /(^|\/)(vendor|vendors|node_modules|third_party|third-party|thirdparty|bower_components|jspm_packages|pods|\.yarn|\.pnp|extern|externals|deps)\//i;
+const GENERATED_PATTERNS = [
+    /(^|\/)__snapshots__\//,
+    /\.snap$/,
+    /\.min\.(js|css|mjs|cjs)$/,
+    /\.(js|css|mjs|cjs)\.map$/,
+    /\.pb\.(go|ts|js|cc|h|swift|rb|py)$/,
+    /_pb2(_grpc)?\.py$/,
+    /\.pb\.dart$/,
+    /\.g\.(dart|cs)$/,
+    /\.generated\.[a-z0-9]+$/i,
+    /\.designer\.cs$/i,
+    /(^|\/)generated\//i,
+    /(^|\/)__generated__\//,
+    /(^|\/)dist\//,
+    /(^|\/)build\/.*\.(js|css)$/,
+    /(^|\/)swagger\.(json|yaml|yml)$/i,
+    /(^|\/)openapi\.(json|yaml|yml)$/i,
+    /\.xcodeproj\//,
+    /\.nib$/,
+    /\.xib$/,
+    /\.storyboard$/,
+    /(^|\/)Godeps\//,
+    /(^|\/)Pipfile\.lock$/,
+];
+/** True for paths the built-in lists treat as generated, vendored, lock or snapshot files. */
+export function isExcludedPath(path) {
+    const base = path.slice(path.lastIndexOf("/") + 1).toLowerCase();
+    if (LOCK_FILES.has(base))
+        return true;
+    if (VENDORED_DIRS.test(path))
+        return true;
+    return GENERATED_PATTERNS.some((re) => re.test(path));
+}
+/**
+ * The set of paths to drop, from the built-in lists, the repository's .gitattributes,
+ * and the user's --exclude globs (already compiled to RegExp).
+ */
+export function excludedSet(paths, attrs, extra) {
+    const out = new Set();
+    for (const p of paths) {
+        const a = attrs.get(p);
+        if (isExcludedPath(p) || a?.generated || a?.vendored || extra.some((re) => re.test(p)))
+            out.add(p);
+    }
+    return out;
+}

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

@@ -0,0 +1,53 @@
+import type { Commit } from "../git.js";
+import type { Figure, Identity } from "./types.js";
+/** Avelino et al. 2016, "A novel approach for estimating truck factors": degree of authorship. */
+export declare const degreeOfAuthorship: (fa: 0 | 1, dl: number, ac: number) => number;
+export declare const DOA_MIN = 3.293;
+export declare const DOA_NORMALISED_MIN = 0.75;
+/**
+ * Files alive at HEAD whose degree of authorship for the subject is at least 0.75 of the
+ * file's maximum and at least 3.293 in absolute terms. Renames carry their history along.
+ */
+export declare function filesAuthored(commits: Commit[], id: Identity, headFiles: Set<string>): Figure<{
+    authored: number;
+    total: number;
+    share: number;
+}>;
+export declare const MAJOR_THRESHOLD = 0.05;
+/** Bird et al. 2011, "Don't touch my code": directories where the subject's commit share is at least 5%. */
+export declare function majorContributor(commits: Commit[], id: Identity, depth: number): Figure<{
+    major: number;
+    dirs: number;
+    threshold: number;
+}>;
+export declare const HUGE_COMMIT = 10000;
+/** Added plus deleted lines per non-merge commit by the subject, after exclusions. */
+export declare function commitSize(commits: Commit[], id: Identity): Figure<{
+    median: number;
+    p90: number;
+    huge: number;
+}>;
+/** Commits by someone else that name the subject in a Co-authored-by trailer. */
+export declare function coAuthored(commits: Commit[], id: Identity): Figure<{
+    trailerCommits: number;
+}>;
+/** CHAOSS Contributor Absence Factor: the smallest set of authors covering half the commits. */
+export declare function absenceFactor(commits: Commit[], id: Identity): Figure<{
+    authorsToHalf: number;
+    authorRank: number;
+    authors: number;
+}>;
+export declare const AI_TOOLS: RegExp;
+/** Subject commits whose trailers or author name declare an AI tool. */
+export declare function aiAssisted(commits: Commit[], id: Identity): Figure<{
+    commits: number;
+    share: number;
+}>;
+/** The subject's surviving lines by the year of the commit that last touched them, from the same blame pass. */
+export declare function survivalByCohort(byYear: {
+    year: number;
+    lines: number;
+}[], sample: number): Figure<{
+    year: number;
+    lines: number;
+}[]>;

package/dist/src/figures/authorship.js

@@ -0,0 +1,190 @@
+import { isMine } from "./identity.js";
+/**
+ * Figures about who owns what, each with its bias stated in limits. Bots and excluded
+ * files have already left the commit lists these functions receive.
+ */
+const nonMerge = (commits) => commits.filter((c) => c.parents <= 1);
+const oldestFirst = (commits) => [...commits].sort((a, b) => a.date.getTime() - b.date.getTime());
+/** Avelino et al. 2016, "A novel approach for estimating truck factors": degree of authorship. */
+export const degreeOfAuthorship = (fa, dl, ac) => 3.293 + 1.098 * fa + 0.164 * dl - 0.321 * Math.log(1 + ac);
+export const DOA_MIN = 3.293;
+export const DOA_NORMALISED_MIN = 0.75;
+/**
+ * Files alive at HEAD whose degree of authorship for the subject is at least 0.75 of the
+ * file's maximum and at least 3.293 in absolute terms. Renames carry their history along.
+ */
+export function filesAuthored(commits, id, headFiles) {
+    // path -> author email -> contribution; bots and excluded paths are already gone.
+    const files = new Map();
+    for (const c of oldestFirst(nonMerge(commits))) {
+        for (const f of c.files) {
+            let authors = files.get(f.path);
+            if (f.from && files.has(f.from) && !authors) {
+                authors = new Map([...files.get(f.from)].map(([email, v]) => [email, { ...v }]));
+                files.set(f.path, authors);
+            }
+            if (!authors) {
+                authors = new Map();
+                files.set(f.path, authors);
+            }
+            const entry = authors.get(c.email) ?? { first: authors.size === 0 && [...authors.values()].every((v) => !v.first), later: 0 };
+            if (authors.has(c.email))
+                entry.later++;
+            authors.set(c.email, entry);
+        }
+    }
+    let authored = 0;
+    for (const path of headFiles) {
+        const authors = files.get(path);
+        if (!authors)
+            continue;
+        const total = [...authors.values()].reduce((s, v) => s + (v.first ? 1 : 0) + v.later, 0);
+        const doaOf = (email) => {
+            const v = authors.get(email);
+            if (!v)
+                return 0;
+            const own = (v.first ? 1 : 0) + v.later;
+            return degreeOfAuthorship(v.first ? 1 : 0, v.later, total - own);
+        };
+        const max = Math.max(...[...authors.keys()].map(doaOf));
+        const mine = Math.max(...id.emails.map(doaOf));
+        if (mine >= DOA_MIN && max > 0 && mine / max > DOA_NORMALISED_MIN)
+            authored++;
+    }
+    const value = { authored, total: headFiles.size, share: headFiles.size ? authored / headFiles.size : 0 };
+    const figure = {
+        id: "filesAuthored",
+        title: "Files authored",
+        value,
+        command: "git log --no-merges --numstat -M over the history read; DOA = 3.293 + 1.098*FA + 0.164*DL - 0.321*ln(1 + AC) per file and author (Avelino et al.); authored when DOA is at least 3.293 and above 75% of the file's maximum; over files alive at HEAD",
+        limits: [
+            "The coefficients were fitted on other systems; first authorship outweighs later rewrites, so a file rewritten from scratch by someone else can stay with its creator.",
+            "A file that was renamed carries its history only when git detected the rename.",
+        ],
+    };
+    return figure;
+}
+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 const MAJOR_THRESHOLD = 0.05;
+/** Bird et al. 2011, "Don't touch my code": directories where the subject's commit share is at least 5%. */
+export function majorContributor(commits, id, depth) {
+    const dirs = new Map();
+    for (const c of nonMerge(commits)) {
+        const seen = new Set();
+        for (const f of c.files) {
+            const d = dirAt(f.path, depth);
+            if (d)
+                seen.add(d);
+        }
+        for (const d of seen) {
+            const e = dirs.get(d) ?? { author: 0, total: 0 };
+            e.total++;
+            if (isMine(c, id))
+                e.author++;
+            dirs.set(d, e);
+        }
+    }
+    const major = [...dirs.values()].filter((e) => e.total && e.author / e.total >= MAJOR_THRESHOLD).length;
+    const value = { major, dirs: dirs.size, threshold: MAJOR_THRESHOLD };
+    const figure = {
+        id: "majorContributor",
+        title: "Major-contributor components",
+        value,
+        command: `git log --no-merges --numstat; directories at depth ${depth} where the author's share of commits touching them is at least ${MAJOR_THRESHOLD * 100}% (Bird et al.)`,
+        limits: ["Commit exposure treats a typo and a subsystem alike; five percent of the commits to a directory is a low bar by design."],
+    };
+    return figure;
+}
+const rank = (sorted, p) => (sorted.length ? sorted[Math.max(0, Math.ceil(p * sorted.length) - 1)] : 0);
+export const HUGE_COMMIT = 10000;
+/** Added plus deleted lines per non-merge commit by the subject, after exclusions. */
+export function commitSize(commits, id) {
+    const sizes = nonMerge(commits)
+        .filter((c) => isMine(c, id))
+        .map((c) => c.files.reduce((s, f) => s + (f.added ?? 0) + (f.deleted ?? 0), 0))
+        .sort((a, b) => a - b);
+    const value = { median: rank(sizes, 0.5), p90: rank(sizes, 0.9), huge: sizes.filter((s) => s > HUGE_COMMIT).length };
+    const figure = {
+        id: "commitSize",
+        title: "Commit size",
+        value,
+        command: `git log --no-merges --numstat --author=<identity>; added plus deleted lines per commit over included files; median and 90th percentile by nearest rank; huge counts commits over ${HUGE_COMMIT.toLocaleString("en-US")} lines`,
+        limits: ["Size is not value. Imports, vendoring that slipped past the exclusions and reformat commits dominate the 90th percentile."],
+    };
+    return figure;
+}
+/** Commits by someone else that name the subject in a Co-authored-by trailer. */
+export function coAuthored(commits, id) {
+    const trailerCommits = nonMerge(commits).filter((c) => !isMine(c, id) && c.coAuthors.some((e) => id.emails.includes(e))).length;
+    const value = { trailerCommits };
+    const figure = {
+        id: "coAuthored",
+        title: "Co-authored commits",
+        value,
+        command: "git log --no-merges --format=%(trailers:key=Co-authored-by); commits by another author whose trailer names one of the subject's emails",
+        limits: ["Trailers are written by whoever merges and can be absent or wrong; pairing without a trailer is invisible."],
+    };
+    return figure;
+}
+/** CHAOSS Contributor Absence Factor: the smallest set of authors covering half the commits. */
+export function absenceFactor(commits, id) {
+    const counts = new Map();
+    for (const c of nonMerge(commits)) {
+        const key = isMine(c, id) ? "\0subject" : c.email;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    const total = sorted.reduce((s, [, n]) => s + n, 0);
+    let covered = 0;
+    let authorsToHalf = 0;
+    for (const [, n] of sorted) {
+        if (covered >= total / 2)
+            break;
+        covered += n;
+        authorsToHalf++;
+    }
+    const value = { authorsToHalf, authorRank: sorted.findIndex(([k]) => k === "\0subject") + 1, authors: sorted.length };
+    const figure = {
+        id: "absenceFactor",
+        title: "Absence factor",
+        value,
+        command: "git log --no-merges --format=%aE; authors sorted by commit count; the smallest set covering 50% of commits (CHAOSS Contributor Absence Factor); the subject's rank by commit count",
+        limits: ["An author with several unmerged email addresses counts as several people; drive-by commits count as authors."],
+    };
+    return figure;
+}
+export const AI_TOOLS = /claude|cursor|copilot|codex|gemini|chatgpt|aider|devin|windsurf/i;
+/** Subject commits whose trailers or author name declare an AI tool. */
+export function aiAssisted(commits, id) {
+    const mine = nonMerge(commits).filter((c) => isMine(c, id));
+    const assisted = mine.filter((c) => c.coAuthorNames.some((n) => AI_TOOLS.test(n)) || c.assistedBy.some((a) => AI_TOOLS.test(a)) || /\(aider\)$/i.test(c.name)).length;
+    const value = { commits: assisted, share: mine.length ? assisted / mine.length : 0 };
+    const figure = {
+        id: "aiAssisted",
+        title: "AI-assisted commits",
+        value,
+        command: "git log --no-merges --format=%aN%(trailers:key=Co-authored-by)%(trailers:key=Assisted-by) --author=<identity>; commits naming Claude, Cursor, Copilot, Codex, Gemini, ChatGPT, Aider, Devin or Windsurf in a trailer, or an author name ending in (aider)",
+        limits: [
+            "The absence of a trailer is not evidence of unassisted work.",
+            "Blame credits the human for every line, so surviving lines say nothing about who typed them; authorship no longer implies comprehension.",
+            "These commits are never excluded from any other figure.",
+        ],
+    };
+    return figure;
+}
+/** The subject's surviving lines by the year of the commit that last touched them, from the same blame pass. */
+export function survivalByCohort(byYear, sample) {
+    const figure = {
+        id: "survivalByCohort",
+        title: "Survival by cohort",
+        value: byYear,
+        command: `the same git blame --line-porcelain pass as the surviving-lines figure (1-in-${sample} sample); the subject's lines bucketed by author-time year`,
+        limits: ["Newer cohorts have had less time to die; comments and licence headers survive indefinitely."],
+    };
+    return figure;
+}

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

@@ -20,9 +20,13 @@ export declare function footprint(commits: Commit[], id: Identity, opts: {
         share: number;
     }[];
 }>;
+/**
+ * Test-file changes by the author over all, and documents the author created: Markdown,
+ * MDX and RST files whose oldest commit in the history read is the author's.
+ */
 export declare function testsAndDocs(commits: Commit[], id: Identity): Figure<{
     testChangesAuthor: number;
     testChangesTotal: number;
     testShare: number;
-    docsAuthored: number;
+    docsCreated: number;
 }>;

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) {
@@ -60,18 +61,22 @@ export function footprint(commits, id, opts) {
         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.",
+            "Generated, vendored, lock and snapshot files are excluded by the built-in lists and .gitattributes; anything they miss still counts.",
             "A directory owned by commit count may still contain other people's surviving code; see the blame figure.",
         ],
     };
     return figure;
 }
+/**
+ * Test-file changes by the author over all, and documents the author created: Markdown,
+ * MDX and RST files whose oldest commit in the history read is the author's.
+ */
 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 firstTouch = new Map();
+    for (const c of [...nonMerge].sort((a, b) => a.date.getTime() - b.date.getTime())) {
         const mine = isMine(c, id);
         for (const f of c.files) {
             if (isTest(f.path)) {
@@ -79,17 +84,18 @@ export function testsAndDocs(commits, id) {
                 if (mine)
                     testChangesAuthor++;
             }
-            if (mine && isDoc(f.path))
-                docs.add(f.path);
+            if (isDoc(f.path) && !firstTouch.has(f.path))
+                firstTouch.set(f.path, mine);
         }
     }
-    const value = { testChangesAuthor, testChangesTotal, testShare: testChangesTotal ? testChangesAuthor / testChangesTotal : 0, docsAuthored: docs.size };
+    const docsCreated = [...firstTouch.values()].filter(Boolean).length;
+    const value = { testChangesAuthor, testChangesTotal, testShare: testChangesTotal ? testChangesAuthor / testChangesTotal : 0, docsCreated };
     const figure = {
         id: "testsAndDocs",
-        title: "Tests and documentation",
+        title: "Test-file changes and documents created",
         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."],
+        command: "git log --no-merges --numstat; test paths match __tests__/, test/, tests/, spec/, e2e/ or *.test.* / *.spec.*; a document (.md, .mdx, .rst) is created by whoever made its oldest commit in the history read",
+        limits: ["Test-file changes are counted, not test cases or coverage.", "A one-line README and a design document count the same; a document rewritten by someone else stays with its creator."],
     };
     return figure;
 }

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

@@ -1,12 +1,48 @@
 import type { Figure, Identity } from "./types.js";
-export declare function survivingLines(cwd: string, id: Identity, opts: {
+export interface SurvivingOptions {
     sample: number;
+    seed: string;
+    /** Globs with surviving-lines semantics (a pattern without a slash also matches the basename). */
+    exclude: string[];
+    copies: boolean;
+    /** As recorded in the report: ".git-blame-ignore-revs" for the root file, or the path given. */
+    ignoreRevsFile: string | null;
+    /** Paths already dropped by the exclusion rules. */
+    excluded: Set<string>;
     version: string;
-}): Promise<Figure<{
+    jobs?: number;
+}
+/** The blame flags a report records under environment.blame, in the order git receives them. */
+export declare function blameFlags(copies: boolean, ignoreRevsFile: string | null): string[];
+/** The empty tree's id under this repository's hash algorithm, without touching /dev/null. */
+export declare const emptyTreeId: (cwd: string) => Promise<string>;
+/** Text files at HEAD with their line counts, in one git call; binaries come back as "-" and are skipped. */
+export declare function listTextFiles(cwd: string): Promise<{
+    path: string;
+    lines: number;
+}[]>;
+interface BlameLine {
+    mail: string;
+    year: number;
+}
+/** One entry per surviving line: the author email and the year of the blamed commit. */
+export declare function parseBlame(porcelain: string): BlameLine[];
+/**
+ * One blame pass over a deterministic sample of the included text files. Every line is
+ * attributed once; the subject's lines are also bucketed by the year of the commit that
+ * last touched them, which is what survivalByCohort reports.
+ */
+export declare function survivingLines(cwd: string, id: Identity, opts: SurvivingOptions): Promise<Figure<{
     lines: number;
     linesAttributed: number;
     share: number;
     filesSampled: number;
     filesTotal: number;
     sample: number;
+    seed: string;
+    byYear: {
+        year: number;
+        lines: number;
+    }[];
 }>>;
+export {};

package/dist/src/figures/surviving.js

@@ -1,26 +1,97 @@
+import { isAbsolute, join } from "node:path";
+import { git } from "../git.js";
 // surviving-lines ships plain ESM JavaScript without type declarations.
 // @ts-ignore
-import { analyse, parseArgs } from "surviving-lines/bin/surviving-lines.js";
+import { globToRegExp, inSample } from "surviving-lines/bin/surviving-lines.js";
+/** The blame flags a report records under environment.blame, in the order git receives them. */
+export function blameFlags(copies, ignoreRevsFile) {
+    return ["-w", "-M", ...(copies ? ["-C"] : []), ...(ignoreRevsFile ? [`--ignore-revs-file ${ignoreRevsFile}`] : [])];
+}
+/** The empty tree's id under this repository's hash algorithm, without touching /dev/null. */
+export const emptyTreeId = async (cwd) => (await git(["hash-object", "-t", "tree", "--stdin"], cwd, "")).trim();
+/** Text files at HEAD with their line counts, in one git call; binaries come back as "-" and are skipped. */
+export async function listTextFiles(cwd) {
+    const out = await git(["diff", "--numstat", "-z", await emptyTreeId(cwd), "HEAD"], cwd);
+    const files = [];
+    for (const rec of out.split("\0")) {
+        if (!rec)
+            continue;
+        const [added, , path] = rec.split("\t");
+        if (added === "-" || path === undefined)
+            continue;
+        files.push({ path, lines: Number(added) });
+    }
+    return files;
+}
+/** One entry per surviving line: the author email and the year of the blamed commit. */
+export function parseBlame(porcelain) {
+    const lines = [];
+    let mail = "";
+    let year = 0;
+    for (const line of porcelain.split("\n")) {
+        if (line.startsWith("author-mail "))
+            mail = line.slice(12).replace(/^<|>$/g, "").toLowerCase();
+        else if (line.startsWith("author-time "))
+            year = new Date(Number(line.slice(12)) * 1000).getUTCFullYear();
+        else if (line.startsWith("\t"))
+            lines.push({ mail, year });
+    }
+    return lines;
+}
+/**
+ * One blame pass over a deterministic sample of the included text files. Every line is
+ * attributed once; the subject's lines are also bucketed by the year of the commit that
+ * last touched them, which is what survivalByCohort reports.
+ */
 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 excludeRe = opts.exclude.map((g) => globToRegExp(g));
+    const excludeBare = opts.exclude.map((g) => !g.includes("/"));
+    const dropped = (path) => {
+        if (opts.excluded.has(path))
+            return true;
+        const base = path.slice(path.lastIndexOf("/") + 1);
+        return excludeRe.some((re, i) => re.test(path) || (excludeBare[i] && re.test(base)));
+    };
+    const all = (await listTextFiles(cwd)).filter((f) => !dropped(f.path));
+    const sampled = all.filter((f) => inSample(f.path, opts.sample, opts.seed));
+    const ignoreRevs = opts.ignoreRevsFile === null ? null : isAbsolute(opts.ignoreRevsFile) ? opts.ignoreRevsFile : join(cwd, opts.ignoreRevsFile);
+    const args = ["blame", "--line-porcelain", "-w", "-M", ...(opts.copies ? ["-C"] : []), ...(ignoreRevs ? ["--ignore-revs-file", ignoreRevs] : []), "HEAD", "--"];
+    let attributed = 0;
+    let mine = 0;
+    const byYear = new Map();
+    let cursor = 0;
+    const worker = async () => {
+        while (cursor < sampled.length) {
+            const file = sampled[cursor++];
+            for (const line of parseBlame(await git([...args, file.path], cwd))) {
+                attributed++;
+                if (id.emails.includes(line.mail)) {
+                    mine++;
+                    byYear.set(line.year, (byYear.get(line.year) ?? 0) + 1);
+                }
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(opts.jobs ?? 4, sampled.length || 1) }, worker));
     const value = {
-        lines,
-        linesAttributed: result.sample.linesAttributed,
-        share: result.sample.linesAttributed ? lines / result.sample.linesAttributed : 0,
-        filesSampled: result.sample.filesSampled,
-        filesTotal: result.sample.filesTotal,
+        lines: mine,
+        linesAttributed: attributed,
+        share: attributed ? mine / attributed : 0,
+        filesSampled: sampled.length,
+        filesTotal: all.length,
         sample: opts.sample,
+        seed: opts.seed,
+        byYear: [...byYear.entries()].sort((a, b) => a[0] - b[0]).map(([year, lines]) => ({ year, lines })),
     };
     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)`,
+        command: `git blame --line-porcelain ${blameFlags(opts.copies, opts.ignoreRevsFile).join(" ")} HEAD -- <file> over a deterministic 1-in-${opts.sample} file sample (surviving-lines ${opts.version}: FNV-1a on path${opts.seed ? ` with seed "${opts.seed}"` : ""}); generated, vendored and lock files excluded`,
         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.",
+            "Whitespace and moved lines keep their original author; copied lines do not unless --copies is used.",
+            opts.ignoreRevsFile ? `Commits listed in ${opts.ignoreRevsFile} are skipped, so a reformat does not take the lines it touched.` : "A reformat commit takes every line it touched; list such commits in .git-blame-ignore-revs.",
         ],
     };
     return figure;

package/dist/src/git.d.ts

@@ -1,8 +1,17 @@
-export declare function git(args: string[], cwd: string): Promise<string>;
+/**
+ * Settings that change what diff and blame attribute, pinned so two machines with different
+ * defaults produce the same figures. indentHeuristic became the default in git 2.14 and
+ * rename detection in 2.9; a report records the git version it ran under as well.
+ */
+export declare const PINNED_CONFIG: string[];
+export declare function git(args: string[], cwd: string, input?: string): Promise<string>;
+export declare const gitVersion: (cwd: string) => Promise<string>;
 export interface FileChange {
     path: string;
     added: number | null;
     deleted: number | null;
+    /** The previous path when git detected a rename in this commit. */
+    from?: string;
 }
 export interface Commit {
     sha: string;
@@ -11,8 +20,14 @@ export interface Commit {
     date: Date;
     parents: number;
     files: FileChange[];
+    /** Lower-cased emails from Co-authored-by trailers. */
+    coAuthors: string[];
+    /** Names from Co-authored-by trailers, as written. */
+    coAuthorNames: string[];
+    /** Values of Assisted-by trailers, as written. */
+    assistedBy: string[];
 }
-/** All commits reachable from HEAD, newest first, with per-file numstat. One git call. */
+/** All commits reachable from HEAD, newest first, with per-file numstat and trailers. One git call. */
 export declare function listCommits(cwd: string, opts: {
     since?: string;
     until?: string;
@@ -24,10 +39,17 @@ export interface Tag {
     email: string;
 }
 export declare function listTags(cwd: string): Promise<Tag[]>;
+/** Every path in the HEAD tree. */
+export declare function listHeadFiles(cwd: string): Promise<string[]>;
 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>;
+/** linguist-generated and linguist-vendored from .gitattributes, for the given paths. */
+export declare function checkAttr(cwd: string, paths: string[]): Promise<Map<string, {
+    generated: boolean;
+    vendored: boolean;
+}>>;
 export declare function configuredEmail(cwd: string): Promise<string>;