workproof 0.3.0 → 0.3.1

package/README.md

@@ -144,6 +144,37 @@ only comparable when that line matches:
 How: `git blame --line-porcelain -w -M --ignore-revs-file .git-blame-ignore-revs HEAD -- <file> over a deterministic 1-in-1 file sample (surviving-lines 0.1.1: FNV-1a on path); generated, vendored and lock files excluded`
 ```
 
+## When you are two people
+
+Git has no idea that the address on your laptop and the address on your work machine belong to
+one person. It counts them as two authors, so a report about one of them describes half your
+work and says nothing about the rest, and every figure in it is quietly too small. This is the
+most common way these numbers go wrong and nothing normally tells you.
+
+The report tells you:
+
+```
+**1 other identity in this repository looks like the same person and was not counted here**:
+Efe Genc. The same name, "Efe Genc", on another address. Every figure below therefore describes
+only the work under the identities named above. If they are the same person, re-run with each
+address passed to `--author`, or merge them in a `.mailmap`.
+```
+
+The same line appears as a warning on stderr while the run is happening, and as
+`identity.possiblySplit` in the JSON. Three signals raise it: the same name on another address,
+a GitHub noreply login that matches your address or your name, and the same address name on
+another domain. Role addresses like `dev@` and bot addresses are ignored, because sharing one
+proves nothing.
+
+It is a disclosure, not a correction. The tool cannot know whether two addresses are one person,
+so it never merges them for you: pass each address to `--author`, or write a `.mailmap`, which
+`git log`, `git blame` and `git shortlog` all read as well.
+[`surviving-lines --identities`](https://github.com/Bubblegunn/surviving-lines) prints the
+`.mailmap` lines for a whole repository if you want to fix it once for everyone.
+
+The addresses themselves stay out of the document unless you pass `--emails`, the same rule the
+rest of the report follows.
+
 ## In plain language
 
 Each repository section of the Markdown report opens with a paragraph a non-engineer can
@@ -461,6 +492,16 @@ workproof's only dependency. Degree of authorship follows Avelino, Hora and Vale
 (2016), major contributors follow Bird et al. (2011), and the absence factor is the CHAOSS
 Contributor Absence Factor.
 
+## Thanks
+
+[@edwardsong08](https://github.com/edwardsong08) sent two pull requests on the day this was
+published, without knowing me: `--format markdown|json|both`, so a pipeline can ask for one file
+instead of two ([#9](https://github.com/Bubblegunn/workproof/pull/9)), and a language map that
+covers Elixir, Scala, Haskell, Lua, R, Objective-C and Zig
+([#3](https://github.com/Bubblegunn/workproof/pull/3)). Both shipped in 0.1.3 and are in every
+release since. The second one is why the footprint figure names the right language for anyone
+outside the handful I had thought to list.
+
 ## Development
 
 ```

package/dist/src/analyse.d.ts

