@shortlink-org/portolan 0.1.0 → 0.2.0

package/scripts/delivery-presets.mjs

@@ -0,0 +1,353 @@
+// CI and publication recipes installed from Settings while Portolan is running
+// locally. Every generated region identifies itself, so a later Portolan
+// version can update its own work without taking ownership of the user's CI.
+
+import { execFileSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const VERSION = packageJson.version;
+const GENERATED = "# Generated by Portolan. Preview changes in Settings before updating.";
+const GITLAB_START = "# >>> Portolan delivery preset >>>";
+const GITLAB_END = "# <<< Portolan delivery preset <<<";
+const PROVIDERS = new Set(["github", "gitlab"]);
+
+function exists(path) {
+  try { lstatSync(path); return true; } catch { return false; }
+}
+
+function git(workspace, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd: workspace,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5_000,
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+export function providerFromRemote(remote) {
+  const value = String(remote ?? "").trim().toLowerCase();
+  if (!value) return null;
+  const host = /^(?:https?|ssh):\/\/(?:[^@/]+@)?([^/:]+)/.exec(value)?.[1]
+    ?? /^[^@]+@([^:]+):/.exec(value)?.[1]
+    ?? "";
+  if (host === "github.com" || host.endsWith(".github.com")) return "github";
+  if (host === "gitlab.com" || host.includes("gitlab")) return "gitlab";
+  return null;
+}
+
+function repositoryName(remote, workspace) {
+  const clean = String(remote ?? "").replace(/\/+$/, "").replace(/\.git$/, "");
+  return clean.split(/[/:]/).filter(Boolean).pop() || relative(dirname(workspace), workspace) || "repository";
+}
+
+function defaultBranch(workspace) {
+  const remoteHead = git(workspace, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
+  if (remoteHead.startsWith("origin/")) return remoteHead.slice("origin/".length);
+  for (const candidate of ["main", "master"]) {
+    if (git(workspace, ["rev-parse", "--verify", `refs/heads/${candidate}`])) return candidate;
+  }
+  return git(workspace, ["branch", "--show-current"]) || "main";
+}
+
+export function detectDeliveryForge(workspace) {
+  const remote = git(workspace, ["config", "--get", "remote.origin.url"]);
+  return {
+    provider: providerFromRemote(remote),
+    remote: remote || null,
+    repository: repositoryName(remote, workspace),
+    defaultBranch: defaultBranch(workspace),
+  };
+}
+
+function githubCheck(branch) {
+  return `${GENERATED}
+name: Portolan architecture check
+
+on:
+  pull_request:
+  push:
+    branches: [${branch}]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: portolan-check-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: shortlink-org/portolan@${VERSION}
+        with:
+          command: check
+          version: ${VERSION}
+`;
+}
+
+function githubPages(branch) {
+  return `${GENERATED}
+name: Publish Portolan catalog
+
+on:
+  push:
+    branches: [${branch}]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: portolan-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: shortlink-org/portolan@${VERSION}
+        with:
+          command: build
+          version: ${VERSION}
+          output: dist
+          base: /\${{ github.event.repository.name }}/
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5
+`;
+}
+
+function gitlabBlock() {
+  return `${GITLAB_START}
+"portolan:check":
+  stage: .pre
+  image:
+    name: ghcr.io/shortlink-org/portolan:${VERSION}
+    entrypoint: [""]
+  variables:
+    GIT_DEPTH: "0"
+  script:
+    - portolan check
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+
+"portolan:pages":
+  stage: .post
+  image:
+    name: ghcr.io/shortlink-org/portolan:${VERSION}
+    entrypoint: [""]
+  variables:
+    GIT_DEPTH: "0"
+  script:
+    - BASE_PATH="$(node -p 'new URL(process.env.CI_PAGES_URL).pathname.replace(/\\/?$/, "/") || "/"')"
+    - portolan build --output dist --base "$BASE_PATH"
+  pages:
+    publish: dist
+  rules:
+    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+${GITLAB_END}
+`;
+}
+
+function mergeGitlab(existing) {
+  const start = existing.indexOf(GITLAB_START);
+  const end = existing.indexOf(GITLAB_END);
+  if ((start === -1) !== (end === -1) || (start !== -1 && end < start)) {
+    return { conflict: "The existing Portolan managed region is incomplete." };
+  }
+  if (start !== -1) {
+    const after = end + GITLAB_END.length;
+    return { content: `${existing.slice(0, start)}${gitlabBlock().trimEnd()}${existing.slice(after)}`.replace(/\n*$/, "\n") };
+  }
+  if (/^[ \t]*["']?portolan:(?:check|pages)["']?\s*:/m.test(existing)) {
+    return { conflict: "This pipeline already declares a Portolan job outside the managed region." };
+  }
+  return { content: `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${gitlabBlock()}` };
+}
+
+function textDiff(path, before, after) {
+  if (before === after) return "";
+  const holder = mkdtempSync(join(tmpdir(), "portolan-preset-diff-"));
+  const left = join(holder, "before");
+  const right = join(holder, "after");
+  try {
+    writeFileSync(left, before);
+    writeFileSync(right, after);
+    let output = "";
+    try {
+      output = execFileSync("git", ["diff", "--no-index", "--no-ext-diff", "--unified=3", "--", left, right], {
+        encoding: "utf8",
+        maxBuffer: 2 * 1024 * 1024,
+      });
+    } catch (cause) {
+      if (cause?.status !== 1) throw cause;
+      output = String(cause.stdout ?? "");
+    }
+    return output
+      .replaceAll(`a${left}`, `a/${path}`)
+      .replaceAll(`b${right}`, `b/${path}`)
+      .replaceAll(left, path)
+      .replaceAll(right, path);
+  } finally {
+    rmSync(holder, { recursive: true, force: true });
+  }
+}
+
+function readTarget(workspace, path) {
+  const target = resolve(workspace, path);
+  const root = resolve(workspace);
+  if (target !== root && !target.startsWith(`${root}${sep}`)) throw new Error("Preset target must stay inside this repository.");
+  let cursor = root;
+  for (const segment of relative(root, target).split(sep).filter(Boolean)) {
+    cursor = join(cursor, segment);
+    if (exists(cursor) && lstatSync(cursor).isSymbolicLink()) return { exists: true, content: "", safe: false };
+  }
+  if (!exists(target)) return { exists: false, content: "", safe: true };
+  const stat = lstatSync(target);
+  if (!stat.isFile() || stat.isSymbolicLink()) return { exists: true, content: "", safe: false };
+  if (stat.size > 512_000) return { exists: true, content: "", safe: false };
+  const bytes = readFileSync(target);
+  if (bytes.includes(0)) return { exists: true, content: "", safe: false };
+  return { exists: true, content: bytes.toString("utf8"), safe: true };
+}
+
+function githubFile(workspace, path, content) {
+  const current = readTarget(workspace, path);
+  const managed = current.safe && current.content.startsWith(GENERATED);
+  const status = !current.exists ? "added" : !current.safe || !managed ? "conflict" : current.content === content ? "unchanged" : "changed";
+  return {
+    path,
+    status,
+    message: status === "conflict" ? "A file already exists here and was not created by Portolan." : undefined,
+    diff: current.safe ? textDiff(path, current.content, content) : "Existing file is not a safe UTF-8 file.",
+    current: current.content,
+    next: content,
+  };
+}
+
+function gitlabFile(workspace) {
+  const path = ".gitlab-ci.yml";
+  const current = readTarget(workspace, path);
+  if (!current.safe) return { path, status: "conflict", message: "The existing pipeline is not a safe UTF-8 file.", diff: "", current: "", next: "" };
+  const merged = mergeGitlab(current.content);
+  if (merged.conflict) return { path, status: "conflict", message: merged.conflict, diff: "", current: current.content, next: "" };
+  const status = !current.exists ? "added" : current.content === merged.content ? "unchanged" : "changed";
+  return { path, status, diff: textDiff(path, current.content, merged.content), current: current.content, next: merged.content };
+}
+
+function revisionFor(provider, files) {
+  const hash = createHash("sha256").update(provider);
+  for (const file of files) {
+    hash.update("\0"); hash.update(file.path); hash.update("\0"); hash.update(file.current); hash.update("\0"); hash.update(file.next);
+  }
+  return hash.digest("hex");
+}
+
+export function planDeliveryPreset(workspace, requestedProvider) {
+  const detected = detectDeliveryForge(workspace);
+  const provider = requestedProvider || detected.provider || "github";
+  if (!PROVIDERS.has(provider)) throw new Error("Delivery preset must be github or gitlab.");
+  const files = provider === "github"
+    ? [
+        githubFile(workspace, ".github/workflows/portolan-check.yml", githubCheck(detected.defaultBranch)),
+        githubFile(workspace, ".github/workflows/portolan-pages.yml", githubPages(detected.defaultBranch)),
+      ]
+    : [gitlabFile(workspace)];
+  const status = files.some((file) => file.status === "conflict")
+    ? "conflict"
+    : files.every((file) => file.status === "unchanged")
+      ? "installed"
+      : files.some((file) => file.status === "changed") && (provider !== "gitlab" || files[0].current.includes(GITLAB_START))
+        ? "update"
+        : "available";
+  return {
+    provider,
+    detectedProvider: detected.provider,
+    remote: detected.remote,
+    repository: detected.repository,
+    defaultBranch: detected.defaultBranch,
+    status,
+    revision: revisionFor(provider, files),
+    features: ["Validate generated architecture in reviews", "Publish the static catalog"],
+    files,
+  };
+}
+
+export function publicDeliveryPreset(plan) {
+  return { ...plan, files: plan.files.map(({ current: _current, next: _next, ...file }) => file) };
+}
+
+export function installDeliveryPreset(workspace, request) {
+  const plan = planDeliveryPreset(workspace, request.provider);
+  if (!request.revision || request.revision !== plan.revision) {
+    const error = new Error("Files changed after this preset preview. Preview it again.");
+    error.status = 409;
+    throw error;
+  }
+  const conflict = plan.files.find((file) => file.status === "conflict");
+  if (conflict) {
+    const error = new Error(`${conflict.path}: ${conflict.message}`);
+    error.status = 409;
+    throw error;
+  }
+  for (const file of plan.files) {
+    const current = readTarget(workspace, file.path);
+    if (!current.safe || current.content !== file.current) {
+      const error = new Error("Files changed after this preset preview. Preview it again.");
+      error.status = 409;
+      throw error;
+    }
+  }
+  const written = [];
+  for (const file of plan.files) {
+    if (file.status === "unchanged") continue;
+    const target = resolve(workspace, file.path);
+    mkdirSync(dirname(target), { recursive: true });
+    const temporary = join(dirname(target), `.portolan-${randomUUID()}.tmp`);
+    try {
+      writeFileSync(temporary, file.next, { flag: "wx" });
+      renameSync(temporary, target);
+    } finally {
+      if (exists(temporary)) rmSync(temporary, { force: true });
+    }
+    written.push(file.path);
+  }
+  return { ...publicDeliveryPreset(planDeliveryPreset(workspace, request.provider)), written };
+}

package/scripts/gen.mjs

@@ -26,8 +26,9 @@ import {
   writeBuildReport,
 } from "./build-report.mjs";
 import { loadCatalog } from "./catalog-sources.mjs";
+import { historyFor } from "./history.mjs";
 import { loadManifest, stepKeys } from "./manifest.mjs";
-import { runPlugin } from "./plugin-host.mjs";
+import { describePlugin, runPlugin } from "./plugin-host.mjs";
 import { vendoredCommit } from "./vendor-lock.mjs";
 import {
   removeOutputFile,
@@ -73,6 +74,8 @@ const report = createBuildReport({
 let manifest = {};
 let keys = stepKeys({});
 let drifted = false;
+// What each plugin said it needs from the host (portolan.0007), by name.
+const pluginNeeds = new Map();
 
 // What each step wrote into each directory on this run, by key. The listing
 // on disk says what was written last time; in check mode it is never updated,
@@ -122,12 +125,22 @@ async function generate() {
   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.
+    const history = (await needsOf(plugin)).has("history") ? historyFor(process.cwd(), step.in) : undefined;
     await executeStep("extract", 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,
+          commit: stamp.commit,
+          generatedAt: stamp.generatedAt,
+          ...(history ? { history } : {}),
+        },
         options: step.options ?? {},
-      }),
+      }, {}, { workspace: process.cwd() }),
     );
   }
 
@@ -148,7 +161,7 @@ async function generate() {
         input: { root: step.in, output: step.out, commit: stamp.commit, generatedAt: stamp.generatedAt },
         catalog,
         options: step.options ?? {},
-      }),
+      }, {}, { workspace: process.cwd() }),
     );
   }
 
