dsh-plugin-codegraph-tree-sitter 0.1.6 → 0.2.0

package/lib/cache.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Parse-result cache: the extraction this package computed for each file on the previous run, so a
+ * repeat index of an unchanged workspace can skip the read, the parse, and the tree walk for every
+ * file whose content did not change.
+ *
+ * The cache is an accelerator with no authority. It is read only as a hint — anything missing,
+ * unreadable, corrupt, written by another version, or shaped unexpectedly is discarded and the file
+ * is parsed again, so losing it costs time and never correctness. That is what lets
+ * {@link readParseCache} swallow every failure and {@link writeParseCache} tolerate a workspace this
+ * process may not write to.
+ * @module dsh-plugin-codegraph-tree-sitter/cache
+ */
+import type { FileExtraction } from './extract.ts';
+import type { ExtractedFile } from './resolve.ts';
+/**
+ * Version of the extraction semantics this cache records. Bump it by hand whenever `extract.ts` (or
+ * a grammar that feeds it) starts producing a different result for the same source text: a stale
+ * entry would otherwise be reused as if it were current, and the graph would silently keep the old
+ * shape.
+ */
+export declare const EXTRACTION_CACHE_VERSION = 1;
+/** Path of the parse cache, relative to a project root. */
+export declare const EXTRACTION_CACHE_RELATIVE_PATH = ".codegraph/cache/extractions.json";
+/** One file's cached extraction, together with the identity it was computed from. */
+export interface CachedFile {
+    /** Epoch milliseconds of the file's modification time when its extraction was produced. */
+    readonly modifiedAt: number;
+    /** File size in bytes at that same moment. */
+    readonly size: number;
+    /** SHA-256 of the content the extraction was produced from, hex-encoded. */
+    readonly contentHash: string;
+    /** Line count of that content, recorded so a reused file still gets a correct span. */
+    readonly lineCount: number;
+    /** Seam language label the extraction was produced for. */
+    readonly language: string;
+    /** The extraction itself. */
+    readonly extraction: FileExtraction;
+}
+/**
+ * Load the previous run's extractions for `projectRoot`.
+ *
+ * Never throws: a cache that cannot be read, parsed, or trusted yields an empty map, which makes the
+ * caller parse everything. A single malformed entry discards the whole file — an entry is either a
+ * complete record this package wrote or evidence the document was damaged, and reasoning about
+ * partial reuse is not worth the risk of a graph built from a half-written entry.
+ * @param projectRoot - absolute path of the workspace whose cache to load.
+ * @returns the cached extractions keyed by project-relative path, empty when none can be trusted.
+ */
+export declare function readParseCache(projectRoot: string): Promise<Map<string, CachedFile>>;
+/**
+ * Record this run's extractions as the next run's cache.
+ *
+ * Written through a sibling temporary name and `rename`d into place, the same way `./schema.ts`
+ * replaces its status sidecar, so a reader never sees half a document. The temporary name is fixed
+ * rather than unique: a write interrupted before its rename is overwritten by the next attempt
+ * instead of accumulating, and a torn leftover is rejected by {@link readParseCache} at the cost of
+ * one run's reuse.
+ *
+ * A failure is swallowed on purpose. A read-only workspace, a full disk, or a locked directory must
+ * still be indexable; the cache is the optimization, never the product.
+ * @param projectRoot - absolute path of the workspace to record the cache for.
+ * @param files - every file this run produced an extraction for.
+ */
+export declare function writeParseCache(projectRoot: string, files: readonly ExtractedFile[]): Promise<void>;
+//# sourceMappingURL=cache.d.ts.map

package/lib/cache.js

