ancient-fences 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcin1000
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/readme-banner.png">
+  <img src="assets/readme-banner-light.png" alt="Ancient Fences" width="100%">
+</picture>
+
+# Ancient Fences
+
+**Find the code you wrote because of someone else's bug. Then check whether that bug is still there.**
+
+Dependabot bumps the version. Nobody removes the workaround you wrote because
+the old version was broken.
+
+```bash
+# Not on npm yet, so run it straight from this repository:
+npx github:Marcin1000/ancient-fences .           # what is standing in this codebase
+npx github:Marcin1000/ancient-fences . --check   # and whether the reasons still hold
+```
+
+Once it is published to npm the command becomes `npx ancient-fences .`. Until
+then the line above is the one that works, and this README says so rather than
+promising something that returns a 404.
+
+## The problem
+
+You hit a bug in a library. You write code around it and, if you are decent, leave a note:
+
+```js
+// Workaround for https://github.com/some/lib/issues/2500 (remove when fixed)
+```
+
+Then the bug gets fixed. The issue is closed. The library is replaced. And
+nothing happens, because there is no link between someone else's tracker and
+your code. The workaround stays forever, and after two years nobody dares
+touch it: the note says "bug", so maybe the bug is still there.
+
+This is Chesterton's Fence at industrial scale. The code knows the fence is
+there. Git knows how long it has stood. Nobody checks whether the reason
+still exists.
+
+## Real example
+
+In `webpack`, `test/configCases/plugins/terser-plugin/extract.js:3`:
+
+```js
+// ⚠️ move the following comment back to the top
+// https://github.com/mishoo/UglifyJS2/issues/2500
+```
+
+Written **2017-11-08**. The referenced issue is closed. Webpack dropped
+UglifyJS for terser in 2018. The string `uglify` does not appear in its
+`package.json` even once. The directory is literally named `terser-plugin`.
+The fence has stood untouched for **8.8 years**, guarding a hole in a road
+that no longer exists.
+
+Two runs, full clones, August 2026:
+
+| Repository | Fences | Because of someone else's bug | No reason recorded | Oldest |
+|---|---|---|---|---|
+| puppeteer/puppeteer | 99 | 63 | 29 | 7.9 yr |
+| webpack/webpack | 354 | 65 | 288 | 8.8 yr |
+
+Both are well-maintained projects by good engineers. That is the point.
+
+## What it finds
+
+| Kind | What it means | The repair when the reason dies |
+|---|---|---|
+| `code` | code written because of someone else's bug | delete the workaround |
+| `docs` | a documented limitation pointing at an issue | the docs now lie, so fix them |
+| `deadline` | a date written into a comment | the date passed, revisit |
+| `unmarked` | clearly a workaround, no recorded reason | write the reason down, or remove it |
+
+Trackers understood: GitHub issues and pull requests, Chromium (`crbug.com`),
+Mozilla Bugzilla, WebKit.
+
+## Verdicts
+
+`remove` · `upgrade first` · `review` · `still valid` · `unchecked` · `unmarked`
+
+A closed issue is weak evidence on its own. With `--check`, Ancient Fences also
+reads the version the fix shipped in (a release milestone, or "fixed in 1.2.3"
+in the issue) and compares it against your lockfile:
+
+```
+VERDICT:  remove (fix shipped in 0.30.0 (milestone), you run sharp 0.33.1)
+VERDICT:  upgrade first (fix shipped in 0.34.0, but sharp is pinned at 0.33.1)
+```
+
+Those are two different jobs. The first is code you can delete this afternoon.
+The second is the more uncomfortable finding: you are still paying to maintain
+a workaround for a bug that was fixed years ago, because nobody upgraded.
+
+`package-lock.json`, `yarn.lock` and `pnpm-lock.yaml` are read when present. No
+lockfile means the tool says less, never something false.
+
+**An unknown issue state never produces `still valid`.** Not knowing is not a
+green light. A tool that reassures you without grounds is worse than no tool.
+(The test enforcing this caught a real bug on the prototype's first run.)
+
+## Options
+
+```
+--check             ask GitHub whether the referenced issues are still open
+                    (set GITHUB_TOKEN to lift the 60 requests/hour limit)
+--report[=file]     write a shareable HTML report (default: ancient-fences.html)
+--tasks[=file]      write the dead fences as instructions for a coding agent
+--api-base=URL      alternate API (GitHub Enterprise, or a mock in tests)
+--json              full machine-readable output
+--no-blame          skip fence age (faster, tells you less)
+```
+
+Issue states are cached in `.ancient-fences-cache.json` next to the scanned
+repository. Add it to your `.gitignore`.
+
+## Working with an agent
+
+Ancient Fences does not edit your code, and that is deliberate. Knowing that a
+fence is dead is the scarce part; every editor now ships something that can do
+the deleting. So `--tasks` writes the verified findings as work:
+
+```bash
+npx github:Marcin1000/ancient-fences . --check --tasks
+```
+
+You get a markdown file with one entry per dead fence: the file and line, the
+reason originally recorded, what proves it no longer holds, and the instruction
+("remove the workaround and the comment, then run the test suite"). Point Claude
+Code, Cursor, Copilot or your own script at it. The tests are the safety net,
+which is why the instruction always ends there.
+
+## Tests
+
+```bash
+npm test
+```
+
+The tracker tests run against a mock GitHub API on localhost, so they work
+offline and without a token.
+
+## Status
+
+Early, but real. Detection, ageing, issue checking, fix-version matching against
+the lockfile, the HTML report and agent tasks all work and are covered by tests
+that run offline. Not there yet: `@ancient premise:` annotations for conditions
+that live outside a tracker (a contract, a vendor limit, a certificate expiry),
+trackers other than GitHub and Chromium, and a GitHub Action that comments on
+pull requests.
+
+## Ancient Code
+
+Ancient Fences answers one question about one repository. The same blindness
+applies to everything else nobody re-checks in a long-running codebase: what
+was already paid for, which parts only one person understands, whether the
+whole thing could be handed to another team at all. That is
+[Ancient Code](https://ancientcode.net). This tool is its open-source front door.
+
+MIT licensed.

package/bin/ancient-fences.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { resolve, basename, join } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+import { walkFiles } from '../src/walk.mjs';
+import { detectFences } from '../src/detect.mjs';
+import { blameAll } from '../src/age.mjs';
+import { checkGithubRefs, verdict } from '../src/tracker.mjs';
+import { renderText, renderHtml, renderTasks, summarize } from '../src/report.mjs';
+import { readInstalled } from '../src/lockfile.mjs';
+
+const args = process.argv.slice(2);
+
+// "ancient-fences ." has to scan the current directory. The first version read
+// any first argument as a command name, so the documented form printed the
+// help text and did nothing. Only the words below are commands; everything
+// else is a path.
+const COMMANDS = new Set(['scan', 'help']);
+const cmd = args[0] && COMMANDS.has(args[0]) ? args[0] : 'scan';
+const flags = args.filter((a) => a.startsWith('--'));
+const has = (f) => flags.some((x) => x === f);
+const value = (f) => {
+  const hit = flags.find((x) => x.startsWith(`${f}=`));
+  return hit ? hit.slice(f.length + 1) : null;
+};
+const positional = args.filter((a) => !a.startsWith('--') && !COMMANDS.has(a));
+const root = resolve(positional[0] ?? process.cwd());
+
+if (cmd !== 'scan') {
+  const usage = `ancient-fences: find the code you wrote because of someone else's bug,
+then check whether that bug is still there.
+
+  npx ancient-fences [path] [options]
+
+  --check             ask GitHub whether the referenced issues are still open
+                      (set GITHUB_TOKEN to lift the 60 requests/hour limit)
+  --report[=file]     write a shareable HTML report (default: ancient-fences.html)
+  --tasks[=file]      write the dead fences as instructions for a coding agent
+  --api-base=URL      alternate API (GitHub Enterprise, or a mock in tests)
+  --json              full machine-readable output
+  --no-blame          skip fence age (faster, tells you less)
+`;
+  console.log(usage);
+  process.exit(cmd === 'help' || has('--help') ? 0 : 1);
+}
+
+const fences = [];
+for await (const file of walkFiles(root)) {
+  fences.push(...detectFences(file.path, file.text));
+}
+
+if (!has('--no-blame')) await blameAll(root, fences);
+
+let states = new Map();
+const checking = has('--check');
+if (checking) {
+  const ids = new Set();
+  for (const f of fences) {
+    if (f.premise.type === 'tracker') {
+      for (const r of f.premise.refs) if (r.id.startsWith('github:')) ids.add(r.id);
+    }
+  }
+  states = await checkGithubRefs([...ids], {
+    apiBase: value('--api-base') ?? undefined,
+    cachePath: join(root, '.ancient-fences-cache.json'),
+  });
+  // What the lockfile says you actually run turns "the issue is closed" into
+  // "you can delete this today", or into "upgrade before you can".
+  const installed = await readInstalled(root);
+  for (const f of fences) f.verdict = verdict(f, states, installed);
+}
+
+const summary = summarize(fences, states);
+const name = basename(root);
+
+const reportFlag = flags.find((f) => f === '--report' || f.startsWith('--report='));
+if (reportFlag) {
+  const out = resolve(value('--report') ?? 'ancient-fences.html');
+  await writeFile(out, renderHtml(fences, summary, name, checking), 'utf8');
+  console.error(`report written to ${out}`);
+}
+
+const tasksFlag = flags.find((f) => f === '--tasks' || f.startsWith('--tasks='));
+if (tasksFlag) {
+  const out = resolve(value('--tasks') ?? 'ancient-fences-tasks.md');
+  await writeFile(out, renderTasks(fences, name), 'utf8');
+  console.error(`agent tasks written to ${out}`);
+}
+
+if (has('--json')) {
+  console.log(JSON.stringify({ repo: root, summary, fences }, null, 2));
+} else {
+  console.log(renderText(fences, summary, name, checking));
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "ancient-fences",
+  "version": "0.1.0",
+  "description": "Finds the code you wrote because of someone else's bug, and checks whether that bug is still there.",
+  "type": "module",
+  "bin": {
+    "ancient-fences": "bin/ancient-fences.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "technical-debt",
+    "workaround",
+    "chesterton-fence",
+    "code-audit",
+    "maintenance",
+    "stale-code"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "node test/detect.test.mjs && node test/tracker.test.mjs && node test/versions.test.mjs && node test/lockfile.test.mjs && node test/cli.test.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Marcin1000/ancient-fences.git"
+  },
+  "homepage": "https://ancientcode.net",
+  "bugs": {
+    "url": "https://github.com/Marcin1000/ancient-fences/issues"
+  },
+  "author": "Marcin Przybylski"
+}

package/src/age.mjs

@@ -0,0 +1,35 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+/**
+ * How long the fence has stood: when anyone last touched this line.
+ * This is the one number nobody can fake. A comment can lie, blame cannot.
+ */
+export async function blameYear(repo, file, line) {
+  try {
+    const { stdout } = await run(
+      'git',
+      ['blame', '--porcelain', '-L', `${line},${line}`, '--', file],
+      { cwd: repo, maxBuffer: 1024 * 1024 },
+    );
+    const m = stdout.match(/^author-time (\d+)$/m);
+    if (!m) return null;
+    return new Date(Number(m[1]) * 1000);
+  } catch {
+    return null;
+  }
+}
+
+export async function blameAll(repo, fences, concurrency = 8) {
+  let i = 0;
+  const workers = Array.from({ length: concurrency }, async () => {
+    while (i < fences.length) {
+      const f = fences[i++];
+      f.lastTouched = await blameYear(repo, f.file, f.line);
+    }
+  });
+  await Promise.all(workers);
+  return fences;
+}

package/src/detect.mjs

@@ -0,0 +1,129 @@
+// Finding "fences": code that exists because of an external condition.
+// Chesterton's Fence at industrial scale. The fence stands long after the
+// reason for building it is gone, and nobody dares take it down.
+
+const FENCE_WORDS = [
+  'workaround', 'work around', 'work-around',
+  'hack', 'kludge', 'monkey patch', 'monkeypatch', 'monkey-patch',
+  'temporary', 'temporarily', 'for now',
+  'remove when', 'remove once', 'remove after', 'remove this',
+  'revert when', 'revert once', 'drop when', 'delete when',
+  'can be removed', 'no longer needed', 'once fixed', 'when fixed',
+  'until ', 'due to a bug', 'due to bug', 'because of a bug',
+  'broken in', 'regression', 'upstream bug', 'known bug',
+  'polyfill', 'shim ', 'pinned because', 'pin because', 'do not upgrade',
+];
+
+// External trackers: the condition lives outside this repository, which is
+// exactly why nobody notices when it stops being true.
+const REF_PATTERNS = [
+  { kind: 'github', re: /https?:\/\/github\.com\/([\w.-]+)\/([\w.-]+)\/(?:issues|pull)\/(\d+)/gi,
+    id: (m) => `github:${m[1]}/${m[2]}#${m[3]}`, url: (m) => m[0] },
+  { kind: 'chromium', re: /(?:https?:\/\/)?(?:crbug\.com\/|bugs\.chromium\.org\/p\/chromium\/issues\/detail\?id=)(\d+)/gi,
+    id: (m) => `crbug:${m[1]}`, url: (m) => `https://crbug.com/${m[1]}` },
+  { kind: 'mozilla', re: /bugzilla\.mozilla\.org\/show_bug\.cgi\?id=(\d+)/gi,
+    id: (m) => `bugzilla:${m[1]}`, url: (m) => m[0] },
+  { kind: 'webkit', re: /bugs\.webkit\.org\/show_bug\.cgi\?id=(\d+)/gi,
+    id: (m) => `webkit:${m[1]}`, url: (m) => m[0] },
+];
+
+const DATE_RE = /\b(?:until|after|before|remove|revisit|expires?|expire[sd]?|do)\b[^\n]{0,24}?(20\d{2})-(\d{2})(?:-(\d{2}))?/i;
+const VERSION_RE = /\b(?:until|once|when|fixed in|released in|requires?|needs?)\b[^\n]{0,40}?\bv?(\d+\.\d+(?:\.\d+)?)/i;
+
+const COMMENT_START = /^\s*(?:\/\/+|#+|\*|\/\*|--|;;?|<!--|%|"""|''')/;
+
+function isCommentish(line) {
+  return COMMENT_START.test(line);
+}
+
+// Group adjacent comment lines into blocks. Deliberately language-agnostic:
+// this has to work on any text file, including languages we have never seen.
+export function commentBlocks(text) {
+  const lines = text.split('\n');
+  const blocks = [];
+  let cur = null;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const inlineComment = !isCommentish(line) && /(?:\/\/|#|\/\*)\s*\S/.test(line) && !/['"`]/.test(line);
+    if (isCommentish(line) || inlineComment) {
+      if (!cur) cur = { start: i + 1, end: i + 1, lines: [] };
+      cur.end = i + 1;
+      cur.lines.push(line.trim());
+    } else if (cur) {
+      blocks.push(cur);
+      cur = null;
+    }
+  }
+  if (cur) blocks.push(cur);
+  return blocks;
+}
+
+function fenceWordsIn(text) {
+  const low = text.toLowerCase();
+  return FENCE_WORDS.filter((w) => low.includes(w));
+}
+
+function refsIn(text) {
+  const found = [];
+  for (const p of REF_PATTERNS) {
+    p.re.lastIndex = 0;
+    let m;
+    while ((m = p.re.exec(text)) !== null) {
+      const id = p.id(m);
+      if (!found.some((f) => f.id === id)) found.push({ id, kind: p.kind, url: p.url(m) });
+    }
+  }
+  return found;
+}
+
+/**
+ * Fences found in a single file.
+ * A fence is a comment showing that code exists because of an external
+ * condition: someone else's bug, a version, a deadline.
+ */
+export function detectFences(file, text) {
+  const out = [];
+  for (const block of commentBlocks(text)) {
+    const body = block.lines.join(' ').replace(/\s+/g, ' ').slice(0, 600);
+    if (body.length < 12) continue;
+
+    const words = fenceWordsIn(body);
+    const refs = refsIn(body);
+    const dateM = body.match(DATE_RE);
+    const verM = body.match(VERSION_RE);
+
+    // A link to an external tracker is itself the premise: someone wrote this
+    // code because of that bug. Words like "workaround" only confirm it.
+    if (refs.length === 0 && words.length === 0) continue;
+
+    let premise;
+    if (refs.length > 0) premise = { type: 'tracker', refs };
+    else if (dateM) {
+      const iso = `${dateM[1]}-${dateM[2]}-${dateM[3] ?? '01'}`;
+      premise = { type: 'date', date: iso, overdue: new Date(iso) < new Date() };
+    } else if (verM) premise = { type: 'version', version: verM[1] };
+    else premise = { type: 'none' };
+
+    // The class says what breaks when the premise dies, and those are two
+    // different repairs, which is why the distinction earns its keep.
+    const isDoc = /^\s*(?:\/\*\*|\*)/.test(block.lines[0] ?? '')
+      || /@remarks|@param|@returns|\{@link/.test(body);
+    let kind;
+    if (refs.length > 0 && (words.length > 0 || !isDoc)) kind = 'code';
+    else if (refs.length > 0) kind = 'docs';
+    else if (premise.type === 'date') kind = 'deadline';
+    else kind = 'unmarked';
+
+    out.push({
+      file,
+      line: block.start,
+      endLine: block.end,
+      text: body.replace(/^\W+/, '').slice(0, 240),
+      words: words.slice(0, 3),
+      premise,
+      kind,
+      confidence: refs.length > 0 ? 'high' : premise.type === 'date' ? 'medium' : 'low',
+    });
+  }
+  return out;
+}

package/src/lockfile.mjs

@@ -0,0 +1,85 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * What is actually installed, read from whatever lockfile the project keeps.
+ * Deliberately forgiving: a lockfile we cannot parse means we say less, never
+ * that we say something wrong.
+ */
+export async function readInstalled(root) {
+  const installed = new Map();
+  await npmLock(root, installed);
+  await yarnLock(root, installed);
+  await pnpmLock(root, installed);
+  return installed;
+}
+
+async function npmLock(root, out) {
+  let raw;
+  try {
+    raw = JSON.parse(await readFile(join(root, 'package-lock.json'), 'utf8'));
+  } catch {
+    return;
+  }
+  // lockfileVersion 2 and 3 keep everything under "packages", keyed by path.
+  for (const [path, entry] of Object.entries(raw.packages ?? {})) {
+    if (!path || !entry?.version) continue;
+    const name = entry.name ?? path.replace(/^.*node_modules\//, '');
+    if (name) keep(out, name, entry.version);
+  }
+  for (const [name, entry] of Object.entries(raw.dependencies ?? {})) {
+    if (entry?.version) keep(out, name, entry.version);
+  }
+}
+
+async function yarnLock(root, out) {
+  let text;
+  try {
+    text = await readFile(join(root, 'yarn.lock'), 'utf8');
+  } catch {
+    return;
+  }
+  let current = null;
+  for (const line of text.split('\n')) {
+    const header = line.match(/^"?((?:@[^/\s"]+\/)?[^@\s"]+)@/);
+    if (header && !line.startsWith(' ')) {
+      current = header[1];
+      continue;
+    }
+    const version = line.match(/^\s+version:?\s+"?([\w.\-+]+)"?/);
+    if (version && current) {
+      keep(out, current, version[1]);
+      current = null;
+    }
+  }
+}
+
+async function pnpmLock(root, out) {
+  let text;
+  try {
+    text = await readFile(join(root, 'pnpm-lock.yaml'), 'utf8');
+  } catch {
+    return;
+  }
+  for (const line of text.split('\n')) {
+    const m = line.match(/^\s{2}\/?((?:@[^/\s]+\/)?[^/\s@]+)[@/](\d+\.\d+\.\d+[\w.\-+]*)/);
+    if (m) keep(out, m[1], m[2]);
+  }
+}
+
+/** Keep the highest version seen: transitive copies of a package are common. */
+function keep(map, name, version) {
+  const prev = map.get(name);
+  if (!prev) {
+    map.set(name, version);
+    return;
+  }
+  const a = prev.split('.').map(Number);
+  const b = version.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] ?? 0) !== (b[i] ?? 0)) {
+      if ((b[i] ?? 0) > (a[i] ?? 0)) map.set(name, version);
+      return;
+    }
+  }
+}

package/src/report.mjs

@@ -0,0 +1,207 @@
+const YEAR = 365.25 * 24 * 3600 * 1000;
+
+export function yearsSince(date) {
+  if (!date) return null;
+  return (Date.now() - date.getTime()) / YEAR;
+}
+
+export const KIND_LABEL = {
+  code: 'code written because of someone else’s bug',
+  docs: 'documented limitation pointing at an issue',
+  deadline: 'deadline written into a comment',
+  unmarked: 'fence with no sign: nobody recorded why it is there',
+};
+
+export function summarize(fences, states = new Map()) {
+  const byKind = { code: 0, docs: 0, deadline: 0, unmarked: 0 };
+  const trackers = new Set();
+  let overdue = 0;
+  let old = 0;
+  let oldest = null;
+  for (const f of fences) {
+    byKind[f.kind]++;
+    if (f.premise.type === 'tracker') for (const r of f.premise.refs) trackers.add(r.id);
+    if (f.premise.type === 'date' && f.premise.overdue) overdue++;
+    const y = yearsSince(f.lastTouched);
+    if (y !== null && y >= 3) old++;
+    if (y !== null && (oldest === null || y > oldest)) oldest = y;
+  }
+  const verdicts = {};
+  for (const f of fences) {
+    if (!f.verdict) continue;
+    verdicts[f.verdict.level] = (verdicts[f.verdict.level] ?? 0) + 1;
+  }
+  return { total: fences.length, byKind, trackers: trackers.size, overdue, old, oldest, verdicts, checked: states.size };
+}
+
+export function ranked(fences) {
+  return fences
+    .filter((f) => f.premise.type === 'tracker' || (f.premise.type === 'date' && f.premise.overdue))
+    .sort((a, b) => (yearsSince(b.lastTouched) ?? 0) - (yearsSince(a.lastTouched) ?? 0));
+}
+
+function premiseOf(f) {
+  return f.premise.type === 'tracker'
+    ? f.premise.refs.map((r) => r.id).join(', ')
+    : `deadline ${f.premise.date} (passed)`;
+}
+
+export function renderText(fences, summary, repoName, checked = false) {
+  const L = [];
+  const n = (x) => String(x).padStart(4);
+  L.push('');
+  L.push(`  ANCIENT FENCES · ${repoName}`);
+  L.push('  ' + '='.repeat(70));
+  L.push(`  ${n(summary.total)}  fences standing in this codebase`);
+  L.push(`  ${n(summary.byKind.code)}  code written because of someone else's bug`);
+  L.push(`  ${n(summary.byKind.docs)}  documented limitations pointing at an issue`);
+  L.push(`  ${n(summary.byKind.deadline)}  deadlines in comments (passed: ${summary.overdue})`);
+  L.push(`  ${n(summary.byKind.unmarked)}  fences with no sign`);
+  L.push('  ' + '-'.repeat(70));
+  L.push(`  ${n(summary.trackers)}  distinct external issues to check`);
+  L.push(`  ${n(summary.old)}  fences untouched for 3+ years`);
+  if (summary.oldest !== null) L.push(`  ${n(Math.round(summary.oldest))}  years old is the oldest one`);
+  L.push('');
+
+  if (checked) {
+    L.push('  VERDICTS');
+    L.push('  ' + '-'.repeat(70));
+    for (const [level, count] of Object.entries(summary.verdicts).sort((a, b) => b[1] - a[1])) {
+      L.push(`  ${String(count).padStart(4)}  ${level}`);
+    }
+    L.push('');
+  }
+
+  L.push('  CHECK THESE FIRST  (longest untouched)');
+  L.push('  ' + '='.repeat(70));
+  for (const f of ranked(fences).slice(0, 15)) {
+    const y = yearsSince(f.lastTouched);
+    const age = y === null ? '   ?  ' : `${y.toFixed(1)} yr`;
+    L.push(`  ${age.padStart(7)}  ${f.file}:${f.line}   [${f.kind}]`);
+    L.push(`           reason:   ${premiseOf(f)}`);
+    L.push(`           comment:  ${f.text.slice(0, 92)}`);
+    if (f.verdict) L.push(`           VERDICT:  ${f.verdict.level} (${f.verdict.why})`);
+    L.push('');
+  }
+  L.push('  Every closed issue above is code you can delete.');
+  L.push('');
+  return L.join('\n');
+}
+
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+
+/**
+ * A standalone report meant to be forwarded to whoever pays for the codebase.
+ * Developers find the fences; someone else decides what they cost.
+ */
+export function renderHtml(fences, summary, repoName, checked = false) {
+  const rows = ranked(fences).slice(0, 40).map((f) => {
+    const y = yearsSince(f.lastTouched);
+    const v = f.verdict;
+    return `<tr>
+      <td class="num">${y === null ? '-' : y.toFixed(1) + ' yr'}</td>
+      <td><code>${esc(f.file)}:${f.line}</code><p>${esc(f.text.slice(0, 130))}</p></td>
+      <td class="num">${esc(premiseOf(f))}</td>
+      <td>${v ? `<span class="v v-${esc(v.level.replace(/\s+/g, '-'))}">${esc(v.level)}</span><p>${esc(v.why)}</p>` : '<span class="v">not checked</span>'}</td>
+    </tr>`;
+  }).join('\n');
+
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Ancient Fences: ${esc(repoName)}</title>
+<style>
+:root{--ground:#0F1216;--surface:#171C22;--surface2:#1E242B;--line:#2B333B;--ink:#E7E1D4;--dim:#A7A69C;--muted:#83877F;--gold:#E0A45C;--inst:#8FC3D2}
+@media (prefers-color-scheme:light){:root{--ground:#E3E2DC;--surface:#EDEBE4;--surface2:#F3F1EB;--line:#CFCCC1;--ink:#1A1E22;--dim:#4A4F53;--muted:#6B6F68;--gold:#8F5B18;--inst:#2E6B7C}}
+*{box-sizing:border-box}
+body{margin:0;background:var(--ground);color:var(--ink);font:16px/1.6 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;-webkit-font-smoothing:antialiased}
+.wrap{max-width:68rem;margin:0 auto;padding:0 clamp(1rem,4vw,2.5rem)}
+header{border-bottom:1px solid var(--line);padding:3rem 0 2rem}
+h1{font:300 clamp(2rem,5vw,3.2rem)/1.05 ui-serif,Georgia,serif;letter-spacing:-.02em;margin:0}
+.sub{color:var(--dim);margin:.7rem 0 0}
+.mono,code,.num{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
+.mono{font-size:.7rem;letter-spacing:.14em;text-transform:uppercase;color:var(--muted)}
+.stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(9rem,1fr));gap:1px;background:var(--line);border:1px solid var(--line);margin:2.5rem 0}
+.stat{background:var(--surface);padding:1.1rem 1.2rem;display:flex;flex-direction:column;gap:.3rem}
+.stat b{font:400 2rem/1 ui-monospace,monospace;color:var(--gold);font-variant-numeric:tabular-nums}
+.stat span{font-size:.78rem;color:var(--dim);line-height:1.35}
+h2{font:300 1.6rem/1.1 ui-serif,Georgia,serif;margin:2.5rem 0 1rem}
+.scroll{overflow-x:auto;border:1px solid var(--line);background:var(--surface)}
+table{border-collapse:collapse;width:100%;min-width:46rem;font-size:.88rem}
+th,td{text-align:left;padding:.8rem 1rem;border-bottom:1px solid var(--line);vertical-align:top}
+thead th{font-family:ui-monospace,monospace;font-size:.64rem;letter-spacing:.12em;text-transform:uppercase;color:var(--muted);font-weight:400;background:var(--surface2);white-space:nowrap}
+td p{margin:.35rem 0 0;color:var(--dim);font-size:.82rem}
+td.num{white-space:nowrap;color:var(--dim);font-variant-numeric:tabular-nums;font-size:.8rem}
+code{font-size:.82rem;color:var(--ink)}
+.v{font-family:ui-monospace,monospace;font-size:.7rem;letter-spacing:.06em;text-transform:uppercase;color:var(--muted)}
+.v-remove{color:var(--gold)}
+.v-review{color:var(--inst)}
+footer{border-top:1px solid var(--line);margin-top:3rem;padding:2rem 0 4rem;color:var(--muted);font-size:.85rem}
+footer strong{color:var(--ink)}
+footer p{max-width:62ch}
+</style></head><body>
+<header><div class="wrap">
+  <p class="mono">Ancient Fences · ${esc(new Date().toISOString().slice(0, 10))}</p>
+  <h1>${esc(repoName)}</h1>
+  <p class="sub">Code that exists because of an external problem, and whether that problem is still there.</p>
+</div></header>
+<main class="wrap">
+  <div class="stats">
+    <div class="stat"><b>${summary.total}</b><span>fences standing</span></div>
+    <div class="stat"><b>${summary.byKind.code}</b><span>written because of someone else's bug</span></div>
+    <div class="stat"><b>${summary.trackers}</b><span>external issues to check</span></div>
+    <div class="stat"><b>${summary.old}</b><span>untouched for 3+ years</span></div>
+    <div class="stat"><b>${summary.oldest === null ? '-' : Math.round(summary.oldest)}</b><span>years, the oldest one</span></div>
+  </div>
+  <h2>Check these first</h2>
+  <div class="scroll"><table>
+    <thead><tr><th>Untouched</th><th>Where</th><th>Reason given</th><th>${checked ? 'Verdict' : 'State'}</th></tr></thead>
+    <tbody>${rows}</tbody>
+  </table></div>
+</main>
+<footer><div class="wrap">
+  <p><strong>This is one repository and one kind of risk.</strong> The same blindness applies to everything else nobody re-checks: what was already paid for, which parts only one person understands, whether this codebase could be handed to another team at all. That is what Ancient Code measures.</p>
+  <p style="margin-top:1rem">Generated by <strong>Ancient Fences</strong>. Open source, MIT.</p>
+</div></footer>
+</body></html>`;
+}
+
+/**
+ * The dead fences, written as work for whatever agent the team already uses.
+ * Ancient Fences does not edit code: knowing a fence is dead is the scarce
+ * part, and every editor now ships something that can do the deleting.
+ */
+export function renderTasks(fences, repoName) {
+  const dead = fences.filter((f) => f.verdict && (f.verdict.level === 'remove' || f.verdict.level === 'upgrade first'));
+  const L = [];
+  L.push(`# Dead fences in ${repoName}`);
+  L.push('');
+  L.push(`Each item below is code kept alive by a condition that no longer holds.`);
+  L.push(`Verified against the referenced tracker${dead.some((f) => /shipped in/.test(f.verdict.why)) ? ' and the lockfile' : ''}.`);
+  L.push('');
+  if (dead.length === 0) {
+    L.push('Nothing to remove. Run with --check first if you have not.');
+    return L.join('\n');
+  }
+  dead.forEach((f, i) => {
+    const y = yearsSince(f.lastTouched);
+    L.push(`## ${i + 1}. ${f.file}:${f.line}`);
+    L.push('');
+    L.push(`- Recorded reason: ${premiseOf(f)}`);
+    L.push(`- Current state: ${f.verdict.why}`);
+    if (y !== null) L.push(`- Untouched for: ${y.toFixed(1)} years`);
+    L.push(`- Comment says: ${f.text.slice(0, 160)}`);
+    L.push('');
+    if (f.verdict.level === 'upgrade first') {
+      L.push(`Task: do not remove this yet. Upgrade the package to the version named above, run the test suite, and only then delete the workaround and this comment.`);
+    } else if (f.kind === 'docs') {
+      L.push(`Task: the documented limitation no longer exists. Correct the documentation here, do not touch behaviour.`);
+    } else {
+      L.push(`Task: remove the workaround this comment describes, along with the comment. Keep the change minimal, then run the project's test suite and report what broke.`);
+    }
+    L.push('');
+  });
+  L.push('---');
+  L.push('Generated by Ancient Fences. Verify each removal with tests before merging.');
+  return L.join('\n');
+}

package/src/tracker.mjs

@@ -0,0 +1,132 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { fixVersionFrom, packageForRef, shippedStatus } from './versions.mjs';
+
+/**
+ * Checks whether the referenced issues are still open. Without this step the
+ * tool is a glorified grep; with it, it answers the question nobody asks:
+ * does the reason still exist?
+ */
+export async function checkGithubRefs(ids, opts = {}) {
+  const apiBase = opts.apiBase ?? 'https://api.github.com';
+  const token = opts.token ?? process.env.GITHUB_TOKEN ?? null;
+  const cache = await loadCache(opts.cachePath);
+  const result = new Map();
+
+  for (const id of ids) {
+    if (cache[id] && !opts.noCache) {
+      result.set(id, cache[id]);
+      continue;
+    }
+    const m = id.match(/^github:([\w.-]+)\/([\w.-]+)#(\d+)$/);
+    if (!m) continue;
+    const url = `${apiBase}/repos/${m[1]}/${m[2]}/issues/${m[3]}`;
+    const headers = { accept: 'application/vnd.github+json', 'user-agent': 'ancient-fences' };
+    if (token) headers.authorization = `Bearer ${token}`;
+
+    let res;
+    try {
+      res = await fetch(url, { headers });
+    } catch (err) {
+      result.set(id, { state: 'unknown', reason: `network: ${err.message}` });
+      continue;
+    }
+    if (res.status === 403 || res.status === 429) {
+      result.set(id, { state: 'unknown', reason: 'rate limited or no access' });
+      continue;
+    }
+    if (res.status === 404) {
+      result.set(id, { state: 'unknown', reason: 'issue missing or private' });
+      continue;
+    }
+    if (!res.ok) {
+      result.set(id, { state: 'unknown', reason: `HTTP ${res.status}` });
+      continue;
+    }
+    const body = await res.json();
+    const entry = {
+      state: body.state === 'closed' ? 'closed' : 'open',
+      closedAt: body.closed_at ?? null,
+      title: body.title ?? null,
+      isPull: Boolean(body.pull_request),
+      merged: body.pull_request?.merged_at ?? null,
+      // Kept rather than the whole payload: this is the only part that tells
+      // us whether the fix reached a release, and the cache stays small.
+      fix: fixVersionFrom(body),
+    };
+    result.set(id, entry);
+    cache[id] = entry;
+  }
+
+  await saveCache(opts.cachePath, cache);
+  return result;
+}
+
+/**
+ * What to do about it. Without a verdict the report is just a list of links.
+ * `installed` is what the lockfile says you actually run, which is what turns
+ * "the issue is closed" into "you can delete this today".
+ */
+export function verdict(fence, states, installed = new Map()) {
+  if (fence.premise.type === 'date') {
+    return fence.premise.overdue
+      ? { level: 'remove', why: `deadline ${fence.premise.date} has passed` }
+      : { level: 'still valid', why: `deadline ${fence.premise.date} not reached yet` };
+  }
+  if (fence.premise.type !== 'tracker') {
+    return { level: 'unmarked', why: 'no recorded reason for this code' };
+  }
+  // An unknown state must never come out as "still valid". Not knowing is not
+  // a green light, and a tool that reassures without grounds is worse than none.
+  const known = fence.premise.refs
+    .map((r) => states.get(r.id))
+    .filter((s) => s && s.state !== 'unknown');
+  if (known.length === 0) return { level: 'unchecked', why: 'could not determine issue state' };
+  if (known.every((s) => s.state === 'closed')) {
+    const shipped = shippedFor(fence, states, installed);
+    if (shipped?.state === 'shipped') return { level: 'remove', why: shipped.text };
+    if (shipped?.state === 'not upgraded') return { level: 'upgrade first', why: shipped.text };
+    const when = known.map((s) => s.closedAt).filter(Boolean).sort().pop();
+    return { level: 'remove', why: when ? `reason disappeared ${when.slice(0, 10)}` : 'issue closed' };
+  }
+  if (known.some((s) => s.state === 'closed')) {
+    return { level: 'review', why: 'some of the reasons are gone' };
+  }
+  return { level: 'still valid', why: 'issue still open' };
+}
+
+/**
+ * Did the fix reach a version you run? Answered only when both halves are
+ * known: a version stated by the project, and that package in your lockfile.
+ */
+export function shippedFor(fence, states, installed) {
+  if (!installed || installed.size === 0) return null;
+  for (const ref of fence.premise.refs ?? []) {
+    const state = states.get(ref.id);
+    if (!state?.fix) continue;
+    const pkg = packageForRef(ref.id, installed);
+    if (!pkg) continue;
+    const status = shippedStatus({ fix: state.fix, installed: pkg });
+    if (status) return status;
+  }
+  return null;
+}
+
+async function loadCache(path) {
+  if (!path) return {};
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+async function saveCache(path, cache) {
+  if (!path) return;
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(cache, null, 1));
+  } catch {
+    /* a missing cache is annoying, not fatal */
+  }
+}

package/src/versions.mjs

@@ -0,0 +1,77 @@
+/**
+ * A closed issue is weak evidence. The strong question is whether the fix
+ * actually shipped in a version you are running. Everything here answers that,
+ * with no dependencies and no network.
+ */
+
+const SEMVER = /(\d+)\.(\d+)(?:\.(\d+))?/;
+
+export function parseVersion(text) {
+  if (!text) return null;
+  const m = String(text).match(SEMVER);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)];
+}
+
+/** -1, 0, 1 like a comparator. Returns null when either side is unparseable. */
+export function compareVersions(a, b) {
+  const x = parseVersion(a);
+  const y = parseVersion(b);
+  if (!x || !y) return null;
+  for (let i = 0; i < 3; i++) {
+    if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Where a fix version can be stated, in descending order of trust:
+ * a release milestone, then a maintainer writing "fixed in 1.2.3" in the body.
+ */
+export function fixVersionFrom(issue) {
+  if (!issue) return null;
+  const milestone = issue.milestone?.title;
+  if (milestone && parseVersion(milestone)) {
+    return { version: milestone.match(SEMVER)[0], source: 'milestone' };
+  }
+  const body = issue.body ?? '';
+  const m = body.match(/\b(?:fixed|resolved|released|landed|shipped)\s+in\s+v?(\d+\.\d+(?:\.\d+)?)/i);
+  if (m) return { version: m[1], source: 'issue text' };
+  return null;
+}
+
+/**
+ * Guess which installed package a tracker reference belongs to.
+ * Repository name equals package name often enough to be useful, and being
+ * wrong here only means we stay silent rather than say something false.
+ */
+export function packageForRef(refId, installed) {
+  const m = refId.match(/^github:([\w.-]+)\/([\w.-]+)#\d+$/);
+  if (!m) return null;
+  const [, owner, repo] = m;
+  const candidates = [repo, repo.toLowerCase(), `@${owner}/${repo}`, `${owner}-${repo}`];
+  for (const name of candidates) {
+    if (installed.has(name)) return { name, version: installed.get(name) };
+  }
+  return null;
+}
+
+/**
+ * The three answers worth having about one fence, once versions are known.
+ * "shipped" is the only one that lets you delete code with confidence.
+ */
+export function shippedStatus({ fix, installed }) {
+  if (!fix || !installed) return null;
+  const cmp = compareVersions(installed.version, fix.version);
+  if (cmp === null) return null;
+  if (cmp >= 0) {
+    return {
+      state: 'shipped',
+      text: `fix shipped in ${fix.version} (${fix.source}), you run ${installed.name} ${installed.version}`,
+    };
+  }
+  return {
+    state: 'not upgraded',
+    text: `fix shipped in ${fix.version}, but ${installed.name} is pinned at ${installed.version}`,
+  };
+}

package/src/walk.mjs

@@ -0,0 +1,54 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, extname, relative } from 'node:path';
+
+const SKIP_DIRS = new Set([
+  '.git', 'node_modules', 'dist', 'build', 'out', 'vendor', 'target',
+  '.next', '.nuxt', 'coverage', '__pycache__', '.venv', 'venv', 'third_party',
+]);
+
+const TEXT_EXT = new Set([
+  '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.mts', '.cts',
+  '.py', '.rb', '.go', '.rs', '.java', '.kt', '.swift', '.php',
+  '.c', '.h', '.cc', '.cpp', '.hpp', '.cs', '.m', '.mm',
+  '.sh', '.bash', '.zsh', '.sql', '.css', '.scss', '.less',
+  '.yml', '.yaml', '.toml', '.tf', '.gradle', '.dockerfile', '.vue', '.svelte',
+]);
+
+const MAX_BYTES = 512 * 1024;
+
+export async function* walkFiles(root) {
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) stack.push(full);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      const ext = extname(e.name).toLowerCase();
+      if (!TEXT_EXT.has(ext) && e.name.toLowerCase() !== 'dockerfile') continue;
+      let info;
+      try {
+        info = await stat(full);
+      } catch {
+        continue;
+      }
+      if (info.size > MAX_BYTES || info.size === 0) continue;
+      let text;
+      try {
+        text = await readFile(full, 'utf8');
+      } catch {
+        continue;
+      }
+      yield { path: relative(root, full), text };
+    }
+  }
+}