@@ -301,6 +314,26 @@ function pluginNamed(name) {
   return plugin ?? shipped;
 }
 
+/**
+ * What a plugin's descriptor says it needs from the host, asked once per
+ * plugin per run. A plugin that does not describe itself needs nothing it
+ * could be given.
+ */
+
+async function needsOf(plugin) {
+  if (!pluginNeeds.has(plugin.name)) {
+    let descriptor = null;
+    try {
+      descriptor = await describePlugin(plugin);
+    } catch {
+      // A plugin that cannot answer describe cannot ask for anything either;
+      // whatever is wrong with it, the step itself will say.
+    }
+    pluginNeeds.set(plugin.name, new Set(descriptor?.needs ?? []));
+  }
+  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"}` : "";

package/scripts/history.mjs

@@ -0,0 +1,126 @@
+// When each file was first committed and last changed, read by the host for a
+// plugin that asks (portolan.0007).
+//
+// 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
+// ask git this per file with `--follow`; a wasm module cannot run git, and
+// the answer is a fact about the checkout the host already holds, so the host
+// 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";
+
+const RECORD = "\x1e";
+const FIELD = "\x1f";
+
+/** Per repository, per process: the history does not change during a run. */
+const cache = new Map();
+
+/**
+ * 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
+ * not inside a git checkout, which is different from an empty object: a
+ * checkout with nothing committed under the root.
+ *
+ * @param {string} workspace
+ * @param {string} root
+ * @returns {Record<string, {created: Commit, revised?: Commit}> | undefined}
+ */
+export function historyFor(workspace, root) {
+  // Resolved through symlinks, as git reports its top level: on macOS a
+  // temporary directory is one and the two would never compare equal.
+  const workspaceReal = realpathSync(resolve(workspace));
+  const absoluteRoot = resolve(workspaceReal, root);
+  const repo = repositoryOf(absoluteRoot);
+  if (!repo) return undefined;
+
+  const rootKey = toPosix(relative(workspaceReal, absoluteRoot));
+  const under = (key) => rootKey === "" || rootKey === "." || key === rootKey || key.startsWith(`${rootKey}/`);
+  const history = {};
+  for (const [pathInRepo, entry] of fileHistory(repo)) {
+    const key = toPosix(relative(workspaceReal, resolve(repo, pathInRepo)));
+    if (!key || key.startsWith("..") || !under(key)) continue;
+    history[key] = entry.revised ? { created: entry.created, revised: entry.revised } : { created: entry.created };
+  }
+  return history;
+}
+
+/**
+ * Every path in the checkout with its first and last commit, renames
+ * followed: a file moved keeps the commit that first added it under its old
+ * name, and the move counts as a revision. Paths are relative to the
+ * repository, forward slashes.
+ *
+ * @param {string} repo
+ * @returns {Map<string, {created: Commit, revised: Commit | null}>}
+ */
+export function fileHistory(repo) {
+  const key = resolve(repo);
+  if (cache.has(key)) return cache.get(key);
+  const log = git(key, [
+    "log", "--reverse", "--name-status", "-M", "--no-color",
+    `--format=${RECORD}%H${FIELD}%an${FIELD}%cI`,
+  ]);
+  const history = parseLog(log);
+  cache.set(key, history);
+  return history;
+}
+
+/** @param {string} log */
+export function parseLog(log) {
+  const history = new Map();
+  for (const record of log.split(RECORD)) {
+    if (!record.trim()) continue;
+    const [header, ...lines] = record.split("\n");
+    const [sha, author, date] = header.split(FIELD);
+    if (!sha) continue;
+    const commit = { commit: sha, author, date };
+    for (const line of lines) {
+      const match = /^([A-Z])\d*\t([^\t]+)(?:\t([^\t]+))?$/.exec(line);
+      if (!match) continue;
+      const [, status, first, second] = match;
+      if (status === "D") {
+        history.delete(first);
+      } else if (status === "R" && second) {
+        const moved = history.get(first) ?? { created: commit, revised: null };
+        history.delete(first);
+        history.set(second, { created: moved.created, revised: commit });
+      } else {
+        const target = status === "C" && second ? second : first;
+        const known = history.get(target);
+        if (known) history.set(target, { created: known.created, revised: commit });
+        else history.set(target, { created: commit, revised: null });
+      }
+    }
+  }
+  return history;
+}
+
+/** Forget what was read, for a test that commits between two reads. */
+export function forgetHistory() {
+  cache.clear();
+}
+
+/** The working tree a directory belongs to, or "" when no repository holds it. */
+export function repositoryOf(dir) {
+  return git(dir, ["rev-parse", "--show-toplevel"]);
+}
+
+function git(dir, args) {
+  try {
+    return execFileSync("git", ["-C", dir, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 256 * 1024 * 1024,
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function toPosix(path) {
+  return path.split(sep).join("/");
+}
+
+/** @typedef {{commit: string, author: string, date: string}} Commit */

package/scripts/history.test.mjs

@@ -0,0 +1,110 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+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";
+
+const created = [];
+afterEach(() => {
+  forgetHistory();
+  for (const path of created.splice(0)) rmSync(path, { recursive: true, force: true });
+});
+
+const ADA = { GIT_AUTHOR_NAME: "Ada Lovelace", GIT_AUTHOR_EMAIL: "ada@example.com", GIT_COMMITTER_NAME: "Ada Lovelace", GIT_COMMITTER_EMAIL: "ada@example.com" };
+const GRACE = { GIT_AUTHOR_NAME: "Grace Hopper", GIT_AUTHOR_EMAIL: "grace@example.com", GIT_COMMITTER_NAME: "Grace Hopper", GIT_COMMITTER_EMAIL: "grace@example.com" };
+
+function repository() {
+  const root = mkdtempSync(join(tmpdir(), "portolan-history-"));
+  created.push(root);
+  const git = (args, who = ADA, date = "2026-01-01T09:00:00Z") =>
+    execFileSync("git", ["-C", root, ...args], {
+      encoding: "utf8",
+      env: { ...process.env, ...who, GIT_AUTHOR_DATE: date, GIT_COMMITTER_DATE: date },
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  const write = (name, contents) => {
+    mkdirSync(join(root, name, ".."), { recursive: true });
+    writeFileSync(join(root, name), contents);
+  };
+  git(["init", "-q"]);
+  return { root, git, write };
+}
+
+describe("historyFor", () => {
+  it("gives every file its first commit, its last, and follows a move", () => {
+    const { root, git, write } = repository();
+    write("docs/adr/0001-first.md", "# 1. First\n");
+    write("docs/adr/0002-second.md", "# 2. Second\n");
+    git(["add", "."]);
+    git(["commit", "-q", "-m", "two records"]);
+    write("docs/adr/0002-second.md", "# 2. Second\n\nReworded.\n");
+    git(["commit", "-q", "-am", "reword"], GRACE, "2026-01-03T17:30:00Z");
+    mkdirSync(join(root, "adr"));
+    git(["mv", "docs/adr/0001-first.md", "adr/0001-first.md"]);
+    git(["commit", "-q", "-m", "move"], GRACE, "2026-01-05T08:00:00Z");
+
+    const history = historyFor(root, ".");
+    expect(Object.keys(history).sort()).toEqual(["adr/0001-first.md", "docs/adr/0002-second.md"]);
+
+    const second = history["docs/adr/0002-second.md"];
+    expect(second.created).toMatchObject({ author: "Ada Lovelace", date: "2026-01-01T09:00:00Z" });
+    expect(second.created.commit).toHaveLength(40);
+    expect(second.revised).toMatchObject({ author: "Grace Hopper", date: "2026-01-03T17:30:00Z" });
+    expect(second.revised.commit).not.toBe(second.created.commit);
+
+    const moved = history["adr/0001-first.md"];
+    expect(moved.created).toMatchObject({ author: "Ada Lovelace", date: "2026-01-01T09:00:00Z" });
+    expect(moved.revised).toMatchObject({ author: "Grace Hopper", date: "2026-01-05T08:00:00Z" });
+  });
+
+  it("keeps only the root's files, and no revision for a file committed once", () => {
+    const { root, git, write } = repository();
+    write("docs/adr/0001-first.md", "# 1. First\n");
+    write("README.md", "# Repo\n");
+    git(["add", "."]);
+    git(["commit", "-q", "-m", "one"]);
+
+    expect(Object.keys(historyFor(root, "docs/adr"))).toEqual(["docs/adr/0001-first.md"]);
+    expect(historyFor(root, "docs/adr")["docs/adr/0001-first.md"]).not.toHaveProperty("revised");
+    expect(historyFor(root, "docs")).toHaveProperty("docs/adr/0001-first.md");
+  });
+
+  it("names files as a manifest below the repository root would", () => {
+    const { root, git, write } = repository();
+    write("services/auth/docs/adr/0001-first.md", "# 1. First\n");
+    git(["add", "."]);
+    git(["commit", "-q", "-m", "one"]);
+
+    expect(Object.keys(historyFor(join(root, "services/auth"), "docs/adr"))).toEqual(["docs/adr/0001-first.md"]);
+  });
+
+  it("answers undefined outside a checkout, and nothing for a deleted file", () => {
+    const bare = mkdtempSync(join(tmpdir(), "portolan-history-bare-"));
+    created.push(bare);
+    expect(historyFor(bare, ".")).toBeUndefined();
+
+    const { root, git, write } = repository();
+    write("gone.md", "x\n");
+    git(["add", "."]);
+    git(["commit", "-q", "-m", "add"]);
+    git(["rm", "-q", "gone.md"]);
+    git(["commit", "-q", "-m", "remove"]);
+    expect(fileHistory(root).size).toBe(0);
+  });
+});
+
+describe("parseLog", () => {
+  it("reads git's record, field and name-status lines", () => {
+    const log = [
+      "\x1eaaa\x1fAda\x1f2026-01-01T09:00:00Z\n\nA\tdocs/a.md\nA\tdocs/b.md\n",
+      "\x1ebbb\x1fGrace\x1f2026-01-02T09:00:00Z\n\nM\tdocs/b.md\nR100\tdocs/a.md\tadr/a.md\nC075\tdocs/b.md\tdocs/c.md\n",
+      "\x1eccc\x1fGrace\x1f2026-01-03T09:00:00Z\n\nD\tdocs/c.md\n",
+    ].join("");
+    const history = parseLog(log);
+    expect([...history.keys()].sort()).toEqual(["adr/a.md", "docs/b.md"]);
+    expect(history.get("adr/a.md")).toEqual({ created: { commit: "aaa", author: "Ada", date: "2026-01-01T09:00:00Z" }, revised: { commit: "bbb", author: "Grace", date: "2026-01-02T09:00:00Z" } });
+    expect(history.get("docs/b.md").revised.commit).toBe("bbb");
+  });
+});