@massa-ai/core 1.17.0 → 1.18.0

package/dist/services/cache/lru-evict.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared insertion-order eviction for the LRU-bounded `Map`s PR-D unifies (RFS-02 AC-2).
+ *
+ * WHY A FUNCTION AND NOT A CACHE CLASS.
+ * The five caches this serves agree on eviction ORDER and disagree on everything else: cap
+ * (512 at four sites, 50 at `file-filter-cache`), TTL (enforced at `file-content-cache`'s
+ * `fileCache` only) and read-promotion (absent at `file-filter-cache`). A shared cache class would impose
+ * one policy on all five, and that IS the behavior change `spec.md` §3.B measured the eviction
+ * itself is not. RFS-02 AC-2 therefore fixes this as an eviction function; every site keeps its
+ * own cap, its own TTL and its own promotion policy.
+ *
+ * WHY THE SECOND PARAMETER IS A POST-CALL BOUND AND NOT "the cap".
+ * `design.md` §5.1 specifies only "a function taking `(cache, cap)`", and that phrasing does
+ * not determine the predicate, because the five sites do not share one:
+ *
+ *   file-content-cache.ts (T10)        pre-insert   while (size >= 512)
+ *   project-root-cache.ts (T9)         pre-insert   while (size >= 512)
+ *   symbol-graph.service.ts            pre-insert   while (size >= 512)
+ *   web-controller.ts                  post-insert  while (size >  512)
+ *   file-filter-cache.ts               post-insert  if   (size >  50) evict-one
+ *
+ * `spec.md` §3.B establishes that pre-insert `>=` and post-insert `>` retain the same number.
+ * They do — but only while each site keeps BOTH its operator and its call position. Collapsing
+ * them onto one operator with every site passing its own literal cap moves the retained count,
+ * and it moves in opposite directions depending on which operator wins. Measured against T1's
+ * characterization oracle (`tasks.md` §10.7): a shared `>` breaks the three pre-insert sites, a
+ * shared `>=` breaks the two post-insert ones.
+ *
+ * Stating the contract as a POST-CALL BOUND is what lets one function serve both call
+ * positions without moving any retained count, because `size > cap - 1` and `size >= cap` are
+ * the same predicate over integers:
+ *
+ *   pre-insert   caller passes `CAP - 1`  — reserves the slot the pending insert will take
+ *   post-insert  caller passes `CAP`      — the insert already happened
+ *
+ * WHAT THIS MODULE DOES NOT CERTIFY, on RFS-01 AC-6's precedent of naming blind spots.
+ * It evicts in `Map` insertion order and knows nothing about TTL, read-promotion, or whether a
+ * caller's insertion order matches that caller's own notion of "oldest". `file-filter-cache`
+ * evicts by `min(createdAt)` today and coincides with insertion order only because it never
+ * re-inserts an entry on a read — an invariant unstated in that file, guarded by T1's
+ * characterization suite (mutation M5b) and by nothing here. A future read-promotion added
+ * there would silently defeat the shared eviction and no structural gate could see it.
+ *
+ * WHY IT IMPORTS NOTHING, AND WHY THAT IS ASSERTED IN A TEST RATHER THAN BY CI.
+ * `spec.md` RFS-02 AC-3 originally placed this in `kernel/`, where `check-core-layering`'s
+ * leaf-ness clause would have enforced import-freedom. C30 (`design.md` §5.2) moved it to
+ * `services/cache/` because `kernel/`'s admission rule is "serves >= 2 tiers" and 11 of 11
+ * shipped members keep it, while this module serves `services/` alone after Phase 3. Nothing
+ * in CI now prevents this file from growing a dependency. That is a real loss of enforcement
+ * (R-29), recorded rather than glossed, and the replacement is the AST assertion in this
+ * module's own unit test.
+ */
+/**
+ * Evict oldest-first from `cache` until `cache.size <= maxRetained`.
+ *
+ * @param cache        any `Map`; eviction order is the Map's own insertion order, so a caller
+ *                     that promotes on read (delete + re-set) gets LRU and one that does not
+ *                     gets FIFO. That choice stays with the caller.
+ * @param maxRetained  the number of entries that may remain when this returns. Pre-insert
+ *                     callers pass `CAP - 1`; post-insert callers pass `CAP`.
+ */
+export declare function evictOldest<K, V>(cache: Map<K, V>, maxRetained: number): void;
+//# sourceMappingURL=lru-evict.d.ts.map

