@smeltjs/core 0.2.0 → 0.3.0

package/dist/repomap/cache.d.ts

@@ -18,6 +18,32 @@ import type { LanguageId } from '../types.ts';
  * source, and the caller's result carries a warning naming the file. Trusting a
  * damaged cache would silently drop symbols from the map, which is this project's
  * signature failure mode.
+ *
+ * **It is bounded, and the bound is a sweep.** The key is a content hash, so an edit
+ * does not replace an entry — it mints a new one and orphans the old, which is
+ * invisible and permanent: every pre-edit version of every file the caller ever mapped
+ * stays on disk for as long as the directory does. A long session therefore grew this
+ * cache without limit while never reading most of it. So {@link TagsCache.sweep}
+ * deletes every entry the build it just finished did not use, leaving exactly the tags
+ * of the tree as it now stands. The policy is stated as a bound anyone can check: **an
+ * entry survives a build only if that build used it**, so the cache is at most one
+ * entry per mappable file in the tree — plus whatever a crash left mid-write, which
+ * no sweep can safely reclaim; see {@link ENTRY_FILE}.
+ *
+ * Why that is safe, and the rule any other policy would also have to meet: **a miss
+ * can only make a map slower, never wrong.** A missing entry is re-extracted from the
+ * file's own bytes, and a present entry is only ever served for the exact content that
+ * hashed to its key — so sweeping too much costs a re-parse and sweeping too little
+ * costs disk, and neither can change a single symbol in the emitted map. The same rule
+ * is why the sweep never throws: it runs after the map is finished, so a cache
+ * directory that will not list postpones the bound to the next build rather than
+ * turning a computed map into no map at all.
+ *
+ * The cost is paid by a caller who points *one* cache directory at *several* trees:
+ * each build sweeps the others' entries, and every build then re-parses. That is a
+ * slower map, not a wrong one, and it is measured rather than hidden — the sweep's
+ * count rides back in `RepoMap.cache.pruned` and is printed in `smelt map`'s report.
+ * One cache directory per tree is the shape this is tuned for.
  */
 /** The format name every cache entry carries. */
 export declare const TAGS_CACHE_FORMAT = "smelt-repomap-tags";
@@ -49,5 +75,27 @@ export declare class TagsCache {
      * source, so losing one to a crash costs a re-parse, not a broken promise.
      */
     write(key: string, tags: FileTags): void;
+    /**
+     * Delete every entry that is not in `live` — the bound on this cache, described in
+     * full in the module comment above. `live` is the set of keys the build that just
+     * finished actually used, so what survives is exactly the tags of the tree as it
+     * now stands, and the superseded pre-edit entries a content-hash key would otherwise
+     * accumulate forever are gone.
+     *
+     * Returns how many entries were removed, so the caller can report a measured number
+     * rather than a claim.
+     *
+     * **The whole sweep is best effort, listing included.** A directory that will not
+     * list — an unreadable cache directory, or one an external cleaner removed between
+     * the last write and this call — reports `0` pruned and leaves the map alone. It
+     * runs after the tree has been walked, ranked and rendered, so a throw here would
+     * destroy a finished map over housekeeping smelt only wanted to do: no map at all
+     * instead of a slower one, which is the trade this cache is forbidden to make.
+     * Deleting one entry is best effort for the same reason. Nothing is lost by
+     * skipping a sweep — the entries are offered again on the next build, and until
+     * then nothing reads them, because nothing will ever look up a key no file hashes
+     * to.
+     */
+    sweep(live: ReadonlySet<string>): number;
 }
 //# sourceMappingURL=cache.d.ts.map

