@saluzi/codegraph 0.1.0

package/dist/resolution/strip-comments.js

@@ -0,0 +1,441 @@
+"use strict";
+/**
+ * Per-language comment stripper for framework route extractors.
+ *
+ * Replaces comment characters and string-literal contents that hide
+ * routing-shaped text with spaces (NOT removal) so that source offsets
+ * are preserved. This means `match.index` from a regex run on the
+ * stripped output still maps to the same line in the original source.
+ *
+ * Example:
+ *   Input:  "x = 1  # path('/fake/', V)\n real = 2"
+ *   Output: "x = 1                       \n real = 2"
+ *
+ * Why strip strings/docstrings as well as comments? Python module/class
+ * docstrings are a common source of false positives — they often contain
+ * `path('/example/', View)` examples in usage docs. We treat triple-quoted
+ * strings the same as comments. Single-line strings stay intact (a `#`
+ * inside a Python string is NOT a comment).
+ *
+ * Scope: this is a pragmatic, regex-supporting helper, not a full parser.
+ * It does NOT try to detect JS regex literals, Python f-string expressions,
+ * or shell-style heredocs. Those edge cases are not load-bearing for the
+ * `path(...)`, `Route::get(...)`, `app.get(...)` style patterns that
+ * framework extractors scan for.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripCommentsForRegex = stripCommentsForRegex;
+function stripCommentsForRegex(content, lang) {
+    switch (lang) {
+        case 'python':
+            return stripPython(content);
+        case 'ruby':
+            return stripRuby(content);
+        case 'rust':
+            return stripRust(content);
+        case 'php':
+            return stripPhp(content);
+        case 'go':
+            return stripGo(content);
+        case 'javascript':
+        case 'typescript':
+        case 'java':
+        case 'csharp':
+        case 'swift':
+            return stripCStyle(content, /* allowSingleQuoteStrings */ lang === 'javascript' || lang === 'typescript');
+        default:
+            return content;
+    }
+}
+/**
+ * Replace every char in a slice with spaces, but keep newlines so line
+ * numbers computed downstream remain valid.
+ */
+function blankRange(buf, start, end, src) {
+    for (let i = start; i < end; i++) {
+        buf[i] = src[i] === '\n' ? '\n' : ' ';
+    }
+}
+// ---------- Python ----------
+function stripPython(src) {
+    const out = src.split('');
+    let i = 0;
+    const n = src.length;
+    while (i < n) {
+        const c = src[i];
+        const c2 = src[i + 1] ?? '';
+        const c3 = src[i + 2] ?? '';
+        // Triple-quoted string: """...""" or '''...'''
+        if ((c === '"' || c === "'") && c2 === c && c3 === c) {
+            const quote = c;
+            const start = i;
+            i += 3;
+            while (i < n) {
+                if (src[i] === '\\' && i + 1 < n) {
+                    i += 2;
+                    continue;
+                }
+                if (src[i] === quote && src[i + 1] === quote && src[i + 2] === quote) {
+                    i += 3;
+                    break;
+                }
+                i++;
+            }
+            blankRange(out, start, i, src);
+            continue;
+        }
+        // Single-line string: '...' or "..."
+        if (c === '"' || c === "'") {
+            const quote = c;
+            i++;
+            while (i < n && src[i] !== quote) {
+                if (src[i] === '\\' && i + 1 < n) {
+                    i += 2;
+                    continue;
+                }
+                if (src[i] === '\n')
+                    break; // unterminated
+                i++;
+            }
+            if (i < n && src[i] === quote)
+                i++;
+            continue;
+        }
+        // Line comment
+        if (c === '#') {
+            const start = i;
+            while (i < n && src[i] !== '\n')
+                i++;
+            blankRange(out, start, i, src);
+            continue;
+        }
+        i++;
+    }
+    return out.join('');
+}
+// ---------- Ruby ----------
+function stripRuby(src) {
+    const out = src.split('');
+    let i = 0;
+    const n = src.length;
+    let atLineStart = true;
+    while (i < n) {
+        const c = src[i];
+        // =begin / =end block comments must be at start of line (after optional whitespace)
+        if (atLineStart && c === '=' && src.startsWith('=begin', i)) {
+            const start = i;
+            // consume to matching =end at line start
+            i += '=begin'.length;
+            while (i < n) {
+                if (src[i] === '\n') {
+                    // check next line for =end
+                    let j = i + 1;
+                    while (j < n && (src[j] === ' ' || src[j] === '\t'))
+                        j++;
+                    if (src.startsWith('=end', j)) {
+                        i = j + '=end'.length;
+                        // consume rest of that line
+                        while (i < n && src[i] !== '\n')
+                            i++;
+                        break;
+                    }
+                }
+                i++;
+            }
+            blankRange(out, start, i, src);
+            atLineStart = i > 0 && src[i - 1] === '\n';
+            continue;
+        }
+        // String literals
+        if (c === '"' || c === "'") {
+            const quote = c;
+            i++;
+            while (i < n && src[i] !== quote) {
+                if (src[i] === '\\' && i + 1 < n) {
+                    i += 2;
+                    continue;
+                }
+                if (src[i] === '\n')
+                    break;
+                i++;
+            }
+            if (i < n && src[i] === quote)
+                i++;
+            atLineStart = false;
+            continue;
+        }
+        // Line comment
+        if (c === '#') {
+            const start = i;
+            while (i < n && src[i] !== '\n')
+                i++;
+            blankRange(out, start, i, src);
+            atLineStart = false;
+            continue;
+        }
+        if (c === '\n') {
+            atLineStart = true;
+            i++;
+            continue;
+        }
+        if (c === ' ' || c === '\t') {
+            // whitespace doesn't change atLineStart
+            i++;
+            continue;
+        }
+        atLineStart = false;
+        i++;
+    }
+    return out.join('');
+}
+// ---------- C-style (JS/TS/Java/C#/Swift) ----------
+function stripCStyle(src, allowSingleQuoteStrings) {
+    const out = src.split('');
+    let i = 0;
+    const n = src.length;
+    while (i < n) {
+        const c = src[i];
+        const c2 = src[i + 1] ?? '';
+        // Block comment
+        if (c === '/' && c2 === '*') {
+            const start = i;
+            i += 2;
+            while (i < n && !(src[i] === '*' && src[i + 1] === '/'))
+                i++;
+            if (i < n)
+                i += 2;
+            blankRange(out, start, i, src);
+            continue;
+        }
+        // Line comment
+        if (c === '/' && c2 === '/') {
+            const start = i;
+            while (i < n && src[i] !== '\n')
+                i++;
+            blankRange(out, start, i, src);
+            continue;
+        }
+        // String literals
+        if (c === '"' || (allowSingleQuoteStrings && c === "'") || c === '`') {
+            const quote = c;
+            i++;
+            while (i < n && src[i] !== quote) {
+                if (src[i] === '\\' && i + 1 < n) {
+                    i += 2;
+                    continue;
+                }
+                // Template literal can span lines; regular strings break on newline (treat as unterminated)
+                if (quote !== '`' && src[i] === '\n')
+                    break;
+                i++;
+            }
+            if (i < n && src[i] === quote)
+                i++;
+            continue;
+        }
+        i++;
+    }
+    return out.join('');
+}
+// ---------- PHP ----------
+function stripPhp(src) {
+    const out = src.split('');
+    let i = 0;
+    const n = src.length;
+    while (i < n) {
+        const c = src[i];
+        const c2 = src[i + 1] ?? '';
+        // Block comment
+        if (c === '/' && c2 === '*') {
+            const start = i;
+            i += 2;
+            while (i < n && !(src[i] === '*' && src[i + 1] === '/'))
+                i++;
+            if (i < n)
+                i += 2;
+            blankRange(out, start, i, src);
+            continue;
+        }
+        // // line comment
+        if (c === '/' && c2 === '/') {
+            const start = i;
+            while (i < n && src[i] !== '\n')
+                i++;
+            blankRange(out, start, i, src);
+            continue;
+        }
+        // # line comment (PHP supports both)
+        if (c === '#') {
+            const start = i;
+            while (i < n && src[i] !== '\n')
+                i++;
+            blankRange(out, start, i, src);
+            continue;
+        }
+        // String literals: ', ", ` (PHP doesn't really use backticks for strings,
+        // but it does have shell-exec backticks; treating as a string is fine here)
+        if (c === '"' || c === "'" || c === '`') {
+            const quote = c;
+            i++;
+            while (i < n && src[i] !== quote) {
+                if (src[i] === '\\' && i + 1 < n) {
+                    i += 2;
+                    continue;
+                }
+                if (src[i] === '\n')
+                    break;
+                i++;
+            }
+            if (i < n && src[i] === quote)
+                i++;
+            continue;
+        }
+        i++;
+    }
+    return out.join('');
+}
+// ---------- Go ----------
+function stripGo(src) {
+    const out = src.split('');
+    let i = 0;
+    const n = src.length;
+    while (i < n) {
+        const c = src[i];
+        const c2 = src[i + 1] ?? '';
+        // Block comment
+        if (c === '/' && c2 === '*') {
+            const start = i;
+            i += 2;
+            while (i < n && !(src[i] === '*' && src[i + 1] === '/'))
+                i++;
+            if (i < n)
+                i += 2;
+            blankRange(out, start, i, src);
+            continue;
+        }
+        // Line comment
+        if (c === '/' && c2 === '/') {
+            const start = i;
+            while (i < n && src[i] !== '\n')
+                i++;
+            blankRange(out, start, i, src);
+            continue;
+        }
+        // Raw string with backticks (no escapes, can span lines)
+        if (c === '`') {
+            i++;
+            while (i < n && src[i] !== '`')
+                i++;
+            if (i < n)
+                i++;
+            continue;
+        }
+        // Interpreted string with double quotes
+        if (c === '"') {
+            i++;
+            while (i < n && src[i] !== '"') {
+                if (src[i] === '\\' && i + 1 < n) {
+                    i += 2;
+                    continue;
+                }
+                if (src[i] === '\n')
+                    break;
+                i++;
+            }
+            if (i < n && src[i] === '"')
+                i++;
+            continue;
+        }
+        // Rune literal with single quotes (handle as a tiny string)
+        if (c === "'") {
+            i++;
+            while (i < n && src[i] !== "'") {
+                if (src[i] === '\\' && i + 1 < n) {
+                    i += 2;
+                    continue;
+                }
+                if (src[i] === '\n')
+                    break;
+                i++;
+            }
+            if (i < n && src[i] === "'")
+                i++;
+            continue;
+        }
+        i++;
+    }
+    return out.join('');
+}
+// ---------- Rust ----------
+function stripRust(src) {
+    const out = src.split('');
+    let i = 0;
+    const n = src.length;
+    while (i < n) {
+        const c = src[i];
+        const c2 = src[i + 1] ?? '';
+        // Nested block comment /* ... /* ... */ ... */
+        if (c === '/' && c2 === '*') {
+            const start = i;
+            i += 2;
+            let depth = 1;
+            while (i < n && depth > 0) {
+                if (src[i] === '/' && src[i + 1] === '*') {
+                    depth++;
+                    i += 2;
+                }
+                else if (src[i] === '*' && src[i + 1] === '/') {
+                    depth--;
+                    i += 2;
+                }
+                else {
+                    i++;
+                }
+            }
+            blankRange(out, start, i, src);
+            continue;
+        }
+        // Line comment
+        if (c === '/' && c2 === '/') {
+            const start = i;
+            while (i < n && src[i] !== '\n')
+                i++;
+            blankRange(out, start, i, src);
+            continue;
+        }
+        // String literals
+        if (c === '"') {
+            i++;
+            while (i < n && src[i] !== '"') {
+                if (src[i] === '\\' && i + 1 < n) {
+                    i += 2;
+                    continue;
+                }
+                i++;
+            }
+            if (i < n && src[i] === '"')
+                i++;
+            continue;
+        }
+        // Char literal — keep simple: skip 'x' or '\x'
+        if (c === "'") {
+            // Could be a lifetime, e.g. 'a, but those don't contain routing text
+            i++;
+            while (i < n && src[i] !== "'") {
+                if (src[i] === '\\' && i + 1 < n) {
+                    i += 2;
+                    continue;
+                }
+                if (src[i] === '\n')
+                    break;
+                i++;
+            }
+            if (i < n && src[i] === "'")
+                i++;
+            continue;
+        }
+        i++;
+    }
+    return out.join('');
+}
+//# sourceMappingURL=strip-comments.js.map