package/dist/services/cache/lru-evict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru-evict.d.ts","sourceRoot":"","sources":["../../../src/services/cache/lru-evict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAY7E"}

package/dist/services/cache/lru-evict.js

@@ -0,0 +1,76 @@
+/**
+ * Shared insertion-order eviction for the LRU-bounded `Map`s PR-D unifies (RFS-02 AC-2).
+ *
+ * WHY A FUNCTION AND NOT A CACHE CLASS.
+ * The five caches this serves agree on eviction ORDER and disagree on everything else: cap
+ * (512 at four sites, 50 at `file-filter-cache`), TTL (enforced at `file-content-cache`'s
+ * `fileCache` only) and read-promotion (absent at `file-filter-cache`). A shared cache class would impose
+ * one policy on all five, and that IS the behavior change `spec.md` §3.B measured the eviction
+ * itself is not. RFS-02 AC-2 therefore fixes this as an eviction function; every site keeps its
+ * own cap, its own TTL and its own promotion policy.
+ *
+ * WHY THE SECOND PARAMETER IS A POST-CALL BOUND AND NOT "the cap".
+ * `design.md` §5.1 specifies only "a function taking `(cache, cap)`", and that phrasing does
+ * not determine the predicate, because the five sites do not share one:
+ *
+ *   file-content-cache.ts (T10)        pre-insert   while (size >= 512)
+ *   project-root-cache.ts (T9)         pre-insert   while (size >= 512)
+ *   symbol-graph.service.ts            pre-insert   while (size >= 512)
+ *   web-controller.ts                  post-insert  while (size >  512)
+ *   file-filter-cache.ts               post-insert  if   (size >  50) evict-one
+ *
+ * `spec.md` §3.B establishes that pre-insert `>=` and post-insert `>` retain the same number.
+ * They do — but only while each site keeps BOTH its operator and its call position. Collapsing
+ * them onto one operator with every site passing its own literal cap moves the retained count,
+ * and it moves in opposite directions depending on which operator wins. Measured against T1's
+ * characterization oracle (`tasks.md` §10.7): a shared `>` breaks the three pre-insert sites, a
+ * shared `>=` breaks the two post-insert ones.
+ *
+ * Stating the contract as a POST-CALL BOUND is what lets one function serve both call
+ * positions without moving any retained count, because `size > cap - 1` and `size >= cap` are
+ * the same predicate over integers:
+ *
+ *   pre-insert   caller passes `CAP - 1`  — reserves the slot the pending insert will take
+ *   post-insert  caller passes `CAP`      — the insert already happened
+ *
+ * WHAT THIS MODULE DOES NOT CERTIFY, on RFS-01 AC-6's precedent of naming blind spots.
+ * It evicts in `Map` insertion order and knows nothing about TTL, read-promotion, or whether a
+ * caller's insertion order matches that caller's own notion of "oldest". `file-filter-cache`
+ * evicts by `min(createdAt)` today and coincides with insertion order only because it never
+ * re-inserts an entry on a read — an invariant unstated in that file, guarded by T1's
+ * characterization suite (mutation M5b) and by nothing here. A future read-promotion added
+ * there would silently defeat the shared eviction and no structural gate could see it.
+ *
+ * WHY IT IMPORTS NOTHING, AND WHY THAT IS ASSERTED IN A TEST RATHER THAN BY CI.
+ * `spec.md` RFS-02 AC-3 originally placed this in `kernel/`, where `check-core-layering`'s
+ * leaf-ness clause would have enforced import-freedom. C30 (`design.md` §5.2) moved it to
+ * `services/cache/` because `kernel/`'s admission rule is "serves >= 2 tiers" and 11 of 11
+ * shipped members keep it, while this module serves `services/` alone after Phase 3. Nothing
+ * in CI now prevents this file from growing a dependency. That is a real loss of enforcement
+ * (R-29), recorded rather than glossed, and the replacement is the AST assertion in this
+ * module's own unit test.
+ */
+/**
+ * Evict oldest-first from `cache` until `cache.size <= maxRetained`.
+ *
+ * @param cache        any `Map`; eviction order is the Map's own insertion order, so a caller
+ *                     that promotes on read (delete + re-set) gets LRU and one that does not
+ *                     gets FIFO. That choice stays with the caller.
+ * @param maxRetained  the number of entries that may remain when this returns. Pre-insert
+ *                     callers pass `CAP - 1`; post-insert callers pass `CAP`.
+ */
+export function evictOldest(cache, maxRetained) {
+    while (cache.size > maxRetained) {
+        const oldest = cache.keys().next().value;
+        // Defensive and unreachable for any `maxRetained >= 0`: the loop condition forces
+        // `cache.size >= 1`, so `keys().next()` always yields an entry. Kept because all four
+        // original sites carry it, and dropping it inside a behavior-preserving PR would be an
+        // unprovable change. It is NOT here for the 90% line-coverage floor — that gate parses
+        // `DA:` records only (`scripts/check-coverage.ts:320`), never `BRDA:`, so this line counts
+        // as covered the moment it is evaluated, whichever way the branch goes.
+        if (oldest === undefined)
+            break;
+        cache.delete(oldest);
+    }
+}
+//# sourceMappingURL=lru-evict.js.map

