homegraph 1.1.2 → 1.1.3

package/dist/mcp/tools.d.ts

@@ -193,10 +193,11 @@ export declare class ToolHandler {
     hasDefaultHomeGraph(): boolean;
     /**
      * Optional allowlist of exposed tools, parsed from the HOMEGRAPH_MCP_TOOLS
-     * env var (comma-separated short names, e.g. "trace,search,node,context").
-     * Unset/empty → every tool is exposed. Lets an operator (or an A/B harness)
-     * trim the tool surface without rebuilding the client config; the ablated
-     * tool is then truly absent from ListTools rather than merely denied on call.
+     * env var (comma-separated short names, e.g. "explore,search,node").
+     * Unset/empty → every tool is exposed. Set → only the listed tools are
+     * exposed. Lets an operator (or an A/B harness) trim the tool surface
+     * without rebuilding the client config; the ablated tool is then truly
+     * absent from ListTools rather than merely denied on call.
      * Matching is on the short form, so "node" and "homegraph_node" both work.
      */
     private toolAllowlist;
@@ -312,6 +313,8 @@ export declare class ToolHandler {
      * Handle homegraph_impact
      */
     private handleImpact;
+    /** Whether a graph edge may be traversed by homegraph_explore's main Flow BFS. */
+    private isExploreFlowEdge;
     /**
      * Describe a synthesized (dynamic-dispatch) edge for human output: how the
      * callback was wired up — the bridge static parsing can't see. Returns null
@@ -467,6 +470,16 @@ export declare class ToolHandler {
      * Format files as a tree structure
      */
     private formatFilesTree;
+    /**
+     * Match a spec/feature description against the Commit4Spec knowledge graph.
+     *
+     * Uses FTS5 full-text search to find the most similar historical specs,
+     * returning each with its linked commits and optional code fragments.
+     * The database lives at `.homegraph/commit4spec/commit4spec.db` by default and is
+     * separate from the HomeGraph code-symbol index — this tool works whether
+     * or not the code index is present.
+     */
+    private handleSpecMatch;
     /**
      * Find a symbol by name, handling disambiguation when multiple matches exist.
      * Returns the best match and a note about alternatives if any.

package/dist/mcp/tools.d.ts.map

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

package/dist/mcp/tools.js

@@ -25,6 +25,14 @@ const fs_1 = require("fs");
 const utils_1 = require("../utils");
 const generated_detection_1 = require("../extraction/generated-detection");
 const dynamic_boundaries_1 = require("./dynamic-boundaries");
+/** ViewTree structural `references` vias — not UI event bindings. */
+const VIEWTREE_STRUCTURE_VIAS = new Set([
+    'child-component',
+    'state-binding',
+    'prop-transfer',
+    'builder',
+    'builder-param',
+]);
 /**
  * An expected, recoverable "homegraph can't serve this" condition — most
  * importantly a project with no index. The dispatch catch converts these to
@@ -551,6 +559,40 @@ exports.tools = [
             },
         },
     },
+    {
+        name: 'homegraph_spec_match',
+        description: 'Match a new spec/feature description against the Commit4Spec knowledge graph using FTS5 full-text search. ' +
+            'Returns the most similar historical specs with their associated commits and code fragments. ' +
+            'The database defaults to .homegraph/commit4spec/commit4spec.db under the repo path.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Spec text (title + description) to match against historical specs.',
+                },
+                repoPath: {
+                    type: 'string',
+                    description: 'Path to the repository root. Defaults to the current working directory.',
+                },
+                topK: {
+                    type: 'number',
+                    description: 'Maximum number of similar specs to return (default: 5).',
+                    default: 5,
+                },
+                includeFragments: {
+                    type: 'boolean',
+                    description: 'Whether to include full code diffs per commit (default: true).',
+                    default: true,
+                },
+                dbPath: {
+                    type: 'string',
+                    description: 'Explicit path to the Commit4Spec database. Overrides repoPath-based resolution.',
+                },
+            },
+            required: ['query'],
+        },
+    },
 ];
 /**
  * Allowlist-filtered tool definitions WITHOUT an engine — the static surface the
@@ -561,23 +603,11 @@ exports.tools = [
 function getStaticTools() {
     const raw = process.env.HOMEGRAPH_MCP_TOOLS ?? process.env.HOMEGRAPH_MCP_TOOLS;
     if (!raw || !raw.trim()) {
-        return exports.tools.filter(t => DEFAULT_MCP_TOOLS.has(t.name.replace(/^homegraph_/, '')));
+        return exports.tools;
     }
     const allow = new Set(raw.split(',').map(s => s.trim().replace(/^homegraph_/, '').replace(/^homegraph_/, '')).filter(Boolean));
     return allow.size ? exports.tools.filter(t => allow.has(t.name.replace(/^homegraph_/, ''))) : exports.tools;
 }
-/**
- * The MCP tools served by DEFAULT (short names). Pared to ONLY `homegraph_explore`
- * — the single tool that reliably earns its place: one capped call returns the
- * verbatim source of the relevant symbols grouped by file. Every other tool is a
- * narrower slice of what explore already does, and presence itself steers
- * mis-picks, so they are no longer LISTED to agents.
- *
- * The other defined tools (`node`, `search`, `callers`, plus callees/impact/files/
- * status) remain fully functional — handlers stay, the library API and CLI are
- * untouched, and `HOMEGRAPH_MCP_TOOLS=explore,node,...` re-enables any of them.
- */
-const DEFAULT_MCP_TOOLS = new Set(['explore']);
 /**
  * Tool handler that executes tools against a HomeGraph instance
  *
@@ -680,10 +710,11 @@ class ToolHandler {
     }
     /**
      * Optional allowlist of exposed tools, parsed from the HOMEGRAPH_MCP_TOOLS
-     * env var (comma-separated short names, e.g. "trace,search,node,context").
-     * Unset/empty → every tool is exposed. Lets an operator (or an A/B harness)
-     * trim the tool surface without rebuilding the client config; the ablated
-     * tool is then truly absent from ListTools rather than merely denied on call.
+     * env var (comma-separated short names, e.g. "explore,search,node").
+     * Unset/empty → every tool is exposed. Set → only the listed tools are
+     * exposed. Lets an operator (or an A/B harness) trim the tool surface
+     * without rebuilding the client config; the ablated tool is then truly
+     * absent from ListTools rather than merely denied on call.
      * Matching is on the short form, so "node" and "homegraph_node" both work.
      */
     toolAllowlist() {
@@ -707,12 +738,11 @@ class ToolHandler {
      */
     getTools() {
         const allow = this.toolAllowlist();
-        // No explicit allowlist → the default 4-tool surface (see
-        // DEFAULT_MCP_TOOLS for the evidence). An allowlist replaces the
-        // default entirely, so any defined tool can be re-enabled.
+        // No explicit allowlist → expose every defined tool. An allowlist trims
+        // the surface to only the listed short names.
         let visible = allow
             ? exports.tools.filter(t => allow.has(t.name.replace(/^homegraph_/, '')))
-            : exports.tools.filter(t => DEFAULT_MCP_TOOLS.has(t.name.replace(/^homegraph_/, '')));
+            : exports.tools;
         if (!this.cg)
             return visible;
         try {
@@ -1147,6 +1177,9 @@ class ToolHandler {
                 case 'homegraph_files':
                     result = await this.handleFiles(args);
                     break;
+                case 'homegraph_spec_match':
+                    result = await this.handleSpecMatch(args);
+                    break;
                 default:
                     return this.errorResult(`Unknown tool: ${toolName}`);
             }
@@ -1427,6 +1460,18 @@ class ToolHandler {
         }
         return this.textResult(this.truncateOutput(sections.join('\n') + filterNote));
     }
+    /** Whether a graph edge may be traversed by homegraph_explore's main Flow BFS. */
+    isExploreFlowEdge(edge) {
+        if (edge.kind === 'calls')
+            return true;
+        if (edge.kind !== 'references' || edge.provenance !== 'heuristic')
+            return false;
+        const m = edge.metadata;
+        if (m?.synthesizedBy !== 'viewtree')
+            return false;
+        const via = typeof m.via === 'string' ? m.via : '';
+        return via.length > 0 && !VIEWTREE_STRUCTURE_VIAS.has(via);
+    }
     /**
      * Describe a synthesized (dynamic-dispatch) edge for human output: how the
      * callback was wired up — the bridge static parsing can't see. Returns null
@@ -1479,6 +1524,16 @@ class ToolHandler {
                 registeredAt,
             };
         }
+        if (m?.synthesizedBy === 'viewtree') {
+            const via = typeof m.via === 'string' ? m.via : '';
+            if (via && !VIEWTREE_STRUCTURE_VIAS.has(via)) {
+                return {
+                    label: `ArkUI event \`.${via}\` — bound handler (dynamic dispatch)`,
+                    compact: `dynamic: ArkUI .${via}${at}`,
+                    registeredAt,
+                };
+            }
+        }
         if (m?.synthesizedBy === 'interface-impl') {
             return {
                 label: `interface/abstract dispatch — runs the implementation override (dynamic dispatch)`,
@@ -1687,7 +1742,7 @@ class ToolHandler {
                     if (depth >= MAX_HOPS - 1)
                         continue;
                     for (const c of cg.getCallees(id)) {
-                        if (c.edge.kind !== 'calls' || parent.has(c.node.id))
+                        if (!this.isExploreFlowEdge(c.edge) || parent.has(c.node.id))
                             continue;
                         const newStreak = named.has(c.node.id) ? 0 : streak + 1;
                         if (newStreak > MAX_BRIDGE)
@@ -3814,6 +3869,121 @@ class ToolHandler {
         return lines.join('\n');
     }
     // =========================================================================
+    // handleSpecMatch — Commit4Spec knowledge-graph search
+    // =========================================================================
+    /**
+     * Match a spec/feature description against the Commit4Spec knowledge graph.
+     *
+     * Uses FTS5 full-text search to find the most similar historical specs,
+     * returning each with its linked commits and optional code fragments.
+     * The database lives at `.homegraph/commit4spec/commit4spec.db` by default and is
+     * separate from the HomeGraph code-symbol index — this tool works whether
+     * or not the code index is present.
+     */
+    async handleSpecMatch(args) {
+        const query = this.validateString(args.query, 'query');
+        if (typeof query !== 'string')
+            return query;
+        const repoPath = args.repoPath;
+        const explicitDbPath = args.dbPath;
+        const topK = Math.max(1, Math.min(Number(args.topK) || 5, 50));
+        const includeFragments = args.includeFragments !== false;
+        // Lazily require spec modules so the MCP startup path stays lean.
+        const { resolveDbPath } = require('../spec/utils');
+        const { createDatabase } = require('../db/sqlite-adapter');
+        const { initSpecSchema } = require('../spec/db/schema');
+        const { searchAndGetContext } = require('../spec/graph/queries');
+        const { truncateCodeDiff, truncateSubtitles, computeBudgetProfile, } = require('../spec/utils');
+        // Resolve the database path.
+        const dbPath = resolveDbPath(repoPath || process.cwd(), explicitDbPath);
+        // Open the database.
+        let db;
+        try {
+            db = createDatabase(dbPath).db;
+        }
+        catch (err) {
+            return this.errorResult(`Failed to open Commit4Spec database at "${dbPath}": ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            // Ensure the schema exists (idempotent).
+            initSpecSchema(db);
+            // Search and traverse.
+            const contexts = searchAndGetContext(db, query, topK, includeFragments);
+            if (contexts.length === 0) {
+                return this.textResult(JSON.stringify({
+                    query: query.slice(0, 200),
+                    matched_count: 0,
+                    results: [],
+                }, null, 2));
+            }
+            // Build budget profile for truncation.
+            const profile = computeBudgetProfile(contexts.length);
+            // Serialize to JSON (matching Python's spec_contexts_to_results format).
+            const results = contexts.map((ctx) => {
+                const subtitles = profile.tier === 'vlarge'
+                    ? [] // vlarge disables subtitles entirely
+                    : truncateSubtitles(ctx.spec.subtitles, 200, profile.maxContents);
+                const commits = ctx.commits.slice(0, profile.maxContents || 5).map((c) => {
+                    const cd = {
+                        hash: c.commit.hash,
+                        message: c.commit.message,
+                        relation_type: c.relationType,
+                    };
+                    if (includeFragments) {
+                        const maxFrags = profile.maxFragments || 3;
+                        cd.fragments = c.fragments.slice(0, maxFrags).map((f) => ({
+                            file_path: f.filePath,
+                            change_type: f.changeType,
+                            start_line: f.startLine,
+                            end_line: f.endLine,
+                            code_diff: truncateCodeDiff(f.codeDiff),
+                        }));
+                    }
+                    return cd;
+                });
+                return {
+                    spec_id: ctx.spec.id,
+                    title: ctx.spec.title,
+                    subtitles,
+                    file_path: ctx.spec.filePath,
+                    commits,
+                };
+            });
+            const response = {
+                query: query.slice(0, 200),
+                matched_count: results.length,
+                results,
+            };
+            const json = JSON.stringify(response, null, 2);
+            // Hard cap to MAX_OUTPUT_LENGTH to prevent context bloat.
+            if (json.length <= MAX_OUTPUT_LENGTH) {
+                return this.textResult(json);
+            }
+            // When the full payload exceeds the cap, drop fragments first,
+            // then trim commits, then trim the whole thing.
+            if (includeFragments) {
+                const slimResults = results.map((r) => ({
+                    ...r,
+                    commits: r.commits.map((c) => {
+                        const { fragments: _, ...rest } = c;
+                        return rest;
+                    }),
+                }));
+                const slim = JSON.stringify({ ...response, results: slimResults }, null, 2);
+                if (slim.length <= MAX_OUTPUT_LENGTH) {
+                    return this.textResult(`(Fragments elided — output exceeded ${MAX_OUTPUT_LENGTH} chars)\n\n` + slim);
+                }
+            }
+            // Fallback: hard-truncate the JSON.
+            const truncated = json.slice(0, MAX_OUTPUT_LENGTH - 3) + '...';
+            return this.textResult(truncated);
+        }
+        finally {
+            db.close();
+        }
+    }
+    // =========================================================================
     // Symbol resolution helpers
     // =========================================================================
     /**