@spikedpunch/mast 0.1.0

package/dist/graph/sqliteBatch.d.ts

@@ -0,0 +1,48 @@
+/**
+ * better-sqlite3 12.11.1 / SQLite 3.53.2's default `MAX_VARIABLE_NUMBER` — the
+ * maximum number of `?` bound parameters a single statement may carry. A
+ * multi-row `INSERT ... VALUES (?, ?, ...), (?, ?, ...), ...` binds
+ * `columns * rows` parameters; exceeding this throws `SqliteError: too many
+ * SQL variables` and (inside a transaction) rolls back everything the
+ * transaction had written so far. Already documented at
+ * `store/sqliteChunkStore.ts`'s `getChunksByIds` (bounded by the caller, no
+ * batching needed there); this constant is the shared source of truth for
+ * every site that DOES need batching.
+ */
+export declare const SQLITE_MAX_VARIABLES = 32766;
+/**
+ * Splits `rows` into batches sized so that `batch.length * columnsPerRow`
+ * never exceeds {@link SQLITE_MAX_VARIABLES}, where `columnsPerRow` is the
+ * number of keys on `rows[0]`.
+ *
+ * ASSUMPTION: every row in `rows` has the same key count as `rows[0]`. This
+ * holds for every call site in mast — each builds its rows through one
+ * fixed-shape mapper (`chunkToRow`, the `symbols.map(...)` object literal in
+ * `populate.ts`, etc.), never a mapper that conditionally includes/omits
+ * keys — so row 0 is authoritative and this function does not re-check every
+ * row (that would defeat the point of a cheap batching helper).
+ *
+ * Empty input returns `[]`, not `[[]]` — callers that already guard
+ * `if (rows.length > 0)` before inserting keep that guard; this only removes
+ * the *second* guard (staying under the parameter ceiling).
+ */
+export declare function chunkRowsForSqlite<T extends object>(rows: readonly T[]): readonly (readonly T[])[];
+/**
+ * Splits `values` into batches sized so that `batch.length * paramsPerValue`
+ * never exceeds {@link SQLITE_MAX_VARIABLES}. Sibling to
+ * {@link chunkRowsForSqlite} for call sites binding bare scalars (e.g. an
+ * `IN (?, ?, ...)` name list) rather than object rows — `paramsPerValue`
+ * defaults to 1, the parameter each value contributes to an `IN` list.
+ *
+ * `reservedParams` is the number of bound parameters the SAME statement binds
+ * outside this list — a `MATCH` expression, a `LIMIT`, any other predicate.
+ * It defaults to 0 because most call sites bind nothing else, but a batch
+ * sized to exactly the ceiling overflows the moment the statement binds one
+ * more: measured, `searchFts` (whose statement also binds its MATCH
+ * expression and its LIMIT) threw `too many SQL variables` at a batch of
+ * exactly {@link SQLITE_MAX_VARIABLES} paths until it declared its two.
+ *
+ * Empty input returns `[]`, matching {@link chunkRowsForSqlite}.
+ */
+export declare function chunkValuesForSqlite<T>(values: readonly T[], paramsPerValue?: number, reservedParams?: number): readonly (readonly T[])[];
+//# sourceMappingURL=sqliteBatch.d.ts.map

package/dist/graph/sqliteBatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqliteBatch.d.ts","sourceRoot":"","sources":["../../src/graph/sqliteBatch.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EACjD,IAAI,EAAE,SAAS,CAAC,EAAE,GACjB,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAe3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,cAAc,SAAI,EAClB,cAAc,SAAI,GACjB,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAO3B"}

package/dist/graph/sqliteBatch.js

