xcoder-dna 0.0.0-stage → 1.3.1

package/dist/tools/dependency-graph.js

@@ -0,0 +1,164 @@
+// xcoder:version 6 | xcoder:task task-e6370a | xcoder:updated 2026-08-12T16:41:56.324Z | xcoder:subtask code-st-cd4444
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { getOrBuildIndex, toPosixPath } from "./workspace-index.js";
+import { resolveInWorkspace } from "./patch-tools.js";
+import { scanFile } from "./ast-tools.js";
+const memo = new Map();
+const EXT_IMPORTABLE = new Set([
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts",
+    ".py", ".go", ".java", ".rs", ".rb",
+]);
+function guessScanLanguages(relPath) {
+    const lower = relPath.toLowerCase();
+    if (lower.endsWith(".ts") || lower.endsWith(".tsx") || lower.endsWith(".mts") || lower.endsWith(".cts"))
+        return "typescript";
+    if (lower.endsWith(".js") || lower.endsWith(".jsx") || lower.endsWith(".mjs") || lower.endsWith(".cjs"))
+        return "javascript";
+    if (lower.endsWith(".py"))
+        return "python";
+    return "none";
+}
+/**
+ * Best-effort import index over `WorkspaceIndex.entries`, memoized by index
+ * `builtAt` so repeated calls in one run don't re-scan the tree.
+ */
+async function buildImportIndex(root, index) {
+    const cached = memo.get(index.builtAt);
+    if (cached)
+        return cached;
+    const importsByFile = new Map();
+    for (const entry of index.entries) {
+        if (!EXT_IMPORTABLE.has(path.extname(entry.relPath)))
+            continue;
+        let content;
+        try {
+            content = await fs.readFile(path.join(root, entry.relPath), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const lang = guessScanLanguages(entry.relPath);
+        let specifiers = [];
+        if (lang === "typescript" || lang === "javascript") {
+            const scan = scanFile(content, lang);
+            if (!("ok" in scan)) {
+                specifiers = scan.imports;
+            }
+            else {
+                specifiers = regexImports(content);
+            }
+        }
+        else if (lang === "python") {
+            specifiers = regexImports(content);
+        }
+        importsByFile.set(entry.relPath, specifiers
+            .map((s) => resolveSpecifier(s, entry.relPath, index) ?? s)
+            .filter((s) => s !== ""));
+    }
+    const built = { builtAt: index.builtAt, importsByFile };
+    memo.set(index.builtAt, built);
+    return built;
+}
+/** Regex fallback for non-TS/JS: Python `import x` / `from y import z`, etc. */
+function regexImports(content) {
+    const out = [];
+    for (const line of content.split("\n")) {
+        const m = /^\s*(?:import|from)\s+([A-Za-z_][A-Za-z0-9_.]*)/.exec(line);
+        if (m)
+            out.push(m[1]);
+    }
+    return out;
+}
+/** Converts an import specifier to a relative path candidates list (TS/JS only). */
+function resolveSpecifier(specifier, fromFile, index) {
+    if (specifier.startsWith(".") || specifier.startsWith("/")) {
+        const fromDir = path.posix.dirname(fromFile);
+        const candidates = [
+            specifier,
+            `${specifier}.ts`, `${specifier}.tsx`, `${specifier}.js`, `${specifier}.jsx`,
+            `${specifier}/index.ts`, `${specifier}/index.tsx`, `${specifier}/index.js`, `${specifier}/index.jsx`,
+        ];
+        for (const c of candidates) {
+            const joined = toPosixPath(path.posix.normalize(path.posix.join(fromDir === "." ? "" : fromDir, c)));
+            if (index.entries.some((e) => e.relPath === joined))
+                return joined;
+        }
+        return null;
+    }
+    return null; // bare specifier = external package
+}
+/**
+ * get_dependency_graph — imports + importers for one file, best-effort.
+ * Never throws: unknown extensions (or unparseable files) return typed
+ * `unsupported`, missing files `file_not_found`.
+ */
+export async function getDependencyGraphTool(root, relPath) {
+    let full;
+    try {
+        full = resolveInWorkspace(root, relPath);
+    }
+    catch (e) {
+        return { ok: false, code: "workspace_escape", error: e.message };
+    }
+    const index = await getOrBuildIndex(root);
+    const posix = toPosixPath(relPath).replace(/^\.\//, "");
+    if (!index.entries.some((e) => e.relPath === posix)) {
+        return {
+            ok: false,
+            code: "file_not_found",
+            error: `"${relPath}" is not in the workspace index. Use write_file to create it, or search the index for the right path.`,
+        };
+    }
+    const ext = path.extname(posix).toLowerCase();
+    const lang = guessScanLanguages(posix);
+    if (lang === "none" && !EXT_IMPORTABLE.has(ext)) {
+        return {
+            ok: false,
+            code: "unsupported",
+            error: `get_dependency_graph has no import scanner for "${ext}" files — supported: TS/JS/Python. Fall back to grep/read_file.`,
+        };
+    }
+    let content;
+    try {
+        content = await fs.readFile(full, "utf8");
+    }
+    catch (e) {
+        return { ok: false, code: "file_not_found", error: e.message };
+    }
+    let specifiers = [];
+    let parseMethod = "none";
+    if (lang === "typescript" || lang === "javascript") {
+        const scan = scanFile(content, lang);
+        if (!("ok" in scan)) {
+            specifiers = scan.imports;
+            parseMethod = "tokenizer";
+        }
+        else {
+            specifiers = regexImports(content);
+            parseMethod = "regex";
+        }
+    }
+    else {
+        specifiers = regexImports(content);
+        parseMethod = "regex";
+    }
+    const imports = specifiers.map((specifier) => ({
+        specifier,
+        resolved: resolveSpecifier(specifier, posix, index),
+        isExternal: !specifier.startsWith(".") && !specifier.startsWith("/"),
+    }));
+    const note = content.includes("import(") || content.includes("require(")
+        ? "dynamic imports (import()/require()) are documented, not resolved."
+        : undefined;
+    // Importers: files whose resolved import set includes this file.
+    const impIndex = await buildImportIndex(root, index);
+    const importers = [];
+    for (const [fromFile, fromImports] of impIndex.importsByFile) {
+        if (fromFile === posix)
+            continue;
+        if (fromImports.includes(posix))
+            importers.push(fromFile);
+    }
+    return { ok: true, relPath: posix, imports, importers, parseMethod: parseMethod, note };
+}

package/dist/tools/edit-tool.d.ts

@@ -0,0 +1,34 @@
+export declare class WorkspaceEscapeError extends Error {
+}
+export interface EditFileInput {
+    path: string;
+    old_str: string;
+    new_str: string;
+}
+export type EditFileResult = {
+    ok: true;
+    relPath: string;
+    replaced: true;
+} | {
+    ok: false;
+    error: string;
+    code: "file_not_found" | "not_unique" | "no_match" | "workspace_escape" | "io_error";
+};
+/**
+ * The tool that exists specifically to fix "the programmer can't refactor
+ * large files": `write_file` requires reproducing an ENTIRE file's content
+ * to change one function, which is exactly where a model truncates,
+ * mis-copies, or silently drops unrelated code in a big file. `edit_file`
+ * takes a unique anchor (`old_str`) and its replacement — the same
+ * str_replace pattern Claude Code's own editor uses — so a correction to
+ * one function never risks the other 900 lines.
+ *
+ * `old_str` must match EXACTLY ONCE. Zero matches and multiple matches are
+ * both refused with a specific, actionable error (rather than guessing
+ * which occurrence was meant) so the model can widen its anchor with more
+ * surrounding context and retry.
+ */
+export declare function editFileTool(root: string, input: EditFileInput, ctx?: {
+    taskId: string;
+    subtaskId: string;
+}): Promise<EditFileResult>;

package/dist/tools/edit-tool.js

@@ -0,0 +1,95 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { upsertEntry } from "./workspace-index.js";
+import { getCommentSyntax, injectVersionHeader, } from "./file-header-manager.js";
+import { incrementFileVersion } from "../store/file-version-store.js";
+export class WorkspaceEscapeError extends Error {
+}
+function resolveInWorkspace(root, relPath) {
+    const full = path.resolve(root, relPath);
+    const normalizedRoot = path.resolve(root) + path.sep;
+    if (full + path.sep !== normalizedRoot && !full.startsWith(normalizedRoot)) {
+        throw new WorkspaceEscapeError(`path "${relPath}" resolves outside the workspace root — refusing.`);
+    }
+    return full;
+}
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let idx = 0;
+    while ((idx = haystack.indexOf(needle, idx)) !== -1) {
+        count++;
+        idx += needle.length;
+    }
+    return count;
+}
+/**
+ * The tool that exists specifically to fix "the programmer can't refactor
+ * large files": `write_file` requires reproducing an ENTIRE file's content
+ * to change one function, which is exactly where a model truncates,
+ * mis-copies, or silently drops unrelated code in a big file. `edit_file`
+ * takes a unique anchor (`old_str`) and its replacement — the same
+ * str_replace pattern Claude Code's own editor uses — so a correction to
+ * one function never risks the other 900 lines.
+ *
+ * `old_str` must match EXACTLY ONCE. Zero matches and multiple matches are
+ * both refused with a specific, actionable error (rather than guessing
+ * which occurrence was meant) so the model can widen its anchor with more
+ * surrounding context and retry.
+ */
+export async function editFileTool(root, input, ctx) {
+    let full;
+    try {
+        full = resolveInWorkspace(root, input.path);
+    }
+    catch (e) {
+        return { ok: false, error: e.message, code: "workspace_escape" };
+    }
+    let content;
+    try {
+        content = await fs.readFile(full, "utf8");
+    }
+    catch {
+        return {
+            ok: false,
+            code: "file_not_found",
+            error: `"${input.path}" doesn't exist. Use write_file to create a new file instead of edit_file.`,
+        };
+    }
+    const occurrences = countOccurrences(content, input.old_str);
+    if (occurrences === 0) {
+        return {
+            ok: false,
+            code: "no_match",
+            error: `old_str was not found in "${input.path}". It must match the file's current content EXACTLY, ` +
+                `including whitespace/indentation. Re-read the file (or the relevant range) and copy the anchor precisely.`,
+        };
+    }
+    if (occurrences > 1) {
+        return {
+            ok: false,
+            code: "not_unique",
+            error: `old_str matches ${occurrences} locations in "${input.path}" — it must be unique. ` +
+                `Include more surrounding context (a few extra lines above/below) so the anchor pins exactly one spot.`,
+        };
+    }
+    let next = content.replace(input.old_str, input.new_str);
+    // Header injection (when context is available and file type supports it)
+    if (ctx) {
+        const syntax = getCommentSyntax(input.path);
+        if (syntax) {
+            const meta = await incrementFileVersion(root, input.path, ctx.taskId, ctx.subtaskId);
+            const injected = injectVersionHeader(next, syntax, meta);
+            next = injected.content;
+        }
+    }
+    try {
+        await fs.writeFile(full, next, "utf8");
+        await upsertEntry(root, path.relative(root, full));
+        return { ok: true, relPath: input.path, replaced: true };
+    }
+    catch (e) {
+        return { ok: false, code: "io_error", error: e.message };
+    }
+}

package/dist/tools/file-header-manager.d.ts

@@ -0,0 +1,27 @@
+import type { HeaderMeta } from "../store/file-version-store.js";
+export type CommentSyntax = {
+    open: string;
+    close?: string;
+};
+export interface InjectResult {
+    content: string;
+    isNew: boolean;
+}
+/**
+ * Returns the comment markers and whether the file type supports headers.
+ * Maps extensions: .ts/.js/.tsx/.jsx/.css/.scss/.less → //
+ * .py/.sh/.yaml/.yml/.toml/Dockerfile/.env → #
+ * .html/.md/.mdx → <!-- --> pair
+ * .sql → --
+ * .json → null (skipped)
+ * Unknown extensions → null (skipped)
+ */
+export declare function getCommentSyntax(filePath: string): CommentSyntax | null;
+/**
+ * Builds a version header block and prepends it to content. If content
+ * already begins with a xcoder header block, updates the existing one
+ * (version+1, new task/subtask/timestamp). Uses regex to detect xcoder
+ * headers. Returns new content and a flag indicating if this was a new
+ * header or an update.
+ */
+export declare function injectVersionHeader(content: string, syntax: CommentSyntax, meta: HeaderMeta): InjectResult;

package/dist/tools/file-header-manager.js

@@ -0,0 +1,153 @@
+// ---------------------------------------------------------------------------
+// Extension → comment syntax lookup
+// ---------------------------------------------------------------------------
+function ext(filePath) {
+    const lastDot = filePath.lastIndexOf(".");
+    if (lastDot === -1)
+        return "";
+    return filePath.slice(lastDot).toLowerCase();
+}
+// prettier-ignore
+const LINE_COMMENT_EXTS = new Set([
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts",
+    ".css", ".scss", ".less",
+    ".java", ".swift", ".kt", ".kts", ".go", ".rs",
+    ".php",
+]);
+// prettier-ignore
+const HASH_COMMENT_EXTS = new Set([
+    ".py", ".pyi", ".pyx",
+    ".sh", ".bash", ".zsh",
+    ".yaml", ".yml",
+    ".toml",
+    ".rb", ".rbs",
+    ".pl", ".pm",
+    ".cfg", ".conf", ".ini",
+    ".gitignore", ".dockerignore",
+    ".env", ".env.local", ".env.example",
+]);
+const HTML_COMMENT_EXTS = new Set([".html", ".htm", ".md", ".mdx"]);
+// prettier-ignore
+const SQL_COMMENT_EXTS = new Set([".sql", ".psql"]);
+// Special filenames (no extension or non-standard ext)
+const HASH_COMMENT_NAMES = new Set(["dockerfile", "makefile", "gemfile", "rakefile"]);
+/**
+ * Returns the comment markers and whether the file type supports headers.
+ * Maps extensions: .ts/.js/.tsx/.jsx/.css/.scss/.less → //
+ * .py/.sh/.yaml/.yml/.toml/Dockerfile/.env → #
+ * .html/.md/.mdx → <!-- --> pair
+ * .sql → --
+ * .json → null (skipped)
+ * Unknown extensions → null (skipped)
+ */
+export function getCommentSyntax(filePath) {
+    const e = ext(filePath);
+    const name = filePath.split("/").pop()?.split("\\").pop()?.toLowerCase() ?? "";
+    // JSON files: no comment support — skip headers entirely
+    if (e === ".json")
+        return null;
+    // Binary / image / audio / video: skip
+    if ([
+        ".png",
+        ".jpg",
+        ".jpeg",
+        ".gif",
+        ".svg",
+        ".ico",
+        ".webp",
+        ".bmp",
+        ".mp3",
+        ".wav",
+        ".ogg",
+        ".mp4",
+        ".webm",
+        ".avi",
+        ".mov",
+        ".zip",
+        ".tar",
+        ".gz",
+        ".rar",
+        ".7z",
+        ".pdf",
+        ".woff",
+        ".woff2",
+        ".ttf",
+        ".eot",
+        ".lock",
+    ].includes(e))
+        return null;
+    if (LINE_COMMENT_EXTS.has(e))
+        return { open: "//" };
+    if (HASH_COMMENT_EXTS.has(e) || HASH_COMMENT_NAMES.has(name))
+        return { open: "#" };
+    if (HTML_COMMENT_EXTS.has(e))
+        return { open: "<!--", close: "-->" };
+    if (SQL_COMMENT_EXTS.has(e))
+        return { open: "--" };
+    // Unknown extension: skip headers (conservative)
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Header construction / parsing
+// ---------------------------------------------------------------------------
+/**
+ * Build a single-line xcoder version header using the given comment syntax.
+ *
+ * Format per syntax:
+ *   // xcoder:version 3 | xcoder:task TASK-001 | xcoder:updated 2026-01-23... | xcoder:subtask design-st-7bec8f
+ *   # xcoder:version 3 | xcoder:task TASK-001 | xcoder:updated 2026-01-23... | xcoder:subtask design-st-7bec8f
+ *   <!-- xcoder:version 3 | xcoder:task TASK-001 | xcoder:updated 2026-01-23... | xcoder:subtask design-st-7bec8f -->
+ *   -- xcoder:version 3 | xcoder:task TASK-001 | xcoder:updated 2026-01-23... | xcoder:subtask design-st-7bec8f
+ */
+function buildHeaderLine(syntax, meta) {
+    const payload = `xcoder:version ${meta.version} | xcoder:task ${meta.taskId} | xcoder:updated ${meta.timestamp} | xcoder:subtask ${meta.subtaskId}`;
+    if (syntax.close) {
+        return `${syntax.open} ${payload} ${syntax.close}`;
+    }
+    return `${syntax.open} ${payload}`;
+}
+/**
+ * Regex that detects a xcoder version header line in any comment syntax.
+ * Matches lines like:
+ *   // xcoder:version 3 | ...
+ *   # xcoder:version 1 | ...
+ *   <!-- xcoder:version 5 | ... -->
+ *   -- xcoder:version 2 | ...
+ */
+const XCODER_HEADER_RE = /^\s*\S*\s*xcoder:version\s+\d+/m;
+/**
+ * Builds a version header block and prepends it to content. If content
+ * already begins with a xcoder header block, updates the existing one
+ * (version+1, new task/subtask/timestamp). Uses regex to detect xcoder
+ * headers. Returns new content and a flag indicating if this was a new
+ * header or an update.
+ */
+export function injectVersionHeader(content, syntax, meta) {
+    const newLine = buildHeaderLine(syntax, meta);
+    // Check if a xcoder header already exists
+    const match = content.match(XCODER_HEADER_RE);
+    if (match) {
+        // Extract the full matched line (up to the next newline)
+        const matchIndex = match.index;
+        const lineStart = content.lastIndexOf("\n", matchIndex - 1) + 1;
+        const lineEnd = content.indexOf("\n", matchIndex);
+        const fullLine = lineEnd === -1 ? content.slice(lineStart) : content.slice(lineStart, lineEnd);
+        // Replace the old header line with the new one
+        const before = content.slice(0, lineStart);
+        const after = lineEnd === -1 ? "" : content.slice(lineEnd);
+        return { content: before + newLine + after, isNew: false };
+    }
+    // No existing header: prepend at top
+    // If the file starts with a shebang, insert the header line right after it
+    if (content.startsWith("#!")) {
+        const shebangEnd = content.indexOf("\n");
+        if (shebangEnd !== -1) {
+            return {
+                content: content.slice(0, shebangEnd + 1) + newLine + "\n" + content.slice(shebangEnd + 1),
+                isNew: true,
+            };
+        }
+    }
+    // Prepend the header line at the very top
+    return { content: newLine + "\n" + content, isNew: true };
+}

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

@@ -0,0 +1,154 @@
+import { type WorkspaceIndex } from "./workspace-index.js";
+export declare class WorkspaceEscapeError extends Error {
+}
+export interface ReadFileResult {
+    ok: true;
+    content: string;
+    relPath: string;
+    totalLines?: number;
+    /**
+     * Full-file sha1 (only present on range reads). Stale-enforced write
+     * tools (line_patch) require this — hash the file right before writing.
+     */
+    readSha1?: string;
+}
+export interface ReadFileError {
+    ok: false;
+    error: string;
+    code: "file_not_found" | "workspace_escape" | "read_error";
+}
+/**
+ * The workspace index is the source of truth for "what files exist". If a
+ * requested path isn't in the index, this triggers exactly one automatic
+ * reindex and retries — covering the common case (a file appeared via some
+ * process outside Xcoder SDLC, or the index is simply stale). If it's still not
+ * found after that, the caller gets a typed `file_not_found`, not a crash.
+ *
+ * `startLine`/`endLine` (1-indexed, inclusive) let a large file be read in
+ * slices instead of pulling the whole thing into context at once — pair
+ * this with `edit_file` for surgical changes to files too big to safely
+ * rewrite in full via `write_file`.
+ */
+export declare function readFileTool(root: string, relPath: string, range?: {
+    startLine?: number;
+    endLine?: number;
+}): Promise<ReadFileResult | ReadFileError>;
+export interface WriteFileResult {
+    ok: true;
+    relPath: string;
+    bytesWritten: number;
+}
+export interface WriteFileError {
+    ok: false;
+    error: string;
+    code: "workspace_escape" | "write_error" | "file_too_large";
+}
+/**
+ * write_file gate (AC-15): refuse whole-file rewrites above this many lines
+ * unless the caller explicitly opts out with `force: true`. The refusal is
+ * a steering signal — point the model at the surgical alternatives rather
+ * than silently accepting a 900-line reproduce-the-whole-file risk.
+ */
+export declare const WRITE_FILE_LINE_CEILING = 200;
+export declare function writeFileTool(root: string, relPath: string, content: string, ctx?: {
+    taskId: string;
+    subtaskId: string;
+}, opts?: {
+    force?: boolean;
+}): Promise<WriteFileResult | WriteFileError>;
+export interface ListDirResult {
+    ok: true;
+    entries: string[];
+}
+export declare function listDirTool(index: WorkspaceIndex, relDir: string): Promise<ListDirResult>;
+/**
+ * Maximum characters for a single observation returned to the LLM. Every
+ * growable new-tool output routes through `truncateOutput` — with an
+ * actionable note naming that tool's narrowing parameter, never a silent
+ * cutoff (AC-18).
+ */
+export declare const MAX_OBSERVATION_CHARS = 4000;
+export declare function truncateOutput(text: string, maxChars?: number): {
+    text: string;
+    truncated: boolean;
+    note: string;
+};
+export type ReadOutlineResult = {
+    ok: true;
+    relPath: string;
+    language: "typescript" | "javascript" | "text";
+    lineCount: number;
+    imports: string[];
+    symbols: Array<{
+        kind: "function" | "class" | "interface" | "type" | "const";
+        name: string;
+        startLine: number;
+        endLine: number;
+        signature: string;
+        doc?: string;
+    }>;
+    body: string;
+} | {
+    ok: false;
+    error: string;
+    code: "file_not_found" | "workspace_escape" | "unsupported_language" | "read_error";
+};
+/**
+ * Structural skeleton read: imports, symbol signatures, docstrings, bodies
+ * collapsed. The default first read for files over ~150 lines — far cheaper
+ * than pulling the whole file into context. TS/JS uses the scanner in
+ * ast-tools; other text files get a structural fallback (markdown headings,
+ * `---` separators, first non-empty lines). Binary → unsupported_language.
+ */
+export declare function readOutlineTool(root: string, relPath: string): Promise<ReadOutlineResult>;
+export interface ReadMultipleFilesInput {
+    files: Array<{
+        path: string;
+        startLine?: number;
+        endLine?: number;
+    }>;
+    maxTotalChars?: number;
+}
+export type ReadMultipleFilesResult = {
+    ok: true;
+    sections: Array<{
+        label: string;
+        content: string;
+        totalLines: number;
+        sliced: boolean;
+    }>;
+    totalChars: number;
+    dropped: number;
+    note?: string;
+} | {
+    ok: false;
+    error: string;
+    code: "workspace_escape" | "invalid_files";
+    sections?: never;
+};
+/**
+ * Batched, labeled section reads in ONE call — the replacement for N
+ * separate read_file calls when building cross-file understanding. Parallel
+ * (bounded to 8), each section labeled `--- path (lines a-b of N) ---`.
+ * Over maxTotalChars (default 12000) tail sections are dropped with an
+ * actionable note; never silently swallowed.
+ */
+export declare function readMultipleFilesTool(root: string, input: ReadMultipleFilesInput): Promise<ReadMultipleFilesResult>;
+export type ReadFullFileResult = {
+    ok: true;
+    relPath: string;
+    lineCount: number;
+    content: string;
+} | {
+    ok: false;
+    error: string;
+    code: "file_not_found" | "workspace_escape" | "read_error" | "file_too_large";
+};
+/** read_full_file refuses whole-file reads above this line count unless allowLarge is set. */
+export declare const FULL_FILE_LINE_CEILING = 500;
+/**
+ * Gated whole-file read: refused above 500 lines unless `allowLarge: true`
+ * explicitly opts in. The refusal names the cheaper alternative
+ * (read_outline / read_file with a range) instead of silently auto-chunking.
+ */
+export declare function readFullFileTool(root: string, relPath: string, allowLarge?: boolean): Promise<ReadFullFileResult>;