package/dist/services/cache/lru-evict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru-evict.js","sourceRoot":"","sources":["../../../src/services/cache/lru-evict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAO,KAAgB,EAAE,WAAmB;IACrE,OAAO,KAAK,CAAC,IAAI,GAAG,WAAW,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;QACzC,kFAAkF;QAClF,sFAAsF;QACtF,uFAAuF;QACvF,uFAAuF;QACvF,2FAA2F;QAC3F,wEAAwE;QACxE,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM;QAChC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/services/file-read/file-content-cache.d.ts

@@ -0,0 +1,41 @@
+import type { FileMetadata } from "./file-metadata.js";
+export interface CachedFile {
+    content: string;
+    timestamp: number;
+    metadata?: FileMetadata;
+}
+/**
+ * The 4 → 5 edge. Module 7 (`read-file.service.ts`) binds this with the
+ * `symbolGraph` forwarded to it from `ReadFileTool`'s constructor parameter.
+ * Bound there since T12; `ReadFileTool` itself bound it from T10 until then.
+ */
+export type MetadataExtractor = (content: string, filePath: string, options: {
+    includeSymbols: boolean;
+    includeImports: boolean;
+    projectId?: string;
+    relativePath?: string;
+}) => Promise<FileMetadata>;
+export declare class FileContentCache {
+    private readonly extractMetadata;
+    private fileCache;
+    private readonly CACHE_TTL;
+    /**
+     * Maximum entries retained in the cache. Without a cap, an adversarial caller
+     * cycling distinct cache keys grows the map for the process lifetime. Map
+     * preserves INSERTION order in JS; we promote a key to most-recently-used on
+     * GET via delete+set, and evict the oldest key on SET while over the cap.
+     * Mirrors WebController's WEB_CACHE_MAX_ENTRIES.
+     */
+    private readonly FILE_CACHE_MAX_ENTRIES;
+    constructor(extractMetadata: MetadataExtractor);
+    readFileWithCache(filePath: string, options: {
+        includeSymbols: boolean;
+        includeImports: boolean;
+        projectId?: string;
+        relativePath?: string;
+    }): Promise<{
+        content: string;
+        metadata: FileMetadata;
+    }>;
+}
+//# sourceMappingURL=file-content-cache.d.ts.map