@@ -0,0 +1,93 @@
+// ---------------------------------------------------------------------------
+// SQLite bound-parameter batching (Stage 4.5 S1, IMPLEMENTATION_PLAN.md
+// "batch `replaceChunksForFile`'s insert", added 2026-08-07).
+//
+// Placed in graph/ (alongside db.ts) rather than store/: `store/sqliteChunkStore.ts`
+// already imports `Db` from `../graph/db.js`, so store -> graph is the existing
+// dependency direction. Putting the shared batching helper here lets both
+// `store/sqliteChunkStore.ts` and `graph/populate.ts` import it without
+// introducing a new edge (graph -> store would be the alternative, and mast has
+// no such edge today). mast is one flat align component (CLAUDE.md), so this is
+// a placement choice, not a conformance requirement — stated here for the record.
+// ---------------------------------------------------------------------------
+/**
+ * better-sqlite3 12.11.1 / SQLite 3.53.2's default `MAX_VARIABLE_NUMBER` — the
+ * maximum number of `?` bound parameters a single statement may carry. A
+ * multi-row `INSERT ... VALUES (?, ?, ...), (?, ?, ...), ...` binds
+ * `columns * rows` parameters; exceeding this throws `SqliteError: too many
+ * SQL variables` and (inside a transaction) rolls back everything the
+ * transaction had written so far. Already documented at
+ * `store/sqliteChunkStore.ts`'s `getChunksByIds` (bounded by the caller, no
+ * batching needed there); this constant is the shared source of truth for
+ * every site that DOES need batching.
+ */
+export const SQLITE_MAX_VARIABLES = 32_766;
+/**
+ * Splits `rows` into batches sized so that `batch.length * columnsPerRow`
+ * never exceeds {@link SQLITE_MAX_VARIABLES}, where `columnsPerRow` is the
+ * number of keys on `rows[0]`.
+ *
+ * ASSUMPTION: every row in `rows` has the same key count as `rows[0]`. This
+ * holds for every call site in mast — each builds its rows through one
+ * fixed-shape mapper (`chunkToRow`, the `symbols.map(...)` object literal in
+ * `populate.ts`, etc.), never a mapper that conditionally includes/omits
+ * keys — so row 0 is authoritative and this function does not re-check every
+ * row (that would defeat the point of a cheap batching helper).
+ *
+ * Empty input returns `[]`, not `[[]]` — callers that already guard
+ * `if (rows.length > 0)` before inserting keep that guard; this only removes
+ * the *second* guard (staying under the parameter ceiling).
+ */
+export function chunkRowsForSqlite(rows) {
+    if (rows.length === 0)
+        return [];
+    const first = rows[0];
+    // Unreachable given the length check above; `noUncheckedIndexedAccess`
+    // still types `rows[0]` as `T | undefined`, so this is a real (if
+    // defensive) branch rather than a `!` assertion (CLAUDE.md §3.1).
+    if (first === undefined)
+        return [];
+    const columnsPerRow = Object.keys(first).length;
+    // A 0-column row shape binds no parameters at all, so the whole array fits
+    // in one batch; guard division-by-zero rather than let it fall out of the
+    // Math.floor below.
+    const rowsPerBatch = columnsPerRow > 0
+        ? Math.max(1, Math.floor(SQLITE_MAX_VARIABLES / columnsPerRow))
+        : rows.length;
+    return chunk(rows, rowsPerBatch);
+}
+/**
+ * Splits `values` into batches sized so that `batch.length * paramsPerValue`
+ * never exceeds {@link SQLITE_MAX_VARIABLES}. Sibling to
+ * {@link chunkRowsForSqlite} for call sites binding bare scalars (e.g. an
+ * `IN (?, ?, ...)` name list) rather than object rows — `paramsPerValue`
+ * defaults to 1, the parameter each value contributes to an `IN` list.
+ *
+ * `reservedParams` is the number of bound parameters the SAME statement binds
+ * outside this list — a `MATCH` expression, a `LIMIT`, any other predicate.
+ * It defaults to 0 because most call sites bind nothing else, but a batch
+ * sized to exactly the ceiling overflows the moment the statement binds one
+ * more: measured, `searchFts` (whose statement also binds its MATCH
+ * expression and its LIMIT) threw `too many SQL variables` at a batch of
+ * exactly {@link SQLITE_MAX_VARIABLES} paths until it declared its two.
+ *
+ * Empty input returns `[]`, matching {@link chunkRowsForSqlite}.
+ */
+export function chunkValuesForSqlite(values, paramsPerValue = 1, reservedParams = 0) {
+    if (values.length === 0)
+        return [];
+    const budget = SQLITE_MAX_VARIABLES - reservedParams;
+    const valuesPerBatch = paramsPerValue > 0
+        ? Math.max(1, Math.floor(budget / paramsPerValue))
+        : values.length;
+    return chunk(values, valuesPerBatch);
+}
+/** Plain array-slicing chunker shared by both batching functions above. */
+function chunk(items, size) {
+    const batches = [];
+    for (let i = 0; i < items.length; i += size) {
+        batches.push(items.slice(i, i + size));
+    }
+    return batches;
+}
+//# sourceMappingURL=sqliteBatch.js.map

