devsmind-mcp 2.3.0 → 3.0.0

package/dist/utils/ast.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Extensions the TypeScript parser can read, and therefore the only ones where a symbol's exact
+ * span is knowable — live code extraction, AST edge resolution, and in-place editing are all
+ * limited to these. Every other indexed language falls back to regex reference matching.
+ *
+ * `.mjs`/`.cjs` are plain JavaScript and parse fine (TS understands both script kinds); they are
+ * listed for the same reason `.js` is. Template-based formats (`.vue`, `.svelte`) are NOT here —
+ * their files aren't valid JS, so the parser would choke on the markup.
+ */
+export declare const AST_PARSEABLE_EXTENSIONS: Set<string>;
+/** True when `filePath` can be parsed for exact symbol spans. */
+export declare function isAstParseable(filePath: string): boolean;
+/**
+ * Canonical form for COMPARING two filesystem paths — absolute, forward slashes, lower case.
+ *
+ * Windows reaches the same file through several spellings (`c:\x` vs `C:/x`), so any exact
+ * match against a stored path silently misses unless both sides are folded first. Comparison
+ * only: never write this back to disk or store it as a node's file_path.
+ */
+export declare function normalizeFsPath(p: string): string;
+/**
+ * Drop a file's cached AST. The cache is mtime-keyed, but mtime resolution is coarse enough
+ * that a write followed immediately by a read can still be served the pre-write tree, so a
+ * writer must invalidate explicitly rather than trust the timestamp to have moved.
+ */
+export declare function invalidateParsedFile(filePath: string): void;
 interface ParsedNodeId {
     repo: string;
     filePath: string;
@@ -5,6 +31,12 @@ interface ParsedNodeId {
     className?: string;
     memberName?: string;
 }
+export interface ImportInfo {
+    importedName: string;
+    moduleSpecifier: string;
+    isDefault: boolean;
+    isNamespace?: boolean;
+}
 /** A used reference that resolves to a real repo file but has no node — a Phase-1 gap. */
 export interface MissingRef {
     sourceNodeId: string;
@@ -15,6 +47,27 @@ export interface MissingRef {
  * Parses a DevsMind node ID into constituent parts
  */
 export declare function parseNodeId(id: string): ParsedNodeId | null;
+/** One RTK Query endpoint found by {@link detectRtkEndpointAliases} — the endpoint's own declared
+ * key, plus the hook names RTK Query's codegen convention derives from it. */
+export interface RtkEndpointAlias {
+    /** The endpoint key as written inside `endpoints: (builder) => ({ ... })` — expected to match
+     * an existing node's declared name (the extractor names the node after this same key). */
+    endpointName: string;
+    /** Generated hook names this endpoint is ALSO referenceable by — `useLazy...` only applies to
+     * `.query(...)` endpoints (RTK Query never generates a lazy variant for a mutation). */
+    aliases: string[];
+}
+export declare function detectRtkEndpointAliases(filePath: string): RtkEndpointAlias[];
+/**
+ * The candidate-enumeration counterpart to {@link detectRtkEndpointAliases}: produces full
+ * {@link ExtractionCandidate}s for each RTK endpoint, so {@link enumerateFileCandidates} doesn't
+ * silently skip them (see {@link findRtkEndpointMatches} for why the general declaration walk
+ * can't see them). Always `isExported:true` — an endpoint reached only through its generated hook
+ * is, for every practical purpose, part of the file's export surface; nothing about whether it
+ * "counts" as a node is a judgment call, so this feeds the SAME auto-accept path as a normal
+ * exported declaration.
+ */
+export declare function detectRtkEndpointNodes(filePath: string): ExtractionCandidate[];
 /**
  * Locally analyzes the source file and resolves references to candidate nodes
  */
@@ -23,16 +76,150 @@ export declare function resolveConnectionsLocally(sourceNodeId: string, sourceFi
     name: string;
     type: string;
     file_path: string;
+    aliases?: string[];
 }[], devmindPath: string, onMissing?: (rec: MissingRef) => void): string[];
 /**
  * Derive a node's identity/type/code directly from its declaration in a file — deterministic,
  * no LLM. Used by `--fill-missing` to create nodes that Phase-1 extraction skipped. Returns
  * null when the file isn't TS/JS or the symbol can't be located.
  */
+/** A symbol's exact span in its file — everything needed to splice it in place. */
+export interface NodeLocation {
+    name: string;
+    type: string;
+    signature: string | null;
+    codeSnapshot: string;
+    /** Offset of the symbol's first token. Excludes leading JSDoc/comments, so they survive a replace. */
+    start: number;
+    /** Offset just past the symbol's last token. */
+    end: number;
+    /** 1-based line of `start`. */
+    startLine: number;
+    /** 1-based line of `end`. */
+    endLine: number;
+    /** Whitespace `start` is indented by, or '' when the symbol doesn't begin its line. */
+    indent: string;
+}
+/**
+ * Locate a symbol's span in a file via the AST. This is the write-side counterpart to
+ * `extractNodeFromFile`: same lookup, but it also surfaces the offsets, so a caller can
+ * replace the symbol without the caller ever having to read the file or reproduce its
+ * text byte-exactly.
+ */
+export declare function locateNodeInFile(filePath: string, symbolName: string): NodeLocation | null;
 export declare function extractNodeFromFile(filePath: string, symbolName: string): {
     name: string;
     type: string;
     signature: string | null;
     codeSnapshot: string;
 } | null;
+/** A symbol an edit landed inside — what actually changed, derived from where the write went. */
+export interface TouchedSymbol {
+    /** Set only when the edit fell inside a symbol the graph already knows. */
+    node_id?: string;
+    /** Qualified symbol name, e.g. "Cart.applyPromo" or "calculateTax". */
+    symbolName: string;
+    name: string;
+    type: string;
+    signature: string | null;
+    codeSnapshot: string;
+    /**
+     * The symbol's text before this edit, or null when there is nothing to compare against —
+     * a brand-new symbol, or a caller that passed no before-content. Feeds the diff/revert path.
+     */
+    codeBefore: string | null;
+    startLine: number;
+    endLine: number;
+    /** True when no existing node covered this edit — a symbol that did not exist before. */
+    isNew: boolean;
+}
+/** One deterministically-enumerated candidate entity from {@link enumerateFileCandidates}. */
+export interface ExtractionCandidate {
+    /** Graph node-id name — `Class.method` for a member, a bare name at top level. */
+    qualified: string;
+    name: string;
+    type: string;
+    signature: string | null;
+    codeSnapshot: string;
+    startLine: number;
+    endLine: number;
+    /** See {@link isNodeExported} — the auto-accept signal. */
+    isExported: boolean;
+}
+/**
+ * Enumerates every graph-eligible declaration in a file, deterministically — no LLM, so nothing
+ * gets silently missed the way the old whole-file-to-an-LLM extraction could. A named, EXPORTED
+ * declaration (`isExported:true`) is unambiguous: whether it "counts" as a node requires no
+ * judgment, so the caller can auto-accept it with zero LLM turns. Everything else — unexported
+ * helpers, anonymous default exports, tiny inline callbacks, object-literal factory members whose
+ * significance is genuinely a judgment call — is still enumerated (nothing is dropped silently)
+ * but flagged `isExported:false`, so an agentic curation pass only has to spend turns on THOSE.
+ */
+export declare function enumerateFileCandidates(filePath: string): ExtractionCandidate[];
+/** One entry in {@link outlineFile}'s "what else is declared in this file" list. Deliberately
+ * lean — no `codeSnapshot` — see the function doc for why. */
+export interface FileOutlineEntry {
+    qualified: string;
+    name: string;
+    type: string;
+    signature: string | null;
+    start_line: number;
+    end_line: number;
+    exported: boolean;
+}
+/**
+ * Every OTHER top-level declaration in a file — functions, classes, consts, types, interfaces —
+ * the "what else is here" a raw file read used to be the only way to answer. Reuses
+ * {@link enumerateFileCandidates}'s own declaration walk (`declarationsOverlapping` /
+ * `astBaseType` / `isNodeExported`), but deliberately does NOT call `node.getText()` per hit the
+ * way that function does: `enumerateFileCandidates` materializes each declaration's FULL source
+ * just to build a one-line signature and then discards it, which is an extra copy of potentially
+ * the whole file in string allocations — on every single `get_node_code` call, this is squarely
+ * the wrong trade. A short slice of the already-loaded full text plus a line split gets the same
+ * signature far cheaper. The parse itself is free either way: `getSourceFile` is mtime-cached
+ * ({@link getSourceFile}), and by the time `get_node_code` calls this the file has usually already
+ * been parsed once this same request via `getLiveCode`/`extractLiveCode`.
+ */
+export declare function outlineFile(filePath: string): FileOutlineEntry[];
+/**
+ * A file's own import list — file-path entry point for {@link getFileImports} (which needs an
+ * already-parsed `ts.SourceFile`). Used by the Phase D curation agent's `get_file_imports` tool:
+ * whether an ambiguous candidate is worth keeping is often decided by whether it's ever imported
+ * anywhere, and the file's OWN imports are the cheap first signal (e.g. a candidate that mirrors
+ * a re-exported name, or that only makes sense alongside a specific imported dependency).
+ */
+export declare function listFileImports(filePath: string): ImportInfo[];
+/**
+ * Work out which symbols an edit actually changed, from where the edit landed.
+ *
+ * Position beats name matching: a span is unambiguous where a name is not (fifty classes can
+ * each have a `run`), it survives the symbol being renamed by the very edit being traced, and
+ * it finds code that did not exist until this write.
+ *
+ * Three passes, each removing a specific kind of wrong answer:
+ *   1. OVERLAP — every declaration intersecting the written span. A point would not do: text
+ *      appended after an anchor (`}` → `}\n\nfunction added() {}`) begins inside the PREVIOUS
+ *      function, so a point attributes the new function to its neighbour.
+ *   2. INNERMOST — drop any declaration that contains another hit, so inserting a method
+ *      reports the method and not its whole class.
+ *   3. CHANGED — compare each survivor against `beforeContent` and keep only what actually
+ *      differs. Overlap alone over-reports: the anchor's own function is intersected by an
+ *      append yet is untouched by it, and re-recording it would invent history for a change
+ *      that never happened. A symbol absent from `beforeContent` is new.
+ *
+ * Symbols already in the graph are matched by span against their RECORDED ids, never by
+ * re-deriving a name — a container name may have been chosen at index time and be absent from
+ * the source (`Component({...})` recorded as `ProductImageGalleryComponent`).
+ *
+ * `knownSymbols` should be the graph's nodes for this file; empty is fine, everything is then
+ * reported as new. An edit touching no symbol at all (an import, markup, a config value) yields
+ * nothing — a normal outcome, not an error.
+ */
+export declare function findTouchedSymbols(filePath: string, ranges: {
+    start: number;
+    end: number;
+}[], knownSymbols?: {
+    id: string;
+    symbolName: string;
+}[], beforeContent?: string): TouchedSymbol[];
 export {};