@decaf-ts/mcp-server 0.4.2 → 0.4.7

package/lib/esm/tools/ast-jsdoc-tools/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { runRepository } from "./repoRunner.js";
+import { runFile } from "./fileRunner.js";
+import path from 'path';
+async function main(argv) {
+    const cmd = argv[2];
+    if (cmd === 'run:repo') {
+        const root = argv[3] || '.';
+        const dryRun = argv.includes('--apply') ? false : true;
+        const report = await runRepository(root, { dryRun });
+        console.log('Repository run complete:', report);
+        process.exit(0);
+    }
+    if (cmd === 'analyze:file') {
+        const file = argv[3];
+        if (!file) {
+            console.error('Usage: analyze:file <path-to-file>');
+            process.exit(2);
+        }
+        const report = await runFile(path.resolve(file));
+        console.log('File report:', report);
+        process.exit(0);
+    }
+    console.log('Usage: cli run:repo [root] | analyze:file <file>');
+    process.exit(2);
+}
+if (require.main === module) {
+    main(process.argv).catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=cli.js.map

package/lib/esm/tools/ast-jsdoc-tools/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../../src/tools/ast-jsdoc-tools/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,wBAAqB;AAC7C,OAAO,EAAE,OAAO,EAAE,wBAAqB;AACvC,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,KAAK,UAAU,IAAI,CAAC,IAAc;IAChC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;QAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QACvD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QACrD,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,MAAM,CAAC,CAAC;QAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,GAAG,KAAK,cAAc,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;YACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACjD,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,kDAAkD,CAAC,CAAC;IAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;QAC7B,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/lib/esm/tools/ast-jsdoc-tools/enumerator.d.ts

@@ -0,0 +1 @@
+export declare function listSourceFiles(root: string, exts?: string[]): Promise<string[]>;

package/lib/esm/tools/ast-jsdoc-tools/enumerator.js

@@ -0,0 +1,25 @@
+import fs from 'fs';
+import path from 'path';
+export async function listSourceFiles(root, exts = ['.ts', '.tsx']) {
+    const results = [];
+    const absRoot = path.resolve(root || '.');
+    function walk(dir) {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (['node_modules', 'dist', 'build', '.git'].includes(e.name))
+                    continue;
+                walk(full);
+            }
+            else if (e.isFile()) {
+                const ext = path.extname(e.name).toLowerCase();
+                if (exts.includes(ext))
+                    results.push(full);
+            }
+        }
+    }
+    walk(absRoot);
+    return results;
+}
+//# sourceMappingURL=enumerator.js.map

package/lib/esm/tools/ast-jsdoc-tools/enumerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enumerator.js","sourceRoot":"","sources":["../../../../src/tools/ast-jsdoc-tools/enumerator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC;IACxE,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC;IAE1C,SAAS,IAAI,CAAC,GAAW;QACvB,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YACpC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;gBACpB,IAAI,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;oBAAE,SAAS;gBACzE,IAAI,CAAC,IAAI,CAAC,CAAC;YACb,CAAC;iBAAM,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;gBACtB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;gBAC/C,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;oBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,CAAC;IACd,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/lib/esm/tools/ast-jsdoc-tools/fileRunner.d.ts

@@ -0,0 +1,11 @@
+export type FileReport = {
+    filePath: string;
+    astObjects: any[];
+    suggestions: any[];
+    summary: {
+        objectsFound: number;
+        suggestionsGenerated: number;
+    };
+    timestamp: string;
+};
+export declare function runFile(filePath: string): Promise<FileReport>;

package/lib/esm/tools/ast-jsdoc-tools/fileRunner.js