package/dist/graph/sqliteBatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqliteBatch.js","sourceRoot":"","sources":["../../src/graph/sqliteBatch.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,wEAAwE;AACxE,8DAA8D;AAC9D,EAAE;AACF,qFAAqF;AACrF,gFAAgF;AAChF,0EAA0E;AAC1E,wEAAwE;AACxE,gFAAgF;AAChF,gFAAgF;AAChF,kFAAkF;AAClF,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAkB;IAElB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACtB,uEAAuE;IACvE,kEAAkE;IAClE,kEAAkE;IAClE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;IAChD,2EAA2E;IAC3E,0EAA0E;IAC1E,oBAAoB;IACpB,MAAM,YAAY,GAAG,aAAa,GAAG,CAAC;QACpC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,oBAAoB,GAAG,aAAa,CAAC,CAAC;QAC/D,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;IAChB,OAAO,KAAK,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAoB,EACpB,cAAc,GAAG,CAAC,EAClB,cAAc,GAAG,CAAC;IAElB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,MAAM,GAAG,oBAAoB,GAAG,cAAc,CAAC;IACrD,MAAM,cAAc,GAAG,cAAc,GAAG,CAAC;QACvC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,cAAc,CAAC,CAAC;QAClD,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;IAClB,OAAO,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACvC,CAAC;AAED,2EAA2E;AAC3E,SAAS,KAAK,CAAI,KAAmB,EAAE,IAAY;IACjD,MAAM,OAAO,GAAU,EAAE,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;QAC5C,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/indexer/freshness.d.ts

@@ -0,0 +1,48 @@
+/**
+ * How far the index has drifted from the working tree — one producer, read by
+ * both `mast status` (CLI) and `mast_status` (MCP).
+ *
+ * The two surfaces used to compute this separately and disagree. The CLI
+ * diffed `file_manifest.json` against a fresh walk; the MCP tool enumerated the
+ * `files` table and stat'd each row. Neither is sufficient alone, which is why
+ * this reads **both** signals and takes the union:
+ *
+ *  - The **manifest** knows which files the last run considered. It is the only
+ *    signal that can see a file which exists on disk and was never indexed —
+ *    such a file is in no `files` row, so a table-driven check is structurally
+ *    blind to it. That blindness was the MCP tool's defect
+ *    (`docs/defects/LEDGER.md` D035): add one file to a project and it reported
+ *    `index_fresh: true`.
+ *  - The **`files.mtime` stamp** knows what was actually written, and records
+ *    the mtime of the content that was parsed (invariant 1 in `runIndex`'s
+ *    WHY-comment — stamped BEFORE the extract, never re-stat'd at write time).
+ *    The manifest, by contrast, is stamped from a re-stat during the finalise
+ *    phase, so an edit landing mid-run leaves the manifest looking current
+ *    while the row correctly reads stale. It is also the only signal that sees
+ *    a file which is in the manifest but absent from the index — the residue
+ *    D034 left on indexes written before that fix, which would otherwise need a
+ *    full reindex to detect.
+ *
+ * A file counts once, under the first heading that applies.
+ */
+import type { Db } from '../graph/db.js';
+import type { ResolvedConfig } from '../store/config.js';
+export interface IndexFreshness {
+    /** On disk and known to the index, but its content has changed since. */
+    readonly stale: number;
+    /** On disk and not indexed — never seen, or lost to a failed run. */
+    readonly unindexed: number;
+    /** Known to the index, no longer on disk. */
+    readonly deleted: number;
+    /** `stale + unindexed + deleted` — what both surfaces report as `stale_files`. */
+    readonly total: number;
+}
+/**
+ * Measure the index against the working tree.
+ *
+ * Costs one project walk plus one `files` scan per call, which is why it is
+ * called from the status surfaces and not from the read tools. The walk stats
+ * every file anyway, so the mtime comparisons below are free.
+ */
+export declare function measureFreshness(config: ResolvedConfig, db: Db): Promise<IndexFreshness>;
+//# sourceMappingURL=freshness.d.ts.map

