bantamkit-mcp 0.29.2 → 0.31.0

package/dist/pricing.js

@@ -0,0 +1,357 @@
+/**
+ * Layer 4 (Policy/Profile): the price table, and the arithmetic that turns tokens into money.
+ *
+ * A port of `runtime-py/src/bantamkit/pricing.py`, arm for arm. The Python module is the
+ * reference and carries the full reasoning -- why the shipped table has NO rates, why the
+ * three properties are where they are, why money is an integer. Read it first; what follows
+ * here is only what this side does DIFFERENTLY, and every one of those is a mechanical
+ * consequence of the language rather than a decision.
+ *
+ * 1. `BigInt` FOR THE MULTIPLY, `number` ON THE WIRE. `count * rate` with both operands
+ *    allowed up to 2**53-1 reaches 2**106, which a JS `number` rounds silently and Python
+ *    does not. So the product, the half-up rounding and the running total are all `bigint`
+ *    here, and only the final micro-USD -- bounded by the shared 2**53-1 ceiling, refused
+ *    above it on BOTH sides with the same sentence -- becomes a `number`. Python needs none
+ *    of this because its `int` is arbitrary precision; the ceiling exists so that the place
+ *    where the two would part company is a refusal rather than a wrong answer.
+ *
+ * 2. `pyRepr` AND `cmpCodepoint`, NOT `JSON.stringify` AND `.sort()`. Every quoted name in
+ *    a sentence goes through `pyRepr` because Python's `repr` is what the reference emits,
+ *    and every "which offender is named first" goes through `cmpCodepoint` because
+ *    `.sort()` is UTF-16 code-unit order and `sorted()` is code-point order. Both are
+ *    already the port's shared primitives and both are already under conformance.
+ *
+ * 3. `JSON.parse` IS THE STRICTER READER AND PYTHON WAS BROUGHT TO IT. `json.loads` accepts
+ *    the bare tokens `NaN` / `Infinity` / `-Infinity`; `JSON.parse` does not. The reference
+ *    passes `parse_constant` to refuse them, so both sides answer
+ *    `price table is not valid JSON: <path>` for the same bytes.
+ *
+ * 4. AN INTEGRAL FLOAT IS A COUNT. `JSON.parse('3000000.0')` is `3000000` and cannot be told
+ *    from the integer; the reference therefore accepts an integral `float` and narrows it,
+ *    rather than refusing a spelling this side cannot even see.
+ *
+ * `tools/conformance/suites/pricing.mjs` is the gate.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { assetsRoot } from './assets.js';
+import { BantamError } from './errors.js';
+import { cmpCodepoint, pyRepr } from './pysem.js';
+export const PRICES_ENV = 'BANTAMKIT_PRICES';
+export const PRICE_SCHEMA_VERSION = 1;
+export const CURRENCY = 'USD';
+export const RATE_UNIT = 'micro_usd_per_million_tokens';
+/** A rate is micro-USD per this many tokens. */
+export const TOKENS_PER_RATE_UNIT = 1000000;
+/** Micro-USD in one USD. Also the rounding divisor, hence `HALF` below. */
+export const MICROS_PER_UNIT = 1000000;
+const MICROS_PER_UNIT_BIG = 1000000n;
+const HALF_BIG = 500000n;
+/** The largest integer both runtimes represent exactly. */
+export const MAX_SAFE_INT = 2 ** 53 - 1;
+const MAX_SAFE_INT_BIG = BigInt(Number.MAX_SAFE_INTEGER);
+/**
+ * The four classes the host's own `usage` block distinguishes, in the order the ledger
+ * accumulates them. This tuple is the unit of pricing; see property 1 in the reference.
+ */
+export const TOKEN_CLASSES = [
+    'input_tokens',
+    'cache_creation_input_tokens',
+    'cache_read_input_tokens',
+    'output_tokens',
+];
+const CLASSES = TOKEN_CLASSES.join(', ');
+const TABLE_KEYS = ['schema_version', 'currency', 'unit', 'note', 'rates'];
+const RATE_META = ['recorded', 'source'];
+/**
+ * The table on disk is malformed.
+ *
+ * This THROWS rather than returning `{unavailable}`, and the split is deliberate: a broken
+ * price table is an operator configuration fault that must stop and name itself, while an
+ * unpriced model is a normal, expected answer that a caller keeps working past.
+ */
+export class PriceTableError extends BantamError {
+}
+/**
+ * A non-negative integer both runtimes hold exactly, however JSON spelled it.
+ *
+ * `Number.isInteger` is false for `Infinity` and `NaN`, which is what makes `1e400` -- valid
+ * JSON here, `inf` after `json.loads` there -- refuse identically on both sides.
+ */
+function isCount(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= MAX_SAFE_INT;
+}
+/** The number behind an accepted count. Only ever called after `isCount`. `-0` normalises to `0`. */
+function asCount(value) {
+    return value + 0;
+}
+/**
+ * Sorted by code point, so "which key is named first" is not a function of object order.
+ *
+ * `JSON.parse` hoists integer-like keys ahead of the rest and orders them numerically;
+ * `json.loads` preserves the file. Naming the code-point-least offender makes the two answer
+ * the same sentence for the same file.
+ */
+function sortedByCodePoint(names) {
+    return [...names].sort(cmpCodepoint);
+}
+/**
+ * `YYYY-MM-DD`, shape and range only -- deliberately not a calendar.
+ *
+ * A real calendar check would be `datetime.date` on the reference side, which this side has
+ * no equivalent of without writing a third leap-year rule. 2026-02-31 passes and that is a
+ * known, stated limit.
+ */
+function isDate(value) {
+    if (typeof value !== 'string' || value.length !== 10)
+        return false;
+    if (value[4] !== '-' || value[7] !== '-')
+        return false;
+    for (const part of [value.slice(0, 4), value.slice(5, 7), value.slice(8, 10)]) {
+        for (const ch of part) {
+            if (ch < '0' || ch > '9')
+                return false;
+        }
+    }
+    const month = Number(value.slice(5, 7));
+    const day = Number(value.slice(8, 10));
+    return month >= 1 && month <= 12 && day >= 1 && day <= 31;
+}
+/**
+ * `$BANTAMKIT_PRICES` verbatim if set, else the shipped table in the asset pack.
+ *
+ * The override wins even when it is wrong -- same arm order and same reasoning as
+ * `assetsRoot()`: an override that points nowhere must fail naming itself rather than fall
+ * through to a table the operator did not ask for.
+ */
+export function priceTablePath() {
+    const env = process.env[PRICES_ENV];
+    if (env)
+        return env;
+    return join(assetsRoot(), 'pricing', 'default.json');
+}
+/**
+ * Read and validate a price table. `path` is used VERBATIM in every message it appears in,
+ * never normalised, because `Path('./x')` is `x` on the reference side and `./x` here and the
+ * fault sentence would then differ over a path neither runtime chose.
+ */
+export function loadPriceTable(path) {
+    const label = path === undefined ? priceTablePath() : path;
+    if (!existsSync(label)) {
+        throw new PriceTableError(`price table not found: ${label}`);
+    }
+    let raw;
+    try {
+        // The decoder's own text is NOT quoted. `validate.mjs` covers the two decoders'
+        // sentences separately and they are not identical everywhere; quoting one here would
+        // make every malformed table a divergence, over bytes that name the same fault.
+        raw = decodePriceJson(readFileSync(label, 'utf8'));
+    }
+    catch {
+        throw new PriceTableError(`price table is not valid JSON: ${label}`);
+    }
+    return validatePriceTable(raw);
+}
+/**
+ * The decode both runtimes must agree on, in one place so the gate can reach it.
+ *
+ * This side is already the strict one -- `JSON.parse` rejects the bare `NaN` / `Infinity` /
+ * `-Infinity` tokens that `json.loads` accepts -- so the function is a plain `JSON.parse`
+ * and the reference is what had to move. It exists as a named arm anyway, because a rule
+ * that lives in only one of two runtimes is a rule the conformance harness cannot reach.
+ */
+export function decodePriceJson(text) {
+    return JSON.parse(text);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Every rule the table must satisfy, each with its own sentence.
+ *
+ * Returns a NORMALISED table: the top-level keys in a fixed order, rate names in code-point
+ * order, and every count narrowed. See the reference for the ONE thing normalisation cannot
+ * buy -- the iteration order of `rates` for a model name JavaScript reads as an array index.
+ */
+export function validatePriceTable(raw) {
+    if (!isPlainObject(raw)) {
+        throw new PriceTableError('price table must be a JSON object');
+    }
+    const unknown = sortedByCodePoint(Object.keys(raw).filter((k) => !TABLE_KEYS.includes(k)));
+    if (unknown.length > 0) {
+        throw new PriceTableError(`price table has unknown key ${pyRepr(unknown[0])}`);
+    }
+    // No parsed VALUE is ever interpolated into a sentence below -- only key names and
+    // integers this module computed. A parsed value would drag the two runtimes' number
+    // formatting into the message, which is a serialiser divergence wearing an error
+    // message's clothes.
+    const version = raw['schema_version'];
+    if (!isCount(version) || version !== PRICE_SCHEMA_VERSION) {
+        throw new PriceTableError('price table schema_version must be the integer 1');
+    }
+    if (raw['currency'] !== CURRENCY) {
+        throw new PriceTableError("price table currency must be the string 'USD'");
+    }
+    if (raw['unit'] !== RATE_UNIT) {
+        throw new PriceTableError("price table unit must be the string 'micro_usd_per_million_tokens'");
+    }
+    if ('note' in raw && typeof raw['note'] !== 'string') {
+        throw new PriceTableError('price table note must be a string');
+    }
+    const rates = raw['rates'];
+    if (!isPlainObject(rates)) {
+        throw new PriceTableError('price table rates must be a JSON object');
+    }
+    const built = {};
+    for (const model of sortedByCodePoint(Object.keys(rates))) {
+        built[model] = validateRate(model, rates[model]);
+    }
+    // Assigned in the reference's own key order -- `note`, when present, sits between `unit`
+    // and `rates` -- because insertion order is what `JSON.stringify` emits and the suite
+    // compares the serialised table.
+    const out = {};
+    out.schema_version = PRICE_SCHEMA_VERSION;
+    out.currency = CURRENCY;
+    out.unit = RATE_UNIT;
+    if ('note' in raw)
+        out.note = raw['note'];
+    out.rates = built;
+    return out;
+}
+function validateRate(model, rate) {
+    if (!isPlainObject(rate)) {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} must be a JSON object`);
+    }
+    const known = [...RATE_META, ...TOKEN_CLASSES];
+    const unknown = sortedByCodePoint(Object.keys(rate).filter((k) => !known.includes(k)));
+    if (unknown.length > 0) {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} has unknown key ${pyRepr(unknown[0])}`);
+    }
+    // Property 2, enforced where it cannot be skipped: at load, before any arithmetic.
+    if (!('recorded' in rate)) {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} is missing 'recorded' -- a rate with no date is not a fact`);
+    }
+    if (!isDate(rate['recorded'])) {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} has a 'recorded' that is not a YYYY-MM-DD date`);
+    }
+    if (!('source' in rate)) {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} is missing 'source' -- a rate with no source cannot be re-derived`);
+    }
+    if (typeof rate['source'] !== 'string' || rate['source'] === '') {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} has a 'source' that is not a non-empty string`);
+    }
+    for (const cls of TOKEN_CLASSES) {
+        if (cls in rate && !isCount(rate[cls])) {
+            throw new PriceTableError(`price table rate ${pyRepr(model)} prices ${pyRepr(cls)} with something that is not a ` +
+                `non-negative integer below 2**53`);
+        }
+    }
+    if (!TOKEN_CLASSES.some((cls) => cls in rate)) {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} prices no token class at all`);
+    }
+    const narrowed = { ...rate };
+    for (const cls of TOKEN_CLASSES) {
+        if (cls in rate)
+            narrowed[cls] = asCount(rate[cls]);
+    }
+    return rateView(narrowed);
+}
+/** `build_identity`'s shape, on purpose: one key, and the key IS the refusal. */
+function unavailable(reason) {
+    return { unavailable: reason };
+}
+/**
+ * Micro-USD as a fixed-6-decimal string, built from integers only.
+ *
+ * Non-negative input only; every producer in this module is a sum of non-negative products.
+ */
+export function formatMicros(micros) {
+    const n = BigInt(micros);
+    return `${n / MICROS_PER_UNIT_BIG}.${String(n % MICROS_PER_UNIT_BIG).padStart(6, '0')}`;
+}
+/**
+ * The cost of one `usage` block under one model's rate, or a named refusal.
+ *
+ * `table` must be a table `validatePriceTable` returned.
+ *
+ * THE ORDER OF THE CHECKS IS PART OF THE CONTRACT. The usage is validated BEFORE the model is
+ * looked up, so a caller who passed a malformed usage is told that, rather than being sent to
+ * edit a price table over a bug in the call.
+ *
+ * THE USAGE MUST CARRY ALL FOUR CLASSES AND NOTHING ELSE. See the reference: a token class
+ * silently ignored is money silently dropped, and a class silently defaulted to zero is money
+ * silently invented.
+ */
+export function priceTokens(table, model, usage) {
+    if (typeof model !== 'string') {
+        return unavailable('model must be a string');
+    }
+    if (!isPlainObject(usage)) {
+        return unavailable('usage must be a mapping of token class to count');
+    }
+    const extra = sortedByCodePoint(Object.keys(usage).filter((k) => !TOKEN_CLASSES.includes(k)));
+    if (extra.length > 0) {
+        return unavailable(`usage has unknown token class ${pyRepr(extra[0])} -- the price table prices exactly ${CLASSES}`);
+    }
+    for (const cls of TOKEN_CLASSES) {
+        if (!(cls in usage)) {
+            return unavailable(`usage is missing token class ${pyRepr(cls)} -- all four of ${CLASSES} must be ` +
+                `given, because a missing count is not a zero`);
+        }
+        if (!isCount(usage[cls])) {
+            return unavailable(`usage token class ${pyRepr(cls)} is not a non-negative integer below 2**53`);
+        }
+    }
+    const rate = table.rates?.[model];
+    if (rate === undefined) {
+        return unavailable(`no rate recorded for model ${pyRepr(model)} -- add one with its date and source, or ` +
+            `point ${PRICES_ENV} at a table that has it`);
+    }
+    const breakdown = {};
+    let total = 0n;
+    for (const cls of TOKEN_CLASSES) {
+        const count = asCount(usage[cls]);
+        let micros;
+        if (!(cls in rate)) {
+            // Zero tokens cost zero under ANY rate, so this arm invents nothing. Any other count
+            // with no rate is property 3 and is refused rather than silently dropped.
+            if (count !== 0) {
+                return unavailable(`rate for model ${pyRepr(model)} does not price ${pyRepr(cls)}, and ${count} such ` +
+                    `tokens were used -- a missing rate is not a zero`);
+            }
+            micros = 0n;
+        }
+        else {
+            micros = (BigInt(count) * BigInt(rate[cls]) + HALF_BIG) / MICROS_PER_UNIT_BIG;
+        }
+        breakdown[cls] = Number(micros);
+        total += micros;
+    }
+    if (total > MAX_SAFE_INT_BIG) {
+        return unavailable(`cost for model ${pyRepr(model)} exceeds 2**53-1 micro-USD, which is the largest ` +
+            `integer both runtimes represent exactly`);
+    }
+    const micros = Number(total);
+    return {
+        model,
+        currency: CURRENCY,
+        micros,
+        amount: formatMicros(micros),
+        breakdown,
+        rate: rateView(rate),
+    };
+}
+/**
+ * The rate that produced a cost, echoed in a fixed key order so the answer is re-derivable.
+ *
+ * Fixed order rather than the file's own order, because the file's order is not stable across
+ * the two JSON parsers and this object is compared byte for byte by the conformance suite.
+ */
+function rateView(rate) {
+    const view = { recorded: rate['recorded'], source: rate['source'] };
+    for (const cls of TOKEN_CLASSES) {
+        if (cls in rate)
+            view[cls] = rate[cls];
+    }
+    return view;
+}

package/dist/repomap.d.ts

@@ -0,0 +1,247 @@
+export declare const DAMPING = 0.2;
+export declare const ITERATIONS = 30;
+export declare const MIN_REFERENCE_LENGTH = 3;
+export declare const REFERENCE_DF_MAX_NUM = 1;
+export declare const REFERENCE_DF_MAX_DEN = 8;
+export declare const MAX_DEFINITIONS_PER_FILE = 4;
+export declare const DEFAULT_BUDGET = 4000;
+export declare const SCORE_SCALE = 1000000000;
+export declare const MAX_FILE_BYTES = 1048576;
+export declare const SKIP_DIRS: readonly string[];
+/**
+ * Suffix -> dialect. Two dialects only: `python` and `ecma`. TypeScript and JavaScript
+ * share a scanner because their DECLARATION forms are the same set; the extra TypeScript
+ * keywords (`interface`, `type`, `enum`) are simply absent from a `.js` file.
+ */
+export declare const LANGUAGES: Readonly<Record<string, string>>;
+export declare const OMIT_UNKNOWN_LANGUAGE = "unknown-language";
+export declare const OMIT_UNREADABLE = "unreadable-bytes";
+export declare const OMIT_SIZE_CAP = "size-cap";
+export declare const OMIT_NO_DEFINITIONS = "no-definitions";
+export declare const OMIT_UNREACHABLE = "unreachable";
+export declare const OMIT_PER_FILE_CAP = "per-file-cap";
+export declare const OMIT_BUDGET = "budget";
+/**
+ * Fixed render order for the footer, so two runs of the same map cannot disagree about the
+ * order of their disclosures.
+ */
+export declare const OMISSION_ORDER: readonly string[];
+/**
+ * One definition, at the line it was declared on. `line` is 1-based and counts lines of the
+ * ORIGINAL file, not of the comment-stripped view: a caller that jumps to it must land
+ * where the reader would.
+ */
+export interface Definition {
+    readonly path: string;
+    readonly line: number;
+    readonly kind: string;
+    readonly name: string;
+}
+/**
+ * Something the tree holds that the map does not carry, as a COUNT and the fact behind it —
+ * `docread`'s `Omission` discipline, deliberately re-stated here rather than imported,
+ * because these subjects are this module's and a shared vocabulary would make a change to
+ * one reader a change to the other.
+ *
+ * Never an adjective. `subject` is one of the `OMIT_*` tokens; a renderer that meets a token
+ * it does not know must still print the count. A silent skip is how a reader lies about its
+ * coverage.
+ */
+export interface Omission {
+    readonly subject: string;
+    readonly count: number;
+    readonly size: number;
+    readonly facts: readonly (readonly [string, number])[];
+}
+export interface RankedFile {
+    readonly path: string;
+    readonly rankUnits: number;
+    readonly definitions: readonly Definition[];
+    /**
+     * The raw double. Reported for a caller that wants it; NEVER rendered, and never the sort
+     * key — see trap (8).
+     */
+    readonly score: number;
+}
+export interface RepoMap {
+    readonly text: string;
+    readonly ranked: readonly RankedFile[];
+    readonly omissions: readonly Omission[];
+    readonly focus: readonly string[];
+    readonly nodes: number;
+    readonly edges: number;
+    readonly definitions: number;
+    readonly damping: number;
+    readonly iterations: number;
+    readonly budget: number;
+    readonly perFile: number;
+    readonly listingBytes: number;
+    readonly filesRendered: number;
+    readonly definitionsRendered: number;
+}
+export interface RepoMapOptions {
+    readonly focus?: readonly string[];
+    readonly budget?: number;
+    readonly files?: readonly string[] | null;
+    readonly damping?: number;
+    readonly iterations?: number;
+    readonly perFile?: number;
+}
+/**
+ * The dialect for a path, or `null` when this scanner has no reader for it.
+ *
+ * Dispatch is on SUFFIX, and that is a deliberate departure from `docread`, which sniffs
+ * because a suffix is measurably a lie about a document's container. A source file is
+ * different: `.py` and `.ts` name a GRAMMAR, and there is no magic number for a grammar. A
+ * file whose suffix is unknown is reported, never guessed at.
+ */
+export declare function languageOf(path: string): string | null;
+/**
+ * The file's lines with comments and docstrings blanked, one output line per input line so
+ * line numbers survive.
+ *
+ * Line-oriented and stateful across lines, because both traps that matter span lines: a
+ * Python triple-quoted docstring and an ECMAScript block comment. What is removed:
+ *
+ * - `python` — `'''`/`"""` blocks (the delimiter that opens is the only one that can close),
+ *   and everything from an unquoted `#` to end of line.
+ * - `ecma` — block comments, and everything from `//` to end of line.
+ *
+ * What is NOT removed, and is declared rather than hidden: the contents of a SINGLE-line
+ * string literal. Stripping those would lose the real references inside an f-string, and
+ * keeping them costs a definition-shaped line inside a one-line string being read as a
+ * definition. Backslash escapes are NOT honoured: a `"""` inside a string toggles the state
+ * machine. Both runtimes get that wrong identically, which is the requirement.
+ */
+export declare function stripNoncode(text: string, language: string): string[];
+/**
+ * Every definition in `text`, in source order.
+ *
+ * `python` — `def` and `class` at ANY indentation, so a method counts. Methods are the
+ * signal that made the difference in measurement: a focus on `memory/dream.py` reaches
+ * `memory/store.py` through `_write_fact`, `_fact_path` and `_check_index_budget`, none of
+ * which is top-level. Plus a bare `NAME =` or `NAME: T =` at column 0, which is how this
+ * repository declares its constants.
+ *
+ * `ecma` — `function class interface type const let var enum` at COLUMN 0 only, optionally
+ * behind `export` and `default` and `async`. Restricting to column 0 was the second-largest
+ * measured improvement in this module (recall@10 0.361 -> 0.410 on its own): an indented
+ * `const` is a local, and `runtime-ts/src/docread.ts` was contributing 452 of them.
+ *
+ * The asymmetry is real and is not an oversight: an ECMAScript class member cannot be told
+ * from a call at the same indentation without tracking braces, and a scanner that guessed
+ * would invent definitions. Python's `def` keyword makes the same question free.
+ */
+export declare function scanDefinitions(text: string, language: string, path?: string): Definition[];
+/**
+ * Every identifier of at least `MIN_REFERENCE_LENGTH` characters outside a comment.
+ *
+ * A SET, not a count. The edge weight below is "how many DISTINCT names of B does A
+ * mention", so a file that repeats one name a hundred times does not out-weigh a file that
+ * mentions ten. That is the choice the ambiguity filter and `MIN_REFERENCE_LENGTH` were
+ * tuned against and it keeps every weight an exact integer.
+ */
+export declare function referenceNames(text: string, language: string): Set<string>;
+/**
+ * Every path under `root`, relative, POSIX, code-point sorted.
+ *
+ * DIRECTORY SYMLINKS ARE NOT FOLLOWED, AND ON THIS SIDE THAT IS REAL LOGIC RATHER THAN A
+ * FLAG. `os.walk(followlinks=False)` gives CPython the whole rule for free, and J45-9's
+ * mutation 24 — delete the explicit `islink` filter — SURVIVED there for exactly that
+ * reason. Node has no equivalent, and the Dirent that looks like the answer is the wrong
+ * one: `readdirSync(..., {withFileTypes: true})` reports from **lstat**, so a symlink to a
+ * directory answers `isDirectory() === false` and a naive port hands it to the scanner as a
+ * source FILE. CPython does the opposite — `os.scandir`'s `entry.is_dir()` FOLLOWS, so the
+ * link lands in `dirs`, and `followlinks=False` then declines to descend, so it appears in
+ * the output neither as a file nor as a directory.
+ *
+ * Measured on node v25.2.1 and CPython 3.12.13 over one tree holding `real/`,
+ * `linkdir -> real`, `linkfile.py -> plain.py` and a dangling `dangling.py`: CPython's walk
+ * yields `dirs=['linkdir', 'real'] files=['dangling.py', 'linkfile.py', 'plain.py']` and
+ * `walk_sources` returns `['dangling.py', 'linkfile.py', 'plain.py', 'real/a.py']`. So the
+ * three cases are separated by a FOLLOW-`stat`, not by the Dirent:
+ *
+ * - symlink whose target is a directory  -> a directory, and not descended into: gone.
+ * - symlink whose target is a file       -> a file: kept.
+ * - dangling symlink                     -> `stat` throws, CPython's `is_dir()` raises and
+ *                                           is caught as False: a file, kept, and it will
+ *                                           be counted as `unreadable-bytes` downstream.
+ *
+ * Two reasons the rule exists and both are measured elsewhere in this repository: a symlink
+ * cycle makes the walk non-terminating, and a dangling directory symlink is one error shape
+ * on POSIX and two on Windows (`reference-windows-dangling-symlink-two-shapes`).
+ *
+ * A directory whose listing throws is skipped whole, silently, because that is what
+ * `os.walk`'s default `onerror=None` does.
+ */
+export declare function walkSources(root: string): string[];
+/**
+ * `source -> {target: weight}`, weight being the number of surviving names the source
+ * mentions that ONLY the target defines.
+ *
+ * Weights are exact integers, so `out[i]` in `pagerank` is an exact integer too and the only
+ * inexact step in the whole pass is the one division.
+ */
+export declare function buildGraph(definitions: Map<string, readonly Definition[]>, references: Map<string, ReadonlySet<string>>): Map<string, Map<string, number>>;
+/**
+ * At most `limit` of a file's definitions, chosen by kind then reach, returned in SOURCE
+ * order.
+ *
+ * The key is `(kind rank, -reference count, line, name)`, and every part of it is an integer
+ * or a code-point comparison, so the choice is TOTAL — which is why this port does not lean
+ * on `Array.prototype.sort` being stable. `references` is the RAW count from `nameIndex`;
+ * see there for why it is not the filtered one.
+ *
+ * **This ordering is argued, not measured, and the difference matters.** Every other
+ * constant in this module beat a named alternative on a yardstick. This one cannot: the
+ * yardstick is "does the focus file's own import appear in the rendered map", which is a
+ * question about which FILES are listed, and selection only decides which lines appear UNDER
+ * a file already listed. Measured, it moves that number by zero. So it rests on a stated
+ * principle instead — name the file's subject before its details — and a later unit with a
+ * definition-level yardstick is entitled to overturn it. What it is NOT is source order,
+ * which put `VALID_TYPES`, `DURABLE_TYPES`, `NAME_RE` and `DUPLICATE_JACCARD` at the head of
+ * `memory/store.py`'s block.
+ *
+ * The selected definitions are re-sorted into SOURCE order for rendering: a block whose line
+ * numbers ran backwards would be harder to read for no gain, and the order a block is chosen
+ * in is not the order it is read in.
+ */
+export declare function selectDefinitions(definitions: readonly Definition[], references: Map<string, number>, limit: number): readonly Definition[];
+/**
+ * Personalised PageRank, bit-identical to `repomap.py` by construction.
+ *
+ * The port contract, in the order the loop performs it:
+ *
+ * 1. `nodes` is already sorted; index by position in it.
+ * 2. `out[i]` is the exact integer sum of node i's out-weights.
+ * 3. Each node's out-edges are visited in sorted TARGET order.
+ * 4. The personalisation vector is `1/len(personal)` on each focus node and 0 elsewhere;
+ *    with no focus it is `1/n` on every node. The INITIAL vector is that same vector.
+ * 5. Per round: zero `next`; walk sources in node order; a node with no out-edges adds its
+ *    whole score to `dangling`; otherwise each out-edge adds `score[i] * weight / out[i]`,
+ *    evaluated strictly left to right.
+ * 6. `tele = damping * dangling + (1.0 - damping)`, then
+ *    `next[i] = next[i] * damping + tele * personal[i]`.
+ * 7. Exactly `iterations` rounds. No early stop, no convergence test — a branch on a float
+ *    is one more thing for a port to get wrong, and the contraction bound (the linear part
+ *    is `damping * column-stochastic`, so the residual after 30 rounds is under
+ *    `2 * 0.2 ** 30` = 2.1e-21) makes the test unnecessary.
+ *
+ * THERE IS NO `reduce` HERE AND THERE MUST NOT BE ONE: every accumulation is a written-out
+ * loop in the same order as CPython's, because CPython's `sum()` is Neumaier-compensated and
+ * nothing in JavaScript is (trap 7). The Python side is held to the same rule by
+ * `test_no_float_summation_or_rounding_in_the_source`, which reads that function's body.
+ */
+export declare function pagerank(nodes: readonly string[], edges: Map<string, Map<string, number>>, personal: readonly string[], damping?: number, iterations?: number): number[];
+/**
+ * Scan `root`, rank its files against `focus`, and render a listing within `budget`.
+ *
+ * `focus` is the current unit's files, relative to `root` and POSIX-separated; a focus entry
+ * that is not a scanned source is ignored for the personalisation vector but is still
+ * excluded from the listing, because a caller naming a file has it open already. An empty
+ * focus gives the uniform vector — plain centrality over the whole tree.
+ *
+ * `budget` is UTF-8 BYTES of the listing. See the header: this runtime has no model
+ * tokenizer and will not pretend to one.
+ */
+export declare function repoMap(root: string, options?: RepoMapOptions): RepoMap;