ancient-fences 0.1.1 → 0.2.0

package/README.md

@@ -52,13 +52,18 @@ that no longer exists.
 
 Two runs, full clones, August 2026:
 
-| Repository | Fences | Because of someone else's bug | No reason recorded | Oldest |
+| Repository | Fences | Because of someone else's bug | Untouched 3+ years | Oldest |
 |---|---|---|---|---|
-| puppeteer/puppeteer | 99 | 63 | 29 | 7.9 yr |
-| webpack/webpack | 354 | 65 | 288 | 8.8 yr |
+| puppeteer/puppeteer | 77 | 62 | 48 | 9.1 yr |
+| webpack/webpack | 93 | 65 | 23 | 8.8 yr |
 
 Both are well-maintained projects by good engineers. That is the point.
 
+Measured on a full clone, because a shallow one cannot date a line. Numbers
+from earlier versions were higher and worse: counting the word "until" as
+evidence turned two hundred ordinary comments in webpack into findings. A
+number you have to discount is not worth printing.
+
 ## What it finds
 
 | Kind | What it means | The repair when the reason dies |
@@ -68,6 +73,15 @@ Both are well-maintained projects by good engineers. That is the point.
 | `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 |
 
+A comment counts as a fence when it links to an external tracker, or says
+something that only a fence says ("workaround", "kludge", "no longer needed",
+"do not upgrade"). Words that merely appear in fences ("until", "polyfill",
+"temporary", "regression") count only when the comment also names the
+condition: a deadline or a version. Phrases that read as prose elsewhere
+("remove this", "blocked by") count next to a `TODO`, `FIXME` or `HACK`, or
+next to a named condition. Comment markers are read per language, so `#fff` in
+a stylesheet and `a // b` in Python are not comments.
+
 Trackers understood: GitHub issues and pull requests, Chromium (`crbug.com`),
 Mozilla Bugzilla, WebKit.
 
@@ -91,6 +105,11 @@ 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.
 
+Fence age comes from `git blame`, which needs history. In a shallow clone
+(`--depth 1`, and every default CI checkout) git dates every line to the day it
+was fetched, so the report says age was not measured rather than printing a
+confident zero.
+
 **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.)
@@ -106,16 +125,35 @@ green light. A tool that reassures you without grounds is worse than no tool.
 --json              full machine-readable output
 --no-blame          skip fence age (faster, tells you less)
 --include-generated scan bundles and minified builds too
+--cache=FILE        where to keep issue states
+--no-cache          ignore cached state and ask the tracker again
+--max-age-days=N    how old a cached state may be before it is re-checked
+                    (default 7)
 ```
 
+An option this tool does not recognise stops the run. A mistyped `--chek`
+used to print a normal report, and the reader believed the trackers had been
+consulted.
+
+You can also point it at a single file: `npx ancient-fences src/thing.js`.
+
 Bundles committed into a repository (`vendor.js`, a browserify or webpack
 build, anything minified) are skipped, and the summary says how many were left
 out. The fences inside them belong to the libraries they were built from, so
 listing them buries the ones your team can actually act on. `dist`, `build`,
 `node_modules`, `vendor` and `third_party` are skipped for the same reason.
 
-Issue states are cached in `.ancient-fences-cache.json` next to the scanned
-repository. Add it to your `.gitignore`.
+Issue states are cached in your user cache directory (`$XDG_CACHE_HOME`,
+`%LOCALAPPDATA%`, or `~/.cache`), never inside the repository being scanned.
+Every entry records when it was read, entries older than a week are re-checked,
+and if the tracker cannot be reached the report says which day the answer is
+from:
+
+```
+VERDICT:  remove (reason disappeared 2021-04-02 (state as of 2026-08-18))
+```
+
+An issue state is a snapshot, not a fact. Closed issues get reopened.
 
 ## Working with an agent
 

package/bin/ancient-fences.mjs

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
-import { resolve, basename, join } from 'node:path';
+import { resolve, basename, dirname, join } from 'node:path';
 import { writeFile, stat } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
 import { walkFiles } from '../src/walk.mjs';
 import { detectFences } from '../src/detect.mjs';
-import { blameAll } from '../src/age.mjs';
+import { blameAll, historyDepth } 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';
@@ -23,10 +25,13 @@ const value = (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,
+const KNOWN = new Set([
+  '--check', '--report', '--tasks', '--api-base', '--json', '--no-blame',
+  '--include-generated', '--no-cache', '--cache', '--help', '--max-age-days',
+]);
+
+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]
@@ -41,19 +46,47 @@ then check whether that bug is still there.
   --include-generated scan bundles and minified builds too. They are skipped by
                       default: their fences belong to the libraries they were
                       built from, not to you
+  --cache=FILE        where to keep issue states (default: your user cache
+                      directory, never inside the repository being scanned)
+  --no-cache          ignore any cached issue state and ask the tracker again
+  --max-age-days=N    how old a cached state may be before it is re-checked
+                      (default 7)
 `;
