workproof 0.3.1 → 0.4.0

package/README.md

@@ -229,6 +229,16 @@ Three commands, in increasing order of what the reader needs to have.
   compares HEAD, then recomputes every figure and prints what differs. A report from another
   repository stops at the fingerprint. If HEAD moved since the report, it says so and shows
   which figures changed.
+The hash is reproducible **across operating systems, git versions, locales and directory
+names**, for the same repository at the same commit with the same command and the same
+`--fingerprint-key`. It is not reproducible across a rewritten history, a different sample
+or a different seed, and it is not meant to be: those change the measurement. Two fields
+in the report are deliberately outside the hash, because a verifier on another machine
+cannot reproduce them: the local directory name, and the git version. They stay in the
+document, where they explain why two runs might legitimately differ. Before 0.4.0 both
+were inside it, so the same repository in a folder with a different name hashed
+differently; a test now pins all of this, and CI checks it on Linux, macOS and Windows.
+
 - `workproof attest report.json` writes `report.intoto.json`, an
   [in-toto](https://in-toto.io) v1 Statement whose subject is the report hash and whose
   predicate carries the tool version, parameters, HEAD, keyed fingerprint, git version and
@@ -483,6 +493,28 @@ with an attestation if the reader cannot reach the repository.
 It measures survivorship and activity, not quality, review, design or mentoring. It does
 not rank people. It does not replace references. It is not a legal document.
 
+## What the research says about numbers like these
+
+Repository-derived figures have a literature, and most of it is a warning. Kalliamvakou,
+Gousios and Blincoe catalogued the traps in mining a forge, including that most repositories
+are personal and inactive and that a large share of merged pull requests are not recorded as
+merged ([MSR 2014](https://doi.org/10.1145/2597073.2597074), extended in [EMSE
+2015](https://doi.org/10.1007/s10664-015-9393-5)). Bird and colleagues related ownership
+concentration to defects rather than to credit, which is a different question from this one
+and is not evidence that a high share means good work. On survival, Spinellis, Louridas and
+Kechagia put the median line lifespan at about 2.4 years across 89 repositories ([PeerJ CS
+7:e372, 2021](https://doi.org/10.7717/peerj-cs.372)), and Gurov found over half of all lines
+are never deleted in 120 TypeScript repositories ([arXiv
+2606.04993](https://arxiv.org/abs/2606.04993)).
+
+None of that work measures a person's share of the surviving code, which is what the
+surviving-lines figure here reports. A first measurement of how far that share diverges from
+commit share, over twelve repositories, is in
+[surviving-lines/research](https://github.com/Bubblegunn/surviving-lines/tree/main/research):
+the same person tops both in 25 of 36 runs, and among substantial contributors the two
+differ by a median of 7.5 percentage points. That is the honest size of the effect this
+report exists to expose, measured rather than asserted.
+
 ## Where it comes from
 
 The method is written up in

package/dist/src/report.d.ts

@@ -10,7 +10,6 @@ export interface Report {
     /** sha256 of the RFC 8785 canonical JSON of { params, repositories }. */
     hash: string;
 }
-/** The hash a report with these parameters and repositories must carry. */
 export declare const hashOf: (params: unknown, repositories: unknown) => string;
 export declare function buildReport(repositories: RepoReport[], params: Params, meta: {
     version: string;

package/dist/src/report.js

@@ -3,7 +3,34 @@ import { canonicalize } from "./canonical.js";
 import { publicEmail } from "./analyse.js";
 import { plainSummary } from "./summary.js";
 /** The hash a report with these parameters and repositories must carry. */
-export const hashOf = (params, repositories) => createHash("sha256").update(canonicalize({ params, repositories })).digest("hex");
+/**
+ * What of a repository the hash covers: everything a stranger with the same repository at
+ * the same commit can reproduce, and nothing else.
+ *
+ * Two fields are recorded in the report and deliberately left out. `name` is the local
+ * directory's basename, so the same repository cloned to a different folder hashed
+ * differently. `environment.git` is the local git version string, so two people with the
+ * same repository and different git hashed differently. Both were reproduced with real
+ * runs before 0.4.0. They stay in the document because they explain why two runs might
+ * legitimately differ; they are not something a verifier can be asked to reproduce.
+ *
+ * The blame flags, the ignore-revs file and the seed stay in, because those are the
+ * question the caller asked, not the machine they asked it on.
+ */
+function forHash(repositories) {
+    if (!Array.isArray(repositories))
+        return repositories;
+    return repositories.map((repo) => {
+        if (repo === null || typeof repo !== "object")
+            return repo;
+        const { name: _name, environment, ...rest } = repo;
+        if (environment === null || typeof environment !== "object")
+            return rest;
+        const { git: _git, ...restEnvironment } = environment;
+        return { ...rest, environment: restEnvironment };
+    });
+}
+export const hashOf = (params, repositories) => createHash("sha256").update(canonicalize({ params, repositories: forHash(repositories) })).digest("hex");
 /**
  * What of the parameters the report may carry: never the fingerprint key, never a GitHub
  * noreply login, and without --emails no author given as an email address.

package/package.json

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