@@ -0,0 +1,142 @@
+/**
+ * Parse-result cache: the extraction this package computed for each file on the previous run, so a
+ * repeat index of an unchanged workspace can skip the read, the parse, and the tree walk for every
+ * file whose content did not change.
+ *
+ * The cache is an accelerator with no authority. It is read only as a hint — anything missing,
+ * unreadable, corrupt, written by another version, or shaped unexpectedly is discarded and the file
+ * is parsed again, so losing it costs time and never correctness. That is what lets
+ * {@link readParseCache} swallow every failure and {@link writeParseCache} tolerate a workspace this
+ * process may not write to.
+ * @module dsh-plugin-codegraph-tree-sitter/cache
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/**
+ * Version of the extraction semantics this cache records. Bump it by hand whenever `extract.ts` (or
+ * a grammar that feeds it) starts producing a different result for the same source text: a stale
+ * entry would otherwise be reused as if it were current, and the graph would silently keep the old
+ * shape.
+ */
+export const EXTRACTION_CACHE_VERSION = 1;
+/** Path of the parse cache, relative to a project root. */
+export const EXTRACTION_CACHE_RELATIVE_PATH = '.codegraph/cache/extractions.json';
+/**
+ * Whether `value` is a plain JSON object. Arrays are deliberately included: every caller still
+ * validates the fields it needs, and an array simply carries none of them.
+ * @param value - the parsed JSON value to test.
+ * @returns whether it is a non-null object.
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Whether `value` is a usable extraction. Deliberately shallow past the four arrays: those are what
+ * `resolveWorkspace` indexes into, and the only expected producer is this package's own writer.
+ * @param value - the value to test.
+ * @returns whether it has the four collections an extraction consists of.
+ */
+function isFileExtraction(value) {
+    return isRecord(value)
+        && Array.isArray(value.definitions)
+        && Array.isArray(value.calls)
+        && Array.isArray(value.imports)
+        && Array.isArray(value.heritage);
+}
+/**
+ * Whether `value` is a complete cache entry.
+ * @param value - the value to test.
+ * @returns whether every field is present and of the type a reader will use it as.
+ */
+function isCachedFile(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.modifiedAt === 'number'
+        && typeof value.size === 'number'
+        && typeof value.contentHash === 'string'
+        && typeof value.lineCount === 'number'
+        && typeof value.language === 'string'
+        && isFileExtraction(value.extraction);
+}
+/**
+ * Load the previous run's extractions for `projectRoot`.
+ *
+ * Never throws: a cache that cannot be read, parsed, or trusted yields an empty map, which makes the
+ * caller parse everything. A single malformed entry discards the whole file — an entry is either a
+ * complete record this package wrote or evidence the document was damaged, and reasoning about
+ * partial reuse is not worth the risk of a graph built from a half-written entry.
+ * @param projectRoot - absolute path of the workspace whose cache to load.
+ * @returns the cached extractions keyed by project-relative path, empty when none can be trusted.
+ */
+export async function readParseCache(projectRoot) {
+    const cachePath = join(projectRoot, EXTRACTION_CACHE_RELATIVE_PATH);
+    let raw;
+    try {
+        raw = await readFile(cachePath, 'utf8');
+    }
+    catch {
+        // The ordinary first run has no cache file yet; an unreadable one is the same answer to the
+        // caller — nothing to reuse — and must not fail an index that can still parse the workspace.
+        return new Map();
+    }
+    let document;
+    try {
+        document = JSON.parse(raw);
+    }
+    catch {
+        return new Map();
+    }
+    if (!isRecord(document))
+        return new Map();
+    if (document.cacheVersion !== EXTRACTION_CACHE_VERSION)
+        return new Map();
+    const entries = document.files;
+    if (!isRecord(entries))
+        return new Map();
+    const cache = new Map();
+    for (const [path, entry] of Object.entries(entries)) {
+        if (!isCachedFile(entry))
+            return new Map();
+        cache.set(path, entry);
+    }
+    return cache;
+}
+/**
+ * Record this run's extractions as the next run's cache.
+ *
+ * Written through a sibling temporary name and `rename`d into place, the same way `./schema.ts`
+ * replaces its status sidecar, so a reader never sees half a document. The temporary name is fixed
+ * rather than unique: a write interrupted before its rename is overwritten by the next attempt
+ * instead of accumulating, and a torn leftover is rejected by {@link readParseCache} at the cost of
+ * one run's reuse.
+ *
+ * A failure is swallowed on purpose. A read-only workspace, a full disk, or a locked directory must
+ * still be indexable; the cache is the optimization, never the product.
+ * @param projectRoot - absolute path of the workspace to record the cache for.
+ * @param files - every file this run produced an extraction for.
+ */
+export async function writeParseCache(projectRoot, files) {
+    const cachePath = join(projectRoot, EXTRACTION_CACHE_RELATIVE_PATH);
+    const tempPath = `${cachePath}.tmp`;
+    try {
+        const entries = {};
+        for (const file of files) {
+            entries[file.path] = {
+                modifiedAt: file.modifiedAt,
+                size: file.size,
+                contentHash: file.contentHash,
+                lineCount: file.lineCount,
+                language: file.language,
+                extraction: file.extraction,
+            };
+        }
+        const document = { cacheVersion: EXTRACTION_CACHE_VERSION, files: entries };
+        await mkdir(dirname(cachePath), { recursive: true });
+        await writeFile(tempPath, JSON.stringify(document));
+        await rename(tempPath, cachePath);
+    }
+    catch {
+        // See above: an unusable cache location only means the next run parses everything again.
+    }
+}
+//# sourceMappingURL=cache.js.map