package/dist/services/file-read/file-content-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-content-cache.d.ts","sourceRoot":"","sources":["../../../src/services/file-read/file-content-cache.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IACP,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,KACE,OAAO,CAAC,YAAY,CAAC,CAAC;AAE3B,qBAAa,gBAAgB;IAYf,OAAO,CAAC,QAAQ,CAAC,eAAe;IAX5C,OAAO,CAAC,SAAS,CAAsC;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAO;gBAEjB,eAAe,EAAE,iBAAiB;IAEzD,iBAAiB,CACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;QACP,cAAc,EAAE,OAAO,CAAC;QACxB,cAAc,EAAE,OAAO,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,GACA,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;CAuDxD"}

package/dist/services/file-read/file-content-cache.js

@@ -0,0 +1,109 @@
+/**
+ * @massa-ai/core - File content cache
+ *
+ * Module 4 of the `tools/read_file.ts` extraction (PR-D, T10). Owns the
+ * TTL-and-LRU-bounded file CONTENT cache `ReadFileTool` used to carry as
+ * private state: `readFileWithCache`, the `fileCache` Map, `CACHE_TTL`,
+ * `FILE_CACHE_MAX_ENTRIES` and the `CachedFile` shape.
+ *
+ * `readFileWithCache`'s BODY IS MOVED VERBATIM apart from one line. The private
+ * `ReadFileTool.evictOldest` wrapper it used to call no longer exists — its body
+ * read `this.FILE_CACHE_MAX_ENTRIES`, which this module takes, so the wrapper
+ * could not survive this task even as dead code — and the call is now the shared
+ * operator directly, on module 3's exact shape:
+ * `evictOldest(map, CAP - 1)`. `lru-evict.ts`'s second parameter is a POST-CALL
+ * BOUND rather than the cap, so a pre-insert caller passes `CAP - 1` to reserve
+ * the slot the pending `set()` takes; `size > CAP - 1` and `size >= CAP` are the
+ * same predicate over the integers, so the retained count at this call position
+ * is unchanged (C44).
+ *
+ * IT NEVER NAMES SymbolGraphService. Metadata extraction arrives as a
+ * constructor callback (`tasks.md` §4.1, decided there with its rejected
+ * option), and the parameter is deliberately named `extractMetadata` so the
+ * moved body's two call sites — the legacy-entry repair path and the cache
+ * miss — read exactly as they did before the move. The type-only import of
+ * `FileMetadata` from module 5 is unavoidable and is not what §4.1 forbids:
+ * `SymbolGraphService` is the database-backed collaborator the callback exists
+ * to keep out of this file.
+ *
+ * INSTANTIATED PER ReadFileTool, on module 3's precedent — each tool owned its
+ * own `fileCache` Map before the move, so a module singleton would leak cached
+ * file content between independently-constructed tools. That is a behavior
+ * change, and this extraction is behavior-preserving by contract (RFS-02 AC-1).
+ *
+ * CACHE_TTL IS ENFORCED HERE and that is the half of RFS-02 AC-4 that holds.
+ * `__tests__/read-file-project-root-rename-pin.test.ts` measured it: past 60 s
+ * the content re-reads. Its sibling `ROOT_CACHE_TTL` in
+ * `project-root-cache.ts` is declared and read nowhere, so that cache is
+ * LRU-bounded only. The two constants were never related and are now not even
+ * in the same file.
+ */
+import { logger } from "@massa-ai/shared";
+import fs from "fs/promises";
+import { evictOldest } from "../cache/lru-evict.js";
+export class FileContentCache {
+    extractMetadata;
+    fileCache = new Map();
+    CACHE_TTL = 60000; // 1 minute
+    /**
+     * Maximum entries retained in the cache. Without a cap, an adversarial caller
+     * cycling distinct cache keys grows the map for the process lifetime. Map
+     * preserves INSERTION order in JS; we promote a key to most-recently-used on
+     * GET via delete+set, and evict the oldest key on SET while over the cap.
+     * Mirrors WebController's WEB_CACHE_MAX_ENTRIES.
+     */
+    FILE_CACHE_MAX_ENTRIES = 512;
+    constructor(extractMetadata) {
+        this.extractMetadata = extractMetadata;
+    }
+    async readFileWithCache(filePath, options) {
+        // Cache key MUST include every option that changes metadata extraction.
+        // Keying on filePath alone returned stale, options-baked metadata for a
+        // later read of the same file with different includeSymbols/includeImports/
+        // projectId/relativePath (the only e2e red — 08.search F33). Deliberately
+        // exclude offset/limit/lineStart/lineEnd/compress/targetRatio/format: those
+        // are applied AFTER the cache in handle(), and coalescing them across reads
+        // is the cache's purpose.
+        const cacheKey = JSON.stringify({
+            filePath,
+            includeSymbols: options.includeSymbols ?? false,
+            includeImports: options.includeImports ?? false,
+            projectId: options.projectId ?? null,
+            relativePath: options.relativePath ?? null,
+        });
+        const cached = this.fileCache.get(cacheKey);
+        // Check cache validity
+        if (cached && Date.now() - cached.timestamp < this.CACHE_TTL) {
+            logger.debug("File cache hit", { filePath });
+            // LRU touch: promote this key to most-recently-used so hot files survive
+            // eviction. delete+set reorders the key to the end (newest).
+            this.fileCache.delete(cacheKey);
+            this.fileCache.set(cacheKey, cached);
+            // Legacy/edge entries may have undefined metadata. Re-extract once and
+            // WRITE IT BACK into the cache entry so subsequent hits are served from
+            // cache instead of re-extracting on every request.
+            if (!cached.metadata) {
+                const metadata = await this.extractMetadata(cached.content, filePath, options);
+                this.fileCache.set(cacheKey, { ...cached, metadata });
+                return { content: cached.content, metadata };
+            }
+            return {
+                content: cached.content,
+                metadata: cached.metadata,
+            };
+        }
+        // Read file
+        const content = await fs.readFile(filePath, "utf-8");
+        const metadata = await this.extractMetadata(content, filePath, options);
+        // Update cache (evict oldest if at cap).
+        evictOldest(this.fileCache, this.FILE_CACHE_MAX_ENTRIES - 1);
+        this.fileCache.set(cacheKey, {
+            content,
+            timestamp: Date.now(),
+            metadata,
+        });
+        logger.debug("File read and cached", { filePath });
+        return { content, metadata };
+    }
+}
+//# sourceMappingURL=file-content-cache.js.map