@@ -38,6 +38,12 @@ export interface RepoReport {
         emails: string[];
         names: string[];
         count: number;
+        /** Addresses here that look like the subject and were not counted as them. */
+        possiblySplit?: {
+            names: string[];
+            emails?: string[];
+            reasons: string[];
+        };
     };
     /** What the figures were computed with, so a verifier can tell a drift from an edit. */
     environment: {

package/dist/src/analyse.js

@@ -8,7 +8,7 @@ import { isBot, excludedSet } from "./exclusions.js";
 // surviving-lines ships plain ESM JavaScript without type declarations.
 // @ts-ignore
 import { globToRegExp } from "surviving-lines/bin/surviving-lines.js";
-import { resolveIdentity } from "./figures/identity.js";
+import { resolveIdentity, possibleSplits } from "./figures/identity.js";
 import { tenure, commitShare } from "./figures/commits.js";
 import { cadence } from "./figures/cadence.js";
 import { footprint, testsAndDocs } from "./figures/footprint.js";
@@ -83,6 +83,9 @@ export async function analyseRepo(cwd, params, hooks = {}) {
     const ex = await applyExclusions(cwd, everything, params);
     const all = ex.commits;
     const id = await resolveIdentity(all, params.author, cwd);
+    // Before any figure is computed: does someone else here look like the same person? A split
+    // identity makes every figure below describe half the work, silently.
+    const splits = possibleSplits(all, id);
     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");
@@ -138,7 +141,20 @@ export async function analyseRepo(cwd, params, hooks = {}) {
         head: await headSha(cwd),
         fingerprint: fingerprint(await rootCommit(cwd), await remoteUrl(cwd), key),
         fingerprintKeyed: true,
-        identity: { emails: params.emails ? [...new Set(id.emails.map(publicEmail))] : [], names: id.names, count: id.emails.length },
+        identity: {
+            emails: params.emails ? [...new Set(id.emails.map(publicEmail))] : [],
+            names: id.names,
+            count: id.emails.length,
+            ...(splits.length
+                ? {
+                    possiblySplit: {
+                        names: [...new Set(splits.map((sp) => sp.name))],
+                        ...(params.emails ? { emails: [...new Set(splits.map((sp) => publicEmail(sp.email)))] } : {}),
+                        reasons: [...new Set(splits.map((sp) => sp.reason))],
+                    },
+                }
+                : {}),
+        },
         environment: { git: await gitVersion(cwd), blame, ignoreRevs, seed: params.seed ?? "" },
         excluded: { botCommits: ex.botCommits, files: ex.excluded.size, linesAddedShare: addedAll ? addedExcluded / addedAll : 0, enabled: ex.enabled },
         figures,

package/dist/src/cli.js

@@ -245,6 +245,12 @@ async function main() {
         await writeFile(`${out}.badge.json`, JSON.stringify(badgeFor(report), null, 2));
         written.push(`${out}.badge.json`);
     }
+    for (const repo of report.repositories) {
+        const split = repo.identity.possiblySplit;
+        if (!split)
+            continue;
+        progress(`${repo.name}: warning, ${split.names.length} other identity in this repository looks like the same person and is not in these figures (${split.names.join(", ")}). Pass every address to --author, or merge them in a .mailmap.`);
+    }
     console.log(`wrote ${written.join(" and ")} in ${((Date.now() - started) / 1000).toFixed(1)}s`);
 }
 const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";

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

@@ -22,3 +22,23 @@ export declare function foldIdentity(s: string): string;
  */
 export declare function resolveIdentity(commits: Commit[], author: string[] | undefined, cwd: string): Promise<Identity>;
 export declare const isMine: (c: Commit, id: Identity) => boolean;
+/**
+ * Addresses in this repository that look like the subject but were not counted as them.
+ *
+ * A person who commits from a laptop and a work machine is two authors to git, so a report
+ * describes half of their work and says nothing about the other half. That is a silent wrong
+ * number in a tool whose whole claim is that its numbers can be checked, so the report
+ * discloses the suspicion rather than quietly resolving it: only the author knows whether two
+ * addresses are one person, and `--author` takes both when they are.
+ */
+export declare function possibleSplits(commits: {
+    name: string;
+    email: string;
+}[], identity: {
+    emails: string[];
+    names: string[];
+}): {
+    name: string;
+    email: string;
+    reason: string;
+}[];

package/dist/src/figures/identity.js

@@ -54,3 +54,57 @@ function authorsHint(commits) {
     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);
+/** Local parts that belong to a role rather than a person, so sharing one proves nothing. */
+const GENERIC_LOCAL = new Set(["dev", "admin", "info", "me", "git", "hello", "mail", "noreply", "no-reply", "contact", "support", "team", "root", "user", "build", "ci", "bot", "test", "email", "work", "home"]);
+const isBotAddress = (mail) => /\[bot\]@|^(?:dependabot|renovate|github-actions|greenkeeper)\b/i.test(mail);
+/** The GitHub login inside `12345+login@users.noreply.github.com`, or the older form. */
+const githubLogin = (mail) => {
+    const m = /^(?:\d+\+)?([^@+]+)@users\.noreply\.github\.com$/i.exec(mail);
+    return m ? m[1].toLowerCase() : null;
+};
+const localPart = (mail) => mail.split("@")[0].replace(/^\d+\+/, "");
+const loose = (s) => foldIdentity(s).replace(/[\s._-]/g, "");
+/**
+ * Addresses in this repository that look like the subject but were not counted as them.
+ *
+ * A person who commits from a laptop and a work machine is two authors to git, so a report
+ * describes half of their work and says nothing about the other half. That is a silent wrong
+ * number in a tool whose whole claim is that its numbers can be checked, so the report
+ * discloses the suspicion rather than quietly resolving it: only the author knows whether two
+ * addresses are one person, and `--author` takes both when they are.
+ */
+export function possibleSplits(commits, identity) {
+    const mine = new Set(identity.emails.map(foldIdentity));
+    const myNames = identity.names.map(foldIdentity);
+    const myLogins = identity.emails.map(githubLogin).filter((l) => l !== null);
+    const myLocals = identity.emails.map(localPart);
+    const seen = new Set();
+    const out = [];
+    for (const c of commits) {
+        const email = c.email;
+        if (mine.has(foldIdentity(email)) || seen.has(foldIdentity(email)) || isBotAddress(email))
+            continue;
+        let reason = "";
+        if (myNames.includes(foldIdentity(c.name))) {
+            reason = `the same name, "${c.name}", on another address`;
+        }
+        else {
+            const theirLogin = githubLogin(email);
+            const theirLocal = localPart(email);
+            if (theirLogin && (myLocals.some((l) => loose(l) === loose(theirLogin)) || myNames.some((n) => loose(n) === loose(theirLogin)))) {
+                reason = `the GitHub login "${theirLogin}" matches yours`;
+            }
+            else if (myLogins.some((l) => loose(l) === loose(theirLocal) || myNames.some((n) => loose(n) === loose(theirLocal)))) {
+                reason = `the address name "${theirLocal}" matches your GitHub login`;
+            }
+            else if (!theirLogin && myLocals.some((l) => l === theirLocal && l.length >= 3 && !GENERIC_LOCAL.has(l))) {
+                reason = `the same address name, "${theirLocal}", on another domain`;
+            }
+        }
+        if (reason) {
+            seen.add(foldIdentity(email));
+            out.push({ name: c.name, email, reason });
+        }
+    }
+    return out;
+}

package/dist/src/report.js

@@ -72,7 +72,12 @@ export function renderMarkdown(report, narrative) {
         ``,
     ];
     for (const repo of report.repositories) {
-        out.push(`## ${repo.name}`, ``, `HEAD \`${repo.head.slice(0, 12)}\` · fingerprint \`${repo.fingerprint.slice(0, 16)}\` · identities: ${repo.identity.names.join(", ")}${repo.identity.emails.length ? ` (${repo.identity.emails.join(", ")})` : ""}`, ``, repo.excluded.enabled
+        out.push(`## ${repo.name}`, ``, `HEAD \`${repo.head.slice(0, 12)}\` · fingerprint \`${repo.fingerprint.slice(0, 16)}\` · identities: ${repo.identity.names.join(", ")}${repo.identity.emails.length ? ` (${repo.identity.emails.join(", ")})` : ""}`, ``, ...(repo.identity.possiblySplit
+            ? [
+                `**${plural(repo.identity.possiblySplit.names.length, "other identity", "other identities")} in this repository look${repo.identity.possiblySplit.names.length === 1 ? "s" : ""} like the same person and ${repo.identity.possiblySplit.names.length === 1 ? "was" : "were"} not counted here**: ${repo.identity.possiblySplit.names.join(", ")}${repo.identity.possiblySplit.emails?.length ? ` (${repo.identity.possiblySplit.emails.join(", ")})` : ""}. ${repo.identity.possiblySplit.reasons.map((r, i) => (i === 0 ? r.charAt(0).toUpperCase() + r.slice(1) : r)).join("; ")}. Every figure below therefore describes only the work under the identities named above. If they are the same person, re-run with each address passed to \`--author\`, or merge them in a \`.mailmap\`.`,
+                ``,
+            ]
+            : []), repo.excluded.enabled
             ? `excluded ${plural(repo.excluded.botCommits, "bot commit", "bot commits")} and ${plural(repo.excluded.files, "generated, vendored or lock file", "generated, vendored or lock files")} (${pct(repo.excluded.linesAddedShare)} of lines added)`
             : `exclusions off (--no-exclusions): bot commits and generated files are counted`, ``, `### In plain language`, ``, plainSummary(repo), ``, `That paragraph is assembled from the figures below by a fixed rule, with no model involved, so it says nothing the numbers do not.`, ``);
         for (const f of repo.figures) {

package/dist/src/schema.js

@@ -31,6 +31,13 @@ function checkRepository(problems, path, r) {
         expect(problems, `${path}.identity.emails`, Array.isArray(id.emails), "array");
         expect(problems, `${path}.identity.names`, Array.isArray(id.names), "array");
         expect(problems, `${path}.identity.count`, typeof id.count === "number", "number");
+        if (id.possiblySplit !== undefined && expect(problems, `${path}.identity.possiblySplit`, isObject(id.possiblySplit), "object")) {
+            const ps = id.possiblySplit;
+            expect(problems, `${path}.identity.possiblySplit.names`, Array.isArray(ps.names), "array");
+            expect(problems, `${path}.identity.possiblySplit.reasons`, Array.isArray(ps.reasons), "array");
+            if (ps.emails !== undefined)
+                expect(problems, `${path}.identity.possiblySplit.emails`, Array.isArray(ps.emails), "array");
+        }
     }
     if (expect(problems, `${path}.environment`, isObject(repo.environment), "object")) {
         const env = repo.environment;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workproof",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Turn a private git repository into a verifiable engineering report for one author, without showing any code: thirteen figures from git, a hash anyone can recompute offline, verify, and an in-toto attestation.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -24,7 +24,7 @@
   "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/exclusions.test.js dist/test/adversarial.test.js dist/test/integrity.test.js dist/test/attest.test.js dist/test/report.test.js dist/test/summary.test.js dist/test/cli.test.js dist/test/action.test.js test/release.test.mjs",
+    "test": "npm run build && node --test dist/test/figures.test.js dist/test/exclusions.test.js dist/test/adversarial.test.js dist/test/integrity.test.js dist/test/attest.test.js dist/test/report.test.js dist/test/summary.test.js dist/test/cli.test.js dist/test/action.test.js test/release.test.mjs test/suite.test.mjs",
     "prepublishOnly": "npm test",
     "examples": "npm run build && node examples/basic.mjs",
     "release": "node scripts/release.mjs",

package/schema/report.schema.json

@@ -4,52 +4,169 @@
   "title": "workproof report",
   "description": "A verifiable engineering report for one author. hash is sha256 over the RFC 8785 canonical JSON of { params, repositories }.",
   "type": "object",
-  "required": ["tool", "schemaVersion", "version", "generatedAt", "params", "repositories", "hash"],
+  "required": [
+    "tool",
+    "schemaVersion",
+    "version",
+    "generatedAt",
+    "params",
+    "repositories",
+    "hash"
+  ],
   "properties": {
-    "tool": { "const": "workproof" },
-    "schemaVersion": { "const": 2 },
-    "version": { "type": "string" },
-    "generatedAt": { "type": "string", "format": "date-time" },
-    "params": { "type": "object" },
-    "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "tool": {
+      "const": "workproof"
+    },
+    "schemaVersion": {
+      "const": 2
+    },
+    "version": {
+      "type": "string"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "params": {
+      "type": "object"
+    },
+    "hash": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
     "repositories": {
       "type": "array",
       "minItems": 1,
       "items": {
         "type": "object",
-        "required": ["name", "head", "fingerprint", "identity", "environment", "excluded", "figures"],
+        "required": [
+          "name",
+          "head",
+          "fingerprint",
+          "identity",
+          "environment",
+          "excluded",
+          "figures"
+        ],
         "properties": {
-          "name": { "type": "string" },
-          "head": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
-          "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
-          "fingerprintKeyed": { "type": "boolean" },
+          "name": {
+            "type": "string"
+          },
+          "head": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{40}$"
+          },
+          "fingerprint": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "fingerprintKeyed": {
+            "type": "boolean"
+          },
           "identity": {
             "type": "object",
-            "required": ["emails", "names", "count"],
+            "required": [
+              "emails",
+              "names",
+              "count"
+            ],
             "properties": {
-              "emails": { "type": "array", "items": { "type": "string" } },
-              "names": { "type": "array", "items": { "type": "string" } },
-              "count": { "type": "integer", "minimum": 0 }
+              "emails": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "names": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "count": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "possiblySplit": {
+                "type": "object",
+                "properties": {
+                  "names": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "emails": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "reasons": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "required": [
+                  "names",
+                  "reasons"
+                ]
+              }
             }
           },
           "environment": {
             "type": "object",
-            "required": ["git", "blame"],
+            "required": [
+              "git",
+              "blame"
+            ],
             "properties": {
-              "git": { "type": "string" },
-              "blame": { "type": "array", "items": { "type": "string" } },
-              "ignoreRevs": { "type": ["string", "null"] },
-              "seed": { "type": "string" }
+              "git": {
+                "type": "string"
+              },
+              "blame": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "ignoreRevs": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "seed": {
+                "type": "string"
+              }
             }
           },
           "excluded": {
             "type": "object",
-            "required": ["botCommits", "files", "linesAddedShare"],
+            "required": [
+              "botCommits",
+              "files",
+              "linesAddedShare"
+            ],
             "properties": {
-              "botCommits": { "type": "integer", "minimum": 0 },
-              "files": { "type": "integer", "minimum": 0 },
-              "linesAddedShare": { "type": "number", "minimum": 0, "maximum": 1 },
-              "enabled": { "type": "boolean" }
+              "botCommits": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "files": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "linesAddedShare": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              },
+              "enabled": {
+                "type": "boolean"
+              }
             }
           },
           "figures": {
@@ -57,13 +174,31 @@
             "minItems": 1,
             "items": {
               "type": "object",
-              "required": ["id", "title", "value", "command", "limits"],
+              "required": [
+                "id",
+                "title",
+                "value",
+                "command",
+                "limits"
+              ],
               "properties": {
-                "id": { "type": "string", "minLength": 1 },
-                "title": { "type": "string" },
+                "id": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "title": {
+                  "type": "string"
+                },
                 "value": {},
-                "command": { "type": "string" },
-                "limits": { "type": "array", "items": { "type": "string" } }
+                "command": {
+                  "type": "string"
+                },
+                "limits": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
               }
             }
           }