package/dist/indexer/freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.d.ts","sourceRoot":"","sources":["../../src/indexer/freshness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAiC9F"}

package/dist/indexer/freshness.js

@@ -0,0 +1,72 @@
+/**
+ * How far the index has drifted from the working tree — one producer, read by
+ * both `mast status` (CLI) and `mast_status` (MCP).
+ *
+ * The two surfaces used to compute this separately and disagree. The CLI
+ * diffed `file_manifest.json` against a fresh walk; the MCP tool enumerated the
+ * `files` table and stat'd each row. Neither is sufficient alone, which is why
+ * this reads **both** signals and takes the union:
+ *
+ *  - The **manifest** knows which files the last run considered. It is the only
+ *    signal that can see a file which exists on disk and was never indexed —
+ *    such a file is in no `files` row, so a table-driven check is structurally
+ *    blind to it. That blindness was the MCP tool's defect
+ *    (`docs/defects/LEDGER.md` D035): add one file to a project and it reported
+ *    `index_fresh: true`.
+ *  - The **`files.mtime` stamp** knows what was actually written, and records
+ *    the mtime of the content that was parsed (invariant 1 in `runIndex`'s
+ *    WHY-comment — stamped BEFORE the extract, never re-stat'd at write time).
+ *    The manifest, by contrast, is stamped from a re-stat during the finalise
+ *    phase, so an edit landing mid-run leaves the manifest looking current
+ *    while the row correctly reads stale. It is also the only signal that sees
+ *    a file which is in the manifest but absent from the index — the residue
+ *    D034 left on indexes written before that fix, which would otherwise need a
+ *    full reindex to detect.
+ *
+ * A file counts once, under the first heading that applies.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { walkProject } from './walker.js';
+/**
+ * Measure the index against the working tree.
+ *
+ * Costs one project walk plus one `files` scan per call, which is why it is
+ * called from the status surfaces and not from the read tools. The walk stats
+ * every file anyway, so the mtime comparisons below are free.
+ */
+export async function measureFreshness(config, db) {
+    const manifestPath = join(config.resolved_state_dir, 'file_manifest.json');
+    const manifest = existsSync(manifestPath)
+        ? JSON.parse(readFileSync(manifestPath, 'utf-8'))
+        : {};
+    const currentFiles = await walkProject(config);
+    const onDisk = new Map(currentFiles.map((e) => [e.relativePath, e.mtime]));
+    const rows = await db.selectFrom('files').select(['path', 'mtime']).execute();
+    const indexed = new Map(rows.map((r) => [r.path, r.mtime]));
+    let stale = 0;
+    let unindexed = 0;
+    for (const [path, diskMtime] of onDisk) {
+        const manifestMtime = manifest[path];
+        const storedMtime = indexed.get(path);
+        // Absent from either record means it is not in the index: never walked
+        // before, or walked and then lost when its parse or write failed.
+        if (manifestMtime === undefined || storedMtime === undefined) {
+            unindexed++;
+            continue;
+        }
+        if (diskMtime > manifestMtime || diskMtime > storedMtime)
+            stale++;
+    }
+    // A path recorded by either side but no longer on disk. Deduplicated: the
+    // usual case is that both sides still carry it.
+    const gone = new Set();
+    for (const path of Object.keys(manifest))
+        if (!onDisk.has(path))
+            gone.add(path);
+    for (const path of indexed.keys())
+        if (!onDisk.has(path))
+            gone.add(path);
+    return { stale, unindexed, deleted: gone.size, total: stale + unindexed + gone.size };
+}
+//# sourceMappingURL=freshness.js.map

