mcp-code-context 3.9.2 → 7.0.1

package/dist/src/operations/circularDependencies.js

@@ -0,0 +1,201 @@
+/**
+ * AST Circular Import Cycle Detector (Tarjan's SCC Algorithm)
+ * v7.0.1 Enterprise AST Intelligence
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { existsSync } from "node:fs";
+import { ParserRegistry } from "../parsers/registry.js";
+import { CodeContextEngine } from "../core/engine.js";
+/**
+ * Extracts imported relative module paths from AST
+ */
+function extractRelativeImports(rootNode) {
+    const imports = [];
+    function walk(n) {
+        // import ... from './x'
+        if (n.type === "import_statement") {
+            const srcNode = n.childForFieldName("source");
+            if (srcNode) {
+                const raw = srcNode.text.replace(/^["']|["']$/g, "");
+                if (raw.startsWith("."))
+                    imports.push(raw);
+            }
+        }
+        // require('./x')
+        if (n.type === "call_expression") {
+            const fn = n.childForFieldName("function")?.text;
+            if (fn === "require") {
+                const arg = n.childForFieldName("arguments")?.namedChild(0)?.text;
+                if (arg) {
+                    const raw = arg.replace(/^["']|["']$/g, "");
+                    if (raw.startsWith("."))
+                        imports.push(raw);
+                }
+            }
+        }
+        for (let i = 0; i < n.namedChildCount; i++) {
+            const child = n.namedChild(i);
+            if (child)
+                walk(child);
+        }
+    }
+    walk(rootNode);
+    return imports;
+}
+/**
+ * Normalizes an imported path against its parent file
+ */
+function resolveImportPath(parentFile, importPath) {
+    const dir = path.dirname(parentFile);
+    let resolved = path.join(dir, importPath).replace(/\\/g, "/");
+    // Normalize extensions
+    if (resolved.endsWith(".js"))
+        resolved = resolved.slice(0, -3);
+    if (resolved.endsWith(".ts"))
+        resolved = resolved.slice(0, -3);
+    return resolved;
+}
+/**
+ * Tarjan's Strongly Connected Components algorithm for finding cycles
+ */
+function findCyclesTarjan(adjList) {
+    let index = 0;
+    const indices = new Map();
+    const lowlinks = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    function strongConnect(u) {
+        indices.set(u, index);
+        lowlinks.set(u, index);
+        index++;
+        stack.push(u);
+        onStack.add(u);
+        const neighbors = adjList.get(u) || [];
+        for (const v of neighbors) {
+            if (!indices.has(v)) {
+                strongConnect(v);
+                lowlinks.set(u, Math.min(lowlinks.get(u), lowlinks.get(v)));
+            }
+            else if (onStack.has(v)) {
+                lowlinks.set(u, Math.min(lowlinks.get(u), indices.get(v)));
+            }
+        }
+        if (lowlinks.get(u) === indices.get(u)) {
+            const scc = [];
+            let w = "";
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                scc.push(w);
+            } while (w !== u);
+            // A component with > 1 node or a self-loop is a cycle
+            if (scc.length > 1) {
+                sccs.push(scc.reverse());
+            }
+            else if (scc.length === 1 && (adjList.get(scc[0]) || []).includes(scc[0])) {
+                sccs.push([scc[0], scc[0]]);
+            }
+        }
+    }
+    for (const node of adjList.keys()) {
+        if (!indices.has(node)) {
+            strongConnect(node);
+        }
+    }
+    return sccs;
+}
+/**
+ * Detects circular import dependencies across codebase
+ */
+export async function detectCircularDependencies(params) {
+    const projectRoot = params.projectRoot || ".";
+    try {
+        let registry = params.registry;
+        if (!registry) {
+            const engine = new CodeContextEngine();
+            await engine.init();
+            registry = new ParserRegistry(engine);
+            await registry.init();
+        }
+        const parser = registry.getParser(".ts");
+        if (!parser) {
+            return {
+                success: false,
+                error: "No TypeScript parser available for dependency analysis",
+            };
+        }
+        const filesToAnalyze = new Map();
+        if (params.filesMap) {
+            for (const [f, c] of Object.entries(params.filesMap)) {
+                let norm = f.replace(/\\/g, "/");
+                if (norm.endsWith(".ts"))
+                    norm = norm.slice(0, -3);
+                if (norm.endsWith(".js"))
+                    norm = norm.slice(0, -3);
+                filesToAnalyze.set(norm, c);
+            }
+        }
+        else if (params.filePaths) {
+            for (const f of params.filePaths) {
+                if (existsSync(f)) {
+                    const content = await fs.readFile(f, "utf-8");
+                    let norm = path.relative(projectRoot, f).replace(/\\/g, "/");
+                    if (norm.endsWith(".ts"))
+                        norm = norm.slice(0, -3);
+                    if (norm.endsWith(".js"))
+                        norm = norm.slice(0, -3);
+                    filesToAnalyze.set(norm, content);
+                }
+            }
+        }
+        const adjList = new Map();
+        for (const [fileKey, content] of filesToAnalyze.entries()) {
+            let tree = null;
+            try {
+                tree = parser.parse(content);
+                const rawImports = extractRelativeImports(tree.rootNode);
+                const resolved = rawImports.map(imp => resolveImportPath(fileKey, imp));
+                adjList.set(fileKey, resolved.filter(r => filesToAnalyze.has(r)));
+            }
+            finally {
+                if (tree) {
+                    try {
+                        tree.delete();
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            }
+        }
+        const sccs = findCyclesTarjan(adjList);
+        const cycles = sccs.map(scc => {
+            const cycleLoop = [...scc, scc[0]];
+            return {
+                cycleLength: scc.length,
+                cyclePath: cycleLoop,
+                recommendation: `Break circular dependency: Extract shared interfaces or types from '${scc[0]}' into a separate 'types.ts' module or inject dependency.`,
+            };
+        });
+        const report = {
+            projectRoot,
+            totalFilesAnalyzed: filesToAnalyze.size,
+            totalCyclesFound: cycles.length,
+            cycles,
+            summary: `Analyzed ${filesToAnalyze.size} modules. Found ${cycles.length} circular dependency cycles.`,
+        };
+        return {
+            success: true,
+            content: JSON.stringify(report, null, 2),
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `detect_circular_dependencies failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+//# sourceMappingURL=circularDependencies.js.map

package/dist/src/operations/circularDependencies.js.map

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

package/dist/src/operations/classHierarchyFlattener.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Trait, Mixin & Inheritance Class Hierarchy Flattener
+ * v7.0.1 Enterprise AST Intelligence
+ */
+import { ParserRegistry } from "../parsers/registry.js";
+import type { ReadResult } from "./readCore.js";
+export interface FlatClassMethod {
+    name: string;
+    source: "self" | "trait" | "parent";
+    originName: string;
+    visibility: "public" | "protected" | "private";
+    isStatic: boolean;
+    signature: string;
+    line?: number;
+}
+export interface FlattenedClassReport {
+    className: string;
+    parentClass?: string;
+    traitsUsed: string[];
+    totalMethods: number;
+    methods: FlatClassMethod[];
+    summary: string;
+}
+export interface ClassFlattenerOptions {
+    filePath?: string;
+    className?: string;
+    code?: string;
+    content?: string;
+    projectRoot?: string;
+    registry?: ParserRegistry;
+}
+/**
+ * Flattens class traits, mixins and methods
+ */
+export declare function flattenClassHierarchy(params: ClassFlattenerOptions): Promise<ReadResult>;

package/dist/src/operations/classHierarchyFlattener.js

@@ -0,0 +1,185 @@
+/**
+ * Trait, Mixin & Inheritance Class Hierarchy Flattener
+ * v7.0.1 Enterprise AST Intelligence
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { existsSync } from "node:fs";
+import { ParserRegistry } from "../parsers/registry.js";
+import { CodeContextEngine } from "../core/engine.js";
+/**
+ * Parses method declarations from a class or trait body
+ */
+function extractClassMethods(bodyNode, source, originName) {
+    const methods = [];
+    for (let i = 0; i < bodyNode.namedChildCount; i++) {
+        const m = bodyNode.namedChild(i);
+        if (!m)
+            continue;
+        if (m.type === "method_declaration" ||
+            m.type === "method_definition" ||
+            m.type === "function_definition") {
+            const name = m.childForFieldName("name")?.text || "anonymous";
+            const text = m.text;
+            let visibility = "public";
+            if (text.includes("private "))
+                visibility = "private";
+            else if (text.includes("protected "))
+                visibility = "protected";
+            const isStatic = text.includes("static ");
+            const firstLine = text.split("\n")[0].replace(/\{.*$/, "").trim();
+            methods.push({
+                name,
+                source,
+                originName,
+                visibility,
+                isStatic,
+                signature: firstLine,
+                line: m.startPosition.row + 1,
+            });
+        }
+    }
+    return methods;
+}
+/**
+ * Flattens class traits, mixins and methods
+ */
+export async function flattenClassHierarchy(params) {
+    let tree = null;
+    try {
+        const targetPath = params.filePath || "in_memory.php";
+        let content = params.code ?? params.content;
+        if (content === undefined) {
+            if (params.filePath && existsSync(params.filePath)) {
+                content = await fs.readFile(params.filePath, "utf-8");
+            }
+            else {
+                return {
+                    success: false,
+                    error: `File does not exist: ${params.filePath || "none"}`,
+                };
+            }
+        }
+        const ext = path.extname(targetPath).toLowerCase();
+        let registry = params.registry;
+        if (!registry) {
+            const engine = new CodeContextEngine();
+            await engine.init();
+            registry = new ParserRegistry(engine);
+            await registry.init();
+        }
+        const parser = registry.getParser(ext === ".php" ? ".php" : ext === ".py" ? ".py" : ".ts");
+        if (!parser) {
+            return {
+                success: false,
+                error: `No parser available for extension: ${ext}`,
+            };
+        }
+        tree = parser.parse(content);
+        // Locate target class
+        let classNode = null;
+        let resolvedClassName = params.className || "UnknownClass";
+        let parentClass = undefined;
+        const traitsUsed = [];
+        function findClass(n) {
+            if (n.type === "class_declaration" ||
+                n.type === "class_definition") {
+                const nameNode = n.childForFieldName("name");
+                if (!params.className || nameNode?.text === params.className) {
+                    classNode = n;
+                    resolvedClassName = nameNode?.text || resolvedClassName;
+                    return;
+                }
+            }
+            for (let i = 0; i < n.namedChildCount; i++) {
+                if (!classNode) {
+                    const child = n.namedChild(i);
+                    if (child)
+                        findClass(child);
+                }
+            }
+        }
+        findClass(tree.rootNode);
+        if (!classNode) {
+            return {
+                success: false,
+                error: `Class '${params.className || "first"}' not found in AST.`,
+            };
+        }
+        const targetClass = classNode;
+        // Check base class (extends)
+        const baseNode = targetClass.childForFieldName("base") || targetClass.childForFieldName("superclasses");
+        if (baseNode) {
+            parentClass = baseNode.text.replace(/^extends\s+/i, "");
+        }
+        const classBody = targetClass.childForFieldName("body") || targetClass.namedChild(targetClass.namedChildCount - 1);
+        const methods = [];
+        if (classBody) {
+            // 1. Detect trait usages: use PluginManagementTrait, ThemeManagementTrait;
+            for (let i = 0; i < classBody.namedChildCount; i++) {
+                const child = classBody.namedChild(i);
+                if (!child)
+                    continue;
+                if (child.type === "use_declaration" || child.text.startsWith("use ")) {
+                    // Extract trait names from use statement
+                    const traitMatches = child.text.replace(/^use\s+/, "").replace(/;.*$/, "").split(",");
+                    for (const rawTrait of traitMatches) {
+                        const cleanTrait = rawTrait.trim();
+                        if (cleanTrait)
+                            traitsUsed.push(cleanTrait);
+                    }
+                }
+            }
+            // 2. Extract self methods
+            const selfMethods = extractClassMethods(classBody, "self", resolvedClassName);
+            methods.push(...selfMethods);
+        }
+        // 3. Synthesize virtual trait methods if defined in same file
+        for (const traitName of traitsUsed) {
+            function findTrait(n) {
+                if (n.type === "trait_declaration" && n.childForFieldName("name")?.text === traitName) {
+                    const traitBody = n.childForFieldName("body") || n.namedChild(n.namedChildCount - 1);
+                    if (traitBody) {
+                        const traitMethods = extractClassMethods(traitBody, "trait", traitName);
+                        methods.push(...traitMethods);
+                    }
+                }
+                for (let i = 0; i < n.namedChildCount; i++) {
+                    const child = n.namedChild(i);
+                    if (child)
+                        findTrait(child);
+                }
+            }
+            findTrait(tree.rootNode);
+        }
+        const report = {
+            className: resolvedClassName,
+            parentClass,
+            traitsUsed,
+            totalMethods: methods.length,
+            methods,
+            summary: `Flattened class '${resolvedClassName}'. Uses ${traitsUsed.length} traits. Total resolved methods: ${methods.length}.`,
+        };
+        return {
+            success: true,
+            content: JSON.stringify(report, null, 2),
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `flatten_class_hierarchy failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    finally {
+        if (tree) {
+            try {
+                tree.delete();
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+}
+//# sourceMappingURL=classHierarchyFlattener.js.map

package/dist/src/operations/classHierarchyFlattener.js.map

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

package/dist/src/operations/compress.d.ts

@@ -1,5 +1,5 @@
 /**
- * Semantic Compression - v3.9.2
+ * Semantic Compression - v7.0.1
  * IMPROVEMENTS: Centralized constants + size limits + timeout + index feeding
  */
 import { ParserRegistry } from "../parsers/registry.js";
@@ -14,7 +14,7 @@ export interface CompressionResult {
 declare function compressRepository(params: {
     directoryPath: string;
     projectRoot: string;
-    format?: "xml" | "markdown";
+    format?: "xml" | "markdown" | "html";
     registry: ParserRegistry;
     maxDepth?: number;
     includeSymbols?: boolean;

package/dist/src/operations/compress.js

@@ -1,5 +1,5 @@
 /**
- * Semantic Compression - v3.9.2
+ * Semantic Compression - v7.0.1
  * IMPROVEMENTS: Centralized constants + size limits + timeout + index feeding
  */
 import * as fs from "node:fs/promises";
@@ -8,7 +8,8 @@ import * as crypto from "node:crypto";
 import { EXCLUDE_DIRS, MAX_FILES_REPO_MAP, MAX_TOTAL_SIZE_BYTES } from "../utils/constants.js";
 import { walkDir } from "../utils/fileWalker.js";
 import { IndexManager } from "../core/indexManager.js";
-import { loadRailsSchema, modelToTable, findRailsConcerns } from "../utils/railsSchema.js";
+import { modelToTable, findRailsConcerns } from "../utils/railsSchema.js";
+import { loadUnifiedVirtualSchema } from "../utils/virtualSchema.js";
 import { parseGemfile } from "../utils/gemfileParser.js";
 /**
  * Generate semantic repository map
@@ -36,31 +37,42 @@ async function compressRepository(params) {
                             .update(content)
                             .digest("hex");
                         const symbols = await (async () => {
-                            // Skip re-parsing if index is up to date
-                            if (!(await indexManager.isStale(fullPath, fileHash))) {
-                                const tree = parser.parse(content);
-                                return parser.findSymbols(tree);
+                            let tree;
+                            try {
+                                tree = parser.parse(content);
+                                const syms = parser.findSymbols(tree);
+                                // Skip re-indexing if index is up to date
+                                if (await indexManager.isStale(fullPath, fileHash)) {
+                                    // Extract import dependencies
+                                    const deps = extractImports(content, fullPath, params.directoryPath);
+                                    // Feed index (fire-and-forget, never blocks the repo map)
+                                    indexManager.indexFile(fullPath, fileHash, syms, deps).catch(() => {
+                                        // Index feeding is fire-and-forget — never blocks repo map generation
+                                    });
+                                }
+                                return syms;
+                            }
+                            finally {
+                                try {
+                                    tree?.delete();
+                                }
+                                catch {
+                                    // Safe disposal of WASM tree
+                                }
                             }
-                            const tree = parser.parse(content);
-                            const syms = parser.findSymbols(tree);
-                            // Extract import dependencies
-                            const deps = extractImports(content, fullPath, params.directoryPath);
-                            // Feed index (fire-and-forget, never blocks the repo map)
-                            indexManager.indexFile(fullPath, fileHash, syms, deps).catch(() => {
-                                // Index feeding is fire-and-forget — never blocks repo map generation
-                            });
-                            return syms;
                         })();
                         totalSymbols += symbols.length;
-                        // R1: Rails AR schema injection for .rb files in repo map
+                        // R1: Virtual ORM schema injection for .rb, .php, .py, .ts, .tsx in repo map
                         let fileSymbols = symbols.map(s => ({ type: s.type, name: s.name }));
-                        if (path.extname(fullPath) === ".rb") {
-                            const schema = await loadRailsSchema(params.projectRoot).catch(() => null);
+                        const ext = path.extname(fullPath);
+                        if (ext === ".rb" || ext === ".php" || ext === ".py" || ext === ".ts" || ext === ".tsx") {
+                            const unified = await loadUnifiedVirtualSchema(params.projectRoot, ext).catch(() => null);
+                            const schema = unified?.schema;
                             if (schema) {
                                 for (const sym of symbols) {
-                                    if (sym.type === "class") {
+                                    if (sym.type === "class" || sym.type === "interface" || sym.type === "variable_declarator") {
                                         const tableName = modelToTable(sym.name);
-                                        const columns = schema[tableName];
+                                        const columns = schema[tableName] || schema[sym.name.toLowerCase()] || schema[sym.name];
                                         if (columns && Object.keys(columns).length > 0) {
                                             const dbCols = Object.entries(columns).map(([col, type]) => ({
                                                 type: "db_column",
@@ -96,6 +108,128 @@ async function compressRepository(params) {
         const includeSymbols = params.includeSymbols !== false && files.length <= 100 && totalSymbols <= 1000;
         // Project-wide metadata: Gemfile + Concerns
         let projectMetadata = "";
+        if (format === "html") {
+            const escapedPath = params.directoryPath.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+            const filesJson = JSON.stringify(files.map(f => ({
+                path: f.path,
+                symbols: f.symbols
+            }))).replace(/</g, "\\u003c");
+            const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Architecture Map - ${escapedPath}</title>
+  <style>
+    :root {
+      --bg: #0f172a;
+      --card-bg: #1e293b;
+      --border: #334155;
+      --text: #f8fafc;
+      --text-muted: #94a3b8;
+      --accent: #f26419;
+      --badge-class: #38bdf8;
+      --badge-fn: #4ade80;
+      --badge-db: #f59e0b;
+      --badge-other: #a78bfa;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, monospace; }
+    body { background: var(--bg); color: var(--text); padding: 24px; }
+    header { margin-bottom: 24px; border-bottom: 1px solid var(--border); padding-bottom: 16px; }
+    h1 { font-size: 1.5rem; display: flex; align-items: center; gap: 10px; }
+    .badge { font-size: 0.75rem; padding: 2px 8px; border-radius: 9999px; background: var(--accent); color: white; font-weight: bold; }
+    .stats { display: flex; gap: 16px; margin-top: 12px; font-size: 0.875rem; color: var(--text-muted); }
+    .stat-val { color: var(--text); font-weight: bold; }
+    .controls { margin-bottom: 20px; display: flex; gap: 12px; }
+    input#search { flex: 1; padding: 10px 14px; background: var(--card-bg); border: 1px solid var(--border); border-radius: 8px; color: var(--text); font-size: 0.9rem; }
+    input#search:focus { outline: 2px solid var(--accent); border-color: transparent; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(360px, 1fr)); gap: 16px; }
+    .card { background: var(--card-bg); border: 1px solid var(--border); border-radius: 8px; padding: 16px; transition: border-color 0.2s; }
+    .card:hover { border-color: var(--accent); }
+    .card-path { font-weight: bold; font-size: 0.875rem; color: #38bdf8; word-break: break-all; margin-bottom: 8px; }
+    .symbols-list { display: flex; flex-wrap: wrap; gap: 6px; }
+    .sym-badge { font-size: 0.75rem; padding: 3px 6px; border-radius: 4px; background: #0f172a; border: 1px solid var(--border); }
+    .sym-class { border-color: var(--badge-class); color: var(--badge-class); }
+    .sym-function { border-color: var(--badge-fn); color: var(--badge-fn); }
+    .sym-db { border-color: var(--badge-db); color: var(--badge-db); }
+    .empty-note { font-size: 0.75rem; color: var(--text-muted); font-style: italic; }
+  </style>
+</head>
+<body>
+  <header>
+    <h1><span>Architecture & Semantic Repo Map</span> <span class="badge">v4.0.0 Enterprise</span></h1>
+    <div class="stats">
+      <div>Files: <span class="stat-val">${files.length}</span></div>
+      <div>Indexed Symbols: <span class="stat-val">${totalSymbols}</span></div>
+      <div>Path: <span class="stat-val">${escapedPath}</span></div>
+    </div>
+  </header>
+
+  <div class="controls">
+    <input type="text" id="search" placeholder="Filter files or symbols (e.g. User, Controller, handle, schema)..." autofocus>
+  </div>
+
+  <div class="grid" id="fileGrid"></div>
+
+  <script>
+    const files = ${filesJson};
+    const grid = document.getElementById("fileGrid");
+    const search = document.getElementById("search");
+
+    function render(list) {
+      grid.innerHTML = "";
+      if (list.length === 0) {
+        grid.innerHTML = '<div style="color: var(--text-muted); grid-column: 1/-1;">No matching files found.</div>';
+        return;
+      }
+      for (const f of list) {
+        const card = document.createElement("div");
+        card.className = "card";
+
+        const pathEl = document.createElement("div");
+        pathEl.className = "card-path";
+        pathEl.textContent = f.path;
+        card.appendChild(pathEl);
+
+        const symListEl = document.createElement("div");
+        symListEl.className = "symbols-list";
+
+        if (f.symbols.length > 0) {
+          for (const s of f.symbols) {
+            const badge = document.createElement("span");
+            const cls = s.type === "class" ? "sym-class" : s.type === "db_column" ? "sym-db" : "sym-function";
+            badge.className = "sym-badge " + cls;
+            badge.textContent = s.type + ": " + s.name;
+            symListEl.appendChild(badge);
+          }
+        } else {
+          const emptyNote = document.createElement("span");
+          emptyNote.className = "empty-note";
+          emptyNote.textContent = "No exported AST symbols";
+          symListEl.appendChild(emptyNote);
+        }
+
+        card.appendChild(symListEl);
+        grid.appendChild(card);
+      }
+    }
+
+    search.addEventListener("input", (e) => {
+      const q = e.target.value.toLowerCase().trim();
+      if (!q) { render(files); return; }
+      const filtered = files.filter(f => 
+        f.path.toLowerCase().includes(q) || 
+        f.symbols.some(s => s.name.toLowerCase().includes(q) || s.type.toLowerCase().includes(q))
+      );
+      render(filtered);
+    });
+
+    render(files);
+  </script>
+</body>
+</html>`;
+            return { success: true, content: html };
+        }
         if (format === "xml") {
             try {
                 const gemfileResult = await parseGemfile(params.projectRoot);