package/dist/resolution/types.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Reference Resolution Types
+ *
+ * Types for the reference resolution system.
+ */
+import { EdgeKind, Language, Node } from '../types'
+/**
+ * An unresolved reference from extraction
+ */
+export interface UnresolvedRef {
+  /** ID of the source node containing the reference */
+  fromNodeId: string
+  /** The name being referenced */
+  referenceName: string
+  /** Type of reference */
+  referenceKind: EdgeKind
+  /** Line where reference occurs */
+  line: number
+  /** Column where reference occurs */
+  column: number
+  /** File path where reference occurs */
+  filePath: string
+  /** Language of the source file */
+  language: Language
+  /** Possible qualified names it might resolve to */
+  candidates?: string[]
+}
+/**
+ * A resolved reference
+ */
+export interface ResolvedRef {
+  /** Original unresolved reference */
+  original: UnresolvedRef
+  /** ID of the target node */
+  targetNodeId: string
+  /** Confidence score (0-1) */
+  confidence: number
+  /** How it was resolved */
+  resolvedBy:
+    | 'exact-match'
+    | 'import'
+    | 'qualified-name'
+    | 'framework'
+    | 'fuzzy'
+    | 'instance-method'
+    | 'file-path'
+}
+/**
+ * Result of resolution attempt
+ */
+export interface ResolutionResult {
+  /** Successfully resolved references */
+  resolved: ResolvedRef[]
+  /** References that couldn't be resolved */
+  unresolved: UnresolvedRef[]
+  /** Statistics */
+  stats: {
+    total: number
+    resolved: number
+    unresolved: number
+    byMethod: Record<string, number>
+  }
+}
+/**
+ * Context for resolution - provides access to the graph
+ */
+export interface ResolutionContext {
+  /** Get all nodes in a file */
+  getNodesInFile(filePath: string): Node[]
+  /** Get all nodes by name */
+  getNodesByName(name: string): Node[]
+  /** Get all nodes by qualified name */
+  getNodesByQualifiedName(qualifiedName: string): Node[]
+  /** Get all nodes of a kind */
+  getNodesByKind(kind: Node['kind']): Node[]
+  /** Check if a file exists */
+  fileExists(filePath: string): boolean
+  /** Read file content */
+  readFile(filePath: string): string | null
+  /** Get project root */
+  getProjectRoot(): string
+  /** Get all files */
+  getAllFiles(): string[]
+  /** Get nodes by lowercase name (O(1) lookup for fuzzy matching) */
+  getNodesByLowerName(lowerName: string): Node[]
+  /** Get cached import mappings for a file */
+  getImportMappings(filePath: string, language: Language): ImportMapping[]
+  /**
+   * Project import-path aliases (tsconfig/jsconfig `paths`). Returns
+   * `null` when the project doesn't define any. Cached per resolver
+   * instance — safe to call from any resolver code path. Optional so
+   * existing test fixtures and external context implementations
+   * compile without modification; production resolver implements it.
+   */
+  getProjectAliases?(): import('./path-aliases').AliasMap | null
+  /**
+   * Re-exports declared by a file (`export { x } from './other'`,
+   * `export * from './other'`). Empty array when the file has none.
+   * Optional so older callers compile; the import resolver follows
+   * re-export chains when this is provided.
+   */
+  getReExports?(filePath: string, language: Language): ReExport[]
+  /**
+   * List immediate subdirectories of `relativePath` (relative to the
+   * project root). Returns an empty array when the path doesn't exist
+   * or isn't a directory. Used by framework resolvers that need to
+   * walk build-system metadata (e.g. Cargo workspace globs). Optional
+   * so external context implementations and test fixtures compile
+   * without modification.
+   */
+  listDirectories?(relativePath: string): string[]
+}
+/**
+ * Result of framework-specific file extraction.
+ */
+export interface FrameworkExtractionResult {
+  /** Framework-specific nodes (e.g. routes) */
+  nodes: Node[]
+  /** Framework-specific unresolved references (e.g. route -> handler) */
+  references: UnresolvedRef[]
+}
+/**
+ * Framework-specific resolver
+ */
+export interface FrameworkResolver {
+  /** Framework name */
+  name: string
+  /** Languages this framework applies to. If omitted, applies to all languages. */
+  languages?: Language[]
+  /** Detect if project uses this framework (project-level, called once at startup) */
+  detect(context: ResolutionContext): boolean
+  /** Resolve a reference using framework-specific patterns */
+  resolve(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null
+  /**
+   * Extract framework-specific nodes and references from a file.
+   *
+   * Returns route nodes, middleware nodes, etc., plus unresolved references
+   * that link those nodes to handlers (view classes, controller methods,
+   * included modules). Unresolved references flow into the normal resolution
+   * pipeline; the framework's own `resolve()` is one of the strategies tried.
+   */
+  extract?(filePath: string, content: string): FrameworkExtractionResult
+}
+/**
+ * Import mapping from a file
+ */
+export interface ImportMapping {
+  /** Local name used in the file */
+  localName: string
+  /** Original exported name (may differ due to aliasing) */
+  exportedName: string
+  /** Source module/path */
+  source: string
+  /** Whether it's a default import */
+  isDefault: boolean
+  /** Whether it's a namespace import (import * as X) */
+  isNamespace: boolean
+  /** Resolved file path (if local) */
+  resolvedPath?: string
+}
+/**
+ * Re-export from a file: `export { x } from './other'` or
+ * `export * from './other'`. Used by the resolver to chase
+ * symbols through barrel files.
+ */
+export type ReExport =
+  | {
+      kind: 'named'
+      /** Name as exported by THIS file. */
+      exportedName: string
+      /** Name in the upstream module (differs when renamed: `as`). */
+      originalName: string
+      /** Module specifier of the upstream module. */
+      source: string
+    }
+  | {
+      kind: 'wildcard'
+      /** Module specifier of the upstream module. */
+      source: string
+    }
+//# sourceMappingURL=types.d.ts.map

package/dist/resolution/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Reference Resolution Types
+ *
+ * Types for the reference resolution system.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/search/query-parser.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Field-qualified search query parser.
+ *
+ * Splits a raw query like
+ *
+ *     kind:function name:auth path:src/api authenticate
+ *
+ * into structured filters (kind=function, name="auth", path prefix
+ * "src/api") plus the free-text portion ("authenticate") that goes
+ * to FTS. Free-text and filters compose: filters narrow the result
+ * set, FTS scores within the narrowed set.
+ *
+ * Recognised fields (case-insensitive, value is the rest until
+ * whitespace):
+ *
+ *   kind:    one of function|method|class|interface|struct|...
+ *   lang:    one of typescript|python|go|...   (alias: language:)
+ *   path:    case-insensitive substring of file_path
+ *   name:    case-insensitive substring of the symbol's name
+ *
+ * Unknown field prefixes (e.g. `foo:bar`) are passed through to FTS
+ * as plain text — that's how someone searching for `TODO:` gets a
+ * result instead of a parse error.
+ *
+ * Quoting:
+ *   kind:function path:"src/some path/with spaces" → handled by stripping
+ *   the surrounding double quotes from the value (single token only,
+ *   no nested escapes).
+ */
+import type { NodeKind, Language } from '../types'
+export interface ParsedQuery {
+  /** Free-text portion to feed to FTS / LIKE. May be empty. */
+  text: string
+  /** kind: filters (OR'd). Empty when none specified. */
+  kinds: NodeKind[]
+  /** lang:/language: filters (OR'd). Empty when none specified. */
+  languages: Language[]
+  /** path: filters (OR'd, case-insensitive substring of file_path). Empty when none. */
+  pathFilters: string[]
+  /** name: filters (OR'd, case-insensitive substring of node.name). */
+  nameFilters: string[]
+}
+/**
+ * Parse a raw query into structured filters + remaining text.
+ * Always returns a value; never throws.
+ */
+export declare function parseQuery(raw: string): ParsedQuery
+/**
+ * Damerau-Levenshtein-ish bounded edit distance. Returns `maxDist + 1`
+ * as soon as the distance is known to exceed `maxDist`; that early-exit
+ * makes the fuzzy fallback cheap even over tens of thousands of names.
+ *
+ * Pure DP, O(min(len(a), len(b))) memory. Compares case-folded inputs;
+ * callers should pass `lowercase(name)` strings.
+ */
+export declare function boundedEditDistance(
+  a: string,
+  b: string,
+  maxDist: number,
+): number
+//# sourceMappingURL=query-parser.d.ts.map