@@ -0,0 +1,29 @@
+import { extractAstObjects } from "./parser.js";
+import { generateJSDoc } from "./generator.js";
+import path from 'path';
+import fs from 'fs';
+export async function runFile(filePath) {
+    const abs = path.resolve(filePath);
+    const objects = await extractAstObjects(abs);
+    const suggestions = objects.map((o) => generateJSDoc(o));
+    const report = {
+        filePath: abs,
+        astObjects: objects,
+        suggestions,
+        summary: { objectsFound: objects.length, suggestionsGenerated: suggestions.length },
+        timestamp: new Date().toISOString(),
+    };
+    // write a file report under specs folder for reproducibility
+    try {
+        const outDir = path.resolve('specs/001-ast-jsdoc-tools/reports');
+        if (!fs.existsSync(outDir))
+            fs.mkdirSync(outDir, { recursive: true });
+        const filename = path.join(outDir, `${path.basename(filePath)}.report.json`);
+        fs.writeFileSync(filename, JSON.stringify(report, null, 2), 'utf8');
+    }
+    catch (e) {
+        // swallow
+    }
+    return report;
+}
+//# sourceMappingURL=fileRunner.js.map

package/lib/esm/tools/ast-jsdoc-tools/fileRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileRunner.js","sourceRoot":"","sources":["../../../../src/tools/ast-jsdoc-tools/fileRunner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,oBAAiB;AAC7C,OAAO,EAAE,aAAa,EAAE,uBAAoB;AAC5C,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,IAAI,CAAC;AAUpB,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,QAAgB;IAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAC7C,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,MAAM,MAAM,GAAe;QACzB,QAAQ,EAAE,GAAG;QACb,UAAU,EAAE,OAAO;QACnB,WAAW;QACX,OAAO,EAAE,EAAE,YAAY,EAAE,OAAO,CAAC,MAAM,EAAE,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE;QACnF,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IAEF,6DAA6D;IAC7D,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,mCAAmC,CAAC,CAAC;QACjE,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;QAC7E,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACtE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,UAAU;IACZ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/lib/esm/tools/ast-jsdoc-tools/formatter.d.ts

@@ -0,0 +1,6 @@
+import { JSDocSuggestion } from './generator';
+/**
+ * Insert a JSDoc block before the first occurrence of the symbol name in the file content.
+ * This is a simplistic inserter for MVP purposes.
+ */
+export declare function applyJSDocToContent(content: string, suggestion: JSDocSuggestion, symbolName: string): string;

package/lib/esm/tools/ast-jsdoc-tools/formatter.js

@@ -0,0 +1,18 @@
+/**
+ * Insert a JSDoc block before the first occurrence of the symbol name in the file content.
+ * This is a simplistic inserter for MVP purposes.
+ */
+export function applyJSDocToContent(content, suggestion, symbolName) {
+    const lines = content.split(/\r?\n/);
+    // Find line index where symbol is declared (very naive: first line that contains `function ${symbolName}` or `export const ${symbolName}`)
+    const idx = lines.findIndex(l => l.includes(`function ${symbolName}`) || l.includes(`export function ${symbolName}`) || l.includes(`const ${symbolName}`) || l.includes(`export const ${symbolName}`));
+    const jsLines = suggestion.text.split(/\r?\n/);
+    if (idx === -1) {
+        // Append at top
+        return [...jsLines, '', ...lines].join('\n');
+    }
+    const before = lines.slice(0, idx);
+    const after = lines.slice(idx);
+    return [...before, ...jsLines, ...after].join('\n');
+}
+//# sourceMappingURL=formatter.js.map

package/lib/esm/tools/ast-jsdoc-tools/formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../../../../src/tools/ast-jsdoc-tools/formatter.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe,EAAE,UAA2B,EAAE,UAAkB;IAClG,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrC,2IAA2I;IAC3I,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,mBAAmB,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,SAAS,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,gBAAgB,UAAU,EAAE,CAAC,CAAC,CAAC;IACvM,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;QACf,gBAAgB;QAChB,OAAO,CAAC,GAAG,OAAO,EAAE,EAAE,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC"}

package/lib/esm/tools/ast-jsdoc-tools/generator.d.ts

@@ -0,0 +1,12 @@
+import { ASTObject } from "./parser";
+export type JSDocSuggestion = {
+    id: string;
+    text: string;
+    tags: Array<{
+        tag: string;
+        name?: string;
+        description?: string;
+    }>;
+    confidence?: number;
+};
+export declare function generateJSDoc(obj: ASTObject): JSDocSuggestion;

package/lib/esm/tools/ast-jsdoc-tools/generator.js

