xcoder-dna 0.0.0-stage → 1.3.1

package/dist/tools/ast-tools.d.ts

@@ -0,0 +1,183 @@
+/**
+ * A small, dependency-free tokenizer + scope tracker for TypeScript and
+ * JavaScript, powering `read_outline`, `search_ast`, `update_function`,
+ * `rename_symbol`, and the TS/JS import extraction used by
+ * `get_dependency_graph`.
+ *
+ * Deliberately NOT a full parser and NOT type-aware (tradeoff T1): it
+ * tokenizes identifiers / strings / templates / comments / punctuation,
+ * tracks brace nesting to delimit scopes and function bodies, and records
+ * declarations and identifier references. Exotic edge cases (destructuring
+ * with shadowing, hoisting, complex generics) may mis-scope, but every
+ * failure path returns a typed `parse_error`, never silent corruption.
+ */
+export declare const MAX_SCAN_BYTES: number;
+export type TokenType = "identifier" | "string" | "template" | "comment" | "punct" | "number";
+export interface Token {
+    type: TokenType;
+    value: string;
+    line: number;
+    startCol: number;
+    endCol: number;
+    offset: number;
+}
+/**
+ * Tokenizes into a small vocabulary. Handles line/block comments, quoted
+ * strings with escapes, template literals (incl. nested ${}), numbers,
+ * identifiers, and single-char punctuation. Returns `{ error }` on
+ * unterminated constructs instead of throwing.
+ */
+export declare function tokenize(content: string): {
+    tokens: Token[];
+} | {
+    error: string;
+};
+export interface ScopeDecl {
+    name: string;
+    kind: "function" | "class" | "const" | "let" | "var" | "param" | "interface" | "type";
+    startLine: number;
+    startCol: number;
+    endLine: number;
+    /** Internal: brace depth at declaration — used by shadowing-aware resolution. */
+    depth?: number;
+}
+export interface ScanResult {
+    language: "typescript" | "javascript";
+    imports: string[];
+    declarations: ScopeDecl[];
+    references: Array<{
+        name: string;
+        startLine: number;
+        startCol: number;
+        endCol: number;
+    }>;
+    parseError?: string;
+}
+export type ScanFileResult = ScanResult | {
+    ok: false;
+    error: string;
+};
+/**
+ * Tokenizes + scans TS/JS source for imports, declarations, and identifier
+ * references. Single pass with an explicit brace-depth scope stack. Never
+ * throws: all failure modes fold into a typed `{ ok: false, error }` or a
+ * `parseError` on the result.
+ */
+export declare function scanFile(content: string, language: "typescript" | "javascript"): ScanFileResult;
+export interface RefToken {
+    name: string;
+    startLine: number;
+    startCol: number;
+    endCol: number;
+}
+/**
+ * Resolves a reference to the innermost visible declaration with the same
+ * name. Shadowing-aware: a declaration at a deeper brace depth wins over an
+ * outer one; among declarations at the same depth, the most recent one seen
+ * before the reference wins. Returns null when nothing is visible.
+ */
+export declare function resolveReference(ref: RefToken, decls: ScopeDecl[]): ScopeDecl | null;
+/**
+ * Returns the unique declaration for `name` or a typed failure. Used by
+ * update_function / rename_symbol to enforce the no-match / not-unique
+ * contract before any write happens.
+ */
+export declare function findUniqueDeclaration(name: string, decls: ScopeDecl[], kinds?: Set<string>): {
+    ok: true;
+    decl: ScopeDecl;
+} | {
+    ok: false;
+    code: "no_match" | "not_unique";
+    error: string;
+    candidates?: number[];
+};
+export interface SearchAstInput {
+    query: string;
+    pathGlob?: string;
+}
+export interface SearchAstMatch {
+    file: string;
+    kind: "function" | "class" | "call";
+    name: string;
+    startLine: number;
+    endLine: number;
+    signature: string;
+    line: number;
+}
+export type SearchAstResult = {
+    ok: true;
+    matches: SearchAstMatch[];
+    total: number;
+    language: "typescript" | "javascript" | "mixed";
+    note?: string;
+} | {
+    ok: false;
+    error: string;
+    code: "unsupported_language" | "invalid_query" | "read_error" | "file_not_found" | "workspace_escape";
+};
+/**
+ * Structural TS/JS search over the workspace. Supported queries:
+ * - "function Name" → function declarations named Name
+ * - "class Name"    → class declarations named Name
+ * - "call Name"     → identifier references to Name (call sites), shadowing-aware
+ * Uses the scanner — no regex false positives inside strings/comments.
+ */
+export declare function searchAstTool(root: string, input: SearchAstInput): Promise<SearchAstResult>;
+export interface UpdateFunctionInput {
+    path: string;
+    functionName: string;
+    newCode: string;
+}
+export type UpdateFunctionResult = {
+    ok: true;
+    relPath: string;
+    functionName: string;
+    oldLineRange: [number, number];
+    newLineRange: [number, number];
+    sha1After: string;
+} | {
+    ok: false;
+    error: string;
+    code: "no_match" | "not_unique" | "unsupported_language" | "parse_error" | "file_not_found" | "workspace_escape";
+    candidates?: number[];
+};
+/**
+ * Whole-function rewrite (TS/JS only): replaces the declaration's line range
+ * with `newCode`. Refuses when the name is not unique, when the file can't
+ * be scanned, or for non-TS/JS files — never partial.
+ */
+export declare function updateFunctionTool(root: string, input: UpdateFunctionInput, ctx?: {
+    taskId: string;
+    subtaskId: string;
+}): Promise<UpdateFunctionResult>;
+export interface RenameSymbolInput {
+    path: string;
+    name: string;
+    newName: string;
+}
+export type RenameSymbolResult = {
+    ok: true;
+    relPath: string;
+    renames: Array<{
+        line: number;
+        column: number;
+        to: string;
+    }>;
+    count: number;
+    sha1After: string;
+} | {
+    ok: false;
+    error: string;
+    code: "unsupported_language" | "no_match" | "not_unique" | "parse_error" | "file_not_found" | "workspace_escape";
+    candidates?: number[];
+};
+/**
+ * Scope-aware identifier rename (TS/JS only): replaces exactly the
+ * identifier tokens whose binding resolves to the declared symbol. Strings,
+ * comments, template literals, and property access targets are never
+ * touched. Blind sed is NOT used.
+ */
+export declare function renameSymbolTool(root: string, input: RenameSymbolInput, ctx?: {
+    taskId: string;
+    subtaskId: string;
+}): Promise<RenameSymbolResult>;