+
+if (cmd !== 'scan' || has('--help')) {
   console.log(usage);
-  process.exit(cmd === 'help' || has('--help') ? 0 : 1);
+  process.exit(0);
+}
+
+// A mistyped flag used to be ignored in silence, so "--chek" printed a normal
+// report and the reader believed the issues had been checked. Anything this
+// tool does not understand stops it.
+const unknown = flags.filter((f) => !KNOWN.has(f.split('=')[0]));
+if (unknown.length > 0) {
+  console.error(`ancient-fences: unknown option ${unknown.join(', ')}`);
+  console.error(usage);
+  process.exit(2);
 }
+if (positional.length > 1) {
+  console.error(`ancient-fences: one path at a time, got ${positional.length}: ${positional.join(', ')}`);
+  process.exit(2);
+}
+
+const target = resolve(positional[0] ?? process.cwd());
 
 // Scanning a path that is not there used to print a clean report saying zero
 // fences, which reads exactly like good news. A tool that says "nothing to
 // worry about" when it looked at nothing is worse than no tool.
+let single = null;
+let root = target;
 try {
-  const info = await stat(root);
-  if (!info.isDirectory()) throw new Error('not a directory');
+  const info = await stat(target);
+  if (info.isFile()) {
+    single = target;
+    root = dirname(target);
+  }
 } catch {
-  console.error(`ancient-fences: nothing to scan at ${root}`);
+  console.error(`ancient-fences: nothing to scan at ${target}`);
   if (positional[0] && positional[0].includes('--')) {
     console.error('It looks like an option got stuck to the path. Put a space before it:');
     console.error('  npx ancient-fences . --report');
@@ -63,14 +96,30 @@ try {
 
 const skipped = [];
 const fences = [];
-for await (const file of walkFiles(root, { skipped, includeGenerated: has('--include-generated') })) {
-  fences.push(...detectFences(file.path, file.text));
+if (single) {
+  const { readFile } = await import('node:fs/promises');
+  const name = basename(single);
+  fences.push(...detectFences(name, await readFile(single, 'utf8')));
+} else {
+  for await (const file of walkFiles(root, { skipped, includeGenerated: has('--include-generated') })) {
+    fences.push(...detectFences(file.path, file.text));
+  }
 }
 
-if (!has('--no-blame')) await blameAll(root, fences);
+// Age comes from git blame, so it is only a number when there is history to
+// read. A shallow clone dates every line to the day it was fetched, which
+// turned "the oldest fence here is 8 years old" into a confident zero.
+// --no-blame is a choice, not a measurement. Saying "0 untouched for 3+
+// years" after skipping the only step that could tell is the same lie as
+// measuring a shallow clone.
+const history = has('--no-blame')
+  ? { usable: false, why: '--no-blame was given, and blame is the only thing that knows' }
+  : await historyDepth(root);
+if (history.usable) await blameAll(root, fences);
 
 let states = new Map();
 const checking = has('--check');
+const cachePath = value('--cache') ? resolve(value('--cache')) : defaultCachePath(root);
 if (checking) {
   const ids = new Set();
   for (const f of fences) {
@@ -80,17 +129,26 @@ if (checking) {
   }
   states = await checkGithubRefs([...ids], {
     apiBase: value('--api-base') ?? undefined,
-    cachePath: join(root, '.ancient-fences-cache.json'),
+    cachePath,
+    noCache: has('--no-cache'),
+    maxAgeDays: Number(value('--max-age-days') ?? 7),
   });
-  // 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);
 }
 
+// What the lockfile says you actually run turns "the issue is closed" into
+// "you can delete this today", or into "upgrade before you can". Verdicts are
+// computed whether or not the tracker was consulted, because a deadline that
+// has passed needs no network to judge.
+const installed = await readInstalled(root);
+for (const f of fences) f.verdict = verdict(f, states, installed);
+
 const summary = summarize(fences, states);
 summary.skipped = skipped.length;
-const name = basename(root);
+summary.skippedFiles = skipped;
+summary.history = history;
+summary.checkedAt = checking ? checkTimestamp(states) : null;
+
+const name = single ? basename(single) : basename(root);
 
 const reportFlag = flags.find((f) => f === '--report' || f.startsWith('--report='));
 if (reportFlag) {
@@ -102,7 +160,7 @@ if (reportFlag) {
 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');
+  await writeFile(out, renderTasks(fences, name, checking), 'utf8');
   console.error(`agent tasks written to ${out}`);
 }
 
@@ -111,3 +169,21 @@ if (has('--json')) {
 } else {
   console.log(renderText(fences, summary, name, checking));
 }
+
+/**
+ * Issue states are cached so a second run does not spend the hourly request
+ * budget again. The first version wrote that cache into the repository being
+ * scanned, which left a file behind in someone else's working tree.
+ */
+function defaultCachePath(repo) {
+  const base = process.env.XDG_CACHE_HOME
+    ?? (process.platform === 'win32' ? process.env.LOCALAPPDATA : null)
+    ?? join(homedir() || tmpdir(), '.cache');
+  const key = createHash('sha256').update(resolve(repo)).digest('hex').slice(0, 16);
+  return join(base, 'ancient-fences', `${key}.json`);
+}
+
+function checkTimestamp(states) {
+  const times = [...states.values()].map((s) => s.checkedAt).filter(Boolean).sort();
+  return times.length ? { oldest: times[0], newest: times[times.length - 1] } : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ancient-fences",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Finds the code you wrote because of someone else's bug, and checks whether that bug is still there.",
   "type": "module",
   "bin": {

package/src/age.mjs

@@ -22,6 +22,39 @@ export async function blameYear(repo, file, line) {
   }
 }
 
+/**
+ * Whether ages can be measured here at all.
+ *
+ * A shallow clone (`git clone --depth 1`, and every CI checkout by default)
+ * rewrites every line's date to the day it was fetched. Blame then answers
+ * "touched today" for an eight-year-old workaround, and the report says
+ * nothing is old. That reads as an all clear, so the tool has to say plainly
+ * that it could not measure rather than print a confident zero.
+ */
+export async function historyDepth(repo) {
+  const git = async (args) => {
+    try {
+      const { stdout } = await run('git', args, { cwd: repo });
+      return stdout.trim();
+    } catch {
+      return null;
+    }
+  };
+  if (await git(['rev-parse', '--git-dir']) === null) {
+    return { usable: false, why: 'not a git repository, so fence age cannot be measured' };
+  }
+  if (await git(['rev-parse', '--is-shallow-repository']) === 'true') {
+    return {
+      usable: false,
+      shallow: true,
+      why: 'shallow clone: git dates every line to the day it was fetched, so fence age cannot be measured (clone with full history, or actions/checkout with fetch-depth: 0)',
+    };
+  }
+  const count = await git(['rev-list', '--count', 'HEAD']);
+  if (count === null) return { usable: false, why: 'no commits yet, so fence age cannot be measured' };
+  return { usable: true, commits: Number(count) };
+}
+
 export async function blameAll(repo, fences, concurrency = 8) {
   let i = 0;
   const workers = Array.from({ length: concurrency }, async () => {

package/src/detect.mjs

@@ -2,18 +2,44 @@
 // 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 = [
+// Two classes of word, because they carry different weight. A "workaround" is
+// a fence by definition. The word "until" is ordinary English that happens to
+// appear in fences, and treating it as proof produced two hundred findings on
+// webpack that were plain explanatory comments. A weak word only counts when
+// something else in the comment names the condition: a tracker link, a
+// deadline, a version.
+const STRONG_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',
+  'kludge', 'monkey ?-?patch(?:ed|ing)?',
+  'hack(?:s|ed|ing)?(?: around)?',
+  'remove (?:when|once|after)', 'revert (?:when|once)',
+  'drop once', 'delete (?:when|once)',
+  'can be removed', 'no longer needed', '(?:once|when) fixed',
+  'due to (?:a )?bug', 'because of (?:a )?bug', 'upstream bug', 'known bug',
+  'broken in', 'do not upgrade', 'pinn?ed because', 'pin because',
 ];
 
+// Phrases that read as a fence in a note and as ordinary prose everywhere
+// else. "TODO remove this class" is a fence; "remove this chunk from its
+// parents" is a sentence about what the code does. They count only next to a
+// marker or a named condition.
+const MEDIUM_WORDS = [
+  'remove (?:this|it)', 'delete (?:this|it)', 'drop when',
+  'blocked by', 'waiting on',
+];
+
+const MARKER_RE = /\b(?:TODO|FIXME|HACK|XXX)\b/i;
+
+const WEAK_WORDS = [
+  'until', 'temporar(?:y|ily)', 'for now', 'regression',
+  'polyfill', 'shim', 'fallback', 'legacy',
+];
+
+const rx = (words) => new RegExp(`\\b(?:${words.join('|')})\\b`, 'gi');
+const STRONG_RE = rx(STRONG_WORDS);
+const MEDIUM_RE = rx(MEDIUM_WORDS);
+const WEAK_RE = rx(WEAK_WORDS);
+
 // External trackers: the condition lives outside this repository, which is
 // exactly why nobody notices when it stops being true.
 const REF_PATTERNS = [
@@ -30,25 +56,82 @@ const REF_PATTERNS = [
 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*(?:\/\/+|#+|\*|\/\*|--|;;?|<!--|%|"""|''')/;
+/**
+ * Which comment markers a file can have. Getting this wrong in either
+ * direction is expensive: "//" inside a Python floor division is not a
+ * comment, and "#fff" in a stylesheet is not one either. Both produced
+ * findings in the first version.
+ */
+const C_LIKE = new Set(['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.mts', '.cts',
+  '.java', '.kt', '.swift', '.go', '.rs', '.c', '.h', '.cc', '.cpp', '.hpp',
+  '.cs', '.m', '.mm', '.php', '.scss', '.less', '.vue', '.svelte', '.gradle']);
+const HASH_LIKE = new Set(['.py', '.rb', '.sh', '.bash', '.zsh', '.yml', '.yaml',
+  '.toml', '.tf', '.dockerfile']);
 
-function isCommentish(line) {
-  return COMMENT_START.test(line);
+export function styleFor(file) {
+  const lower = file.toLowerCase();
+  const dot = lower.lastIndexOf('.');
+  const ext = dot === -1 ? '' : lower.slice(dot);
+  if (lower.endsWith('dockerfile')) return { hash: true };
+  if (ext === '.sql') return { dashes: true, block: true };
+  if (ext === '.css') return { block: true };
+  if (HASH_LIKE.has(ext)) return { hash: true, docstring: ext === '.py' };
+  if (C_LIKE.has(ext)) return { slash: true, block: true };
+  return { slash: true, hash: true, block: true };
 }
 
-// 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 TRIPLE = ['"""', "'''"];
+
+/**
+ * The comment on one line, or null. Quotes are tracked so that a URL inside a
+ * string is not read as a comment, and so that a comment sitting after real
+ * code is still found: the first version skipped any line containing a quote,
+ * which missed every `doSomething("x"); // workaround for ...`.
+ */
+export function commentPart(line, style = { slash: true, hash: true, block: true }) {
+  const trimmed = line.trimStart();
+  if (style.docstring) {
+    for (const q of TRIPLE) {
+      if (trimmed.startsWith(q)) return trimmed.slice(3).replace(/("""|''')\s*$/, '').trim();
+    }
+  }
+  if (style.block && trimmed.startsWith('*') && !trimmed.startsWith('*/')) {
+    return trimmed.replace(/^\*+\s?/, '').replace(/\*\/\s*$/, '').trim();
+  }
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === '\\') i++;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; continue; }
+    if (style.slash && c === '/' && line[i + 1] === '/') return line.slice(i + 2).trim();
+    if (style.block && c === '/' && line[i + 1] === '*') {
+      return line.slice(i + 2).replace(/\*\/.*$/, '').trim();
+    }
+    if (style.hash && c === '#') return line.slice(i + 1).trim();
+    if (style.dashes && c === '-' && line[i + 1] === '-') return line.slice(i + 2).trim();
+    if (c === '<' && line.startsWith('<!--', i)) return line.slice(i + 4).replace(/-->.*$/, '').trim();
+  }
+  return null;
+}
+
+/**
+ * Adjacent comment lines, grouped, with the code stripped off. Deliberately
+ * language agnostic: this has to work on files nobody here has seen.
+ */
+export function commentBlocks(text, style) {
+  const lines = text.split(/\r?\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: [] };
+    const part = commentPart(lines[i], style);
+    if (part) {
+      if (!cur) cur = { start: i + 1, end: i + 1, lines: [], raw: lines[i] };
       cur.end = i + 1;
-      cur.lines.push(line.trim());
+      cur.lines.push(part);
     } else if (cur) {
       blocks.push(cur);
       cur = null;
@@ -58,9 +141,12 @@ export function commentBlocks(text) {
   return blocks;
 }
 
-function fenceWordsIn(text) {
-  const low = text.toLowerCase();
-  return FENCE_WORDS.filter((w) => low.includes(w));
+function wordsIn(text, re) {
+  re.lastIndex = 0;
+  const found = new Set();
+  let m;
+  while ((m = re.exec(text)) !== null) found.add(m[0].toLowerCase());
+  return [...found];
 }
 
 function refsIn(text) {
@@ -83,19 +169,18 @@ function refsIn(text) {
  */
 export function detectFences(file, text) {
   const out = [];
-  for (const block of commentBlocks(text)) {
+  const style = styleFor(file);
+  for (const block of commentBlocks(text, style)) {
     const body = block.lines.join(' ').replace(/\s+/g, ' ').slice(0, 600);
     if (body.length < 12) continue;
 
-    const words = fenceWordsIn(body);
+    const strong = wordsIn(body, STRONG_RE);
+    const medium = wordsIn(body, MEDIUM_RE);
+    const weak = wordsIn(body, WEAK_RE);
     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) {
@@ -104,12 +189,25 @@ export function detectFences(file, text) {
     } else if (verM) premise = { type: 'version', version: verM[1] };
     else premise = { type: 'none' };
 
+    // What it takes to call a comment a fence. A link to an external tracker
+    // is the premise by itself: someone wrote this code because of that bug.
+    // Failing that, a strong word. A weak word ("until", "polyfill") only
+    // counts when the comment also names a deadline or a version, because on
+    // its own it is ordinary English and produces mostly noise.
+    const named = premise.type === 'date' || premise.type === 'version';
+    const marker = MARKER_RE.test(body);
+    const qualifies = refs.length > 0
+      || strong.length > 0
+      || (medium.length > 0 && (marker || named))
+      || (weak.length > 0 && named);
+    if (!qualifies) continue;
+
     // 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] ?? '')
+    const isDoc = /^\s*(?:\/\*\*|\*)/.test(block.raw ?? '')
       || /@remarks|@param|@returns|\{@link/.test(body);
     let kind;
-    if (refs.length > 0 && (words.length > 0 || !isDoc)) kind = 'code';
+    if (refs.length > 0 && (strong.length > 0 || medium.length > 0 || !isDoc)) kind = 'code';
     else if (refs.length > 0) kind = 'docs';
     else if (premise.type === 'date') kind = 'deadline';
     else kind = 'unmarked';
@@ -119,7 +217,7 @@ export function detectFences(file, text) {
       line: block.start,
       endLine: block.end,
       text: body.replace(/^\W+/, '').slice(0, 240),
-      words: words.slice(0, 3),
+      words: [...strong, ...medium, ...weak].slice(0, 3),
       premise,
       kind,
       confidence: refs.length > 0 ? 'high' : premise.type === 'date' ? 'medium' : 'low',

package/src/report.mjs

@@ -29,11 +29,29 @@ export function summarize(fences, states = new Map()) {
   const verdicts = {};
   for (const f of fences) {
     if (!f.verdict) continue;
+    if (states.size === 0 && f.premise.type !== 'date') 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 };
 }
 
+/**
+ * Fences per file, biggest first. The ranked list only shows the ones with a
+ * tracker or a passed deadline, so without this a reader cannot tell where the
+ * rest of the count comes from, and cannot check whether the tool skipped or
+ * counted the right files.
+ */
+export function byFile(fences, limit = 8) {
+  const counts = new Map();
+  for (const f of fences) {
+    const row = counts.get(f.file) ?? { file: f.file, total: 0, kinds: {} };
+    row.total++;
+    row.kinds[f.kind] = (row.kinds[f.kind] ?? 0) + 1;
+    counts.set(f.file, row);
+  }
+  return [...counts.values()].sort((a, b) => b.total - a.total).slice(0, limit);
+}
+
 export function ranked(fences) {
   return fences
     .filter((f) => f.premise.type === 'tracker' || (f.premise.type === 'date' && f.premise.overdue))
@@ -46,6 +64,22 @@ function premiseOf(f) {
     : `deadline ${f.premise.date} (passed)`;
 }
 
+/** Long explanations have to stay readable in a terminal. */
+function wrap(text, width) {
+  const out = [];
+  let line = '';
+  for (const word of String(text).split(/\s+/)) {
+    if (line && line.length + word.length + 1 > width) {
+      out.push(line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  if (line) out.push(line);
+  return out;
+}
+
 export function renderText(fences, summary, repoName, checked = false) {
   const L = [];
   const n = (x) => String(x).padStart(4);
@@ -59,11 +93,28 @@ export function renderText(fences, summary, repoName, checked = false) {
   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`);
+  if (summary.history && summary.history.usable === false) {
+    L.push(`    --  age not measured`);
+    for (const line of wrap(summary.history.why, 62)) L.push(`        ${line}`);
+  } else {
+    L.push(`  ${n(summary.old)}  fences untouched for 3+ years`);
+    if (summary.oldest !== null && summary.oldest >= 1) {
+      L.push(`  ${n(summary.oldest.toFixed(1))}  years old is the oldest one`);
+    } else if (summary.oldest !== null) {
+      L.push(`        every fence here was touched within the last year`);
+    }
+  }
+  if (summary.checkedAt) {
+    const { oldest, newest } = summary.checkedAt;
+    L.push(oldest.slice(0, 10) === newest.slice(0, 10)
+      ? `        issue states read ${newest.slice(0, 10)}`
+      : `        issue states read between ${oldest.slice(0, 10)} and ${newest.slice(0, 10)}`);
+  }
   if (summary.skipped) {
     L.push(`  ${n(summary.skipped)}  bundled or minified files left out: their fences belong to`);
     L.push('        the libraries they were built from (--include-generated to scan them)');
+    for (const f of (summary.skippedFiles ?? []).slice(0, 6)) L.push(`        ${f.path}  [${f.why}]`);
+    if ((summary.skippedFiles ?? []).length > 6) L.push(`        and ${summary.skippedFiles.length - 6} more`);
   }
   L.push('');
 
@@ -76,18 +127,42 @@ export function renderText(fences, summary, repoName, checked = false) {
     L.push('');
   }
 
-  L.push('  CHECK THESE FIRST  (longest untouched)');
+  if (summary.total === 0) {
+    L.push('  Nothing found. No comment in this codebase records an external');
+    L.push('  reason for the code around it: no tracker link, no deadline, no');
+    L.push('  note about a workaround. That is either a clean codebase or an');
+    L.push('  undocumented one, and this tool cannot tell those apart.');
+    L.push('');
+    return L.join('\n');
+  }
+
+  L.push('  WHERE THEY ARE');
+  L.push('  ' + '-'.repeat(70));
+  for (const row of byFile(fences)) {
+    const kinds = Object.entries(row.kinds).map(([k, n]) => `${n} ${k}`).join(', ');
+    L.push(`  ${n(row.total)}  ${row.file}  (${kinds})`);
+  }
+  L.push('');
+
+  const list = ranked(fences);
+  L.push(`  CHECK THESE FIRST  (longest untouched)`);
   L.push('  ' + '='.repeat(70));
-  for (const f of ranked(fences).slice(0, 15)) {
+  if (list.length > 15) {
+    L.push(`  showing 15 of ${list.length} with a recorded reason; --json or --report has them all`);
+    L.push('');
+  }
+  for (const f of list.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})`);
+    if (showVerdict(f, checked)) L.push(`           VERDICT:  ${f.verdict.level} (${f.verdict.why})`);
     L.push('');
   }
-  L.push('  Every closed issue above is code you can delete.');
+  L.push(checked
+    ? '  Every closed issue above is code you can delete.'
+    : '  Run again with --check to ask the trackers whether these reasons still hold.');
   L.push('');
   return L.join('\n');
 }
@@ -98,6 +173,15 @@ const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&l
  * A standalone report meant to be forwarded to whoever pays for the codebase.
  * Developers find the fences; someone else decides what they cost.
  */
+/**
+ * A verdict is worth showing when it means something. Without --check the only
+ * ones the tool can stand behind are the deadlines, which need no network, and
+ * repeating "the tracker was not consulted" on forty rows says nothing.
+ */
+function showVerdict(fence, checked) {
+  return Boolean(fence.verdict) && (checked || fence.premise.type === 'date');
+}
+
 export function renderHtml(fences, summary, repoName, checked = false) {
   const rows = ranked(fences).slice(0, 40).map((f) => {
     const y = yearsSince(f.lastTouched);
@@ -106,7 +190,7 @@ export function renderHtml(fences, summary, repoName, checked = false) {
       <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>
+      <td>${showVerdict(f, checked) ? `<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');
 
@@ -131,11 +215,13 @@ h1{font:300 clamp(2rem,5vw,3.2rem)/1.05 ui-serif,Georgia,serif;letter-spacing:-.
 .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}
+table{border-collapse:collapse;width:100%;min-width:40rem;font-size:.88rem;table-layout:fixed}
 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}
+td.num{color:var(--dim);font-variant-numeric:tabular-nums;font-size:.8rem;overflow-wrap:anywhere}
+col.age{width:6rem}col.reason{width:14rem}col.state{width:12rem}
+code{overflow-wrap:anywhere}
 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)}
@@ -154,14 +240,30 @@ footer p{max-width:62ch}
     <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 class="stat"><b>${summary.history && summary.history.usable === false ? '-' : summary.old}</b><span>untouched for 3+ years</span></div>
+    <div class="stat"><b>${summary.history && summary.history.usable === false ? '-' : (summary.oldest === null ? '-' : summary.oldest.toFixed(1))}</b><span>years, the oldest one</span></div>
   </div>
-  <h2>Check these first</h2>
+  ${summary.history && summary.history.usable === false ? `<p class="sub">Age was not measured: ${esc(summary.history.why)}.</p>` : ''}
+  ${summary.checkedAt ? `<p class="sub">Issue states read ${esc(summary.checkedAt.newest.slice(0, 10))}.</p>` : ''}
+  ${!checked && summary.trackers > 0 ? `<p class="sub">The trackers were not consulted in this run, so the state column is empty. <code>--check</code> asks them whether these issues are still open.</p>` : ''}
+  ${summary.total === 0 ? `<h2>Nothing found</h2>
+  <p class="sub">No comment in this codebase records an external reason for the code around it: no tracker link, no deadline, no note about a workaround. That is either a clean codebase or an undocumented one, and this tool cannot tell those apart.</p>` : `<h2>Check these first</h2>
   <div class="scroll"><table>
+    <colgroup><col class="age"><col><col class="reason"><col class="state"></colgroup>
     <thead><tr><th>Untouched</th><th>Where</th><th>Reason given</th><th>${checked ? 'Verdict' : 'State'}</th></tr></thead>
     <tbody>${rows}</tbody>
-  </table></div>
+  </table></div>`}
+  ${fences.length ? `<h2>Where they are</h2>
+  <div class="scroll"><table>
+    <thead><tr><th>File</th><th>Fences</th><th>Kinds</th></tr></thead>
+    <tbody>${byFile(fences, 15).map((r) => `<tr><td><code>${esc(r.file)}</code></td><td class="num">${r.total}</td><td class="num">${esc(Object.entries(r.kinds).map(([k, n]) => `${n} ${k}`).join(', '))}</td></tr>`).join('\n')}</tbody>
+  </table></div>` : ''}
+  ${summary.skipped ? `<h2>Left out</h2>
+  <p class="sub">${summary.skipped} file${summary.skipped === 1 ? ' was' : 's were'} skipped as a build product. The fences inside a bundle belong to the libraries it was built from, not to this team.</p>
+  <div class="scroll"><table>
+    <thead><tr><th>File</th><th>Why</th></tr></thead>
+    <tbody>${(summary.skippedFiles ?? []).map((f) => `<tr><td><code>${esc(f.path)}</code></td><td class="num">${esc(f.why)}</td></tr>`).join('\n')}</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>
@@ -175,16 +277,23 @@ footer p{max-width:62ch}
  * 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) {
+export function renderTasks(fences, repoName, checked = false) {
   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' : ''}.`);
+  if (checked) {
+    L.push(`Verified against the referenced tracker${dead.some((f) => /shipped in/.test(f.verdict.why)) ? ' and the lockfile' : ''}.`);
+  } else {
+    L.push(`The trackers were not consulted in this run, so only deadlines written into`);
+    L.push(`the comments were judged. Run with --check to include issue state.`);
+  }
   L.push('');
   if (dead.length === 0) {
-    L.push('Nothing to remove. Run with --check first if you have not.');
+    L.push(checked
+      ? 'Nothing to remove: every recorded reason still holds.'
+      : 'Nothing to remove from deadlines alone. Run again with --check to ask the trackers.');
     return L.join('\n');
   }
   dead.forEach((f, i) => {

package/src/tracker.mjs

@@ -8,14 +8,20 @@ import { fixVersionFrom, packageForRef, shippedStatus } from './versions.mjs';
  * does the reason still exist?
  */
 export async function checkGithubRefs(ids, opts = {}) {
-  const apiBase = opts.apiBase ?? 'https://api.github.com';
+  const apiBase = (opts.apiBase ?? 'https://api.github.com').replace(/\/+$/, '');
   const token = opts.token ?? process.env.GITHUB_TOKEN ?? null;
-  const cache = await loadCache(opts.cachePath);
+  const maxAgeDays = Number.isFinite(opts.maxAgeDays) ? opts.maxAgeDays : 7;
+  const cache = opts.noCache ? {} : await loadCache(opts.cachePath);
   const result = new Map();
 
   for (const id of ids) {
-    if (cache[id] && !opts.noCache) {
-      result.set(id, cache[id]);
+    // An issue state is not a fact, it is a snapshot: closed issues get
+    // reopened. A cache with no age would let this tool say "the reason
+    // disappeared" forever on the strength of one lookup, offline, with
+    // nothing on screen to say how old the answer is.
+    const cached = cache[id];
+    if (cached && freshEnough(cached, maxAgeDays)) {
+      result.set(id, cached);
       continue;
     }
     const m = id.match(/^github:([\w.-]+)\/([\w.-]+)#(\d+)$/);
@@ -28,19 +34,19 @@ export async function checkGithubRefs(ids, opts = {}) {
     try {
       res = await fetch(url, { headers });
     } catch (err) {
-      result.set(id, { state: 'unknown', reason: `network: ${err.message}` });
+      result.set(id, staleOr(cached, { 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' });
+      result.set(id, staleOr(cached, { state: 'unknown', reason: 'rate limited or no access' }));
       continue;
     }
     if (res.status === 404) {
-      result.set(id, { state: 'unknown', reason: 'issue missing or private' });
+      result.set(id, staleOr(cached, { state: 'unknown', reason: 'issue missing or private' }));
       continue;
     }
     if (!res.ok) {
-      result.set(id, { state: 'unknown', reason: `HTTP ${res.status}` });
+      result.set(id, staleOr(cached, { state: 'unknown', reason: `HTTP ${res.status}` }));
       continue;
     }
     const body = await res.json();
@@ -53,6 +59,7 @@ export async function checkGithubRefs(ids, opts = {}) {
       // 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),
+      checkedAt: new Date().toISOString(),
     };
     result.set(id, entry);
     cache[id] = entry;
@@ -62,6 +69,21 @@ export async function checkGithubRefs(ids, opts = {}) {
   return result;
 }
 
+function freshEnough(entry, maxAgeDays) {
+  if (!entry?.checkedAt) return false;
+  const age = Date.now() - new Date(entry.checkedAt).getTime();
+  return Number.isFinite(age) && age >= 0 && age < maxAgeDays * 24 * 3600 * 1000;
+}
+
+/**
+ * The tracker could not be reached now. An old answer is still worth more than
+ * nothing, as long as every report that uses it says how old it is.
+ */
+function staleOr(cached, failure) {
+  if (!cached || !cached.checkedAt) return failure;
+  return { ...cached, stale: true, reason: `${failure.reason}; using the state read on ${cached.checkedAt.slice(0, 10)}` };
+}
+
 /**
  * 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
@@ -78,21 +100,32 @@ export function verdict(fence, states, installed = new Map()) {
   }
   // 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' };
+  const seen = fence.premise.refs.map((r) => states.get(r.id)).filter(Boolean);
+  const known = seen.filter((s) => s.state !== 'unknown');
+  if (known.length === 0) {
+    // Not asking and asking without an answer are different states, and a
+    // report that spells both "unchecked" invites the reader to assume the
+    // worse one happened.
+    return seen.length === 0
+      ? { level: 'unchecked', why: 'the tracker was not consulted in this run (--check does that)' }
+      : { level: 'unchecked', why: seen[0].reason ?? 'could not determine issue state' };
+  }
+  // An answer read from an old cache still says when it was read, in the
+  // verdict itself, so nobody acts on a year-old snapshot believing it is now.
+  const asOf = known.some((s) => s.stale)
+    ? ` (state as of ${known.map((s) => s.checkedAt).filter(Boolean).sort()[0]?.slice(0, 10)})`
+    : '';
   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 };
+    if (shipped?.state === 'shipped') return { level: 'remove', why: shipped.text + asOf };
+    if (shipped?.state === 'not upgraded') return { level: 'upgrade first', why: shipped.text + asOf };
     const when = known.map((s) => s.closedAt).filter(Boolean).sort().pop();
-    return { level: 'remove', why: when ? `reason disappeared ${when.slice(0, 10)}` : 'issue closed' };
+    return { level: 'remove', why: (when ? `reason disappeared ${when.slice(0, 10)}` : 'issue closed') + asOf };
   }
   if (known.some((s) => s.state === 'closed')) {
-    return { level: 'review', why: 'some of the reasons are gone' };
+    return { level: 'review', why: 'some of the reasons are gone' + asOf };
   }
-  return { level: 'still valid', why: 'issue still open' };
+  return { level: 'still valid', why: 'issue still open' + asOf };
 }
 
 /**