package/dist/repomap/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/repomap/cache.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAiB,QAAQ,EAAgB,MAAM,WAAW,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAEtD,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,8CAA8C;AAC9C,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAE/D,qBAAa,SAAS;;IAGpB,qFAAqF;IACrF,YAAY,GAAG,EAAE,MAAM,EAGtB;IAED;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAqBjC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAWvC;CAeF"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/repomap/cache.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAiB,QAAQ,EAAgB,MAAM,WAAW,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAEtD,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,8CAA8C;AAC9C,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAkB/D,qBAAa,SAAS;;IAGpB,qFAAqF;IACrF,YAAY,GAAG,EAAE,MAAM,EAKtB;IAED;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CA2BjC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAavC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,CAqBvC;CAeF","sourcesContent":["import {\n  mkdirSync,\n  readdirSync,\n  readFileSync,\n  renameSync,\n  unlinkSync,\n  writeFileSync,\n} from 'node:fs';\nimport { join } from 'node:path';\nimport process from 'node:process';\n\nimport { contentHash } from '../hash.ts';\nimport { fsCall } from './io.ts';\nimport type { DefinitionTag, FileTags, ReferenceTag } from './tags.ts';\nimport type { LanguageId } from '../types.ts';\n\n/**\n * The repo map's disk cache — per-file tags, keyed by content hash, JSON on disk.\n *\n * Modelled on Aider's repo-map tags cache (https://aider.chat/docs/repomap.html),\n * with one deliberate substitution: Aider persists through SQLite; this repo ships\n * zero new runtime dependencies, so entries are plain JSON files under a directory\n * **the caller explicitly hands in**. smelt never writes outside a store or cache it\n * was handed — no default location, no home-directory guessing.\n *\n * The key is a content hash over the tag-format version, the language, and the file's\n * exact text. That is the whole invalidation story: edit a file and its key changes,\n * so the stale entry is simply never looked up again. Nothing needs a timestamp.\n *\n * A corrupt entry — unparseable JSON, or JSON of the wrong shape — is **discarded\n * loudly, never trusted**: the entry file is deleted, the tags are re-extracted from\n * source, and the caller's result carries a warning naming the file. Trusting a\n * damaged cache would silently drop symbols from the map, which is this project's\n * signature failure mode.\n *\n * **It is bounded, and the bound is a sweep.** The key is a content hash, so an edit\n * does not replace an entry — it mints a new one and orphans the old, which is\n * invisible and permanent: every pre-edit version of every file the caller ever mapped\n * stays on disk for as long as the directory does. A long session therefore grew this\n * cache without limit while never reading most of it. So {@link TagsCache.sweep}\n * deletes every entry the build it just finished did not use, leaving exactly the tags\n * of the tree as it now stands. The policy is stated as a bound anyone can check: **an\n * entry survives a build only if that build used it**, so the cache is at most one\n * entry per mappable file in the tree — plus whatever a crash left mid-write, which\n * no sweep can safely reclaim; see {@link ENTRY_FILE}.\n *\n * Why that is safe, and the rule any other policy would also have to meet: **a miss\n * can only make a map slower, never wrong.** A missing entry is re-extracted from the\n * file's own bytes, and a present entry is only ever served for the exact content that\n * hashed to its key — so sweeping too much costs a re-parse and sweeping too little\n * costs disk, and neither can change a single symbol in the emitted map. The same rule\n * is why the sweep never throws: it runs after the map is finished, so a cache\n * directory that will not list postpones the bound to the next build rather than\n * turning a computed map into no map at all.\n *\n * The cost is paid by a caller who points *one* cache directory at *several* trees:\n * each build sweeps the others' entries, and every build then re-parses. That is a\n * slower map, not a wrong one, and it is measured rather than hidden — the sweep's\n * count rides back in `RepoMap.cache.pruned` and is printed in `smelt map`'s report.\n * One cache directory per tree is the shape this is tuned for.\n */\n\n/** The format name every cache entry carries. */\nexport const TAGS_CACHE_FORMAT = 'smelt-repomap-tags';\n\n/** Bump this when the tag shape changes: old entries then miss instead of misleading. */\nexport const TAGS_CACHE_VERSION = 1;\n\n/**\n * The cache key for one file's tags. The version and language are part of the hashed\n * material, so a format bump or a re-detected language can never resurrect an entry\n * extracted under different rules.\n */\nexport function tagsCacheKey(language: LanguageId, content: string): string {\n  return contentHash(`${TAGS_CACHE_FORMAT}/${String(TAGS_CACHE_VERSION)}\\0${language}\\0${content}`);\n}\n\n/** What `read()` reports about one lookup. */\nexport type TagsCacheLookup = FileTags | 'corrupt' | undefined;\n\n/**\n * An entry file's name, and the key inside it. Only a name of exactly this shape is\n * ever swept: a temp file from a write in flight (`<key>.json.tmp-<pid>`) does not\n * match, so a sweep cannot delete the file another process is at that moment renaming\n * into place.\n *\n * The price of that exclusion, stated rather than hidden: the bound above is over\n * *entries*, and a process killed between the `writeFileSync` and the `renameSync` in\n * {@link TagsCache.write} leaves a temp file no later sweep reclaims. Reclaiming one\n * safely needs a liveness test this cache cannot make — a pid can be reused, and an\n * mtime cutoff is a number smelt would have invented — and the alternative, deleting\n * a temp file a live writer is about to rename, fails that writer's build. So a\n * crash's leftovers are counted as the known cost of never racing a concurrent write.\n */\nconst ENTRY_FILE = /^([0-9a-f]+)\\.json$/;\n\nexport class TagsCache {\n  readonly #entriesDir: string;\n\n  /** `dir` is the directory the caller handed in; entries live under `<dir>/tags/`. */\n  constructor(dir: string) {\n    this.#entriesDir = join(dir, 'tags');\n    fsCall('create the tags cache directory', this.#entriesDir, () => {\n      mkdirSync(this.#entriesDir, { recursive: true });\n    });\n  }\n\n  /**\n   * The cached tags under `key`, `undefined` on a miss, `'corrupt'` when an entry\n   * existed but could not be trusted — in which case it has already been deleted, so\n   * the corruption is reported exactly once and never re-read.\n   */\n  read(key: string): TagsCacheLookup {\n    const path = this.#entryPath(key);\n    const raw = fsCall('read the cache entry', path, (): string | undefined => {\n      try {\n        return readFileSync(path, 'utf8');\n      } catch (error) {\n        // Structural, not `NodeJS.ErrnoException`: this type reaches the shipped\n        // declarations, and an ambient namespace there breaks a consumer compiling\n        // with `skipLibCheck: false`.\n        if ((error as { code?: string }).code === 'ENOENT') return undefined;\n        throw error;\n      }\n    });\n    if (raw === undefined) return undefined;\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      this.#discard(key);\n      return 'corrupt';\n    }\n    const tags = validateEntry(parsed);\n    if (tags === undefined) {\n      this.#discard(key);\n      return 'corrupt';\n    }\n    return tags;\n  }\n\n  /**\n   * Persist one file's tags. Written to a temp name and renamed into place, so a\n   * concurrent reader never sees a half-written entry; both writers of the same key\n   * are writing identical bytes (the key covers the content), so last-rename-wins is\n   * harmless. No fsync: unlike the elision store, every entry here is derivable from\n   * source, so losing one to a crash costs a re-parse, not a broken promise.\n   */\n  write(key: string, tags: FileTags): void {\n    const body = `${JSON.stringify({\n      format: TAGS_CACHE_FORMAT,\n      version: TAGS_CACHE_VERSION,\n      defs: tags.defs,\n      refs: tags.refs,\n    })}\\n`;\n    const target = this.#entryPath(key);\n    const temp = `${target}.tmp-${String(process.pid)}`;\n    fsCall('write the cache entry', target, () => {\n      writeFileSync(temp, body, 'utf8');\n      renameSync(temp, target);\n    });\n  }\n\n  /**\n   * Delete every entry that is not in `live` — the bound on this cache, described in\n   * full in the module comment above. `live` is the set of keys the build that just\n   * finished actually used, so what survives is exactly the tags of the tree as it\n   * now stands, and the superseded pre-edit entries a content-hash key would otherwise\n   * accumulate forever are gone.\n   *\n   * Returns how many entries were removed, so the caller can report a measured number\n   * rather than a claim.\n   *\n   * **The whole sweep is best effort, listing included.** A directory that will not\n   * list — an unreadable cache directory, or one an external cleaner removed between\n   * the last write and this call — reports `0` pruned and leaves the map alone. It\n   * runs after the tree has been walked, ranked and rendered, so a throw here would\n   * destroy a finished map over housekeeping smelt only wanted to do: no map at all\n   * instead of a slower one, which is the trade this cache is forbidden to make.\n   * Deleting one entry is best effort for the same reason. Nothing is lost by\n   * skipping a sweep — the entries are offered again on the next build, and until\n   * then nothing reads them, because nothing will ever look up a key no file hashes\n   * to.\n   */\n  sweep(live: ReadonlySet<string>): number {\n    let names: string[];\n    try {\n      names = readdirSync(this.#entriesDir);\n    } catch {\n      return 0;\n    }\n    let pruned = 0;\n    for (const name of names.toSorted()) {\n      const key = ENTRY_FILE.exec(name)?.[1];\n      if (key === undefined || live.has(key)) continue;\n      try {\n        unlinkSync(join(this.#entriesDir, name));\n        pruned += 1;\n      } catch {\n        // Already gone, or undeletable. Either way it is one stale entry that will be\n        // offered for sweeping again on the next build; nothing reads it meanwhile,\n        // because nothing will ever look up a key no file hashes to.\n      }\n    }\n    return pruned;\n  }\n\n  #entryPath(key: string): string {\n    return join(this.#entriesDir, `${key}.json`);\n  }\n\n  /** Delete a corrupt entry so it can never be re-read as truth. Best effort. */\n  #discard(key: string): void {\n    try {\n      unlinkSync(this.#entryPath(key));\n    } catch {\n      // Already gone, or undeletable — either way it will be overwritten by the\n      // rewrite that follows every discard.\n    }\n  }\n}\n\n/** The parsed entry as `FileTags`, or `undefined` when its shape cannot be trusted. */\nfunction validateEntry(parsed: unknown): FileTags | undefined {\n  if (typeof parsed !== 'object' || parsed === null) return undefined;\n  const entry = parsed as { format?: unknown; version?: unknown; defs?: unknown; refs?: unknown };\n  if (entry.format !== TAGS_CACHE_FORMAT || entry.version !== TAGS_CACHE_VERSION) return undefined;\n  if (!Array.isArray(entry.defs) || !Array.isArray(entry.refs)) return undefined;\n\n  const defs: DefinitionTag[] = [];\n  for (const item of entry.defs as unknown[]) {\n    const def = item as { name?: unknown; kind?: unknown; line?: unknown };\n    if (typeof def.name !== 'string' || def.name === '') return undefined;\n    if (typeof def.kind !== 'string' || def.kind === '') return undefined;\n    if (typeof def.line !== 'number' || !Number.isInteger(def.line) || def.line < 1) {\n      return undefined;\n    }\n    defs.push({ name: def.name, kind: def.kind, line: def.line });\n  }\n  const refs: ReferenceTag[] = [];\n  for (const item of entry.refs as unknown[]) {\n    const ref = item as { name?: unknown; count?: unknown };\n    if (typeof ref.name !== 'string' || ref.name === '') return undefined;\n    if (typeof ref.count !== 'number' || !Number.isInteger(ref.count) || ref.count < 1) {\n      return undefined;\n    }\n    refs.push({ name: ref.name, count: ref.count });\n  }\n  return { defs, refs };\n}\n"]}

package/dist/repomap/cache.js

@@ -1,7 +1,8 @@
-import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
 import process from 'node:process';
 import { contentHash } from '../hash.js';
+import { fsCall } from './io.js';
 /**
  * The repo map's disk cache — per-file tags, keyed by content hash, JSON on disk.
  *
@@ -20,6 +21,32 @@ import { contentHash } from '../hash.js';
  * source, and the caller's result carries a warning naming the file. Trusting a
  * damaged cache would silently drop symbols from the map, which is this project's
  * signature failure mode.
+ *
+ * **It is bounded, and the bound is a sweep.** The key is a content hash, so an edit
+ * does not replace an entry — it mints a new one and orphans the old, which is
+ * invisible and permanent: every pre-edit version of every file the caller ever mapped
+ * stays on disk for as long as the directory does. A long session therefore grew this
+ * cache without limit while never reading most of it. So {@link TagsCache.sweep}
+ * deletes every entry the build it just finished did not use, leaving exactly the tags
+ * of the tree as it now stands. The policy is stated as a bound anyone can check: **an
+ * entry survives a build only if that build used it**, so the cache is at most one
+ * entry per mappable file in the tree — plus whatever a crash left mid-write, which
+ * no sweep can safely reclaim; see {@link ENTRY_FILE}.
+ *
+ * Why that is safe, and the rule any other policy would also have to meet: **a miss
+ * can only make a map slower, never wrong.** A missing entry is re-extracted from the
+ * file's own bytes, and a present entry is only ever served for the exact content that
+ * hashed to its key — so sweeping too much costs a re-parse and sweeping too little
+ * costs disk, and neither can change a single symbol in the emitted map. The same rule
+ * is why the sweep never throws: it runs after the map is finished, so a cache
+ * directory that will not list postpones the bound to the next build rather than
+ * turning a computed map into no map at all.
+ *
+ * The cost is paid by a caller who points *one* cache directory at *several* trees:
+ * each build sweeps the others' entries, and every build then re-parses. That is a
+ * slower map, not a wrong one, and it is measured rather than hidden — the sweep's
+ * count rides back in `RepoMap.cache.pruned` and is printed in `smelt map`'s report.
+ * One cache directory per tree is the shape this is tuned for.
  */
 /** The format name every cache entry carries. */
 export const TAGS_CACHE_FORMAT = 'smelt-repomap-tags';
@@ -33,12 +60,29 @@ export const TAGS_CACHE_VERSION = 1;
 export function tagsCacheKey(language, content) {
     return contentHash(`${TAGS_CACHE_FORMAT}/${String(TAGS_CACHE_VERSION)}\0${language}\0${content}`);
 }