@@ -0,0 +1,55 @@
+import { loadPromptTemplates } from "./prompts/loader.js";
+function renderTemplate(tpl, ctx) {
+    // very small and safe interpolation: replace {{key}} with ctx[key]
+    return tpl.replace(/{{\s*([a-zA-Z0-9_]+)\s*}}/g, (_, k) => {
+        return String(ctx[k] ?? "");
+    });
+}
+export function generateJSDoc(obj) {
+    // Try to load prompt templates from the specs folder and use a matching template
+    const templates = loadPromptTemplates();
+    const ctx = {
+        name: obj.name || "",
+        signature: obj.signature || "",
+    };
+    // pick priority: function.template, default.template, first available
+    const preferredIds = ["function", "default", "jsdoc", "summary"];
+    let tpl = "";
+    for (const id of preferredIds) {
+        const t = templates.find((x) => x.id === id || x.fileName === `${id}.md` || x.fileName === `${id}.template`);
+        if (t) {
+            tpl = t.content;
+            break;
+        }
+    }
+    if (!tpl && templates.length)
+        tpl = templates[0].content;
+    if (tpl) {
+        // Only treat the found file as a template if it looks like a template or a JSDoc snippet.
+        const looksLikeTemplate = /{{|\/\*\*|@param/.test(tpl);
+        if (looksLikeTemplate) {
+            const text = renderTemplate(tpl, ctx);
+            return { id: obj.id, text, tags: [], confidence: 0.7 };
+        }
+        // otherwise ignore README-like files and fall through to heuristic
+    }
+    // Fallback: simple heuristic generation
+    const summary = obj.signature ? `Summary: ${obj.signature.split("\n")[0]}` : `Summary for ${obj.name}`;
+    const tags = [];
+    const paramMatch = obj.signature ? obj.signature.match(/\(([^)]*)\)/) : null;
+    if (paramMatch && paramMatch[1].trim()) {
+        const parts = paramMatch[1].split(",").map((p) => p.trim()).filter(Boolean);
+        for (const p of parts) {
+            const name = p.split(":")[0].replace(/[^a-zA-Z0-9_]/g, "");
+            if (name)
+                tags.push({ tag: "param", name, description: "" });
+        }
+    }
+    const textLines = ["/**", ` * ${summary}`];
+    for (const t of tags) {
+        textLines.push(` * @${t.tag} ${t.name} ${t.description}`.trim());
+    }
+    textLines.push(" */");
+    return { id: obj.id, text: textLines.join("\n"), tags, confidence: 0.5 };
+}
+//# sourceMappingURL=generator.js.map

package/lib/esm/tools/ast-jsdoc-tools/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.js","sourceRoot":"","sources":["../../../../src/tools/ast-jsdoc-tools/generator.ts"],"names":[],"mappings":"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"}

package/lib/esm/tools/ast-jsdoc-tools/index.d.ts

@@ -0,0 +1,7 @@
+import { ToolBuilder } from "../../builders/tool-builder";
+/**
+ * Minimal analyzeFile helper used by other tools (placeholder for real implementation).
+ * Returns an object compatible with the feature's data-model (FileReport-like).
+ */
+export declare function analyzeFile(_filePath: string): Promise<any>;
+export declare const AstJsdocTool: ToolBuilder;

package/lib/esm/tools/ast-jsdoc-tools/index.js

@@ -0,0 +1,29 @@
+import { ToolBuilder } from "./../../builders/tool-builder.js";
+import { z } from "zod";
+import { ReasoningLevel, EffortLevel, Cost } from "./../../constants.js";
+/**
+ * Minimal analyzeFile helper used by other tools (placeholder for real implementation).
+ * Returns an object compatible with the feature's data-model (FileReport-like).
+ */
+export async function analyzeFile(_filePath) {
+    return { astObjects: [] };
+}
+export const AstJsdocTool = ToolBuilder.builder
+    .setName("ast.jsdoc")
+    .setTitle("AST → JSDoc Tool")
+    .setDescription("Generate suggested JSDoc comments for TypeScript AST objects (MVP stub).")
+    .setInputSchema(z.object({ filePath: z.string() }))
+    .setCb(async (_args, _extra) => {
+    // Lightweight stub implementation — real implementation lives under src/tools/ast-jsdoc-tools/*
+    const content = [{ type: "text", text: "Not implemented (stub)" }];
+    return {
+        // human-readable content
+        content,
+        // structuredContent matches the declared outputSchema: { content: array }
+        structuredContent: { content },
+    };
+})
+    .setReasoning(ReasoningLevel.BASIC)
+    .setEffort(EffortLevel.LOW)
+    .setCost(Cost.FREE);
+//# sourceMappingURL=index.js.map

package/lib/esm/tools/ast-jsdoc-tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/tools/ast-jsdoc-tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,yCAAoC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,6BAAwB;AAOpE;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,SAAiB;IACjD,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC,OAAO;KAC5C,OAAO,CAAC,WAAW,CAAC;KACpB,QAAQ,CAAC,kBAAkB,CAAC;KAC5B,cAAc,CAAC,0EAA0E,CAAC;KAC1F,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;KAClD,KAAK,CAAC,KAAK,EAAE,KAAU,EAAE,MAA8D,EAAE,EAAE;IAC1F,gGAAgG;IAChG,MAAM,OAAO,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,wBAAwB,EAAE,CAAC,CAAC;IACnE,OAAO;QACL,yBAAyB;QACzB,OAAO;QACP,0EAA0E;QAC1E,iBAAiB,EAAE,EAAE,OAAO,EAAE;KACxB,CAAC;AACX,CAAC,CAAC;KACD,YAAY,CAAC,cAAc,CAAC,KAAK,CAAC;KAClC,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC;KAC1B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC"}

package/lib/esm/tools/ast-jsdoc-tools/interactive.d.ts

@@ -0,0 +1 @@
+export declare function interactiveAnalyze(filePath: string): Promise<import("./fileRunner").FileReport>;

package/lib/esm/tools/ast-jsdoc-tools/interactive.js

@@ -0,0 +1,7 @@
+import { runFile } from "./fileRunner.js";
+export async function interactiveAnalyze(filePath) {
+    // For MVP: return the file report so callers can present suggestions.
+    const report = await runFile(filePath);
+    return report;
+}
+//# sourceMappingURL=interactive.js.map

package/lib/esm/tools/ast-jsdoc-tools/interactive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive.js","sourceRoot":"","sources":["../../../../src/tools/ast-jsdoc-tools/interactive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,wBAAqB;AAEvC,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,QAAgB;IACvD,sEAAsE;IACtE,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/lib/esm/tools/ast-jsdoc-tools/parser.d.ts

@@ -0,0 +1,13 @@
+export type ASTObject = {
+    id: string;
+    name: string;
+    kind: string;
+    location: {
+        filePath: string;
+        startLine: number;
+        startColumn: number;
+    };
+    isExported: boolean;
+    signature?: string;
+};
+export declare function extractAstObjects(filePath: string): Promise<ASTObject[]>;

package/lib/esm/tools/ast-jsdoc-tools/parser.js

@@ -0,0 +1,71 @@
+import { Project } from "ts-morph";
+import path from "path";
+import fs from "fs";
+export async function extractAstObjects(filePath) {
+    // debug removed in final implementation
+    const project = new Project({ tsConfigFilePath: path.resolve("tsconfig.json") });
+    let sourceFile = project.addSourceFileAtPathIfExists(filePath);
+    if (!sourceFile) {
+        // fallback: read file contents and create source file in-memory
+        try {
+            const contents = fs.readFileSync(filePath, "utf8");
+            sourceFile = project.createSourceFile(filePath, contents, { overwrite: true });
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.log(`extractAstObjects: failed to read/create source file for ${filePath}: ${e}`);
+            return [];
+        }
+    }
+    // parsing completed
+    const objects = [];
+    // Functions
+    for (const fn of sourceFile.getFunctions()) {
+        const name = fn.getName() || "<anonymous>";
+        const isExported = fn.isExported();
+        const start = fn.getStartLineNumber();
+        const col = fn.getStart() ? sourceFile.getLineAndColumnAtPos(fn.getStart()).column : 1;
+        objects.push({
+            id: `${filePath}::${name}`,
+            name,
+            kind: "function",
+            location: { filePath, startLine: start, startColumn: col },
+            isExported,
+            signature: fn.getText(),
+        });
+    }
+    // Classes
+    for (const cls of sourceFile.getClasses()) {
+        const name = cls.getName() || "<anonymous>";
+        const isExported = cls.isExported();
+        const start = cls.getStartLineNumber();
+        const col = cls.getStart() ? sourceFile.getLineAndColumnAtPos(cls.getStart()).column : 1;
+        objects.push({
+            id: `${filePath}::${name}`,
+            name,
+            kind: "class",
+            location: { filePath, startLine: start, startColumn: col },
+            isExported,
+            signature: cls.getText(),
+        });
+    }
+    // Variable statements (consts/exports)
+    for (const vs of sourceFile.getVariableStatements()) {
+        const isExported = vs.isExported();
+        for (const decl of vs.getDeclarations()) {
+            const name = decl.getName();
+            const start = decl.getStartLineNumber();
+            const col = decl.getStart() ? sourceFile.getLineAndColumnAtPos(decl.getStart()).column : 1;
+            objects.push({
+                id: `${filePath}::${name}`,
+                name,
+                kind: "variable",
+                location: { filePath, startLine: start, startColumn: col },
+                isExported,
+                signature: decl.getText(),
+            });
+        }
+    }
+    return objects;
+}
+//# sourceMappingURL=parser.js.map

package/lib/esm/tools/ast-jsdoc-tools/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../../../src/tools/ast-jsdoc-tools/parser.ts"],"names":[],"mappings":"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"}

package/lib/esm/tools/ast-jsdoc-tools/patch.d.ts

@@ -0,0 +1,2 @@
+import { JSDocSuggestion } from './generator';
+export declare function writePatchForFile(filePath: string, suggestions: JSDocSuggestion[]): string;

package/lib/esm/tools/ast-jsdoc-tools/patch.js

@@ -0,0 +1,23 @@
+import fs from 'fs';
+import path from 'path';
+import { applyJSDocToContent } from "./formatter.js";
+export function writePatchForFile(filePath, suggestions) {
+    const abs = path.resolve(filePath);
+    const original = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : '';
+    let patched = original;
+    for (const s of suggestions) {
+        const symbol = (s.id && s.id.split('::')[1]) || '';
+        patched = applyJSDocToContent(patched, s, symbol);
+    }
+    // simple unified-ish patch: header + original/new
+    const header = `--- a/${path.basename(filePath)}\n+++ b/${path.basename(filePath)}\n`;
+    const body = `@@\n- Original:\n${original.split('\n').slice(0, 20).join('\n')}\n+ Patched:\n${patched.split('\n').slice(0, 20).join('\n')}\n`;
+    const out = header + body;
+    const outDir = path.resolve('specs/001-ast-jsdoc-tools/reports/patches');
+    if (!fs.existsSync(outDir))
+        fs.mkdirSync(outDir, { recursive: true });
+    const fileName = path.join(outDir, `${path.basename(filePath)}.patch`);
+    fs.writeFileSync(fileName, out, 'utf8');
+    return fileName;
+}
+//# sourceMappingURL=patch.js.map

package/lib/esm/tools/ast-jsdoc-tools/patch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch.js","sourceRoot":"","sources":["../../../../src/tools/ast-jsdoc-tools/patch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,OAAO,EAAE,mBAAmB,EAAE,uBAAoB;AAElD,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,WAA8B;IAChF,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACxE,IAAI,OAAO,GAAG,QAAQ,CAAC;IACvB,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACnD,OAAO,GAAG,mBAAmB,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IACpD,CAAC;IAED,kDAAkD;IAClD,MAAM,MAAM,GAAG,SAAS,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;IACtF,MAAM,IAAI,GAAG,oBAAoB,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IAC5I,MAAM,GAAG,GAAG,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,2CAA2C,CAAC,CAAC;IACzE,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACvE,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/lib/esm/tools/ast-jsdoc-tools/prompts/loader.d.ts

@@ -0,0 +1,10 @@
+export type PromptTemplate = {
+    id: string;
+    fileName: string;
+    content: string;
+};
+/**
+ * Load all prompt templates from the feature specs prompts folder.
+ * Returns an array of PromptTemplate objects.
+ */
+export declare function loadPromptTemplates(baseDir?: string): PromptTemplate[];

package/lib/esm/tools/ast-jsdoc-tools/prompts/loader.js

@@ -0,0 +1,26 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Load all prompt templates from the feature specs prompts folder.
+ * Returns an array of PromptTemplate objects.
+ */
+export function loadPromptTemplates(baseDir) {
+    const repoRoot = process.cwd();
+    const dir = path.resolve(baseDir || path.join(repoRoot, 'specs/001-ast-jsdoc-tools/prompts'));
+    if (!fs.existsSync(dir))
+        return [];
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.md') || f.endsWith('.txt') || f.endsWith('.template'));
+    const templates = [];
+    for (const f of files) {
+        try {
+            const filePath = path.join(dir, f);
+            const content = fs.readFileSync(filePath, 'utf8');
+            templates.push({ id: f.replace(/\.[^.]+$/, ''), fileName: f, content });
+        }
+        catch (e) {
+            // skip
+        }
+    }
+    return templates;
+}
+//# sourceMappingURL=loader.js.map

package/lib/esm/tools/ast-jsdoc-tools/prompts/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../../../../src/tools/ast-jsdoc-tools/prompts/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAQxB;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAClD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,mCAAmC,CAAC,CAAC,CAAC;IAC9F,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAEnC,MAAM,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;IAClH,MAAM,SAAS,GAAqB,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACnC,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAClD,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QAC1E,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO;QACT,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/lib/esm/tools/ast-jsdoc-tools/repoRunner.d.ts

@@ -0,0 +1,16 @@
+export type RepositoryRunReport = {
+    runId: string;
+    rootPath: string;
+    filesProcessed: number;
+    suggestionsTotal: number;
+    changedFiles: string[];
+    errors: {
+        filePath: string;
+        error: string;
+    }[];
+    startedAt: string;
+    finishedAt?: string;
+};
+export declare function runRepository(rootPath?: string, options?: {
+    dryRun?: boolean;
+}): Promise<RepositoryRunReport>;

package/lib/esm/tools/ast-jsdoc-tools/repoRunner.js

@@ -0,0 +1,61 @@
+import { listSourceFiles } from "./enumerator.js";
+import { runFile } from "./fileRunner.js";
+import { applySuggestionsToFile } from "./apply.js";
+import { writePatchForFile } from "./patch.js";
+import fs from 'fs';
+import path from 'path';
+import { v4 as uuidv4 } from 'uuid';
+export async function runRepository(rootPath = '.', options = { dryRun: true }) {
+    const startedAt = new Date().toISOString();
+    const runId = uuidv4();
+    const files = await listSourceFiles(rootPath);
+    const report = {
+        runId,
+        rootPath: path.resolve(rootPath),
+        filesProcessed: 0,
+        suggestionsTotal: 0,
+        changedFiles: [],
+        errors: [],
+        startedAt,
+    };
+    for (const f of files) {
+        try {
+            const fr = await runFile(f);
+            report.filesProcessed += 1;
+            report.suggestionsTotal += (fr.suggestions || []).length;
+            if (!options.dryRun && fr.suggestions && fr.suggestions.length) {
+                try {
+                    // apply changes in-place and write patch report
+                    const res = applySuggestionsToFile(f, fr.suggestions);
+                    report.changedFiles.push(f);
+                    try {
+                        writePatchForFile(f, fr.suggestions);
+                    }
+                    catch (e) {
+                        // non-fatal
+                    }
+                }
+                catch (e) {
+                    report.errors.push({ filePath: f, error: `apply failed: ${String(e)}` });
+                }
+            }
+        }
+        catch (e) {
+            report.errors.push({ filePath: f, error: String(e) });
+        }
+    }
+    report.finishedAt = new Date().toISOString();
+    // persist run report
+    try {
+        const outDir = path.resolve('specs/001-ast-jsdoc-tools/reports');
+        if (!fs.existsSync(outDir))
+            fs.mkdirSync(outDir, { recursive: true });
+        const filename = path.join(outDir, `${runId}.repo.json`);
+        fs.writeFileSync(filename, JSON.stringify(report, null, 2), 'utf8');
+    }
+    catch (e) {
+        // ignore
+    }
+    return report;
+}
+//# sourceMappingURL=repoRunner.js.map

package/lib/esm/tools/ast-jsdoc-tools/repoRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repoRunner.js","sourceRoot":"","sources":["../../../../src/tools/ast-jsdoc-tools/repoRunner.ts"],"names":[],"mappings":"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"}

package/lib/esm/tools/ast-jsdoc-tools/tools/jsdoc-generator.d.ts

@@ -0,0 +1,5 @@
+export declare function generateForObject(obj: any): {
+    suggestedDoc: string;
+    needsReview?: boolean;
+};
+export default generateForObject;

package/lib/esm/tools/ast-jsdoc-tools/tools/jsdoc-generator.js

@@ -0,0 +1,78 @@
+function paramListFromSignature(sig) {
+    const m = sig.match(/\(([^)]*)\)/);
+    if (!m)
+        return [];
+    const inside = m[1].trim();
+    if (!inside)
+        return [];
+    return inside.split(',').map((s) => s.split(':')[0].trim().replace(/[\s=].*$/, ''));
+}
+export function generateForObject(obj) {
+    const kind = (obj.kind || '').toLowerCase();
+    const sig = obj.signature || obj.signature === '' ? obj.signature : '';
+    let needsReview = false;
+    let lines = [];
+    if (kind === 'function' || kind === 'functiondeclaration' || kind === 'functionexpression') {
+        if (!sig)
+            needsReview = true;
+        const params = paramListFromSignature(sig);
+        lines.push('/**');
+        lines.push(` * Function: ${obj.name || 'function'}`);
+        for (const p of params)
+            lines.push(` * @param ${p} `);
+        const ret = sig.match(/:\s*([^\)\s]+)\s*$/);
+        if (ret)
+            lines.push(` * @returns ${ret[1]}`);
+        if (needsReview)
+            lines.push(` * TODO: Describe ${obj.name || 'function'}`);
+        lines.push(' */');
+        return { suggestedDoc: lines.join('\n'), needsReview };
+    }
+    if (kind === 'class') {
+        // try to parse constructor params
+        const params = paramListFromSignature(sig);
+        lines.push('/**');
+        lines.push(` * Class: ${obj.name}`);
+        for (const p of params)
+            lines.push(` * @param ${p} `);
+        lines.push(' */');
+        return { suggestedDoc: lines.join('\n') };
+    }
+    if (kind === 'type' || kind === 'interface') {
+        // crude property listing
+        const props = (sig.match(/\{([^}]*)\}/) || [])[1] || '';
+        const parts = props.split(';').map((s) => s.trim()).filter(Boolean);
+        lines.push('/**');
+        lines.push(` * Type: ${obj.name}`);
+        for (const part of parts) {
+            const name = (part.split(':')[0] || '').trim();
+            if (name)
+                lines.push(` * @property ${name}`);
+        }
+        lines.push(' */');
+        return { suggestedDoc: lines.join('\n') };
+    }
+    if (kind === 'enum') {
+        const members = (sig.match(/\{([^}]*)\}/) || [])[1] || '';
+        const parts = members.split(',').map((s) => s.trim()).filter(Boolean);
+        lines.push('/**');
+        lines.push(` * Enum: ${obj.name}`);
+        for (const p of parts) {
+            const m = p.split('=')[0].trim();
+            if (m)
+                lines.push(` * @enum ${m}`);
+        }
+        lines.push(' */');
+        return { suggestedDoc: lines.join('\n') };
+    }
+    if (kind === 'constant' || kind === 'variable') {
+        lines.push('/**');
+        lines.push(` * constant: ${obj.name}`);
+        lines.push(' */');
+        return { suggestedDoc: lines.join('\n') };
+    }
+    // default fallback
+    return { suggestedDoc: `/**\n * TODO: Describe ${obj.name || 'item'}\n */`, needsReview: true };
+}
+export default generateForObject;
+//# sourceMappingURL=jsdoc-generator.js.map