package/lib/index.d.ts

@@ -10,6 +10,11 @@
  * runs implicitly from a query — it is a caller-initiated, potentially multi-minute operation, kept
  * out of the seam's read-only query path on purpose.
  *
+ * Watching a root runs through `ctx.fs` (see `./watcher.ts`): the package observes each in-scope
+ * directory through the host's filesystem seam rather than opening paths itself, so a workspace a
+ * backend serves from another execution world is watched where it actually lives, and a backend that
+ * cannot watch at all degrades to explicit indexing instead of failing the plugin.
+ *
  * Namespace plugin (named exports, no default export). Grammars load lazily, one per language, on
  * first sight of a matching file, and stay cached for the process — never eagerly for every grammar
  * this package ships with.
@@ -25,11 +30,15 @@ export { loadGitignore, matchesGitignore, parseGitignore } from './gitignore.ts'
 export type { GitignoreRule } from './gitignore.ts';
 export { resolveWorkspace } from './resolve.ts';
 export type { ExtractedFile, GraphEdge, GraphNode, ResolvedGraph, UnresolvedRef } from './resolve.ts';
+export { isMinifiedName, looksMinified, measureText, MINIFIED_AVERAGE_LINE_LENGTH } from './minified.ts';
+export type { TextShape } from './minified.ts';
 export { SCHEMA_VERSION, writeGraph } from './schema.ts';
+export { EXTRACTION_CACHE_RELATIVE_PATH, EXTRACTION_CACHE_VERSION, readParseCache, writeParseCache } from './cache.ts';
+export type { CachedFile } from './cache.ts';
 export { isExcluded, walkAndExtract } from './walk.ts';
 export type { WalkConfig, WalkResult } from './walk.ts';
-export { createWatcher, nodeWatch } from './watcher.ts';
-export type { DegradeReason, WatchConfig, WatchHandle, WatchPrimitive, Watcher } from './watcher.ts';
+export { createWatcher } from './watcher.ts';
+export type { DegradeReason, WatchConfig, WatchDirEntry, WatchFileSystem, WatchTarget, Watcher, } from './watcher.ts';
 export { decideWatch, readProcVersion } from './watch-policy.ts';
 export type { WatchDecision, WatchPolicyInput } from './watch-policy.ts';
 export { detectWorktree, execGit } from './worktree.ts';