package/dist/services/file-read/file-content-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-content-cache.js","sourceRoot":"","sources":["../../../src/services/file-read/file-content-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,MAAM,aAAa,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAyBpD,MAAM,OAAO,gBAAgB;IAYE;IAXrB,SAAS,GAA4B,IAAI,GAAG,EAAE,CAAC;IACtC,SAAS,GAAG,KAAK,CAAC,CAAC,WAAW;IAC/C;;;;;;OAMG;IACc,sBAAsB,GAAG,GAAG,CAAC;IAE9C,YAA6B,eAAkC;QAAlC,oBAAe,GAAf,eAAe,CAAmB;IAAG,CAAC;IAEnE,KAAK,CAAC,iBAAiB,CACrB,QAAgB,EAChB,OAKC;QAED,wEAAwE;QACxE,wEAAwE;QACxE,4EAA4E;QAC5E,0EAA0E;QAC1E,4EAA4E;QAC5E,4EAA4E;QAC5E,0BAA0B;QAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;YAC9B,QAAQ;YACR,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,KAAK;YAC/C,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,KAAK;YAC/C,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI;YACpC,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,IAAI;SAC3C,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAE5C,uBAAuB;QACvB,IAAI,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YAC7D,MAAM,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC7C,yEAAyE;YACzE,6DAA6D;YAC7D,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAChC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAErC,uEAAuE;YACvE,wEAAwE;YACxE,mDAAmD;YACnD,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACrB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;gBAC/E,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;gBACtD,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC;YAC/C,CAAC;YACD,OAAO;gBACL,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;aAC1B,CAAC;QACJ,CAAC;QAED,YAAY;QACZ,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAExE,yCAAyC;QACzC,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,sBAAsB,GAAG,CAAC,CAAC,CAAC;QAC7D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE;YAC3B,OAAO;YACP,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,QAAQ;SACT,CAAC,CAAC;QAEH,MAAM,CAAC,KAAK,CAAC,sBAAsB,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;QAEnD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAC/B,CAAC;CACF"}