package/dist/indexer/freshness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.js","sourceRoot":"","sources":["../../src/indexer/freshness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAa1C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAsB,EAAE,EAAM;IACnE,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,oBAAoB,CAAC,CAAC;IAC3E,MAAM,QAAQ,GAA2B,UAAU,CAAC,YAAY,CAAC;QAC/D,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAA4B;QAC7E,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,YAAY,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAE3E,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAC9E,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAE5D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,MAAM,EAAE,CAAC;QACvC,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtC,uEAAuE;QACvE,kEAAkE;QAClE,IAAI,aAAa,KAAK,SAAS,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC7D,SAAS,EAAE,CAAC;YACZ,SAAS;QACX,CAAC;QACD,IAAI,SAAS,GAAG,aAAa,IAAI,SAAS,GAAG,WAAW;YAAE,KAAK,EAAE,CAAC;IACpE,CAAC;IAED,0EAA0E;IAC1E,gDAAgD;IAChD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChF,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,IAAI,EAAE;QAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAEzE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;AACxF,CAAC"}

package/dist/indexer/import-resolver.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A specifier that resolved only because the filesystem ignored its casing.
+ *
+ * The import is broken on a case-sensitive filesystem — a Linux CI box will
+ * fail to compile it — so this is a defect in the indexed repository, not in
+ * MAST. MAST resolves it to the on-disk path anyway (see `safeRealpath`) and
+ * reports it rather than dropping the edge.
+ */
+export interface MiscasedImport {
+    /** Project-relative path of the importing file. */
+    readonly fromFile: string;
+    /** The module specifier exactly as written. */
+    readonly specifier: string;
+    /** The target as it is actually spelled on disk. */
+    readonly onDiskPath: string;
+}
+export interface MiscasedImportReport {
+    /** Total observations. Not capped. */
+    readonly count: number;
+    /** The first `MISCASED_SAMPLE_LIMIT` observations, in first-seen order. */
+    readonly samples: readonly MiscasedImport[];
+}
+/**
+ * Samples are capped because a resolver outlives a single index run in the MCP
+ * server (it is cached per project root for the process lifetime), and a repo
+ * that mis-cases one import usually mis-cases many. The count stays exact; only
+ * the retained detail is bounded.
+ */
+export declare const MISCASED_SAMPLE_LIMIT = 20;
+export interface ResolvedImport {
+    /** Project-relative path (with extension) of the resolved file, or null. */
+    readonly resolvedPath: string | null;
+    /** True for node_modules / built-in modules (no intra-repo target). */
+    readonly isExternal: boolean;
+}
+export interface ImportResolver {
+    resolve(moduleSpecifier: string, fromFileRel: string): ResolvedImport;
+    /**
+     * Mis-cased specifiers observed since the last drain, clearing them.
+     *
+     * Draining rather than reading keeps the accumulator bounded across the many
+     * index runs one cached resolver serves, and makes each run's report describe
+     * that run alone.
+     */
+    drainMiscased(): MiscasedImportReport;
+}
+export declare function getImportResolver(projectRoot: string): ImportResolver;
+/** Test seam: forget cached resolvers (inputs may change between tests). */
+export declare function clearImportResolverCache(): void;
+//# sourceMappingURL=import-resolver.d.ts.map

package/dist/indexer/import-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-resolver.d.ts","sourceRoot":"","sources":["../../src/indexer/import-resolver.ts"],"names":[],"mappings":"AAiCA;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CAAC;IACtE;;;;;;OAMG;IACH,aAAa,IAAI,oBAAoB,CAAC;CACvC;AAMD,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAQrE;AAED,4EAA4E;AAC5E,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}

package/dist/indexer/import-resolver.js