@@ -58,7 +67,7 @@ export declare const DEFAULT_MAX_FILES = 50000;
 export declare const DEFAULT_CONCURRENCY = 4;
 /** Default quiet period after the last change before a watch-triggered refresh runs. */
 export declare const DEFAULT_WATCH_DEBOUNCE_MS = 2000;
-/** Default cap on directories watched individually, on platforms without a recursive `fs.watch`. */
+/** Default cap on directories watched individually, one watch each, by the fs seam. */
 export declare const DEFAULT_MAX_WATCHED_DIRECTORIES = 4000;
 /** Plugin configuration: the indexer's identity and every deployment-varying bound on a run. */
 export interface Config {
@@ -80,12 +89,40 @@ export interface Config {
      * see `./gitignore.ts`. A project with no root `.gitignore` is unaffected either way.
      */
     respectGitignore?: boolean;
+    /**
+     * Leave generated (bundled or minified) artifacts out of the index instead of parsing them
+     * (default true). A workspace that commits its build output — `dist/` in version control so a
+     * server can serve it — hands the walk megabytes of bundler output declaring thousands of short
+     * mangled names; indexing it both dominates the run's time and collides with real source symbols,
+     * making "one unique workspace-wide name wins" refuse calls the duplicates made ambiguous.
+     *
+     * Two signals, one structural: a `.min.` path segment, or an average line length past
+     * {@link MINIFIED_AVERAGE_LINE_LENGTH}. Set false to index such files anyway, or name their
+     * directory in `exclude`.
+     */
+    skipMinified?: boolean;
     /** Files larger than this are skipped and counted in the report, never parsed (default 2000000). */
     maxFileBytes?: number;
     /** The walk stops discovering new files once this many have been found (default 50000). */
     maxFiles?: number;
     /** Files parsed concurrently (default 4). */
     concurrency?: number;
+    /**
+     * Reuse the extraction a previous run cached for every file whose content is unchanged (default
+     * true), so a repeat index — or a watch rebuild after one edit — parses only what actually changed
+     * instead of the whole workspace. The cache lives at
+     * {@link EXTRACTION_CACHE_RELATIVE_PATH} and is rewritten after each successful run. Set false to
+     * parse every file every time, at the cost of the full parse each run.
+     */
+    reuseParsedCache?: boolean;
+    /**
+     * How a cached file's unchanged content is confirmed before its extraction is reused (default
+     * `'stat'`): `stat` compares the modification time and size the cache recorded and reads nothing;
+     * `hash` re-reads the file and compares a SHA-256, which also catches a rewrite that preserved both
+     * mtime and size (a checkout restoring an older file over a newer one). Hash mode still skips the
+     * parse and the tree walk, which dominate the per-file cost.
+     */
+    cacheVerify?: 'stat' | 'hash';
     /**
      * Watch the workspace for file changes and refresh the index automatically after a successful
      * `index()` call establishes a baseline (default true). Set `watch: false` to keep indexing purely
@@ -100,16 +137,17 @@ export interface Config {
     /** Quiet period after the last change before a watch-triggered refresh runs, in ms (default 2000). */
     watchDebounceMs?: number;
     /**
-     * Hard cap on directories watched individually (default 4000). Only relevant on platforms without a
-     * recursive `fs.watch` (Linux); exceeding it degrades that root's watcher rather than covering only
-     * part of the tree.
+     * Hard cap on directories watched individually (default 4000). Watching goes through the host's
+     * filesystem seam, whose `watch` covers one directory's direct entries, so a workspace costs one
+     * watch per in-scope directory; exceeding this cap degrades that root's watcher rather than
+     * covering only part of the tree.
      */
     maxWatchedDirectories?: number;
 }
 export declare const Config: z<Config>;
 /**
  * Register the tree-sitter indexer.
- * @param ctx - the plugin context (must inject `codegraph`).
+ * @param ctx - the plugin context (must inject `codegraph` and `fs`).
  * @param config - the resolved plugin configuration.
  */
 export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -10,6 +10,11 @@
  * runs implicitly from a query — it is a caller-initiated, potentially multi-minute operation, kept
  * out of the seam's read-only query path on purpose.
  *
+ * Watching a root runs through `ctx.fs` (see `./watcher.ts`): the package observes each in-scope
+ * directory through the host's filesystem seam rather than opening paths itself, so a workspace a
+ * backend serves from another execution world is watched where it actually lives, and a backend that
+ * cannot watch at all degrades to explicit indexing instead of failing the plugin.
+ *
  * Namespace plugin (named exports, no default export). Grammars load lazily, one per language, on
  * first sight of a matching file, and stay cached for the process — never eagerly for every grammar
  * this package ships with.
@@ -21,6 +26,7 @@ import z from '@deepseek-ai/schemastery';
 import { CodegraphIndexerId } from 'dsh-plugin-codegraph-service';
 import { LANGUAGE_TABLE } from "./languages.js";
 import { walkAndExtract } from "./walk.js";
+import { writeParseCache } from "./cache.js";
 import { resolveWorkspace } from "./resolve.js";
 import { writeGraph } from "./schema.js";
 import { createWatcher } from "./watcher.js";
@@ -29,16 +35,18 @@ export { LANGUAGE_TABLE, languageFor } from "./languages.js";
 export { extractFile } from "./extract.js";
 export { loadGitignore, matchesGitignore, parseGitignore } from "./gitignore.js";
 export { resolveWorkspace } from "./resolve.js";
+export { isMinifiedName, looksMinified, measureText, MINIFIED_AVERAGE_LINE_LENGTH } from "./minified.js";
 export { SCHEMA_VERSION, writeGraph } from "./schema.js";
+export { EXTRACTION_CACHE_RELATIVE_PATH, EXTRACTION_CACHE_VERSION, readParseCache, writeParseCache } from "./cache.js";
 export { isExcluded, walkAndExtract } from "./walk.js";
-export { createWatcher, nodeWatch } from "./watcher.js";
+export { createWatcher } from "./watcher.js";
 export { decideWatch, readProcVersion } from "./watch-policy.js";
 export { detectWorktree, execGit } from "./worktree.js";
 export { HOOK_MARKER_BEGIN, HOOK_MARKER_END, installGitHooks, uninstallGitHooks } from "./git-hooks.js";
 /** Cordis plugin name for loader diagnostics. */
 export const name = 'codegraph-tree-sitter';
 /** Services required by this plugin. */
-export const inject = ['codegraph'];
+export const inject = ['codegraph', 'fs'];
 /** Path of the on-disk graph this package writes, relative to a project root. */
 export const DATABASE_RELATIVE_PATH = '.codegraph/codegraph.db';
 /** Default branded identity this indexer reserves on the seam. */
@@ -57,23 +65,26 @@ export const DEFAULT_MAX_FILES = 50_000;
 export const DEFAULT_CONCURRENCY = 4;
 /** Default quiet period after the last change before a watch-triggered refresh runs. */
 export const DEFAULT_WATCH_DEBOUNCE_MS = 2_000;
-/** Default cap on directories watched individually, on platforms without a recursive `fs.watch`. */
+/** Default cap on directories watched individually, one watch each, by the fs seam. */
 export const DEFAULT_MAX_WATCHED_DIRECTORIES = 4_000;
 export const Config = z.object({
     indexerId: z.string().default(DEFAULT_INDEXER_ID),
     languages: z.array(z.string()).default([...new Set(LANGUAGE_TABLE.map(spec => spec.language))]),
     exclude: z.array(z.string()).default(DEFAULT_EXCLUDE),
     respectGitignore: z.boolean().default(true),
+    skipMinified: z.boolean().default(true),
     maxFileBytes: z.number().default(DEFAULT_MAX_FILE_BYTES),
     maxFiles: z.number().default(DEFAULT_MAX_FILES),
     concurrency: z.number().default(DEFAULT_CONCURRENCY),
+    reuseParsedCache: z.boolean().default(true),
+    cacheVerify: z.union([z.const('stat'), z.const('hash')]).default('stat'),
     watch: z.boolean().default(true),
     watchDebounceMs: z.number().default(DEFAULT_WATCH_DEBOUNCE_MS),
     maxWatchedDirectories: z.number().default(DEFAULT_MAX_WATCHED_DIRECTORIES),
 });
 /**
  * Register the tree-sitter indexer.
- * @param ctx - the plugin context (must inject `codegraph`).
+ * @param ctx - the plugin context (must inject `codegraph` and `fs`).
  * @param config - the resolved plugin configuration.
  */
 export function apply(ctx, config) {
@@ -83,6 +94,13 @@ export function apply(ctx, config) {
     assertPositiveInteger('concurrency', resolved.concurrency);
     assertPositiveInteger('watchDebounceMs', resolved.watchDebounceMs);
     assertPositiveInteger('maxWatchedDirectories', resolved.maxWatchedDirectories);
+    // Watching goes through the host's filesystem seam rather than `node:fs`, so it follows the same
+    // execution world the rest of the harness reads: a remote or confined backend watches its own paths.
+    // The `fs` service is a declared dependency (see `inject`), so it is present whenever `apply` runs.
+    // It is read structurally instead of importing `@deepseek-ai/dsh-fs`: that package is not a
+    // dependency here, and its `watch` method only exists from host 0.2 onward, while this package
+    // supports older peers that have no such member to import.
+    const fileSystem = ctx.fs;
     // Keyed by project root, private to this plugin instance: never registered on `ctx`, so there is no
     // cross-plugin relation here for an invariant to describe — just process-local bookkeeping this
     // effect's cleanup below tears down on unload.
@@ -113,7 +131,7 @@ export function apply(ctx, config) {
                 console.error(`codegraph-tree-sitter: file watching for "${projectRoot}" stopped permanently (${reason.code}); ` +
                     'the index will no longer refresh on its own — run codegraph_index manually to update it.');
             },
-        });
+        }, fileSystem);
         watchers.set(projectRoot, watcher);
         watcher.start();
     }