package/dist/services/file-read/file-metadata.d.ts

@@ -0,0 +1,23 @@
+import type { SymbolGraphService } from "../symbol/symbol-graph.service.js";
+export interface FileMetadata {
+    totalLines: number;
+    language?: string;
+    symbols?: {
+        definitions: number;
+        references: number;
+    };
+    imports?: string[];
+}
+export declare class FileMetadataExtractor {
+    private readonly symbolGraph?;
+    constructor(symbolGraph?: SymbolGraphService | undefined);
+    extractMetadata(content: string, filePath: string, options: {
+        includeSymbols: boolean;
+        includeImports: boolean;
+        projectId?: string;
+        relativePath?: string;
+    }): Promise<FileMetadata>;
+    private detectLanguage;
+    private extractImports;
+}
+//# sourceMappingURL=file-metadata.d.ts.map

package/dist/services/file-read/file-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-metadata.d.ts","sourceRoot":"","sources":["../../../src/services/file-read/file-metadata.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE;QACR,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,qBAAa,qBAAqB;IACpB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;gBAAZ,WAAW,CAAC,EAAE,kBAAkB,YAAA;IAEvD,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;QACP,cAAc,EAAE,OAAO,CAAC;QACxB,cAAc,EAAE,OAAO,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,GACA,OAAO,CAAC,YAAY,CAAC;IAuCxB,OAAO,CAAC,cAAc;IAsCtB,OAAO,CAAC,cAAc;CAwBvB"}

package/dist/services/file-read/file-metadata.js

