@shortlink-org/portolan 0.2.3 → 0.3.0

package/scripts/gen-likec4.test.mjs

@@ -164,11 +164,34 @@ describe("the LikeC4 generator", () => {
             },
           ],
         },
+        {
+          id: "flow.get-book-contract",
+          slug: "get-book-contract",
+          name: "Get book contract",
+          summary: "",
+          owner: "demo",
+          participants: [
+            { id: "demo.api", kind: "service", context: "demo" },
+            { id: "demo.book", kind: "service", context: "demo" },
+          ],
+          steps: [
+            {
+              type: "step",
+              id: "request",
+              from: "demo.api",
+              to: "demo.book",
+              kind: "rpc",
+              ref: "book.v1.Book/Get",
+              label: "Get",
+              status: "declared",
+            },
+          ],
+        },
       ],
     });
 
     expect(views).toContain(
-      "demo.api -> demo.book 'Get' {\n      color declared  line solid  head normal",
+      "demo.api -> demo.book 'GetRequest' {\n      color declared  line solid  head normal",
     );
     expect(views).toContain(
       "demo.book -> demo.api 'GetResponse' {\n      color declared  line dashed  head normal",
@@ -177,7 +200,7 @@ describe("the LikeC4 generator", () => {
       "demo.book -> demo.api '500 · Error' {\n      color response_error  line dashed  head normal",
     );
     expect(spec).toContain("color response_error #b7646b");
-    expect(views).not.toContain("Get → GetResponse");
+    expect(views).not.toContain("GetRequest → GetResponse");
   });
 
   it("treats dots in a root participant id as data, not containment", () => {

package/scripts/gen.mjs

@@ -15,9 +15,8 @@ import {
   rmSync,
   statSync,
 } from "node:fs";
-import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { join, relative, resolve } from "node:path";
+import { isAbsolute, join, relative } from "node:path";
 
 import {
   addBuildStep,
@@ -26,16 +25,17 @@ import {
   writeBuildReport,
 } from "./build-report.mjs";
 import { loadCatalog } from "./catalog-sources.mjs";
-import { historyFor } from "./history.mjs";
+import { changedSince, fileAt, historyFor, lastCommitTouching } from "./history.mjs";
 import { loadManifest, stepKeys } from "./manifest.mjs";
 import { describePlugin, runPlugin } from "./plugin-host.mjs";
-import { vendoredCommit } from "./vendor-lock.mjs";
+import { explainChange } from "./output-diff.mjs";
 import {
   removeOutputFile,
   safeOutputPath,
   writeOutputFile,
 } from "./output-path.mjs";
 import { builtinPlugin } from "./builtin-plugins.mjs";
+import { diagnoseWarnings } from "./warning-policy.mjs";
 
 const PORTOLAN_VERSION = "0.1.0";
 const EVENTS = process.env.PORTOLAN_EVENTS === "1";
@@ -122,9 +122,12 @@ async function generate() {
 
   // Extractors run first and write catalog fragments; only then is there a
   // catalog for anything else to read.
+  //
+  // No stamp travels with the request (portolan.0010). A fragment is content
+  // and nothing else; when it last changed is what the history of the
+  // fragment says, read wherever the catalog is read.
   for (const step of manifest.extract ?? []) {
     const plugin = pluginNamed(step.plugin);
-    const stamp = stampFor(step.in, step.out);
     // A plugin that asks for history gets the root's, read once per checkout
     // (portolan.0007); left out when the root is not in a checkout, which the
     // plugin reports in its own words.
@@ -135,13 +138,11 @@ async function generate() {
         input: {
           root: step.in,
           output: step.out,
-          commit: stamp.commit,
-          generatedAt: stamp.generatedAt,
           ...(history ? { history } : {}),
         },
         options: step.options ?? {},
       }, {}, { workspace: process.cwd() }),
-    );
+    inputsOf(step));
   }
 
   // Verifiers read observed evidence against the merged catalog while leaving
@@ -152,17 +153,16 @@ async function generate() {
   // carry it into the generators and into the next run.
   for (const step of manifest.verify ?? []) {
     const plugin = pluginNamed(step.plugin);
-    const stamp = stampFor(step.in, step.out);
     const own = (previous(step.out)[keys.keyOf(step)] ?? []).map((name) => join(step.out, name));
-    const { catalog } = await loadSources({ exclude: [...own, ...staleAll()] });
+    const { catalog, sources } = await loadSources({ exclude: [...own, ...staleAll()] });
     await executeStep("verify", step, `${step.plugin} ⇐ ${step.in}`, async () =>
       runPlugin(plugin, {
         portolanVersion: PORTOLAN_VERSION,
-        input: { root: step.in, output: step.out, commit: stamp.commit, generatedAt: stamp.generatedAt },
+        input: { root: step.in, output: step.out },
         catalog,
         options: step.options ?? {},
       }, {}, { workspace: process.cwd() }),
-    );
+    inputsOf(step, sources.map((source) => source.path)));
   }
 
   // What a dropped extract step wrote is not part of the catalog, so it is
@@ -182,16 +182,16 @@ async function generate() {
 
   for (const step of manifest.generate ?? []) {
     const plugin = pluginNamed(step.plugin);
-    const generatedCatalog = step.catalog
-      ? (await loadSources({ profile: step.catalog })).catalog
-      : catalog;
+    const generated = step.catalog
+      ? await loadSources({ profile: step.catalog })
+      : { catalog, sources };
     await executeStep("generate", step, `${step.plugin} → ${step.out}`, async () =>
       runPlugin(plugin, {
         portolanVersion: PORTOLAN_VERSION,
-        catalog: generatedCatalog,
+        catalog: generated.catalog,
         options: step.options ?? {},
       }),
-    );
+    { inputs: generated.sources.map((source) => source.path), excludes: [] });
   }
 
   sweepAll();
@@ -249,13 +249,27 @@ function staleIn(out) {
   return stale;
 }
 
-async function executeStep(phase, step, label, work) {
+/**
+ * Runs one step and settles its files. `reads` is what the step reads - paths,
+ * and the output directories among them to leave out - so that an output
+ * that moved can be explained by what moved among its inputs since the
+ * output was last committed.
+ */
+async function executeStep(phase, step, label, work, reads) {
   const startedAt = Date.now();
   event({ type: "step-started", ordinal: report.steps.length, phase, plugin: step.plugin, input: step.in, output: step.out });
   try {
     const { files, warnings = [] } = await work();
+    const diagnostics = diagnoseWarnings({
+      plugin: step.plugin,
+      warnings,
+      policies: manifest.warningPolicies,
+      project: projectForStep(step),
+      phase,
+    });
     const changes = apply(files, step.out, keys.keyOf(step), check);
-    const changed = summarise(label, files, changes, warnings);
+    const since = changes.length > 0 ? whyChanged(step, files.map((file) => join(step.out, file.name)), reads) : null;
+    const changed = summarise(label, files, changes, diagnostics, since);
     drifted = changed || drifted;
     const result = {
       phase,
@@ -267,10 +281,14 @@ async function executeStep(phase, step, label, work) {
       fileCount: files.length,
       changedCount: changes.length,
       changes,
+      // What moved among the inputs since the output was last committed, when
+      // something in the output moved; the Settings page can say why.
+      ...(since ? { since } : {}),
       files: files.map((file) => join(step.out, file.name)),
       // What the plugin could not read, in its own words. Already printed as
       // it ran; kept here so the Settings page can list it beside the step.
       warnings,
+      diagnostics,
     };
     addBuildStep(report, result);
     persistReport();
@@ -296,6 +314,15 @@ async function executeStep(phase, step, label, work) {
   }
 }
 
+function projectForStep(step) {
+  if (!step.in) return "";
+  const input = String(step.in).replace(/\\/g, "/").replace(/\/+$/, "");
+  const projects = (manifest.projects ?? [])
+    .filter((project) => typeof project?.id === "string" && typeof project?.root === "string")
+    .sort((left, right) => right.root.length - left.root.length);
+  return projects.find((project) => input === project.root || input.startsWith(`${project.root}/`))?.id ?? "";
+}
+
 function persistReport() {
   try {
     writeBuildReport(report);
@@ -334,9 +361,17 @@ async function needsOf(plugin) {
   return pluginNeeds.get(plugin.name);
 }
 
-/** Prints what a step did, and says whether it left the tree out of date. */
-function summarise(label, files, changes, warnings = []) {
-  const said = warnings.length > 0 ? `, ${warnings.length} warning${warnings.length === 1 ? "" : "s"}` : "";
+/**
+ * Prints what a step did, and says whether it left the tree out of date. A
+ * file that differs says where it first differs, and the step says what moved
+ * among its inputs since the output was last committed - or that nothing
+ * did, which points at the plugin.
+ */
+function summarise(label, files, changes, diagnostics = [], since = null) {
+  const suppressed = diagnostics.filter((diagnostic) => diagnostic.suppressed).length;
+  const said = diagnostics.length > 0
+    ? `, ${diagnostics.length} warning${diagnostics.length === 1 ? "" : "s"}${suppressed ? ` (${suppressed} suppressed)` : ""}`
+    : "";
   const summary = `${label}: ${files.length} file${files.length === 1 ? "" : "s"}${said}`;
 
   if (changes.length === 0) {
@@ -347,120 +382,84 @@ function summarise(label, files, changes, warnings = []) {
 
   if (!check) {
     console.log(`${summary}, ${changes.length} written`);
+    if (since) console.log(`  ${describeSince(since)}`);
 
     return false;
   }
 
   console.error(`${summary}, ${changes.length} out of date:`);
-  for (const change of changes.slice(0, 20)) console.error(`  ${change.kind.padEnd(8)} ${change.path}`);
+  for (const change of changes.slice(0, 20)) {
+    console.error(`  ${change.kind.padEnd(8)} ${change.path}${change.reason ? ` — ${change.reason}` : ""}`);
+  }
   if (changes.length > 20) console.error(`  ... and ${changes.length - 20} more`);
+  if (since) console.error(`  ${describeSince(since)}`);
 
   return true;
 }
 
 /**
- * When the source a fragment describes last changed, and at which commit
- * (portolan.0002).
- *
- * The host works this out rather than the extractor, for two reasons. A plugin
- * that reads a clock produces a different fragment on every run, which cannot
- * be committed and cannot be checked; and a plugin that shells out to git is a
- * plugin that can never be sandboxed. Stamped from the last commit to touch the
- * directory, a fragment changes exactly when its subject does.
- *
- * The output is excluded from that history, and it has to be: a fragment
- * written beside the code it describes is inside the directory it is stamped
- * from, so committing one would move the stamp, which would make the fragment
- * out of date, which would rewrite it - and `--check` would never come back
- * clean two runs in a row.
+ * What a step reads, for saying why its output moved: its root and whatever
+ * else it was handed, less every output directory inside the root, because a
+ * fragment written beside the code it describes is not an input to itself.
  */
-function stampFor(root, out) {
-  // A copy of another repository is dated by the commit it is a copy OF, which
-  // the fetch step wrote down beside it. Read before git, and without touching
-  // git at all: the local history of a vendored directory says when somebody
-  // ran the fetch, which is a fact about this repository and not about the
-  // service the fragment describes.
-  //
-  // Short, like every other stamp, because a stamp is read rather than
-  // resolved. The full sha travels separately, in the pin the fetch also
-  // wrote, where a link is built from it.
-  const vendored = vendoredCommit(root);
-  if (vendored) {
-    // No date. Nothing here knows when that commit was made - the lock records
-    // what was fetched, not when it was authored - and a date invented from
-    // the local clock would make the merge call this the stalest source in the
-    // estate every time it ran.
-    return { commit: vendored.slice(0, 7), generatedAt: "" };
-  }
-
-  // The history read is the one the root lives in. A manifest pointed at a
-  // checkout elsewhere on the disk - the service being documented, not a copy
-  // of it vendored here - is stamped from that checkout's history, because the
-  // fragment describes that service and not the repository the manifest sits
-  // in. A root with no repository around it is stamped as uncommitted.
-  const repo = repositoryOf(root);
-  if (!repo) {
-    return { commit: "uncommitted", generatedAt: process.env.PORTOLAN_GENERATED_AT || new Date().toISOString() };
-  }
-
-  // A shallow clone has no history to read: the one commit that was fetched has
-  // no parent, so every path looks as though it changed there and every fragment
-  // is stamped with the checkout rather than with its subject. That is wrong
-  // quietly - the fragments regenerate, `--check` reports drift, and nothing
-  // says why - so it is refused here instead.
-  if (shallow(repo)) {
-    fail(
-      `${repo} is a shallow clone, where every path looks as though it changed in ` +
-        "the single commit that was fetched, so a fragment cannot be stamped " +
-        "with the commit it describes. Fetch the full history first " +
-        "(git fetch --unshallow, or actions/checkout with fetch-depth: 0).",
-    );
+function inputsOf(step, extra = []) {
+  const excludes = [];
+  for (const other of allSteps()) {
+    if (!other.out || other.out === step.in) continue;
+    const inside = relative(step.in, other.out);
+    if (inside && !inside.startsWith("..") && !isAbsolute(inside)) excludes.push(other.out);
   }
+  return { inputs: [step.in, ...extra], excludes };
+}
 
-  // Only an output INSIDE the root is excluded. An output beside it, or above
-  // it, is not in the root's history to begin with - and excluding a parent
-  // would exclude the root itself, leaving nothing to read and a stamp that
-  // moved on every commit.
-  const rootInRepo = relative(repo, resolve(root)) || ".";
-  const outInRepo = out ? relative(repo, resolve(out)) : "";
-  const inside = out && (outInRepo === rootInRepo || outInRepo.startsWith(`${rootInRepo.replace(/\/$/, "")}/`) || rootInRepo === ".");
-  const exclude = inside && outInRepo !== rootInRepo && !outInRepo.startsWith("..") ? [`:(exclude)${outInRepo}`] : [];
-
-  for (const args of [
-    ["log", "-1", "--format=%h %cI", "--", rootInRepo, ...exclude],
-    ["log", "-1", "--format=%h %cI"],
-  ]) {
-    const answer = git(repo, args);
-    if (!answer) continue;
-    const [commit, generatedAt] = answer.split(" ");
-    if (commit && generatedAt) return { commit, generatedAt };
-  }
+function allSteps() {
+  return [...(manifest.extract ?? []), ...(manifest.verify ?? []), ...(manifest.generate ?? [])];
+}
 
-  return { commit: "uncommitted", generatedAt: process.env.PORTOLAN_GENERATED_AT || new Date().toISOString() };
+/**
+ * Why a step's output is not what it was: the commit that last touched the
+ * output is when it was last generated, and what changed among the inputs
+ * since then is the reason. The history is the record of the last generation
+ * (portolan.0010); nothing is written down to know this.
+ *
+ * The manifest counts as an input only where this step's own entry moved.
+ * The whole file changes whenever any step is touched, and naming it for
+ * every other step would explain nothing.
+ */
+function whyChanged(step, outputs, reads) {
+  const committed = lastCommitTouching(process.cwd(), outputs);
+  if (!committed) return { committed: null, changed: [] };
+  const changed = changedSince(process.cwd(), committed.commit, reads.inputs, reads.excludes);
+  if (stepEntryChanged(committed.commit, step)) changed.push("portolan.json (this step's entry)");
+  return { committed, changed };
 }
 
-/** Runs git in a repository and answers with its trimmed output, or "" when it refused. */
-function git(repo, args) {
+/** Whether the manifest at `commit` told this step the same thing it is told now. */
+function stepEntryChanged(commit, step) {
+  let then;
   try {
-    return execFileSync("git", ["-C", repo, ...args], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
+    then = JSON.parse(fileAt(process.cwd(), commit, "portolan.json"));
   } catch {
-    // Not a repository, or no commit touches this path yet. git has already
-    // said so on its own stderr, which is not this run's log.
-    return "";
+    return true; // No manifest there, or not one that parses: everything about the step is new.
   }
+  const phase = ["extract", "verify", "generate"].find((name) => (manifest[name] ?? []).includes(step));
+  const before = (then[phase] ?? []).find(
+    (other) =>
+      other.plugin === step.plugin &&
+      (other.in ?? "") === (step.in ?? "") &&
+      other.out === step.out &&
+      (other.options?.out ?? "") === (step.options?.out ?? ""),
+  );
+  return !before || JSON.stringify(before) !== JSON.stringify(step);
 }
 
-/** The working tree a directory belongs to, or "" when no repository holds it. */
-function repositoryOf(dir) {
-  return git(dir, ["rev-parse", "--show-toplevel"]);
-}
-
-/** Whether the history this runs against is truncated. */
-function shallow(repo) {
-  return git(repo, ["rev-parse", "--is-shallow-repository"]) === "true";
+function describeSince({ committed, changed }) {
+  if (!committed) return "the output has never been committed, so there is nothing to compare its inputs against";
+  const when = `${committed.commit} (${committed.date}), when the output was last committed`;
+  if (changed.length === 0) return `no input changed since ${when}; the plugin itself did`;
+  const shown = changed.slice(0, 6).join(", ");
+  const more = changed.length > 6 ? ` and ${changed.length - 6} more` : "";
+  return `since ${when}, ${changed.length} input${changed.length === 1 ? "" : "s"} changed: ${shown}${more}`;
 }
 
 /** Reads, merges and validates every source the manifest names. */
@@ -497,7 +496,11 @@ function apply(files, out, key, checkOnly) {
 
     if (binary ? Buffer.isBuffer(current) && current.equals(wanted) : current === wanted) continue;
 
-    changes.push({ kind: current === null ? "added" : "changed", path: join(out, file.name) });
+    changes.push({
+      kind: current === null ? "added" : "changed",
+      path: join(out, file.name),
+      reason: explainChange(current, wanted, file.name),
+    });
     if (checkOnly) continue;
 
     try {

package/scripts/go-discovery.test.mjs

@@ -0,0 +1,30 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, expect, it } from "vitest";
+import { discoverProject } from "./local-discovery.mjs";
+
+const roots = [];
+afterEach(() => roots.splice(0).forEach((root) => rmSync(root, { recursive: true, force: true })));
+function discover(files) {
+  const root = mkdtempSync(join(tmpdir(), "portolan-go-discovery-"));
+  roots.push(root);
+  for (const [name, text] of Object.entries({ "go.mod": "module example.com/app\n", ...files })) {
+    const path = join(root, name);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+  }
+  return discoverProject(root, ".").detections.map((item) => item.plugin);
+}
+it("offers Go flows and SQL for a service without any DDD directories", () => {
+  expect(discover({
+    "web/routes.go": 'package web\nimport "net/http"\nfunc Register(m *http.ServeMux) { m.HandleFunc("POST /orders", create) }',
+    "store/migrations/001.sql": "CREATE TABLE orders (id uuid PRIMARY KEY);",
+  })).toEqual(expect.arrayContaining(["go-domain", "sql"]));
+});
+it("does not offer Go domain extraction for unregistered helpers or generated handlers", () => {
+  for (const source of [
+    'package web\nimport "net/http"\nfunc Help(w http.ResponseWriter, r *http.Request) {}',
+    '// Code generated by fixture. DO NOT EDIT.\npackage web\nimport "net/http"\nfunc Register() { http.HandleFunc("/x", help) }',
+  ]) expect(discover({ "web/routes.go": source })).not.toContain("go-domain");
+});

package/scripts/history.mjs

@@ -1,5 +1,6 @@
 // When each file was first committed and last changed, read by the host for a
-// plugin that asks (portolan.0007).
+// plugin that asks (portolan.0007), and for the provenance of every catalog
+// source (portolan.0010).
 //
 // One `git log` over the whole checkout, walked oldest first with renames
 // followed, gives every path its first commit and its last. A plugin used to
@@ -8,8 +9,8 @@
 // reads it once and hands each step the part under its root.
 
 import { execFileSync } from "node:child_process";
-import { realpathSync } from "node:fs";
-import { relative, resolve, sep } from "node:path";
+import { realpathSync, statSync } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
 
 const RECORD = "\x1e";
 const FIELD = "\x1f";
@@ -17,6 +18,188 @@ const FIELD = "\x1f";
 /** Per repository, per process: the history does not change during a run. */
 const cache = new Map();
 
+/** Repositories already told they are shallow; it is said once. */
+const warnedShallow = new Set();
+
+/**
+ * When each of `paths` last changed, as the history says: the commit that
+ * last touched the file, and that commit's date.
+ *
+ * This is where a source's provenance comes from (portolan.0010). It is read
+ * off the checkout that holds the file and never written into the file, so a
+ * fragment is content and nothing else, and a regeneration that changes no
+ * fact changes no byte. The stamp names the commit the change landed in,
+ * which a stamp written into the file never could: that one was the parent
+ * at best, and it took a second commit to catch up.
+ *
+ * A file with uncommitted changes, or one git does not track, is
+ * `uncommitted` and dated by its mtime - an observation of the working tree,
+ * shown and never committed. A path outside any repository is the same. A
+ * shallow clone makes every path look as though it changed in the one commit
+ * that was fetched; that is said once, and the stamps are what the truncated
+ * history says, which is at least the checkout.
+ *
+ * @param {string} workspace
+ * @param {string[]} paths  relative to `workspace`, forward slashes
+ * @returns {Map<string, {commit: string, generatedAt: string}>}
+ */
+export function stampsFor(workspace, paths) {
+  const workspaceReal = realpathSync(resolve(workspace));
+  const stamps = new Map();
+  const repoOfDir = new Map();
+  const byRepo = new Map();
+
+  for (const path of paths) {
+    const absolute = resolve(workspaceReal, path);
+    const dir = dirname(absolute);
+    if (!repoOfDir.has(dir)) repoOfDir.set(dir, repositoryOf(dir));
+    const repo = repoOfDir.get(dir);
+    if (!repo) {
+      stamps.set(path, uncommitted(absolute));
+      continue;
+    }
+    if (!byRepo.has(repo)) byRepo.set(repo, []);
+    byRepo.get(repo).push({ path, absolute, key: toPosix(relative(repo, absolute)) });
+  }
+
+  for (const [repo, files] of byRepo) {
+    warnIfShallow(repo);
+    const history = fileHistory(repo);
+    const dirty = dirtyIn(repo);
+    for (const file of files) {
+      const entry = history.get(file.key);
+      const last = entry?.revised ?? entry?.created;
+      stamps.set(
+        file.path,
+        !last || dirty.has(file.key)
+          ? uncommitted(file.absolute)
+          : { commit: last.commit.slice(0, 7), generatedAt: last.date },
+      );
+    }
+  }
+
+  return stamps;
+}
+
+/**
+ * The commit that last touched any of `paths`, and its date, or null when
+ * none of them has been committed. For a step's output this is when it was
+ * last generated: the history remembers it, so nothing has to write it down
+ * anywhere else (portolan.0010).
+ *
+ * @param {string} workspace
+ * @param {string[]} paths  relative to `workspace`
+ * @returns {{commit: string, date: string} | null}
+ */
+export function lastCommitTouching(workspace, paths) {
+  const { repo, keys } = inRepo(workspace, paths);
+  if (!repo || keys.length === 0) return null;
+  const answer = git(repo, ["log", "-1", "--format=%H %cI", "--", ...keys]);
+  if (!answer) return null;
+  const [sha, date] = answer.split(" ");
+  // Seven characters, the width every stamp has, so the two read alike.
+  return sha && date ? { commit: sha.slice(0, 7), date } : null;
+}
+
+/**
+ * Which files under `paths` differ from what `commit` held, working tree
+ * included: modified, added, deleted and untracked, less anything under
+ * `excludes`. Paths in and out are relative to `workspace`.
+ *
+ * @param {string} workspace
+ * @param {string} commit
+ * @param {string[]} paths
+ * @param {string[]} [excludes]
+ * @returns {string[]}
+ */
+export function changedSince(workspace, commit, paths, excludes = []) {
+  const { repo, keys, toWorkspace } = inRepo(workspace, paths);
+  if (!repo || keys.length === 0) return [];
+  const spec = [...keys, ...inRepo(workspace, excludes).keys.map((key) => `:(exclude)${key}`)];
+  const tracked = git(repo, ["diff", "--name-only", commit, "--", ...spec]);
+  const untracked = git(repo, ["ls-files", "--others", "--exclude-standard", "--", ...spec]);
+  const changed = new Set();
+  for (const line of `${tracked}\n${untracked}`.split("\n")) {
+    if (line) changed.add(toWorkspace(line));
+  }
+  return [...changed].sort();
+}
+
+/**
+ * The text of `path` as `commit` held it, or "" when the commit did not hold
+ * it or there is no history to ask.
+ *
+ * @param {string} workspace
+ * @param {string} commit
+ * @param {string} path  relative to `workspace`
+ * @returns {string}
+ */
+export function fileAt(workspace, commit, path) {
+  const { repo, keys } = inRepo(workspace, [path]);
+  if (!repo || keys.length === 0) return "";
+  return git(repo, ["show", `${commit}:${keys[0]}`]);
+}
+
+/** The paths as the workspace's repository spells them, and the way back. */
+function inRepo(workspace, paths) {
+  const workspaceReal = realpathSync(resolve(workspace));
+  const repo = repositoryOf(workspaceReal);
+  if (!repo) return { repo: "", keys: [], toWorkspace: (line) => line };
+  const keys = [];
+  for (const path of paths) {
+    const key = toPosix(relative(repo, resolve(workspaceReal, path)));
+    if (key.startsWith("..")) continue;
+    keys.push(key || ".");
+  }
+  return {
+    repo,
+    keys,
+    toWorkspace: (line) => toPosix(relative(workspaceReal, resolve(repo, line))),
+  };
+}
+
+function uncommitted(absolute) {
+  let generatedAt = "";
+  try {
+    generatedAt = statSync(absolute).mtime.toISOString();
+  } catch {
+    // Gone, or never there: undated rather than dated by a guess.
+  }
+  return { commit: "uncommitted", generatedAt };
+}
+
+/** Every path with a change the history does not hold yet, relative to the repository. */
+function dirtyIn(repo) {
+  const dirty = new Set();
+  // Read raw: an entry begins with two status letters, and a space is one of
+  // them, which the trimming reader would eat off the first line.
+  let status = "";
+  try {
+    status = execFileSync("git", ["-C", repo, "status", "--porcelain", "-z", "--no-renames", "--untracked-files=all"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch {
+    return dirty;
+  }
+  for (const entry of status.split("\0")) {
+    if (entry.length > 3) dirty.add(entry.slice(3));
+  }
+  return dirty;
+}
+
+function warnIfShallow(repo) {
+  if (warnedShallow.has(repo)) return;
+  warnedShallow.add(repo);
+  if (git(repo, ["rev-parse", "--is-shallow-repository"]) !== "true") return;
+  console.warn(
+    `${repo} is a shallow clone, where every source looks as though it last changed in ` +
+      "the one commit that was fetched. Fetch the full history (git fetch --unshallow, " +
+      "or actions/checkout with fetch-depth: 0) for the provenance to say anything.",
+  );
+}
+
 /**
  * History for every file under `root`, keyed by the path a plugin would name
  * it - relative to `workspace`, forward slashes. `undefined` when the root is

package/scripts/history.test.mjs

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 
-import { fileHistory, forgetHistory, historyFor, parseLog } from "./history.mjs";
+import { changedSince, fileHistory, forgetHistory, historyFor, lastCommitTouching, parseLog, stampsFor } from "./history.mjs";
 
 const created = [];
 afterEach(() => {