@@ -0,0 +1,318 @@
+import { existsSync, statSync, realpathSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve, relative } from 'node:path';
+import fg from 'fast-glob';
+import { loadConfig, createMatchPath } from 'tsconfig-paths';
+// Module/import path resolution (§13.7).
+//
+// Turns an import specifier into a project-relative path that matches an
+// indexed `files.path` (extension included), or marks it external. Handles:
+//   1. relative imports (`./x`, `../y`) — probed for the real file on disk;
+//   2. tsconfig `paths` aliases (`@api/types`) — via tsconfig-paths;
+//   3. pnpm workspace package names (`@kluster/shared`) — via the workspace map;
+//   4. everything else — external (node_modules / built-ins).
+// `realpathSync.native` collapses pnpm symlinks so resolved paths point at real
+// files, and reports the on-disk casing (see safeRealpath).
+const CANDIDATE_EXTS = ['.ts', '.tsx', '.js', '.jsx'];
+// NodeNext/ESM TypeScript writes the *output* extension in relative specifiers
+// (`import { x } from './x.js'`) while the on-disk source is `./x.ts`. tsc resolves
+// such a specifier against the TypeScript source first, and only falls back to the
+// literal file — e.g. `./mod.js` looks up `mod.ts`, then `mod.tsx`, then `mod.js`.
+// We mirror that source-first precedence here (declaration files are out of scope
+// since MAST indexes implementation files, not `.d.ts`). See the TypeScript Modules
+// Reference, "File extension substitution":
+// https://www.typescriptlang.org/docs/handbook/modules/reference.html
+const JS_TO_TS_EXTS = [
+    ['.js', ['.ts', '.tsx']],
+    ['.jsx', ['.tsx']],
+    ['.mjs', ['.mts']],
+    ['.cjs', ['.cts']],
+];
+/**
+ * Samples are capped because a resolver outlives a single index run in the MCP
+ * server (it is cached per project root for the process lifetime), and a repo
+ * that mis-cases one import usually mis-cases many. The count stays exact; only
+ * the retained detail is bounded.
+ */
+export const MISCASED_SAMPLE_LIMIT = 20;
+// Built once per project root — reading tsconfig and globbing the workspace is
+// not free, and the inputs are stable for the life of an index run / session.
+const cache = new Map();
+export function getImportResolver(projectRoot) {
+    const key = resolve(projectRoot);
+    let resolver = cache.get(key);
+    if (resolver === undefined) {
+        resolver = buildResolver(key);
+        cache.set(key, resolver);
+    }
+    return resolver;
+}
+/** Test seam: forget cached resolvers (inputs may change between tests). */
+export function clearImportResolverCache() {
+    cache.clear();
+}
+function buildResolver(projectRoot) {
+    const matchPath = buildTsconfigMatcher(projectRoot);
+    const workspace = buildWorkspaceMap(projectRoot);
+    // Relativise against the realpath of the root as well, so a symlinked root
+    // (e.g. macOS /tmp → /private/tmp) cancels out and the result matches the
+    // walker's `files.path`. realpathSync also collapses pnpm package symlinks.
+    const realRoot = safeRealpath(projectRoot);
+    let miscasedCount = 0;
+    const miscasedSamples = [];
+    const norm = (p) => p.split('\\').join('/');
+    /**
+     * Project-relative path of `abs` as it is spelled on disk, noting the case
+     * discrepancy when the specifier's own spelling differed by case alone.
+     *
+     * The comparison uses the raw `abs` rather than a second (case-preserving)
+     * realpath call, so detection costs no extra syscall on the resolution path.
+     * The price is that a mis-casing reached THROUGH a symlinked directory
+     * differs by more than case and so goes unreported — it still resolves to the
+     * right file, it just is not named in the report.
+     */
+    const toRel = (abs, ctx) => {
+        const onDisk = norm(relative(realRoot, safeRealpath(abs)));
+        // Relative to `projectRoot`, not `realRoot`: `abs` was built from
+        // `projectRoot`, and on a symlinked root (macOS /tmp -> /private/tmp) the
+        // two roots differ, which would make every path look like a mismatch.
+        const asWritten = norm(relative(projectRoot, abs));
+        if (asWritten !== onDisk && asWritten.toLowerCase() === onDisk.toLowerCase()) {
+            miscasedCount++;
+            if (miscasedSamples.length < MISCASED_SAMPLE_LIMIT) {
+                miscasedSamples.push({
+                    fromFile: ctx.fromFileRel,
+                    specifier: ctx.specifier,
+                    onDiskPath: onDisk,
+                });
+            }
+        }
+        return onDisk;
+    };
+    /** Resolve a base path (possibly without extension) to a real indexed file. */
+    const probe = (base, ctx) => {
+        // NodeNext source-first precedence: when the specifier carries a compiled
+        // JS extension (`./x.js`), prefer the TypeScript source (`x.ts`) that would
+        // emit it, ahead of any literal `x.js` on disk (see JS_TO_TS_EXTS).
+        for (const [jsExt, tsExts] of JS_TO_TS_EXTS) {
+            if (base.endsWith(jsExt)) {
+                const stem = base.slice(0, -jsExt.length);
+                for (const tsExt of tsExts) {
+                    if (isFile(stem + tsExt))
+                        return toRel(stem + tsExt, ctx);
+                }
+                break; // a base ends in at most one of these extensions
+            }
+        }
+        if (isFile(base))
+            return toRel(base, ctx);
+        for (const ext of CANDIDATE_EXTS) {
+            if (isFile(base + ext))
+                return toRel(base + ext, ctx);
+        }
+        for (const ext of CANDIDATE_EXTS) {
+            const idx = join(base, `index${ext}`);
+            if (isFile(idx))
+                return toRel(idx, ctx);
+        }
+        return null;
+    };
+    return {
+        resolve(spec, fromFileRel) {
+            const ctx = { specifier: spec, fromFileRel };
+            // 1. Relative / absolute imports.
+            if (spec.startsWith('.')) {
+                const fromDir = dirname(join(projectRoot, fromFileRel));
+                return { resolvedPath: probe(resolve(fromDir, spec), ctx), isExternal: false };
+            }
+            if (spec.startsWith('/')) {
+                return { resolvedPath: probe(spec, ctx), isExternal: false };
+            }
+            // 2. tsconfig path alias.
+            if (matchPath !== null) {
+                const aliasBase = matchPath(spec, undefined, undefined, [...CANDIDATE_EXTS]);
+                if (aliasBase !== undefined) {
+                    const rel = probe(aliasBase, ctx);
+                    if (rel !== null)
+                        return { resolvedPath: rel, isExternal: false };
+                }
+            }
+            // 3. pnpm workspace package.
+            const ws = resolveWorkspace(spec, workspace, (base) => probe(base, ctx));
+            if (ws !== null)
+                return { resolvedPath: ws, isExternal: false };
+            // 4. External.
+            return { resolvedPath: null, isExternal: true };
+        },
+        drainMiscased() {
+            const report = {
+                count: miscasedCount,
+                samples: [...miscasedSamples],
+            };
+            miscasedCount = 0;
+            miscasedSamples.length = 0;
+            return report;
+        },
+    };
+}
+/** Resolve `@scope/pkg` or `@scope/pkg/sub` against the workspace package map. */
+function resolveWorkspace(spec, workspace, probe) {
+    for (const [name, dir] of workspace) {
+        if (spec === name) {
+            // Bare package import → its entry point.
+            const main = packageMain(dir);
+            const candidates = [
+                main !== null ? join(dir, main) : null,
+                join(dir, 'src', 'index'),
+                join(dir, 'index'),
+            ].filter((c) => c !== null);
+            for (const c of candidates) {
+                const rel = probe(c);
+                if (rel !== null)
+                    return rel;
+            }
+            return null;
+        }
+        if (spec.startsWith(`${name}/`)) {
+            const sub = spec.slice(name.length + 1);
+            return probe(join(dir, sub)) ?? probe(join(dir, 'src', sub));
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// tsconfig paths
+// ---------------------------------------------------------------------------
+function buildTsconfigMatcher(projectRoot) {
+    const config = loadConfig(projectRoot);
+    if (config.resultType !== 'success')
+        return null;
+    if (Object.keys(config.paths).length === 0)
+        return null;
+    return createMatchPath(config.absoluteBaseUrl, config.paths);
+}
+// ---------------------------------------------------------------------------
+// pnpm workspace map (package name → absolute package dir)
+// ---------------------------------------------------------------------------
+function buildWorkspaceMap(projectRoot) {
+    const map = new Map();
+    const workspaceRoot = findWorkspaceRoot(projectRoot);
+    if (workspaceRoot === null)
+        return map;
+    const globs = readWorkspaceGlobs(workspaceRoot);
+    if (globs.length === 0)
+        return map;
+    const dirs = fg.sync(globs, {
+        cwd: workspaceRoot,
+        onlyDirectories: true,
+        absolute: true,
+        followSymbolicLinks: false,
+    });
+    for (const dir of dirs) {
+        const name = packageName(dir);
+        if (name !== null && !map.has(name))
+            map.set(name, dir);
+    }
+    return map;
+}
+/** Walk up from `start` to the nearest dir containing pnpm-workspace.yaml. */
+function findWorkspaceRoot(start) {
+    let dir = resolve(start);
+    for (;;) {
+        if (existsSync(join(dir, 'pnpm-workspace.yaml')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Parse the `packages:` glob list from pnpm-workspace.yaml. The file is a flat
+ * list of quoted/unquoted globs under a single `packages:` key, so a line scan
+ * is sufficient and avoids a YAML dependency.
+ */
+function readWorkspaceGlobs(workspaceRoot) {
+    let text;
+    try {
+        text = readFileSync(join(workspaceRoot, 'pnpm-workspace.yaml'), 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const globs = [];
+    let inPackages = false;
+    for (const raw of text.split('\n')) {
+        if (/^packages:\s*$/.test(raw)) {
+            inPackages = true;
+            continue;
+        }
+        if (!inPackages)
+            continue;
+        const item = raw.match(/^\s*-\s*['"]?([^'"#]+?)['"]?\s*(?:#.*)?$/);
+        if (item?.[1] !== undefined) {
+            globs.push(item[1].trim());
+            continue;
+        }
+        // A non-list, non-blank line at column 0 ends the packages block.
+        if (raw.trim() !== '' && !/^\s/.test(raw))
+            break;
+    }
+    return globs;
+}
+// ---------------------------------------------------------------------------
+// package.json helpers
+// ---------------------------------------------------------------------------
+function packageName(dir) {
+    const pkg = readPackageJson(dir);
+    return typeof pkg?.name === 'string' ? pkg.name : null;
+}
+function packageMain(dir) {
+    const pkg = readPackageJson(dir);
+    return typeof pkg?.main === 'string' ? pkg.main : null;
+}
+function readPackageJson(dir) {
+    const path = join(dir, 'package.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * realpath that falls back to the input when the path does not exist.
+ *
+ * `.native` is load-bearing, not an optimisation. The JS `realpathSync`
+ * resolves symlinks but echoes back whatever casing it was handed, whereas the
+ * platform `realpath(3)` reports the name as it is spelled on disk. That
+ * matters because `statSync` succeeds for a mis-cased path on a
+ * case-insensitive filesystem (APFS, NTFS): `./utils/foo` finds `Utils/Foo.ts`
+ * and nothing in the return value says the match was inexact. Echoing the
+ * specifier's casing then puts a `resolved_path` in the database that disagrees
+ * with the walker's `files.path` — fast-glob reports the on-disk name — and
+ * every path-range join against `files.path` (`resolveInFileOrReExportChain`,
+ * `insertReExportFiles`, `resolveTypeContext`) matches nothing and drops the
+ * edge silently. Canonicalising here fixes all three at the source, and never
+ * has to guess between two candidates the way a case-folded lookup would: on a
+ * case-insensitive filesystem `Foo.ts` and `foo.ts` cannot coexist, and on a
+ * case-sensitive one `statSync` already matched the literal name.
+ */
+function safeRealpath(path) {
+    try {
+        return realpathSync.native(path);
+    }
+    catch {
+        return path;
+    }
+}
+//# sourceMappingURL=import-resolver.js.map