@@ -167,20 +185,29 @@ async function runSync(projectRoot, config) {
  * @returns the run's report.
  */
 async function runIndex(projectRoot, config, signal) {
-    const { files, filesSkipped } = await walkAndExtract(projectRoot, {
+    const { files, filesSkipped, filesMinified, filesReused } = await walkAndExtract(projectRoot, {
         exclude: config.exclude,
         respectGitignore: config.respectGitignore,
+        skipMinified: config.skipMinified,
         maxFileBytes: config.maxFileBytes,
         maxFiles: config.maxFiles,
         concurrency: config.concurrency,
         languages: config.languages,
+        reuseParsedCache: config.reuseParsedCache,
+        cacheVerify: config.cacheVerify,
     }, signal);
     signal?.throwIfAborted();
     const indexedAt = Date.now();
     const graph = resolveWorkspace(files, indexedAt);
     signal?.throwIfAborted();
     const databasePath = join(projectRoot, DATABASE_RELATIVE_PATH);
-    await writeGraph(databasePath, { files, nodes: graph.nodes, edges: graph.edges, unresolved: graph.unresolved, indexedAt });
+    await writeGraph(databasePath, {
+        files, nodes: graph.nodes, edges: graph.edges, unresolved: graph.unresolved, filesMinified, indexedAt,
+    });
+    // Only after the graph is in place: the cache records the extractions this run actually committed,
+    // so a run that failed before writing its graph leaves the previous cache — and the mtimes it was
+    // built from — alone instead of vouching for a graph that was never written.
+    await writeParseCache(projectRoot, files);
     const languageCounts = new Map();
     for (const file of files)
         languageCounts.set(file.language, (languageCounts.get(file.language) ?? 0) + 1);
@@ -191,6 +218,8 @@ async function runIndex(projectRoot, config, signal) {
         projectRoot,
         filesIndexed: files.length,
         filesSkipped,
+        filesMinified,
+        filesReused,
         nodeCount: graph.nodes.length,
         edgeCount: graph.edges.length,
         unresolvedCount: graph.unresolved.length,

package/lib/minified.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Detection of generated (bundled or minified) code, so an index can leave it out.
+ *
+ * A workspace's build output is not always gitignored: a deployment that ships committed artifacts
+ * (`dist/` committed so a server can serve it as-is) hands the walk megabytes of bundler output that
+ * is neither source nor hidden from version control. Indexing it is not merely wasted time — those
+ * files declare thousands of short, mangled names (`e`, `t`, `n`) that collide with real source
+ * symbols, and "one unique workspace-wide name wins" then refuses to resolve every call that the
+ * duplicate makes ambiguous.
+ *
+ * Two signals, both structural rather than name-based on a build tool:
+ *  - a `.min.` path segment (`bundle.min.js`) — the conventional marker, checked before any read;
+ *  - an average source line longer than {@link MINIFIED_AVERAGE_LINE_LENGTH} characters, which
+ *    hand-written code does not reach. Measured on real workspaces: the longest average found in
+ *    hand-written source is ~70 characters, while bundled output runs from thousands to tens of
+ *    thousands.
+ * @module dsh-plugin-codegraph-tree-sitter/minified
+ */
+/**
+ * Average line length at or above which a file is treated as generated output. Chosen with roughly
+ * 7× headroom over the widest real source line measured (~70 characters), and far below the narrowest
+ * generated sample seen (~5 000).
+ */
+export declare const MINIFIED_AVERAGE_LINE_LENGTH = 500;
+/** A file's size expressed in lines, without allocating one array element per line. */
+export interface TextShape {
+    /** Number of newline-separated lines, matching `text.split('\n').length`. */
+    readonly lineCount: number;
+    /** Mean characters per line, counting the trailing partial line. */
+    readonly averageLineLength: number;
+}
+/**
+ * Measure a file's line structure in one pass over its text.
+ * @param text - the file's decoded contents.
+ * @returns its line count and mean line length. An empty file is one empty line, matching
+ *   `''.split('\n').length`.
+ */
+export declare function measureText(text: string): TextShape;
+/**
+ * Whether a path carries the conventional `.min.` marker, which needs no content read to decide.
+ * @param path - project-relative path of the file.
+ * @returns whether its own name marks it as minified.
+ */
+export declare function isMinifiedName(path: string): boolean;
+/**
+ * Whether a file is generated output the index should leave out.
+ * @param path - project-relative path of the file.
+ * @param shape - the file's measured line structure.
+ * @returns whether its name or its line shape marks it as generated.
+ */
+export declare function looksMinified(path: string, shape: TextShape): boolean;
+//# sourceMappingURL=minified.d.ts.map

package/lib/minified.js

@@ -0,0 +1,58 @@
+/**
+ * Detection of generated (bundled or minified) code, so an index can leave it out.
+ *
+ * A workspace's build output is not always gitignored: a deployment that ships committed artifacts
+ * (`dist/` committed so a server can serve it as-is) hands the walk megabytes of bundler output that
+ * is neither source nor hidden from version control. Indexing it is not merely wasted time — those
+ * files declare thousands of short, mangled names (`e`, `t`, `n`) that collide with real source
+ * symbols, and "one unique workspace-wide name wins" then refuses to resolve every call that the
+ * duplicate makes ambiguous.
+ *
+ * Two signals, both structural rather than name-based on a build tool:
+ *  - a `.min.` path segment (`bundle.min.js`) — the conventional marker, checked before any read;
+ *  - an average source line longer than {@link MINIFIED_AVERAGE_LINE_LENGTH} characters, which
+ *    hand-written code does not reach. Measured on real workspaces: the longest average found in
+ *    hand-written source is ~70 characters, while bundled output runs from thousands to tens of
+ *    thousands.
+ * @module dsh-plugin-codegraph-tree-sitter/minified
+ */
+import { posix } from 'node:path';
+/**
+ * Average line length at or above which a file is treated as generated output. Chosen with roughly
+ * 7× headroom over the widest real source line measured (~70 characters), and far below the narrowest
+ * generated sample seen (~5 000).
+ */
+export const MINIFIED_AVERAGE_LINE_LENGTH = 500;
+/**
+ * Measure a file's line structure in one pass over its text.
+ * @param text - the file's decoded contents.
+ * @returns its line count and mean line length. An empty file is one empty line, matching
+ *   `''.split('\n').length`.
+ */
+export function measureText(text) {
+    let newlines = 0;
+    for (let index = 0; index < text.length; index++) {
+        if (text.charCodeAt(index) === 10)
+            newlines++;
+    }
+    const lineCount = newlines + 1;
+    return { lineCount, averageLineLength: text.length / lineCount };
+}
+/**
+ * Whether a path carries the conventional `.min.` marker, which needs no content read to decide.
+ * @param path - project-relative path of the file.
+ * @returns whether its own name marks it as minified.
+ */
+export function isMinifiedName(path) {
+    return posix.basename(path).includes('.min.');
+}
+/**
+ * Whether a file is generated output the index should leave out.
+ * @param path - project-relative path of the file.
+ * @param shape - the file's measured line structure.
+ * @returns whether its name or its line shape marks it as generated.
+ */
+export function looksMinified(path, shape) {
+    return isMinifiedName(path) || shape.averageLineLength >= MINIFIED_AVERAGE_LINE_LENGTH;
+}
+//# sourceMappingURL=minified.js.map

package/lib/resolve.d.ts

@@ -3,13 +3,20 @@
  *
  * Pass 1 collects every definition into a name index. Pass 2 resolves each call site's callee name,
  * in order: (1) the enclosing file imports that name from a relative specifier resolving to a file
- * this run indexed — that file's matching declaration wins; (2) otherwise exactly one definition
- * workspace-wide carries the name — it wins; (3) otherwise the call is recorded in `unresolved` and no
- * `calls` edge is written. An ambiguous edge is worse than a missing one: the model acts on `callers`
- * output, so a confidently wrong caller sends it to edit the wrong file, while a missing caller merely
- * sends it back to text search.
+ * this run indexed — that file's matching declaration wins; (2) otherwise exactly one definition **in
+ * the calling file itself** carries the name — lexical scope settles it before the workspace gets a
+ * say, which is what keeps a helper declared in two test files (or a `render` in two components) from
+ * being counted as ambiguous; (3) otherwise exactly one definition workspace-wide carries the name —
+ * it wins; (4) otherwise the call is recorded in `unresolved` and no `calls` edge is written. An
+ * ambiguous edge is worse than a missing one: the model acts on `callers` output, so a confidently
+ * wrong caller sends it to edit the wrong file, while a missing caller merely sends it back to text
+ * search.
  *
- * Rule 3's `unresolved` entries are not one uniform signal. Each carries {@link UnresolvedRef.likelyExternal},
+ * Rule 2 is restricted to bare calls. A member call (`x.map()`) names a property of a receiver whose
+ * type this resolver does not track, so a same-named local declaration winning it would be a guess
+ * rather than a scope resolution — exactly the kind of confidently wrong edge rule 4 exists to avoid.
+ *
+ * Rule 4's `unresolved` entries are not one uniform signal. Each carries {@link UnresolvedRef.likelyExternal},
  * which is true for a member call (no type information behind its receiver) or a name the file itself
  * imports (a known external origin the specifier just didn't resolve) — both real code that was never a
  * candidate for a workspace edge, as against a bare, undeclared name, which is the actual gap this