@doquflow/server 0.2.0 → 0.4.0

package/dist/extractor.js

@@ -48,6 +48,35 @@ const RE_PROCESS_ENV = /\bprocess\.env\.([A-Z_][A-Z0-9_]*)/g;
 const RE_DOTNET_ENV = /\bEnvironment\.GetEnvironmentVariable\(\s*["']([^"']+)["']/g;
 const RE_ICONFIG = /\bIConfiguration\b/g;
 const RE_APPSETTINGS = /\bappsettings(?:\.[A-Za-z0-9]+)?\.json\b/g;
+// ─── Go ─────────────────────────────────────────────────────────────────────
+// type FooBar struct | type FooBar interface
+const RE_GO_TYPE = /\btype\s+([A-Z]\w*)\s+(?:struct|interface)/g;
+// func FuncName( or func (recv *Type) MethodName(
+const RE_GO_FUNC = /\bfunc\s+(?:\([^)]+\)\s+)?([A-Za-z_]\w*)\s*\(/g;
+// import "pkg" or import ( "pkg" ) — individual quoted paths inside import blocks
+const RE_GO_IMPORT = /^\s+["']([^"'\s]+)["']\s*(?:\/\/.*)?$/gm;
+// os.Getenv("KEY") or os.LookupEnv("KEY")
+const RE_GO_ENV = /\bos\.(?:Getenv|LookupEnv)\s*\(\s*["']([A-Z_][A-Z0-9_]*)["']/g;
+// gorilla/mux, gin, chi, echo, stdlib: router.GET("/path", ...)
+const RE_GO_HTTP = /\b(?:r|router|e|mux|g|app)\s*\.\s*(?:HandleFunc|GET|POST|PUT|DELETE|PATCH|Handle|Any)\s*\(\s*["']([^"']+)["']/g;
+// GORM explicit table: db.Table("name")
+const RE_GO_GORM_TABLE = /\bdb\s*\.\s*Table\s*\(\s*["']([^"']+)["']/g;
+// ─── Ruby / Rails ────────────────────────────────────────────────────────────
+// class Foo or module Bar
+const RE_RUBY_CLASS = /\b(?:class|module)\s+([A-Z]\w*(?:::[A-Z]\w*)*)/g;
+// def method_name or def self.method_name
+const RE_RUBY_DEF = /^\s*def\s+(?:self\.)?([a-z_]\w*)/gm;
+// require 'gem' or require_relative '../path'
+const RE_RUBY_REQUIRE = /\brequire(?:_relative)?\s+["']([^"']+)["']/g;
+// ENV['KEY'] or ENV["KEY"]
+const RE_RUBY_ENV = /\bENV\s*\[\s*["']([A-Z_][A-Z0-9_]*)["']\s*\]/g;
+// Rails routes: get '/path', post '/path', resources :users, root 'home#index'
+const RE_RAILS_ROUTE = /^\s*(?:get|post|put|delete|patch|resources|resource|root)\s+["']([^"']+)["']/gm;
+// ActiveRecord associations: has_many :users, belongs_to :user
+const RE_AR_HAS = /\bhas_(?:many|one)\s+:(\w+)/g;
+const RE_AR_BELONGS = /\bbelongs_to\s+:(\w+)/g;
+// Explicit table name: self.table_name = 'table'
+const RE_AR_TABLE = /\bself\.table_name\s*=\s*["']([^"']+)["']/g;
 // SQL keywords and noise that the regex may pick up as table names.
 // Also strips single-letter hits (LINQ aliases: `from u in _db.Users` → u).
 const SQL_KEYWORD_NOISE = new Set([
@@ -77,11 +106,17 @@ function cleanTableNames(names) {
     });
 }
 function extract(content) {
-    const classes = collect(new RegExp(RE_CLASS.source, "g"), content);
+    const classes = uniq([
+        ...collect(new RegExp(RE_CLASS.source, "g"), content),
+        ...collect(new RegExp(RE_GO_TYPE.source, "g"), content),
+        ...collect(new RegExp(RE_RUBY_CLASS.source, "g"), content),
+    ]);
     const functions = uniq([
         ...collect(new RegExp(RE_FUNC_KW.source, "g"), content),
         ...collect(new RegExp(RE_FUNC_ARROW.source, "g"), content),
         ...collect(new RegExp(RE_METHOD_TS.source, "gm"), content),
+        ...collect(new RegExp(RE_GO_FUNC.source, "g"), content),
+        ...collect(new RegExp(RE_RUBY_DEF.source, "gm"), content),
     ]).filter((n) => !["if", "for", "while", "switch", "catch", "return", "function"].includes(n));
     const dependencies = uniq([
         ...collect(new RegExp(RE_USING.source, "g"), content),
@@ -89,6 +124,8 @@ function extract(content) {
         ...collect(new RegExp(RE_REQUIRE.source, "g"), content),
         ...collect(new RegExp(RE_DECORATOR.source, "g"), content),
         ...collect(new RegExp(RE_NEW_CLASS.source, "g"), content),
+        ...collect(new RegExp(RE_GO_IMPORT.source, "gm"), content),
+        ...collect(new RegExp(RE_RUBY_REQUIRE.source, "g"), content),
     ]);
     const db_tables = uniq(cleanTableNames([
         ...collect(new RegExp(RE_SQL_TABLE.source, "gi"), content),
@@ -96,6 +133,10 @@ function extract(content) {
         ...collect(new RegExp(RE_TABLE_ATTR.source, "g"), content),
         ...collect(new RegExp(RE_TABLE_FLUENT.source, "g"), content),
         ...collect(new RegExp(RE_EF_PROP.source, "g"), content),
+        ...collect(new RegExp(RE_GO_GORM_TABLE.source, "g"), content),
+        ...collect(new RegExp(RE_AR_HAS.source, "g"), content),
+        ...collect(new RegExp(RE_AR_BELONGS.source, "g"), content),
+        ...collect(new RegExp(RE_AR_TABLE.source, "g"), content),
     ]));
     const endpoints = uniq([
         ...collect(new RegExp(RE_DOTNET_ROUTE.source, "g"), content),
@@ -106,11 +147,15 @@ function extract(content) {
         ...collect(new RegExp(RE_FLASK.source, "g"), content),
         ...collect(new RegExp(RE_FASTAPI.source, "g"), content),
         ...collect(new RegExp(RE_DJANGO.source, "g"), content),
+        ...collect(new RegExp(RE_GO_HTTP.source, "g"), content),
+        ...collect(new RegExp(RE_RAILS_ROUTE.source, "gm"), content),
     ]);
     const config_refs = [];
     config_refs.push(...collect(new RegExp(RE_CFG_CONNSTR.source, "g"), content).map((s) => `ConnectionStrings:${s}`));
     config_refs.push(...collect(new RegExp(RE_PROCESS_ENV.source, "g"), content).map((s) => `process.env.${s}`));
     config_refs.push(...collect(new RegExp(RE_DOTNET_ENV.source, "g"), content));
+    config_refs.push(...collect(new RegExp(RE_GO_ENV.source, "g"), content).map((s) => `os.Getenv(${s})`));
+    config_refs.push(...collect(new RegExp(RE_RUBY_ENV.source, "g"), content).map((s) => `ENV[${s}]`));
     if (RE_ICONFIG.test(content))
         config_refs.push("IConfiguration");
     if (RE_APPSETTINGS.test(content))

package/dist/index.js

@@ -8,6 +8,17 @@ const read_module_1 = require("./tools/read-module");
 const list_modules_1 = require("./tools/list-modules");
 const write_spec_1 = require("./tools/write-spec");
 const read_specs_1 = require("./tools/read-specs");
+const ingest_source_1 = require("./tools/ingest-source");
+const update_index_1 = require("./tools/update-index");
+const list_wiki_1 = require("./tools/list-wiki");
+const wiki_search_1 = require("./tools/wiki-search");
+const answer_synthesis_1 = require("./tools/answer-synthesis");
+const query_wiki_1 = require("./tools/query-wiki");
+const save_answer_as_page_1 = require("./tools/save-answer-as-page");
+const lint_wiki_1 = require("./tools/lint-wiki");
+const get_schema_guidance_1 = require("./tools/get-schema-guidance");
+const preview_generation_1 = require("./tools/preview-generation");
+const generate_dependency_graph_1 = require("./tools/generate-dependency-graph");
 const server = new index_js_1.Server({ name: "docuflow", version: "0.1.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
     tools: [
@@ -66,6 +77,190 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
                 required: ["project_path"],
             },
         },
+        {
+            name: "ingest_source",
+            description: "Ingest a markdown source document from .docuflow/sources/ and generate wiki pages (entities, concepts) with cross-references. Returns pages created and entities discovered.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    source_filename: {
+                        type: "string",
+                        description: "Filename in .docuflow/sources/ to ingest (e.g., 'overview.md').",
+                    },
+                },
+                required: ["project_path", "source_filename"],
+            },
+        },
+        {
+            name: "update_index",
+            description: "Scan all wiki pages in .docuflow/wiki/ and regenerate .docuflow/index.md organized by category. Appends operation to log.md.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                },
+                required: ["project_path"],
+            },
+        },
+        {
+            name: "list_wiki",
+            description: "List all wiki pages in .docuflow/wiki/, optionally filtered by category. Returns metadata (title, created_at, sources, tags, stale) and page counts by category. Pages not updated in 30+ days are flagged stale:true.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    category: {
+                        type: "string",
+                        enum: ["entity", "concept", "timeline", "synthesis"],
+                        description: "Optional: filter to a specific category.",
+                    },
+                },
+                required: ["project_path"],
+            },
+        },
+        {
+            name: "wiki_search",
+            description: "Search the wiki for pages matching a query using relevance scoring. Returns ranked results with preview snippets and matched terms. BM25-inspired ranking weights entity pages higher.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    query: { type: "string", description: "Search query (e.g., 'MCP protocol design')." },
+                    limit: {
+                        type: "number",
+                        description: "Optional: max results to return (default: 10).",
+                    },
+                    category: {
+                        type: "string",
+                        enum: ["entity", "concept", "timeline", "synthesis"],
+                        description: "Optional: filter to a specific category.",
+                    },
+                },
+                required: ["project_path", "query"],
+            },
+        },
+        {
+            name: "synthesize_answer",
+            description: "Generate a synthesis answer from multiple wiki pages. Extracts relevant sentences, key concepts, and builds a markdown answer with citations.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    query: { type: "string", description: "The question being answered." },
+                    source_page_ids: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "List of wiki page IDs to synthesize from.",
+                    },
+                },
+                required: ["project_path", "query", "source_page_ids"],
+            },
+        },
+        {
+            name: "query_wiki",
+            description: "Ask a question against the wiki. Automatically searches for relevant pages, synthesizes an answer, and returns source pages with confidence score. One-stop tool for querying accumulated knowledge.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    question: { type: "string", description: "The question to ask (e.g., 'How does the MCP protocol work?')." },
+                    max_sources: {
+                        type: "number",
+                        description: "Optional: max source pages to use in synthesis (default: 5).",
+                    },
+                },
+                required: ["project_path", "question"],
+            },
+        },
+        {
+            name: "save_answer_as_page",
+            description: "Save a generated answer as a new wiki page. Allows query results to compound back into the knowledge base, growing the wiki with new synthesis pages. Automatically adds frontmatter and updates log.md.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    question: { type: "string", description: "The original question that was answered." },
+                    answer: { type: "string", description: "The markdown answer text to save." },
+                    page_title: { type: "string", description: "Title for the new page (e.g., 'How MCP Protocol Works')." },
+                    category: {
+                        type: "string",
+                        enum: ["synthesis", "entity", "concept", "timeline"],
+                        description: "Optional: wiki category for the page (default: synthesis).",
+                    },
+                    source_page_ids: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Optional: list of source wiki page IDs used to generate this answer.",
+                    },
+                },
+                required: ["project_path", "question", "answer", "page_title"],
+            },
+        },
+        {
+            name: "lint_wiki",
+            description: "Health check wiki for quality issues: orphan pages, broken references, stale content, metadata gaps, and contradictions. Returns issues found, metrics, health score, and recommendations.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    check_type: {
+                        type: "string",
+                        enum: ["all", "orphans", "contradictions", "stale", "metadata"],
+                        description: "Optional: type of check to run (default: all).",
+                    },
+                },
+                required: ["project_path"],
+            },
+        },
+        {
+            name: "get_schema_guidance",
+            description: "Analyze what documents should exist based on project schema and current wiki. Removes decision fatigue by suggesting what to create next.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    domain: {
+                        type: "string",
+                        description: "Optional: domain hint (Code/Architecture, Research, Business, Personal). Auto-detected if not provided.",
+                    },
+                },
+                required: ["project_path"],
+            },
+        },
+        {
+            name: "preview_generation",
+            description: "Preview what a tool will generate before running it. Removes black-box feeling by showing predicted actions, outputs, and impact.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tool_name: { type: "string", description: "Name of the tool to preview (e.g., ingest_source, query_wiki)." },
+                    project_path: { type: "string", description: "Root of the project." },
+                    params: { type: "object", description: "Parameters you would pass to that tool." },
+                },
+                required: ["tool_name", "project_path", "params"],
+            },
+        },
+        {
+            name: "generate_dependency_graph",
+            description: "Scan a project and build a dependency graph showing how modules import each other, which DB tables are shared, and which files are most connected. Returns nodes, edges, shared tables, and the top 10 most-connected modules. Use this to understand coupling and identify risky files to change.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root directory of the project to analyse." },
+                    extensions: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Optional extension filter e.g. [\".ts\",\".go\"]. If omitted, all non-binary files are scanned.",
+                    },
+                    focus: {
+                        type: "string",
+                        description: "Optional: filter graph to neighbours of a specific file or module name (partial match, e.g. 'user-service').",
+                    },
+                },
+                required: ["project_path"],
+            },
+        },
     ],
 }));
 server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