@@ -0,0 +1,127 @@
+/**
+ * @massa-ai/core - File metadata extraction
+ *
+ * Module 5 of the `tools/read_file.ts` extraction (PR-D, T10). Owns the three
+ * private methods `ReadFileTool` used to carry for describing a file's content:
+ * `extractMetadata` (the composer), `detectLanguage` (extension → language) and
+ * `extractImports` (per-language import scan), together with the `FileMetadata`
+ * shape they produce.
+ *
+ * ALL THREE BODIES ARE MOVED VERBATIM, and so is `interface FileMetadata`.
+ *
+ * IT NAMES SymbolGraphService AND MODULE 4 DOES NOT, WHICH IS THE WHOLE POINT
+ * OF THE 4 → 5 EDGE. `design.md` §5.1 records that `readFileWithCache` calls
+ * `extractMetadata` on two of three paths and that `extractMetadata` reaches
+ * `symbolGraph.listDefinitions`, so a direct edge would make the file CONTENT
+ * cache thread a database-backed collaborator through purely to satisfy this
+ * module. `tasks.md` §4.1 decided the mechanism — module 4 takes a
+ * `(content, filePath, options) => Promise<FileMetadata>` callback — and
+ * rejected inverting the call order on measurement rather than on taste: module
+ * 7 pre-computing metadata is eager on all three paths, so every cache HIT
+ * would newly run a `listDefinitions` query. That is a behavior change inside a
+ * behavior-preserving PR, and the callback keeps the laziness and the
+ * legacy-entry write-back exactly where they were.
+ *
+ * INSTANTIATED PER ReadFileTool, on module 3's precedent. `symbolGraph` is the
+ * tool's own optional constructor parameter, forwarded unchanged; a module
+ * singleton would have to pick one graph for every tool ever constructed, and
+ * the parameter is public surface (`design.md` §3.2, 41 construction sites).
+ */
+import { logger } from "@massa-ai/shared";
+import path from "path";
+export class FileMetadataExtractor {
+    symbolGraph;
+    constructor(symbolGraph) {
+        this.symbolGraph = symbolGraph;
+    }
+    async extractMetadata(content, filePath, options) {
+        const lines = content.split("\n");
+        const language = this.detectLanguage(filePath);
+        const metadata = {
+            totalLines: lines.length,
+            language,
+        };
+        // Extract imports if requested
+        if (options.includeImports && language) {
+            metadata.imports = this.extractImports(lines, language);
+        }
+        // Get symbol metadata if symbol graph available
+        if (options.includeSymbols && this.symbolGraph && options.projectId) {
+            try {
+                // Symbol DB stores relative paths — use original relative path for queries
+                const queryPath = options.relativePath || filePath;
+                const { definitions } = await this.symbolGraph.listDefinitions(options.projectId, {
+                    file: queryPath,
+                    limit: 100,
+                });
+                metadata.symbols = {
+                    definitions: definitions.length,
+                    references: 0, // Would need separate query
+                };
+            }
+            catch (error) {
+                logger.debug("Failed to get symbol metadata", { filePath, error });
+            }
+        }
+        return metadata;
+    }
+    detectLanguage(filePath) {
+        const ext = path.extname(filePath).toLowerCase();
+        const languageMap = {
+            ".ts": "TypeScript",
+            ".tsx": "TypeScript",
+            ".js": "JavaScript",
+            ".jsx": "JavaScript",
+            ".vue": "Vue",
+            ".py": "Python",
+            ".go": "Go",
+            ".rs": "Rust",
+            ".java": "Java",
+            ".cpp": "C++",
+            ".c": "C",
+            ".h": "C",
+            ".hpp": "C++",
+            ".cs": "C#",
+            ".rb": "Ruby",
+            ".php": "PHP",
+            ".swift": "Swift",
+            ".kt": "Kotlin",
+            ".kts": "Kotlin",
+            ".scala": "Scala",
+            ".md": "Markdown",
+            ".json": "JSON",
+            ".yaml": "YAML",
+            ".yml": "YAML",
+            ".xml": "XML",
+            ".html": "HTML",
+            ".css": "CSS",
+            ".scss": "SCSS",
+            ".sql": "SQL",
+            ".sh": "Shell",
+            ".bash": "Shell",
+        };
+        return languageMap[ext];
+    }
+    extractImports(lines, language) {
+        const imports = [];
+        const importPatterns = {
+            TypeScript: /^(import\s+.*?from\s+['"]|import\s+['"])/,
+            JavaScript: /^(import\s+.*?from\s+['"]|import\s+['"]|require\s*\(\s*['"])/,
+            Python: /^(import\s+|from\s+\S+\s+import)/,
+            Go: /^import\s+/,
+            Java: /^import\s+/,
+            Rust: /^use\s+/,
+        };
+        const pattern = importPatterns[language];
+        if (!pattern)
+            return imports;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (pattern.test(trimmed)) {
+                imports.push(trimmed);
+            }
+        }
+        return imports;
+    }
+}
+//# sourceMappingURL=file-metadata.js.map

package/dist/services/file-read/file-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-metadata.js","sourceRoot":"","sources":["../../../src/services/file-read/file-metadata.ts"],"names":[],"mappings":"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"}

package/dist/services/file-read/line-range.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @massa-ai/core - Line range selection
+ *
+ * Module 6 of the `tools/read_file.ts` extraction (PR-D, T11). Owns everything
+ * that turns a request into the slice of a file the caller actually receives:
+ * `calculateRange` (request → range), `adjustRange` (range → range clamped to
+ * the file), `extractLines` (range → line-numbered text), the `ReadRange` shape
+ * they pass around, and the N9 output cap — the `MASSA_AI_READ_FILE_MAX_LINES`
+ * ceiling together with the clipping block that used to sit inside `handle()`.
+ *
+ * FREE FUNCTIONS, NOT A CLASS, and that is a decision rather than a default.
+ * Modules 2-5 are classes because each owns per-tool state — a Map, a
+ * subscription, an injected collaborator. This module owns none: every function
+ * here is pure, and the one piece of state is a process-wide constant read from
+ * the environment. `services/cache/lru-evict.ts` (module 1) is a bare function
+ * for exactly this reason (`design.md` §5.2). A class would also have to be
+ * constructed in `ReadFileTool`'s constructor, which is the one surface C64 is
+ * about, and would falsely imply per-instance state.
+ *
+ * IT IMPORTS NOTHING AT ALL, which is `lru-evict.ts`'s property and is asserted
+ * by this module's own unit test rather than by any tier rule.
+ *
+ * `LineRangeRequest` EXISTS BECAUSE `ReadFileParams` IS MODULE 7's. `design.md`
+ * §5.1 assigns `interface ReadFileParams` to `read-file.service.ts`, which T12
+ * built and which COMPOSES this module — so importing it here would be a 6 → 7
+ * edge against the composition direction. It exists now and the rule is
+ * unchanged. `calculateRange` reads exactly four fields off its argument, so
+ * this module declares those four and `ReadFileParams` satisfies it
+ * structurally. The alternative Design's module table hides is that module 6
+ * silently depends on module 7's type; naming the subset is what keeps 6
+ * standalone. Same shape as the 4 → 5 edge §4.1 decided, which Design handed to
+ * Tasks explicitly — this one it handed to nobody.
+ *
+ * THE CLIPPED PATH RETURNS UNNUMBERED TEXT, AND THAT IS PRESERVED DELIBERATELY.
+ * `extractLines` prefixes every line with a padded line number; the cap does NOT
+ * slice that string — it re-slices the RAW `lines` array and joins it, so a
+ * clipped response loses the prefixes an unclipped one carries. Found by the
+ * Plan Challenge gate's red-team lens before this file was written, and
+ * confirmed by the evidence audit: no test anywhere asserts content on the
+ * clipped path, so composing this as "extract, then slice the extracted text"
+ * would have been a silent behavior change inside a behavior-preserving PR.
+ * `__tests__/line-range.test.ts` pins both branches' exact format. Whether the
+ * asymmetry is intentional is not PR-D's question — it is logged, not fixed
+ * (`spec.md` §6, R-07's precedent).
+ */
+/** An inclusive, 1-indexed line range. `end` may be `Infinity` before adjustment. */
+export interface ReadRange {
+    start: number;
+    end: number;
+}
+/**
+ * The four fields `calculateRange` reads. `ReadFileParams` (module 7, T12)
+ * satisfies this structurally; declaring the subset is what stops module 6
+ * depending on the module that composes it.
+ */
+export interface LineRangeRequest {
+    offset?: number;
+    limit?: number;
+    lineStart?: number;
+    lineEnd?: number;
+}
+/** The result of selecting lines, after the N9 cap has been applied. */
+export interface LineSelection {
+    /** The text served to the caller. Line-numbered unless `clipped`. */
+    content: string;
+    /** `content.split("\n").length` — recomputed after any clipping. */
+    lineCount: number;
+    /** True when the N9 cap trimmed the selection. Surfaces as `source_clipped`. */
+    clipped: boolean;
+}
+export declare function calculateRange(params: LineRangeRequest): ReadRange;
+export declare function adjustRange(range: ReadRange, totalLines: number): ReadRange;
+export declare function extractLines(lines: string[], range: ReadRange): string;
+/**
+ * Extract the requested lines and apply the N9 cap, returning the clipped flag
+ * rather than mutating the caller's locals.
+ *
+ * The two steps ship as one function because they were never separable at the
+ * call site: before this task the cap read and reassigned the very
+ * `selectedContent` and `selectedLineCount` that the `extractLines` call one
+ * line above it had produced, inside `handle()`. Deliberately unnumbered — a
+ * line citation into `read_file.ts` written here would name a revision that no
+ * longer exists the moment this commit lands, and T12 moves that whole region
+ * again (T8b's de-numbering precedent). Splitting them would mean passing
+ * the already-extracted string and its line count back in as parameters, which
+ * duplicates the `.split("\n")` at the call site and adds an argument derivable
+ * from another. `extractLines` stays exported so its own contract is pinnable
+ * independently.
+ */
+export declare function selectLines(lines: string[], range: ReadRange): LineSelection;
+//# sourceMappingURL=line-range.d.ts.map

package/dist/services/file-read/line-range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-range.d.ts","sourceRoot":"","sources":["../../../src/services/file-read/line-range.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AA2BH,qFAAqF;AACrF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAsBlE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,CAK3E;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAatE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,GAAG,aAAa,CA0B5E"}