workproof 0.1.2 → 0.1.3

package/README.md

@@ -6,6 +6,9 @@
 
 <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>
@@ -126,8 +129,10 @@ workproof verify <report.json> [--repo <dir>]...
 --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
@@ -135,6 +140,58 @@ stderr while history is read and files are blamed, so a long run is visibly aliv
 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"
+```
+
+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.

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>]...
 
@@ -18,16 +18,20 @@ Turn a git repository into a verifiable engineering report for one author, witho
   --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];
@@ -66,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);
@@ -81,11 +95,11 @@ 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 started = Date.now();
-    const { params, repos, out, json, doNarrate, verifyFile } = parse(process.argv.slice(2));
+    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"));
@@ -112,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 in ${((Date.now() - started) / 1000).toFixed(1)}s`);
+    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/index.d.ts

@@ -6,3 +6,5 @@ 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.2",
+  "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"
+  }
 }