@@ -84,6 +279,39 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         else if (name === "read_specs") {
             result = await (0, read_specs_1.readSpecs)(args);
         }
+        else if (name === "ingest_source") {
+            result = await (0, ingest_source_1.ingestSource)(args);
+        }
+        else if (name === "update_index") {
+            result = await (0, update_index_1.updateIndex)(args);
+        }
+        else if (name === "list_wiki") {
+            result = await (0, list_wiki_1.listWiki)(args);
+        }
+        else if (name === "wiki_search") {
+            result = await (0, wiki_search_1.wikiSearch)(args);
+        }
+        else if (name === "synthesize_answer") {
+            result = await (0, answer_synthesis_1.synthesizeAnswer)(args);
+        }
+        else if (name === "query_wiki") {
+            result = await (0, query_wiki_1.queryWiki)(args);
+        }
+        else if (name === "save_answer_as_page") {
+            result = await (0, save_answer_as_page_1.saveAnswerAsPage)(args);
+        }
+        else if (name === "lint_wiki") {
+            result = await (0, lint_wiki_1.lintWiki)(args);
+        }
+        else if (name === "get_schema_guidance") {
+            result = await (0, get_schema_guidance_1.getSchemataGuidance)(args);
+        }
+        else if (name === "preview_generation") {
+            result = await (0, preview_generation_1.previewGeneration)(args);
+        }
+        else if (name === "generate_dependency_graph") {
+            result = await (0, generate_dependency_graph_1.generateDependencyGraph)(args);
+        }
         else {
             result = { error: `Unknown tool: ${name}` };
         }