+/**
+ * An entry file's name, and the key inside it. Only a name of exactly this shape is
+ * ever swept: a temp file from a write in flight (`<key>.json.tmp-<pid>`) does not
+ * match, so a sweep cannot delete the file another process is at that moment renaming
+ * into place.
+ *
+ * The price of that exclusion, stated rather than hidden: the bound above is over
+ * *entries*, and a process killed between the `writeFileSync` and the `renameSync` in
+ * {@link TagsCache.write} leaves a temp file no later sweep reclaims. Reclaiming one
+ * safely needs a liveness test this cache cannot make — a pid can be reused, and an
+ * mtime cutoff is a number smelt would have invented — and the alternative, deleting
+ * a temp file a live writer is about to rename, fails that writer's build. So a
+ * crash's leftovers are counted as the known cost of never racing a concurrent write.
+ */
+const ENTRY_FILE = /^([0-9a-f]+)\.json$/;
 export class TagsCache {
     #entriesDir;
     /** `dir` is the directory the caller handed in; entries live under `<dir>/tags/`. */
     constructor(dir) {
         this.#entriesDir = join(dir, 'tags');
-        mkdirSync(this.#entriesDir, { recursive: true });
+        fsCall('create the tags cache directory', this.#entriesDir, () => {
+            mkdirSync(this.#entriesDir, { recursive: true });
+        });
     }
     /**
      * The cached tags under `key`, `undefined` on a miss, `'corrupt'` when an entry
@@ -46,15 +90,22 @@ export class TagsCache {
      * the corruption is reported exactly once and never re-read.
      */
     read(key) {
-        let raw;
-        try {
-            raw = readFileSync(this.#entryPath(key), 'utf8');
-        }
-        catch (error) {
-            if (error.code === 'ENOENT')
-                return undefined;
-            throw error;
-        }
+        const path = this.#entryPath(key);
+        const raw = fsCall('read the cache entry', path, () => {
+            try {
+                return readFileSync(path, 'utf8');
+            }
+            catch (error) {
+                // Structural, not `NodeJS.ErrnoException`: this type reaches the shipped
+                // declarations, and an ambient namespace there breaks a consumer compiling
+                // with `skipLibCheck: false`.
+                if (error.code === 'ENOENT')
+                    return undefined;
+                throw error;
+            }
+        });
+        if (raw === undefined)
+            return undefined;
         let parsed;
         try {
             parsed = JSON.parse(raw);
@@ -86,8 +137,56 @@ export class TagsCache {
         })}\n`;
         const target = this.#entryPath(key);
         const temp = `${target}.tmp-${String(process.pid)}`;
-        writeFileSync(temp, body, 'utf8');
-        renameSync(temp, target);
+        fsCall('write the cache entry', target, () => {
+            writeFileSync(temp, body, 'utf8');
+            renameSync(temp, target);
+        });
+    }
+    /**
+     * Delete every entry that is not in `live` — the bound on this cache, described in
+     * full in the module comment above. `live` is the set of keys the build that just
+     * finished actually used, so what survives is exactly the tags of the tree as it
+     * now stands, and the superseded pre-edit entries a content-hash key would otherwise
+     * accumulate forever are gone.
+     *
+     * Returns how many entries were removed, so the caller can report a measured number
+     * rather than a claim.
+     *
+     * **The whole sweep is best effort, listing included.** A directory that will not
+     * list — an unreadable cache directory, or one an external cleaner removed between
+     * the last write and this call — reports `0` pruned and leaves the map alone. It
+     * runs after the tree has been walked, ranked and rendered, so a throw here would
+     * destroy a finished map over housekeeping smelt only wanted to do: no map at all
+     * instead of a slower one, which is the trade this cache is forbidden to make.
+     * Deleting one entry is best effort for the same reason. Nothing is lost by
+     * skipping a sweep — the entries are offered again on the next build, and until
+     * then nothing reads them, because nothing will ever look up a key no file hashes
+     * to.
+     */
+    sweep(live) {
+        let names;
+        try {
+            names = readdirSync(this.#entriesDir);
+        }
+        catch {
+            return 0;
+        }
+        let pruned = 0;
+        for (const name of names.toSorted()) {
+            const key = ENTRY_FILE.exec(name)?.[1];
+            if (key === undefined || live.has(key))
+                continue;
+            try {
+                unlinkSync(join(this.#entriesDir, name));
+                pruned += 1;
+            }
+            catch {
+                // Already gone, or undeletable. Either way it is one stale entry that will be
+                // offered for sweeping again on the next build; nothing reads it meanwhile,
+                // because nothing will ever look up a key no file hashes to.
+            }
+        }
+        return pruned;
     }
     #entryPath(key) {
         return join(this.#entriesDir, `${key}.json`);

package/dist/repomap/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/repomap/cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/repomap/cache.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  mkdirSync,\n  readdirSync,\n  readFileSync,\n  renameSync,\n  unlinkSync,\n  writeFileSync,\n} from 'node:fs';\nimport { join } from 'node:path';\nimport process from 'node:process';\n\nimport { contentHash } from '../hash.ts';\nimport { fsCall } from './io.ts';\nimport type { DefinitionTag, FileTags, ReferenceTag } from './tags.ts';\nimport type { LanguageId } from '../types.ts';\n\n/**\n * The repo map's disk cache — per-file tags, keyed by content hash, JSON on disk.\n *\n * Modelled on Aider's repo-map tags cache (https://aider.chat/docs/repomap.html),\n * with one deliberate substitution: Aider persists through SQLite; this repo ships\n * zero new runtime dependencies, so entries are plain JSON files under a directory\n * **the caller explicitly hands in**. smelt never writes outside a store or cache it\n * was handed — no default location, no home-directory guessing.\n *\n * The key is a content hash over the tag-format version, the language, and the file's\n * exact text. That is the whole invalidation story: edit a file and its key changes,\n * so the stale entry is simply never looked up again. Nothing needs a timestamp.\n *\n * A corrupt entry — unparseable JSON, or JSON of the wrong shape — is **discarded\n * loudly, never trusted**: the entry file is deleted, the tags are re-extracted from\n * source, and the caller's result carries a warning naming the file. Trusting a\n * damaged cache would silently drop symbols from the map, which is this project's\n * signature failure mode.\n *\n * **It is bounded, and the bound is a sweep.** The key is a content hash, so an edit\n * does not replace an entry — it mints a new one and orphans the old, which is\n * invisible and permanent: every pre-edit version of every file the caller ever mapped\n * stays on disk for as long as the directory does. A long session therefore grew this\n * cache without limit while never reading most of it. So {@link TagsCache.sweep}\n * deletes every entry the build it just finished did not use, leaving exactly the tags\n * of the tree as it now stands. The policy is stated as a bound anyone can check: **an\n * entry survives a build only if that build used it**, so the cache is at most one\n * entry per mappable file in the tree — plus whatever a crash left mid-write, which\n * no sweep can safely reclaim; see {@link ENTRY_FILE}.\n *\n * Why that is safe, and the rule any other policy would also have to meet: **a miss\n * can only make a map slower, never wrong.** A missing entry is re-extracted from the\n * file's own bytes, and a present entry is only ever served for the exact content that\n * hashed to its key — so sweeping too much costs a re-parse and sweeping too little\n * costs disk, and neither can change a single symbol in the emitted map. The same rule\n * is why the sweep never throws: it runs after the map is finished, so a cache\n * directory that will not list postpones the bound to the next build rather than\n * turning a computed map into no map at all.\n *\n * The cost is paid by a caller who points *one* cache directory at *several* trees:\n * each build sweeps the others' entries, and every build then re-parses. That is a\n * slower map, not a wrong one, and it is measured rather than hidden — the sweep's\n * count rides back in `RepoMap.cache.pruned` and is printed in `smelt map`'s report.\n * One cache directory per tree is the shape this is tuned for.\n */\n\n/** The format name every cache entry carries. */\nexport const TAGS_CACHE_FORMAT = 'smelt-repomap-tags';\n\n/** Bump this when the tag shape changes: old entries then miss instead of misleading. */\nexport const TAGS_CACHE_VERSION = 1;\n\n/**\n * The cache key for one file's tags. The version and language are part of the hashed\n * material, so a format bump or a re-detected language can never resurrect an entry\n * extracted under different rules.\n */\nexport function tagsCacheKey(language: LanguageId, content: string): string {\n  return contentHash(`${TAGS_CACHE_FORMAT}/${String(TAGS_CACHE_VERSION)}\\0${language}\\0${content}`);\n}\n\n/** What `read()` reports about one lookup. */\nexport type TagsCacheLookup = FileTags | 'corrupt' | undefined;\n\n/**\n * An entry file's name, and the key inside it. Only a name of exactly this shape is\n * ever swept: a temp file from a write in flight (`<key>.json.tmp-<pid>`) does not\n * match, so a sweep cannot delete the file another process is at that moment renaming\n * into place.\n *\n * The price of that exclusion, stated rather than hidden: the bound above is over\n * *entries*, and a process killed between the `writeFileSync` and the `renameSync` in\n * {@link TagsCache.write} leaves a temp file no later sweep reclaims. Reclaiming one\n * safely needs a liveness test this cache cannot make — a pid can be reused, and an\n * mtime cutoff is a number smelt would have invented — and the alternative, deleting\n * a temp file a live writer is about to rename, fails that writer's build. So a\n * crash's leftovers are counted as the known cost of never racing a concurrent write.\n */\nconst ENTRY_FILE = /^([0-9a-f]+)\\.json$/;\n\nexport class TagsCache {\n  readonly #entriesDir: string;\n\n  /** `dir` is the directory the caller handed in; entries live under `<dir>/tags/`. */\n  constructor(dir: string) {\n    this.#entriesDir = join(dir, 'tags');\n    fsCall('create the tags cache directory', this.#entriesDir, () => {\n      mkdirSync(this.#entriesDir, { recursive: true });\n    });\n  }\n\n  /**\n   * The cached tags under `key`, `undefined` on a miss, `'corrupt'` when an entry\n   * existed but could not be trusted — in which case it has already been deleted, so\n   * the corruption is reported exactly once and never re-read.\n   */\n  read(key: string): TagsCacheLookup {\n    const path = this.#entryPath(key);\n    const raw = fsCall('read the cache entry', path, (): string | undefined => {\n      try {\n        return readFileSync(path, 'utf8');\n      } catch (error) {\n        // Structural, not `NodeJS.ErrnoException`: this type reaches the shipped\n        // declarations, and an ambient namespace there breaks a consumer compiling\n        // with `skipLibCheck: false`.\n        if ((error as { code?: string }).code === 'ENOENT') return undefined;\n        throw error;\n      }\n    });\n    if (raw === undefined) return undefined;\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      this.#discard(key);\n      return 'corrupt';\n    }\n    const tags = validateEntry(parsed);\n    if (tags === undefined) {\n      this.#discard(key);\n      return 'corrupt';\n    }\n    return tags;\n  }\n\n  /**\n   * Persist one file's tags. Written to a temp name and renamed into place, so a\n   * concurrent reader never sees a half-written entry; both writers of the same key\n   * are writing identical bytes (the key covers the content), so last-rename-wins is\n   * harmless. No fsync: unlike the elision store, every entry here is derivable from\n   * source, so losing one to a crash costs a re-parse, not a broken promise.\n   */\n  write(key: string, tags: FileTags): void {\n    const body = `${JSON.stringify({\n      format: TAGS_CACHE_FORMAT,\n      version: TAGS_CACHE_VERSION,\n      defs: tags.defs,\n      refs: tags.refs,\n    })}\\n`;\n    const target = this.#entryPath(key);\n    const temp = `${target}.tmp-${String(process.pid)}`;\n    fsCall('write the cache entry', target, () => {\n      writeFileSync(temp, body, 'utf8');\n      renameSync(temp, target);\n    });\n  }\n\n  /**\n   * Delete every entry that is not in `live` — the bound on this cache, described in\n   * full in the module comment above. `live` is the set of keys the build that just\n   * finished actually used, so what survives is exactly the tags of the tree as it\n   * now stands, and the superseded pre-edit entries a content-hash key would otherwise\n   * accumulate forever are gone.\n   *\n   * Returns how many entries were removed, so the caller can report a measured number\n   * rather than a claim.\n   *\n   * **The whole sweep is best effort, listing included.** A directory that will not\n   * list — an unreadable cache directory, or one an external cleaner removed between\n   * the last write and this call — reports `0` pruned and leaves the map alone. It\n   * runs after the tree has been walked, ranked and rendered, so a throw here would\n   * destroy a finished map over housekeeping smelt only wanted to do: no map at all\n   * instead of a slower one, which is the trade this cache is forbidden to make.\n   * Deleting one entry is best effort for the same reason. Nothing is lost by\n   * skipping a sweep — the entries are offered again on the next build, and until\n   * then nothing reads them, because nothing will ever look up a key no file hashes\n   * to.\n   */\n  sweep(live: ReadonlySet<string>): number {\n    let names: string[];\n    try {\n      names = readdirSync(this.#entriesDir);\n    } catch {\n      return 0;\n    }\n    let pruned = 0;\n    for (const name of names.toSorted()) {\n      const key = ENTRY_FILE.exec(name)?.[1];\n      if (key === undefined || live.has(key)) continue;\n      try {\n        unlinkSync(join(this.#entriesDir, name));\n        pruned += 1;\n      } catch {\n        // Already gone, or undeletable. Either way it is one stale entry that will be\n        // offered for sweeping again on the next build; nothing reads it meanwhile,\n        // because nothing will ever look up a key no file hashes to.\n      }\n    }\n    return pruned;\n  }\n\n  #entryPath(key: string): string {\n    return join(this.#entriesDir, `${key}.json`);\n  }\n\n  /** Delete a corrupt entry so it can never be re-read as truth. Best effort. */\n  #discard(key: string): void {\n    try {\n      unlinkSync(this.#entryPath(key));\n    } catch {\n      // Already gone, or undeletable — either way it will be overwritten by the\n      // rewrite that follows every discard.\n    }\n  }\n}\n\n/** The parsed entry as `FileTags`, or `undefined` when its shape cannot be trusted. */\nfunction validateEntry(parsed: unknown): FileTags | undefined {\n  if (typeof parsed !== 'object' || parsed === null) return undefined;\n  const entry = parsed as { format?: unknown; version?: unknown; defs?: unknown; refs?: unknown };\n  if (entry.format !== TAGS_CACHE_FORMAT || entry.version !== TAGS_CACHE_VERSION) return undefined;\n  if (!Array.isArray(entry.defs) || !Array.isArray(entry.refs)) return undefined;\n\n  const defs: DefinitionTag[] = [];\n  for (const item of entry.defs as unknown[]) {\n    const def = item as { name?: unknown; kind?: unknown; line?: unknown };\n    if (typeof def.name !== 'string' || def.name === '') return undefined;\n    if (typeof def.kind !== 'string' || def.kind === '') return undefined;\n    if (typeof def.line !== 'number' || !Number.isInteger(def.line) || def.line < 1) {\n      return undefined;\n    }\n    defs.push({ name: def.name, kind: def.kind, line: def.line });\n  }\n  const refs: ReferenceTag[] = [];\n  for (const item of entry.refs as unknown[]) {\n    const ref = item as { name?: unknown; count?: unknown };\n    if (typeof ref.name !== 'string' || ref.name === '') return undefined;\n    if (typeof ref.count !== 'number' || !Number.isInteger(ref.count) || ref.count < 1) {\n      return undefined;\n    }\n    refs.push({ name: ref.name, count: ref.count });\n  }\n  return { defs, refs };\n}\n"]}

package/dist/repomap/io.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The one place the repo map touches a filesystem call that can throw.
+ *
+ * The consumer contract makes exactly one promise about errors — every error smelt
+ * throws is an `instanceof SmeltError` — and the repo map is the module most able to
+ * break it, because it walks a whole tree the caller named. `buildRepoMap({ root:
+ * '/nonexistent' })` threw the raw Node `ENOENT` from `readdirSync`: not a
+ * `SmeltError`, past the documented `catch`, with the path only in a stack trace. The
+ * same escape was one `EACCES` away in the tags cache, in `stat`, and in `read`.
+ *
+ * So every such call is written as `fsCall(operation, path, () => …)`. It adds no
+ * behaviour — the call still fails, at the same moment, for the same reason — it only
+ * puts the failure inside the contract and names the path in the message.
+ *
+ * A {@link SmeltError} passes through untouched. A caller's own {@link RepoReader} may
+ * refuse in smelt's own currency (a store that will not serve a path, say); that
+ * refusal is already inside the contract, and rewrapping it would bury a sentence its
+ * author wrote deliberately under a generic one.
+ *
+ * `operation` is a verb phrase that reads as `could not <operation> "<path>"` —
+ * `list the directory`, `read the file`, `write the cache entry`.
+ */
+export declare function fsCall<T>(operation: string, path: string, run: () => T): T;
+//# sourceMappingURL=io.d.ts.map

package/dist/repomap/io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../src/repomap/io.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAO1E","sourcesContent":["import { RepoMapIoError, SmeltError } from '../errors.ts';\n\n/**\n * The one place the repo map touches a filesystem call that can throw.\n *\n * The consumer contract makes exactly one promise about errors — every error smelt\n * throws is an `instanceof SmeltError` — and the repo map is the module most able to\n * break it, because it walks a whole tree the caller named. `buildRepoMap({ root:\n * '/nonexistent' })` threw the raw Node `ENOENT` from `readdirSync`: not a\n * `SmeltError`, past the documented `catch`, with the path only in a stack trace. The\n * same escape was one `EACCES` away in the tags cache, in `stat`, and in `read`.\n *\n * So every such call is written as `fsCall(operation, path, () => …)`. It adds no\n * behaviour — the call still fails, at the same moment, for the same reason — it only\n * puts the failure inside the contract and names the path in the message.\n *\n * A {@link SmeltError} passes through untouched. A caller's own {@link RepoReader} may\n * refuse in smelt's own currency (a store that will not serve a path, say); that\n * refusal is already inside the contract, and rewrapping it would bury a sentence its\n * author wrote deliberately under a generic one.\n *\n * `operation` is a verb phrase that reads as `could not <operation> \"<path>\"` —\n * `list the directory`, `read the file`, `write the cache entry`.\n */\nexport function fsCall<T>(operation: string, path: string, run: () => T): T {\n  try {\n    return run();\n  } catch (error) {\n    if (error instanceof SmeltError) throw error;\n    throw new RepoMapIoError(operation, path, error);\n  }\n}\n"]}

package/dist/repomap/io.js

@@ -0,0 +1,34 @@
+import { RepoMapIoError, SmeltError } from '../errors.js';
+/**
+ * The one place the repo map touches a filesystem call that can throw.
+ *
+ * The consumer contract makes exactly one promise about errors — every error smelt
+ * throws is an `instanceof SmeltError` — and the repo map is the module most able to
+ * break it, because it walks a whole tree the caller named. `buildRepoMap({ root:
+ * '/nonexistent' })` threw the raw Node `ENOENT` from `readdirSync`: not a
+ * `SmeltError`, past the documented `catch`, with the path only in a stack trace. The
+ * same escape was one `EACCES` away in the tags cache, in `stat`, and in `read`.
+ *
+ * So every such call is written as `fsCall(operation, path, () => …)`. It adds no
+ * behaviour — the call still fails, at the same moment, for the same reason — it only
+ * puts the failure inside the contract and names the path in the message.
+ *
+ * A {@link SmeltError} passes through untouched. A caller's own {@link RepoReader} may
+ * refuse in smelt's own currency (a store that will not serve a path, say); that
+ * refusal is already inside the contract, and rewrapping it would bury a sentence its
+ * author wrote deliberately under a generic one.
+ *
+ * `operation` is a verb phrase that reads as `could not <operation> "<path>"` —
+ * `list the directory`, `read the file`, `write the cache entry`.
+ */
+export function fsCall(operation, path, run) {
+    try {
+        return run();
+    }
+    catch (error) {
+        if (error instanceof SmeltError)
+            throw error;
+        throw new RepoMapIoError(operation, path, error);
+    }
+}
+//# sourceMappingURL=io.js.map

package/dist/repomap/io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../../src/repomap/io.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,MAAM,CAAI,SAAiB,EAAE,IAAY,EAAE,GAAY;IACrE,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,UAAU;YAAE,MAAM,KAAK,CAAC;QAC7C,MAAM,IAAI,cAAc,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC;AACH,CAAC","sourcesContent":["import { RepoMapIoError, SmeltError } from '../errors.ts';\n\n/**\n * The one place the repo map touches a filesystem call that can throw.\n *\n * The consumer contract makes exactly one promise about errors — every error smelt\n * throws is an `instanceof SmeltError` — and the repo map is the module most able to\n * break it, because it walks a whole tree the caller named. `buildRepoMap({ root:\n * '/nonexistent' })` threw the raw Node `ENOENT` from `readdirSync`: not a\n * `SmeltError`, past the documented `catch`, with the path only in a stack trace. The\n * same escape was one `EACCES` away in the tags cache, in `stat`, and in `read`.\n *\n * So every such call is written as `fsCall(operation, path, () => …)`. It adds no\n * behaviour — the call still fails, at the same moment, for the same reason — it only\n * puts the failure inside the contract and names the path in the message.\n *\n * A {@link SmeltError} passes through untouched. A caller's own {@link RepoReader} may\n * refuse in smelt's own currency (a store that will not serve a path, say); that\n * refusal is already inside the contract, and rewrapping it would bury a sentence its\n * author wrote deliberately under a generic one.\n *\n * `operation` is a verb phrase that reads as `could not <operation> \"<path>\"` —\n * `list the directory`, `read the file`, `write the cache entry`.\n */\nexport function fsCall<T>(operation: string, path: string, run: () => T): T {\n  try {\n    return run();\n  } catch (error) {\n    if (error instanceof SmeltError) throw error;\n    throw new RepoMapIoError(operation, path, error);\n  }\n}\n"]}

package/dist/repomap/map.d.ts

@@ -1,5 +1,6 @@
+import type { RepoReader } from './reader.ts';
 /**
- * The repo-map builder — Slice 7, the cross-file shape.
+ * The repo-map builder — the cross-file shape.
  *
  * **Modelled on Aider's repo-map, and credited as such.** The whole design is prior
  * art: Paul Gauthier's Aider extracts tree-sitter definition/reference tags per file,
@@ -11,6 +12,9 @@
  *
  *  - **Local files only** (Law 1). The caller names the root; symlinks are never
  *    followed, so the walk cannot leave it; binary files are skipped; no network.
+ *    The whole tree is read through one read-only seam, {@link RepoReader} — the
+ *    default is `node:fs` and the interface has no writer, so the only bytes this
+ *    module can write are the tags cache the caller asked for by name.
  *  - **Every inclusion is explainable** (Law 2, applied to inclusion rather than
  *    elision): each symbol in the map carries a rule id and a sentence stating its
  *    definition site and the measured reference counts that ranked it.
@@ -18,8 +22,32 @@
  *    path, name, and line. Two runs over the same tree are byte-identical.
  *  - **The budget is bytes**, same contract as the planners, and it is respected by
  *    construction: symbols are added in rank order until the next line would not fit.
- *  - **The cache lives only in a directory the caller explicitly hands in**, and a
- *    corrupt entry is discarded loudly — a warning in the result — never trusted.
+ *  - **The cache lives only in a directory the caller explicitly hands in**, a corrupt
+ *    entry is discarded loudly — a warning in the result — never trusted, and it is
+ *    bounded: each build sweeps the entries it did not use, so the superseded
+ *    pre-edit version of every file does not accumulate forever. The sweep is
+ *    housekeeping and never fatal: it runs after the map is computed, so a cache it
+ *    cannot tidy costs a re-parse next time, never this map. See `cache.ts`.
+ *  - **Every failure is a `SmeltError`**: the consumer contract's one promise about
+ *    errors holds here too, so a missing root or an unreadable file arrives as
+ *    {@link RepoMapIoError} naming the path, not as a raw Node `ENOENT`. Every
+ *    filesystem call in this module goes through `fsCall` in `io.ts`.
+ *
+ * **What the ranking can and cannot resolve.** A reference binds to a definition **by
+ * bare identifier** — the tags carry names, not resolved symbols — so every definition
+ * of a name receives every reference to that name, wherever either lives. Two files
+ * that both define `run` share one another's inbound references and therefore rank
+ * alike; two overloads of one name each count the whole traffic to it, so a name is
+ * counted once per definition of it; an identifier that happens to collide with an
+ * unrelated one somewhere else in the tree lends it rank. This is Aider's design, not
+ * a defect introduced here: resolving properly means per-language import and scope
+ * resolution — a type checker per language — and the map is a *ranking heuristic* for
+ * deciding what a human or a model should look at first, never a symbol resolver.
+ * What it must not do is *claim* a resolution it did not perform, and it does not: the
+ * receipt on each entry says what was actually measured — `refsIn` is the number of
+ * references to that **name** across the scanned tree — so a reader who knows this
+ * paragraph can read the numbers for exactly what they are. Anything that needs true
+ * binding (rename, call graph, dead-code detection) needs a different tool.
  *
  * **Deliberately NOT a `Planner`.** `buildRepoMap` returns a {@link RepoMap},
  * not an `ElisionPlan`: nothing here is elided, nothing is stored under a hash, and
@@ -50,9 +78,26 @@ export declare const REPO_MAP_PATH_ONLY_RULE = "path-only";
 /** Rule id for the warning left behind when a corrupt cache entry is discarded. */
 export declare const REPO_MAP_CACHE_CORRUPT_RULE = "cache-entry-corrupt";
 /**
- * The ignore list used when the caller supplies none. Deliberately tiny: `.git` is
- * object storage, `node_modules` is other people's code. A caller with opinions passes
- * its own list, which *replaces* this one.
+ * The ignore list used when the caller supplies none.
+ *
+ * Two kinds of directory are on it, for one reason: **including them makes the map
+ * wrong, not merely large.** `.git` is object storage and `node_modules` is other
+ * people's code — neither is the repository's own source. The rest are build outputs,
+ * and they are the sharper case: a built TypeScript repo carries `dist/foo.js` and
+ * `dist/foo.d.ts` beside `src/foo.ts`, so *every* symbol was ranked and rendered three
+ * times, the duplicates referenced each other, and the default map of the commonest
+ * repo shape in this ecosystem was a third source and two-thirds its own compiler
+ * output. The names here (`dist`, `build`, `out`, `coverage`) are the conventional
+ * output directories of the toolchains this map is most often pointed at; a repo that
+ * builds somewhere else passes its own list.
+ *
+ * Deliberately still tiny, and deliberately **not** a `.gitignore` parser: an ignore
+ * list smelt cannot state in one sentence is one nobody can predict.
+ *
+ * A caller with opinions passes its own list, which *replaces* this one — it is not
+ * merged with it. Replacement is the documented contract because a merge means there
+ * is no way to say "map my `dist`, I meant it", and a default you cannot turn off is
+ * not a default.
  */
 export declare const DEFAULT_REPO_IGNORE: readonly string[];
 /** Why an entry is in the map — same two-register shape as {@link ElisionReason}. */
@@ -87,6 +132,14 @@ export interface RepoMapOptions {
      * to disk — smelt never writes outside a store or cache it was explicitly handed.
      */
     readonly cacheDir?: string;
+    /**
+     * The filesystem the map reads through. Defaults to {@link nodeFsReader} — plain
+     * `node:fs`, the calls this module used to make in-line — so callers that do not
+     * care never mention it. Hand in a {@link RepoReader} to map a tree that is not on
+     * this disk, or to watch, call by call, exactly what the walk touched. Read-only
+     * by construction: the interface has no writer.
+     */
+    readonly reader?: RepoReader;
 }
 /** One symbol included in the rendered map, with the receipt for its inclusion. */
 export interface RepoMapEntry {
@@ -123,6 +176,12 @@ export interface RepoMapCacheCounts {
     readonly misses: number;
     /** Corrupt entries deleted and re-extracted; each one also left a warning. */
     readonly discarded: number;
+    /**
+     * Entries this build swept because it did not use them — the bound on the cache,
+     * made visible. A non-zero count on a repeat build over an unchanged tree means the
+     * cache directory is shared with another tree, which costs re-parses.
+     */
+    readonly pruned: number;
 }
 export interface RepoMap {
     readonly id: typeof REPO_MAP_ID;
@@ -154,6 +213,10 @@ export interface RepoMap {
  * `test/guards/repo-map.test.ts`, not assumed.
  *
  * @throws {SmeltError} when `budgetBytes` is not a positive integer.
+ * @throws {RepoMapIoError} when a filesystem call fails — a root that is not there, a
+ *   directory that will not list, a file that will not read. Never a raw Node error:
+ *   the contract says every error smelt throws is a `SmeltError`, and a repo map that
+ *   let `ENOENT` past would be the exception that made the promise worthless.
  * @throws {GrammarUnavailableError} when a supported language's grammar cannot load —
  *   never a silent skip that would make the map quietly incomplete.
  */

package/dist/repomap/map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../src/repomap/map.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../src/repomap/map.ts"],"names":[],"mappings":"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","sourcesContent":["import { join } from 'node:path';\n\nimport { detectLanguage } from '../detect.ts';\nimport { SmeltError } from '../errors.ts';\nimport type { LanguageId } from '../types.ts';\n\nimport { TagsCache, tagsCacheKey } from './cache.ts';\nimport { fsCall } from './io.ts';\nimport { rankDefinitions } from './rank.ts';\nimport type { FileTagsEntry, RankedDefinition } from './rank.ts';\nimport { nodeFsReader } from './reader.ts';\nimport type { RepoReader } from './reader.ts';\nimport { extractTags } from './tags.ts';\nimport type { FileTags } from './tags.ts';\n\n/**\n * The repo-map builder — the cross-file shape.\n *\n * **Modelled on Aider's repo-map, and credited as such.** The whole design is prior\n * art: Paul Gauthier's Aider extracts tree-sitter definition/reference tags per file,\n * runs PageRank over the cross-file reference graph, fits the ranked result to a\n * budget, and caches tags on disk keyed by content — see\n * https://aider.chat/docs/repomap.html and `aider/repomap.py` in\n * https://github.com/Aider-AI/aider. Nothing about the approach is this project's\n * invention; what this module adds is only smelt's own house rules:\n *\n *  - **Local files only** (Law 1). The caller names the root; symlinks are never\n *    followed, so the walk cannot leave it; binary files are skipped; no network.\n *    The whole tree is read through one read-only seam, {@link RepoReader} — the\n *    default is `node:fs` and the interface has no writer, so the only bytes this\n *    module can write are the tags cache the caller asked for by name.\n *  - **Every inclusion is explainable** (Law 2, applied to inclusion rather than\n *    elision): each symbol in the map carries a rule id and a sentence stating its\n *    definition site and the measured reference counts that ranked it.\n *  - **Deterministic**: fixed PageRank constants, sorted walks, a total tie-break by\n *    path, name, and line. Two runs over the same tree are byte-identical.\n *  - **The budget is bytes**, same contract as the planners, and it is respected by\n *    construction: symbols are added in rank order until the next line would not fit.\n *  - **The cache lives only in a directory the caller explicitly hands in**, a corrupt\n *    entry is discarded loudly — a warning in the result — never trusted, and it is\n *    bounded: each build sweeps the entries it did not use, so the superseded\n *    pre-edit version of every file does not accumulate forever. The sweep is\n *    housekeeping and never fatal: it runs after the map is computed, so a cache it\n *    cannot tidy costs a re-parse next time, never this map. See `cache.ts`.\n *  - **Every failure is a `SmeltError`**: the consumer contract's one promise about\n *    errors holds here too, so a missing root or an unreadable file arrives as\n *    {@link RepoMapIoError} naming the path, not as a raw Node `ENOENT`. Every\n *    filesystem call in this module goes through `fsCall` in `io.ts`.\n *\n * **What the ranking can and cannot resolve.** A reference binds to a definition **by\n * bare identifier** — the tags carry names, not resolved symbols — so every definition\n * of a name receives every reference to that name, wherever either lives. Two files\n * that both define `run` share one another's inbound references and therefore rank\n * alike; two overloads of one name each count the whole traffic to it, so a name is\n * counted once per definition of it; an identifier that happens to collide with an\n * unrelated one somewhere else in the tree lends it rank. This is Aider's design, not\n * a defect introduced here: resolving properly means per-language import and scope\n * resolution — a type checker per language — and the map is a *ranking heuristic* for\n * deciding what a human or a model should look at first, never a symbol resolver.\n * What it must not do is *claim* a resolution it did not perform, and it does not: the\n * receipt on each entry says what was actually measured — `refsIn` is the number of\n * references to that **name** across the scanned tree — so a reader who knows this\n * paragraph can read the numbers for exactly what they are. Anything that needs true\n * binding (rename, call graph, dead-code detection) needs a different tool.\n *\n * **Deliberately NOT a `Planner`.** `buildRepoMap` returns a {@link RepoMap},\n * not an `ElisionPlan`: nothing here is elided, nothing is stored under a hash, and\n * there is no original to reconstruct — the map is a *summary built up under a\n * budget*, not a *removal to be reversed*. Forcing the Planner interface onto it\n * would claim Law 3 (reversibility) about output that has no bytes to give back,\n * which is exactly the kind of lie the interface exists to prevent. The CLI serves\n * it as its own subcommand (`smelt map`), never as a `--strategy`.\n */\n\n/** The id stamped on every map this module emits. */\nexport const REPO_MAP_ID = 'repomap/v1';\n\n/**\n * Rule id for a symbol something in the scanned tree references — its own file\n * included, so its rank may still be zero when every reference is same-file (only\n * cross-file references move rank).\n */\nexport const REPO_MAP_RANKED_RULE = 'ranked-definition';\n\n/** Rule id for a definition nothing in the scanned tree references. */\nexport const REPO_MAP_UNREFERENCED_RULE = 'unreferenced-definition';\n\n/**\n * Rule id for a definition promoted because it matches a caller-supplied focus term.\n * The rank stays the measured PageRank share — focus moves a symbol's *place in the\n * fill order*, never its numbers.\n */\nexport const REPO_MAP_FOCUS_RULE = 'focus-match';\n\n/** Rule id for a file listed by path because no definitions were extracted from it. */\nexport const REPO_MAP_PATH_ONLY_RULE = 'path-only';\n\n/** Rule id for the warning left behind when a corrupt cache entry is discarded. */\nexport const REPO_MAP_CACHE_CORRUPT_RULE = 'cache-entry-corrupt';\n\n/**\n * The ignore list used when the caller supplies none.\n *\n * Two kinds of directory are on it, for one reason: **including them makes the map\n * wrong, not merely large.** `.git` is object storage and `node_modules` is other\n * people's code — neither is the repository's own source. The rest are build outputs,\n * and they are the sharper case: a built TypeScript repo carries `dist/foo.js` and\n * `dist/foo.d.ts` beside `src/foo.ts`, so *every* symbol was ranked and rendered three\n * times, the duplicates referenced each other, and the default map of the commonest\n * repo shape in this ecosystem was a third source and two-thirds its own compiler\n * output. The names here (`dist`, `build`, `out`, `coverage`) are the conventional\n * output directories of the toolchains this map is most often pointed at; a repo that\n * builds somewhere else passes its own list.\n *\n * Deliberately still tiny, and deliberately **not** a `.gitignore` parser: an ignore\n * list smelt cannot state in one sentence is one nobody can predict.\n *\n * A caller with opinions passes its own list, which *replaces* this one — it is not\n * merged with it. Replacement is the documented contract because a merge means there\n * is no way to say \"map my `dist`, I meant it\", and a default you cannot turn off is\n * not a default.\n */\nexport const DEFAULT_REPO_IGNORE: readonly string[] = [\n  '.git',\n  'node_modules',\n  'dist',\n  'build',\n  'out',\n  'coverage',\n];\n\n/** Why an entry is in the map — same two-register shape as {@link ElisionReason}. */\nexport interface RepoMapReason {\n  /** Stable machine id, e.g. `'ranked-definition'`. */\n  readonly rule: string;\n  /** A sentence a human can read: definition site and the counts that ranked it. */\n  readonly explanation: string;\n}\n\nexport interface RepoMapOptions {\n  /** The repository root to read. Local files only; symlinks are never followed. */\n  readonly root: string;\n  /** Ceiling for the rendered map, in UTF-8 bytes. Respected, not aimed at. */\n  readonly budgetBytes: number;\n  /**\n   * What the task is actually about — same meaning as a planner's focus. A\n   * definition whose name or path contains a term (case-insensitive, like the\n   * lexical planner's default) is promoted to the front of the fill order, so it\n   * survives a tight budget. Promotion only: the measured rank and reference\n   * counts are never altered, and each promoted entry says which term it matched.\n   */\n  readonly focus?: readonly string[];\n  /**\n   * Paths to skip, replacing {@link DEFAULT_REPO_IGNORE}. An entry containing `/` is\n   * matched as a root-relative path prefix — a trailing slash counts, so `build/`\n   * means the root-level `build` tree, never every `build` segment anywhere; a bare\n   * name matches any path segment.\n   */\n  readonly ignore?: readonly string[];\n  /**\n   * Directory for the tags cache. **Only** when this is passed is anything written\n   * to disk — smelt never writes outside a store or cache it was explicitly handed.\n   */\n  readonly cacheDir?: string;\n  /**\n   * The filesystem the map reads through. Defaults to {@link nodeFsReader} — plain\n   * `node:fs`, the calls this module used to make in-line — so callers that do not\n   * care never mention it. Hand in a {@link RepoReader} to map a tree that is not on\n   * this disk, or to watch, call by call, exactly what the walk touched. Read-only\n   * by construction: the interface has no writer.\n   */\n  readonly reader?: RepoReader;\n}\n\n/** One symbol included in the rendered map, with the receipt for its inclusion. */\nexport interface RepoMapEntry {\n  readonly path: string;\n  readonly name: string;\n  readonly kind: string;\n  /** 1-based line of the definition. */\n  readonly line: number;\n  /** PageRank share this definition attracted. `0` for unreferenced definitions. */\n  readonly rank: number;\n  /** Measured: total references to this name across the scanned tree. */\n  readonly refsIn: number;\n  /** Measured: distinct files holding those references. */\n  readonly refsInFiles: number;\n  /** Measured: references the defining file makes to names defined elsewhere. */\n  readonly refsOut: number;\n  readonly reason: RepoMapReason;\n}\n\n/** A file listed by path because no definitions were extracted from it. */\nexport interface RepoMapPathEntry {\n  readonly path: string;\n  readonly reason: RepoMapReason;\n}\n\n/** Something worth telling the caller that is not worth failing the build over. */\nexport interface RepoMapWarning {\n  readonly rule: string;\n  readonly explanation: string;\n}\n\n/** Measured cache activity for one build. Counts only — smelt claims no rates. */\nexport interface RepoMapCacheCounts {\n  /** Lookups answered from disk. */\n  readonly hits: number;\n  /** Lookups that found nothing and re-extracted from source. */\n  readonly misses: number;\n  /** Corrupt entries deleted and re-extracted; each one also left a warning. */\n  readonly discarded: number;\n  /**\n   * Entries this build swept because it did not use them — the bound on the cache,\n   * made visible. A non-zero count on a repeat build over an unchanged tree means the\n   * cache directory is shared with another tree, which costs re-parses.\n   */\n  readonly pruned: number;\n}\n\nexport interface RepoMap {\n  readonly id: typeof REPO_MAP_ID;\n  /** The rendered map. Always at most `budgetBytes` UTF-8 bytes. */\n  readonly text: string;\n  readonly outputBytes: number;\n  readonly budgetBytes: number;\n  /** The symbols that fit, in fill order (focus matches first, then rank). */\n  readonly entries: readonly RepoMapEntry[];\n  /** Path-only files that fit, after the symbols, in path order. */\n  readonly pathOnly: readonly RepoMapPathEntry[];\n  /** All ranked definitions found, before the budget cut anything. */\n  readonly definitionsTotal: number;\n  /** All path-only candidates found, before the budget cut anything. */\n  readonly pathOnlyTotal: number;\n  /** Regular files examined under the root, after the ignore list. */\n  readonly filesScanned: number;\n  /** Files skipped because their bytes contain a NUL — binary, not mappable. */\n  readonly binarySkipped: number;\n  readonly warnings: readonly RepoMapWarning[];\n  /** Present only when the caller handed in a `cacheDir`. Never invented. */\n  readonly cache?: RepoMapCacheCounts;\n}\n\n/**\n * Build a ranked symbol map of the repository under `options.root`.\n *\n * Reads local files only. Deterministic: two runs over the same tree, with or without\n * a warm cache, produce byte-identical maps — asserted by the guard in\n * `test/guards/repo-map.test.ts`, not assumed.\n *\n * @throws {SmeltError} when `budgetBytes` is not a positive integer.\n * @throws {RepoMapIoError} when a filesystem call fails — a root that is not there, a\n *   directory that will not list, a file that will not read. Never a raw Node error:\n *   the contract says every error smelt throws is a `SmeltError`, and a repo map that\n *   let `ENOENT` past would be the exception that made the promise worthless.\n * @throws {GrammarUnavailableError} when a supported language's grammar cannot load —\n *   never a silent skip that would make the map quietly incomplete.\n */\nexport async function buildRepoMap(options: RepoMapOptions): Promise<RepoMap> {\n  const { root, budgetBytes } = options;\n  if (!Number.isInteger(budgetBytes) || budgetBytes < 1) {\n    throw new SmeltError(\n      `smelt: budgetBytes must be a positive integer, got ${String(budgetBytes)}. ` +\n        `There is no default budget — a budget smelt invented would silently decide ` +\n        `how much of the map to throw away.`,\n    );\n  }\n  const ignore = options.ignore ?? DEFAULT_REPO_IGNORE;\n  const reader = options.reader ?? nodeFsReader();\n  const cacheDir = options.cacheDir;\n  const cache =\n    cacheDir === undefined\n      ? undefined\n      : fsCall('open the tags cache directory', cacheDir, () => new TagsCache(cacheDir));\n  const cacheCounts = { hits: 0, misses: 0, discarded: 0, pruned: 0 };\n  // The keys this build used. Everything else under the cache directory is a\n  // superseded entry — the pre-edit version of a file, or another tree's tags — and\n  // is swept once the walk is done. See the bound in `cache.ts`.\n  const liveKeys = new Set<string>();\n  const warnings: RepoMapWarning[] = [];\n\n  const files = scanFiles(reader, root, ignore);\n  let binarySkipped = 0;\n  const parsed: FileTagsEntry[] = [];\n  const pathOnlyPaths: string[] = [];\n\n  for (const rel of files) {\n    const path = join(root, ...rel.split('/'));\n    const bytes = fsCall('read the file', path, () => reader.read(path));\n    if (bytes.includes(0)) {\n      binarySkipped += 1;\n      continue;\n    }\n    const language = detectLanguage(rel);\n    if (language === 'unknown') {\n      pathOnlyPaths.push(rel);\n      continue;\n    }\n    // `RepoReader.read` promises `Uint8Array`, not `Buffer` (its own note says why),\n    // and `ignoreBOM` keeps this byte-for-byte what `Buffer.toString('utf8')` did: a\n    // leading U+FEFF stays in the text instead of being silently eaten.\n    const text = new TextDecoder('utf-8', { ignoreBOM: true }).decode(bytes);\n    const tags = await tagsFor(text, language, cache, cacheCounts, liveKeys, warnings, rel);\n    if (tags.defs.length === 0) pathOnlyPaths.push(rel);\n    if (tags.defs.length > 0 || tags.refs.length > 0) parsed.push({ path: rel, tags });\n  }\n\n  if (cache !== undefined) cacheCounts.pruned = cache.sweep(liveKeys);\n\n  const ranked = rankDefinitions(parsed);\n  const focus = (options.focus ?? []).filter((term) => term.length > 0);\n  const ordered = orderWithFocus(ranked, focus);\n\n  // Fit to the budget: ranked symbols first — focus matches promoted to the front,\n  // each partition in rank order — then path-only files, in path order. Filling\n  // stops at the first line that does not fit, so the included set is always a\n  // prefix of that order — a map that skipped its #2 symbol to squeeze in its #9\n  // would be lying about what mattered.\n  const lines: string[] = [];\n  let bytes = 0;\n  const tryAppend = (line: string): boolean => {\n    const lineBytes = Buffer.byteLength(line, 'utf8') + 1; // its trailing newline\n    if (bytes + lineBytes > budgetBytes) return false;\n    lines.push(line);\n    bytes += lineBytes;\n    return true;\n  };\n\n  const entries: RepoMapEntry[] = [];\n  for (const { definition, focusTerm } of ordered) {\n    if (!tryAppend(renderDefinition(definition))) break;\n    entries.push(toEntry(definition, focusTerm));\n  }\n  const pathOnly: RepoMapPathEntry[] = [];\n  if (entries.length === ordered.length) {\n    for (const rel of pathOnlyPaths) {\n      if (!tryAppend(`${rel} [path only]`)) break;\n      pathOnly.push({\n        path: rel,\n        reason: {\n          rule: REPO_MAP_PATH_ONLY_RULE,\n          explanation: `no definitions extracted from ${rel}; listed by path so the file stays visible`,\n        },\n      });\n    }\n  }\n\n  const text = lines.length === 0 ? '' : `${lines.join('\\n')}\\n`;\n  return {\n    id: REPO_MAP_ID,\n    text,\n    outputBytes: Buffer.byteLength(text, 'utf8'),\n    budgetBytes,\n    entries,\n    pathOnly,\n    definitionsTotal: ranked.length,\n    pathOnlyTotal: pathOnlyPaths.length,\n    filesScanned: files.length,\n    binarySkipped,\n    warnings,\n    ...(cache === undefined ? {} : { cache: { ...cacheCounts } }),\n  };\n}\n\n/** One file's tags — from the cache when possible, from the grammar when not. */\nasync function tagsFor(\n  text: string,\n  language: LanguageId,\n  cache: TagsCache | undefined,\n  counts: { hits: number; misses: number; discarded: number; pruned: number },\n  liveKeys: Set<string>,\n  warnings: RepoMapWarning[],\n  rel: string,\n): Promise<FileTags> {\n  if (cache === undefined) return extractTags(text, language);\n\n  const key = tagsCacheKey(language, text);\n  // Recorded before the lookup, not after: this key is what the tree holds now, so it\n  // survives the sweep whether it was a hit, a miss, or a discard-and-rewrite.\n  liveKeys.add(key);\n  const found = cache.read(key);\n  if (found === 'corrupt') {\n    counts.discarded += 1;\n    warnings.push({\n      rule: REPO_MAP_CACHE_CORRUPT_RULE,\n      explanation:\n        `discarded a corrupt cache entry for ${rel} and re-extracted its tags from ` +\n        `source; the entry file was deleted so it cannot be read again`,\n    });\n  } else if (found !== undefined) {\n    counts.hits += 1;\n    return found;\n  } else {\n    counts.misses += 1;\n  }\n  const tags = await extractTags(text, language);\n  cache.write(key, tags);\n  return tags;\n}\n\n/**\n * Walk the tree under `root`, depth-first in sorted order, returning `/`-separated\n * relative paths of every regular file that survives the ignore list.\n *\n * Symlinks are skipped outright — file or directory, in-root or out. Never following\n * one is the simplest true implementation of \"never follow a symlink out of the\n * root\": there is no resolution step to get wrong. The refusal is stated on\n * `isSymlink`, not left to the accident that an `lstat` of a link is neither file\n * nor directory — so a reader whose `stat` resolves the target is refused just the\n * same, and the guard can watch the refusal happen by counting reader calls.\n *\n * The ignore list is applied before the entry is statted, so an ignored path costs\n * nothing and is never even looked at.\n */\nfunction scanFiles(reader: RepoReader, root: string, ignore: readonly string[]): readonly string[] {\n  const found: string[] = [];\n  const walk = (dir: string, relDir: string): void => {\n    const listed = fsCall('list the directory', dir, () => reader.list(dir));\n    for (const entry of listed.map((item) => item.name).toSorted()) {\n      const rel = relDir === '' ? entry : `${relDir}/${entry}`;\n      if (isIgnored(rel, ignore)) continue;\n      const full = join(dir, entry);\n      const stat = fsCall('stat', full, () => reader.stat(full));\n      if (stat === undefined) continue; // the reader has nothing there\n      if (stat.isSymlink) continue;\n      if (stat.isDirectory) walk(full, rel);\n      else if (stat.isFile) found.push(rel);\n    }\n  };\n  walk(root, '');\n  return found;\n}\n\n/** See {@link RepoMapOptions.ignore} for the two match modes. */\nfunction isIgnored(rel: string, ignore: readonly string[]): boolean {\n  for (const entry of ignore) {\n    const cleaned = entry.replace(/\\/+$/, '');\n    if (cleaned === '') continue;\n    // Prefix mode is decided on the entry AS WRITTEN, before the trailing slash is\n    // trimmed: `build/` contains a `/` and so is the documented root-relative prefix\n    // (the root-level `build` tree), not a bare name that would match a `build`\n    // segment at any depth.\n    if (entry.includes('/')) {\n      if (rel === cleaned || rel.startsWith(`${cleaned}/`)) return true;\n    } else if (rel.split('/').includes(cleaned)) {\n      return true;\n    }\n  }\n  return false;\n}\n\n/** One ranked definition in fill order, with the focus term that promoted it, if any. */\ninterface OrderedDefinition {\n  readonly definition: RankedDefinition;\n  readonly focusTerm?: string;\n}\n\n/**\n * The fill order: focus-matched definitions first, then the rest, each partition\n * keeping the ranker's total order. A stable partition of a deterministic order is\n * itself deterministic, so the map's byte-for-byte claim survives focus untouched.\n * The match is a case-insensitive substring over name and path — the lexical\n * planner's default, so \"focus\" means the same thing in both places — and the\n * *first* matching term in caller order is the one the receipt names.\n */\nfunction orderWithFocus(\n  ranked: readonly RankedDefinition[],\n  focus: readonly string[],\n): readonly OrderedDefinition[] {\n  if (focus.length === 0) return ranked.map((definition) => ({ definition }));\n  const needles = focus.map((term) => term.toLowerCase());\n  const matched: OrderedDefinition[] = [];\n  const rest: OrderedDefinition[] = [];\n  for (const definition of ranked) {\n    const haystack = `${definition.path}\\0${definition.name}`.toLowerCase();\n    const index = needles.findIndex((needle) => haystack.includes(needle));\n    if (index === -1) rest.push({ definition });\n    else matched.push({ definition, focusTerm: focus[index]! });\n  }\n  return [...matched, ...rest];\n}\n\n/** One rendered map line. Everything in it is measured, nothing estimated. */\nfunction renderDefinition(definition: RankedDefinition): string {\n  return (\n    `${definition.path}:${String(definition.line)} ${definition.kind} ${definition.name} ` +\n    `[${String(definition.refsIn)} in from ${String(definition.refsInFiles)} ` +\n    `${plural('file', definition.refsInFiles)}, ${String(definition.refsOut)} out]`\n  );\n}\n\n/** Law 2, applied to inclusion: the receipt every included symbol carries. */\nfunction toEntry(definition: RankedDefinition, focusTerm?: string): RepoMapEntry {\n  const site = `defined at ${definition.path}:${String(definition.line)}`;\n  const counts =\n    `${String(definition.refsIn)} ${plural('reference', definition.refsIn)} in ` +\n    `from ${String(definition.refsInFiles)} ${plural('file', definition.refsInFiles)}; ` +\n    `its file makes ${String(definition.refsOut)} ` +\n    `${plural('reference', definition.refsOut)} out`;\n  const reason: RepoMapReason =\n    focusTerm !== undefined\n      ? {\n          rule: REPO_MAP_FOCUS_RULE,\n          explanation: `${site}; matches focus \"${focusTerm}\"; ${counts}`,\n        }\n      : definition.refsIn === 0\n        ? {\n            rule: REPO_MAP_UNREFERENCED_RULE,\n            explanation: `${site}; no references to it anywhere in the scanned tree`,\n          }\n        : {\n            rule: REPO_MAP_RANKED_RULE,\n            explanation: `${site}; ${counts}`,\n          };\n  return {\n    path: definition.path,\n    name: definition.name,\n    kind: definition.kind,\n    line: definition.line,\n    rank: definition.rank,\n    refsIn: definition.refsIn,\n    refsInFiles: definition.refsInFiles,\n    refsOut: definition.refsOut,\n    reason,\n  };\n}\n\nfunction plural(word: string, count: number): string {\n  return count === 1 ? word : `${word}s`;\n}\n"]}