package/dist/tools/answer-synthesis.js

@@ -0,0 +1,189 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.synthesizeAnswer = synthesizeAnswer;
+const node_path_1 = __importDefault(require("node:path"));
+const filesystem_1 = require("../filesystem");
+/**
+ * Extract key sentences from content that relate to the query
+ */
+function extractRelevantSentences(content, queryTerms, maxSentences = 3) {
+    const sentences = content
+        .split(/[.!?]+/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 10 && !s.startsWith("#") && !s.startsWith("---"));
+    const scoredSentences = [];
+    for (const sentence of sentences) {
+        let score = 0;
+        const sentenceLower = sentence.toLowerCase();
+        for (const term of queryTerms) {
+            if (sentenceLower.includes(term)) {
+                // Count occurrences
+                const matches = sentenceLower.split(term).length - 1;
+                score += matches * 2;
+            }
+        }
+        if (score > 0) {
+            scoredSentences.push({ text: sentence, score });
+        }
+    }
+    // Sort by score and take top N
+    return scoredSentences
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxSentences)
+        .map((s) => s.text);
+}
+/**
+ * Extract key concepts from page content (from H3 headers, bold text)
+ */
+function extractKeyConcepts(content) {
+    const concepts = new Set();
+    // Extract from H3 headers
+    const h3Matches = content.matchAll(/^###\s+(.+?)$/gm);
+    for (const match of h3Matches) {
+        const concept = match[1].trim();
+        if (concept && concept.length < 80) {
+            concepts.add(concept);
+        }
+    }
+    // Extract from bold text (but not arrays/JSON)
+    const boldMatches = content.matchAll(/\*\*([^*]+)\*\*/g);
+    for (const match of boldMatches) {
+        const text = match[1].trim();
+        if (text.length > 3 &&
+            text.length < 60 &&
+            !text.includes("[") &&
+            !text.includes("{") &&
+            !text.includes('"')) {
+            concepts.add(text);
+        }
+    }
+    return Array.from(concepts).slice(0, 5);
+}
+/**
+ * Build a synthesis answer from multiple source pages
+ */
+function buildSynthesis(query, sourcePages, queryTerms) {
+    if (!sourcePages.length) {
+        return {
+            answer: `No information found related to: ${query}`,
+            concepts: [],
+        };
+    }
+    const allConcepts = new Set();
+    const sections = [];
+    // Add introduction
+    sections.push(`## Synthesis: ${query}\n`);
+    sections.push(`Based on ${sourcePages.length} source page(s):\n`);
+    // Add content from each source
+    for (const page of sourcePages) {
+        sections.push(`### ${page.title}`);
+        sections.push(`*Category: ${page.category} | Relevance: ${Math.round(page.relevance * 100)}%*\n`);
+        // Extract relevant sentences
+        const relevantSentences = extractRelevantSentences(page.content, queryTerms, 2);
+        if (relevantSentences.length > 0) {
+            sections.push(relevantSentences.map((s) => `- ${s.trim()}`).join("\n"));
+        }
+        else {
+            // Fallback: use first paragraph
+            const firstPara = page.content
+                .split("\n")
+                .filter((l) => l.trim() && !l.startsWith("#") && !l.startsWith("---"))
+                .slice(0, 1);
+            sections.push(firstPara.join("\n"));
+        }
+        // Collect concepts
+        const pageConcepts = extractKeyConcepts(page.content);
+        pageConcepts.forEach((c) => allConcepts.add(c));
+        sections.push("");
+    }
+    // Add summary
+    sections.push("\n## Key Concepts Found");
+    Array.from(allConcepts).forEach((c) => {
+        sections.push(`- ${c}`);
+    });
+    sections.push("\n## How to Extend This\n");
+    sections.push(`This synthesis was generated from ${sourcePages.length} page(s) containing the key terms: `);
+    sections.push(queryTerms.join(", "));
+    sections.push("\n\nAdd more source pages to deepen this synthesis.");
+    return {
+        answer: sections.join("\n"),
+        concepts: Array.from(allConcepts),
+    };
+}
+async function synthesizeAnswer(input) {
+    try {
+        const projectPath = node_path_1.default.resolve(input.project_path);
+        const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+        const wikiDir = node_path_1.default.join(docuDir, "wiki");
+        // Load each source page
+        const sourcePages = [];
+        for (const pageId of input.source_page_ids) {
+            // Try to find the page (scan all category directories)
+            let found = false;
+            for (const categoryDir of ["entities", "concepts", "timelines", "syntheses"]) {
+                const filePath = node_path_1.default.join(wikiDir, categoryDir, `${pageId}.md`);
+                try {
+                    const read = await (0, filesystem_1.safeReadFile)(filePath);
+                    if (!read.error && !read.binary && read.content) {
+                        const titleMatch = read.content.match(/^#\s+(.+?)$/m);
+                        const title = titleMatch ? titleMatch[1].trim() : pageId;
+                        const category = categoryDir.replace("s", "");
+                        sourcePages.push({
+                            page_id: pageId,
+                            title,
+                            category,
+                            content: read.content,
+                            relevance: 1.0 - (sourcePages.length * 0.1), // Slight decay for order
+                        });
+                        found = true;
+                        break;
+                    }
+                }
+                catch (e) {
+                    // Try next category
+                }
+            }
+            if (!found && sourcePages.length === 0) {
+                // At least one page should be found
+                return {
+                    query: input.query,
+                    answer: `Could not find source page: ${pageId}`,
+                    source_pages: [],
+                    confidence: 0,
+                    key_concepts: [],
+                    error: `Page not found: ${pageId}`,
+                };
+            }
+        }
+        // Build query terms
+        const queryTerms = input.query.toLowerCase().split(/\s+/).filter((t) => t.length > 2);
+        // Generate synthesis
+        const { answer, concepts } = buildSynthesis(input.query, sourcePages, queryTerms);
+        // Calculate confidence based on number and relevance of sources
+        const confidence = Math.min(1.0, Math.max(0.3, sourcePages.length * 0.25));
+        return {
+            query: input.query,
+            answer,
+            source_pages: sourcePages.map((p) => ({
+                page_id: p.page_id,
+                title: p.title,
+                category: p.category,
+            })),
+            confidence,
+            key_concepts: concepts,
+        };
+    }
+    catch (e) {
+        return {
+            query: input.query,
+            answer: `Error synthesizing answer: ${e?.message ?? String(e)}`,
+            source_pages: [],
+            confidence: 0,
+            key_concepts: [],
+            error: e?.message ?? String(e),
+        };
+    }
+}