@mohantn/gate-keeper 2.1.0

package/dist/graph/graph-summary.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Pre-computed analytics for the dependency graph response.
+ *
+ * Surfaces the signals AI agents otherwise have to derive with custom code:
+ * rating distribution, top fan-in / fan-out hotspots, worst-rated files, and
+ * cross-module coupling. All functions are pure and operate on the raw
+ * GraphResponse shape from the daemon.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.moduleOf = moduleOf;
+exports.buildGraphSummary = buildGraphSummary;
+exports.formatGraphSummaryMarkdown = formatGraphSummaryMarkdown;
+const path = __importStar(require("path"));
+const graph_algorithms_1 = require("./graph-algorithms");
+const TOP_N = 10;
+const MODULE_COUPLING_LIMIT = 15;
+const FRAGILE_HUB_FANIN = 5;
+const FRAGILE_RATING_THRESHOLD = 7.0;
+/** Derive a stable module label from a file path, handling sub-projects. */
+function moduleOf(filePath, repo) {
+    const rel = path.relative(repo, filePath);
+    if (!rel || rel.startsWith('..'))
+        return path.dirname(filePath);
+    const parts = rel.split(/[\\/]/);
+    if (parts[0] === 'src')
+        return parts.length >= 2 ? `src/${parts[1]}` : 'src';
+    if (parts.length >= 3 && parts[1] === 'src')
+        return `${parts[0]}/src/${parts[2]}`;
+    return parts.slice(0, 2).join('/');
+}
+function computeRatingDistribution(nodes) {
+    const dist = { excellent: 0, good: 0, warning: 0, critical: 0 };
+    for (const n of nodes) {
+        if (n.rating >= 8)
+            dist.excellent++;
+        else if (n.rating >= 7)
+            dist.good++;
+        else if (n.rating >= 6.5)
+            dist.warning++;
+        else
+            dist.critical++;
+    }
+    return dist;
+}
+function computeAvgRating(nodes) {
+    if (nodes.length === 0)
+        return 0;
+    let sum = 0;
+    let count = 0;
+    for (const n of nodes) {
+        if (Number.isFinite(n.rating)) {
+            sum += n.rating;
+            count++;
+        }
+    }
+    return count === 0 ? 0 : Math.round((sum / count) * 100) / 100;
+}
+function enrichHotspot(e, locByNode) {
+    const entry = {
+        path: e.path,
+        inDegree: e.inDegree,
+        outDegree: e.outDegree,
+        rating: e.rating,
+        loc: locByNode.get(e.path) ?? 0,
+    };
+    if (e.inDegree >= FRAGILE_HUB_FANIN && e.rating < FRAGILE_RATING_THRESHOLD) {
+        entry.fragileHub = true;
+    }
+    return entry;
+}
+function topHotspots(centrality, pick, locByNode) {
+    return [...centrality]
+        .filter(e => pick(e) > 0)
+        .sort((a, b) => pick(b) - pick(a) || a.rating - b.rating)
+        .slice(0, TOP_N)
+        .map(e => enrichHotspot(e, locByNode));
+}
+function topWorstFiles(nodes, violationsByNode) {
+    return [...nodes]
+        .sort((a, b) => a.rating - b.rating || b.metrics.linesOfCode - a.metrics.linesOfCode)
+        .slice(0, TOP_N)
+        .map(n => ({
+        path: n.id,
+        rating: n.rating,
+        loc: n.metrics.linesOfCode,
+        violations: violationsByNode.get(n.id) ?? 0,
+    }));
+}
+function computeModuleCoupling(edges, repo) {
+    const counts = new Map();
+    for (const e of edges) {
+        const from = moduleOf(e.source, repo);
+        const to = moduleOf(e.target, repo);
+        if (from === to)
+            continue;
+        let inner = counts.get(from);
+        if (!inner) {
+            inner = new Map();
+            counts.set(from, inner);
+        }
+        inner.set(to, (inner.get(to) ?? 0) + 1);
+    }
+    const out = [];
+    for (const [from, inner] of counts) {
+        for (const [to, count] of inner)
+            out.push({ from, to, count });
+    }
+    out.sort((a, b) => b.count - a.count);
+    return out.slice(0, MODULE_COUPLING_LIMIT);
+}
+function buildGraphSummary(nodes, edges, cycles, repo) {
+    const centrality = (0, graph_algorithms_1.computeCentrality)(nodes.map(n => ({ id: n.id, label: n.label ?? path.basename(n.id), rating: n.rating })), edges);
+    const locByNode = new Map(nodes.map(n => [n.id, n.metrics.linesOfCode]));
+    const violationsByNode = new Map(nodes.map(n => [n.id, n.violations.length]));
+    return {
+        fileCount: nodes.length,
+        edgeCount: edges.length,
+        cycleCount: cycles.length,
+        avgRating: computeAvgRating(nodes),
+        ratingDistribution: computeRatingDistribution(nodes),
+        mostDependedOn: topHotspots(centrality, e => e.inDegree, locByNode),
+        mostDependencies: topHotspots(centrality, e => e.outDegree, locByNode),
+        worstFiles: topWorstFiles(nodes, violationsByNode),
+        moduleCoupling: computeModuleCoupling(edges, repo),
+    };
+}
+/** Format the summary as compact markdown for the human-readable channel. */
+function formatGraphSummaryMarkdown(summary, repo) {
+    const rel = (p) => {
+        const r = path.relative(repo, p);
+        return r && !r.startsWith('..') ? r : p;
+    };
+    const lines = [];
+    const d = summary.ratingDistribution;
+    lines.push('## Dependency Graph');
+    lines.push(`**Files:** ${summary.fileCount} | **Edges:** ${summary.edgeCount} | ` +
+        `**Cycles:** ${summary.cycleCount} | **Avg rating:** ${summary.avgRating}`);
+    lines.push('');
+    lines.push('### Rating Distribution');
+    lines.push(`- >=8 (excellent): **${d.excellent}**` +
+        ` | 7-8 (good): **${d.good}**` +
+        ` | 6.5-7 (warning): **${d.warning}**` +
+        ` | <6.5 (critical): **${d.critical}**`);
+    lines.push('');
+    if (summary.mostDependedOn.length > 0) {
+        lines.push('### Top Fan-In (most depended-on - risky to change)');
+        for (const h of summary.mostDependedOn.slice(0, 5)) {
+            const flag = h.fragileHub ? '  [fragile hub]' : '';
+            lines.push(`- in=${h.inDegree} | r=${h.rating} | ${h.loc} LOC | \`${rel(h.path)}\`${flag}`);
+        }
+        lines.push('');
+    }
+    if (summary.mostDependencies.length > 0) {
+        lines.push('### Top Fan-Out (highest afferent coupling - potential god-modules)');
+        for (const h of summary.mostDependencies.slice(0, 5)) {
+            lines.push(`- out=${h.outDegree} | r=${h.rating} | ${h.loc} LOC | \`${rel(h.path)}\``);
+        }
+        lines.push('');
+    }
+    if (summary.worstFiles.length > 0) {
+        lines.push('### Worst-Rated Files');
+        for (const w of summary.worstFiles.slice(0, 5)) {
+            lines.push(`- r=${w.rating} | ${w.loc} LOC | ${w.violations} viol | \`${rel(w.path)}\``);
+        }
+        lines.push('');
+    }
+    if (summary.moduleCoupling.length > 0) {
+        lines.push('### Top Cross-Module Edges');
+        for (const m of summary.moduleCoupling.slice(0, 8)) {
+            lines.push(`- ${m.count}x \`${m.from}\` -> \`${m.to}\``);
+        }
+        lines.push('');
+    }
+    lines.push('Full structured data in `structuredContent.data`: `nodes`, `edges`, `adjacency`, ' +
+        '`reverseAdjacency`, `cycles`, plus the pre-computed `summary` (rating distribution, ' +
+        'hotspots, worst files, module coupling).');
+    return lines.join('\n');
+}
+//# sourceMappingURL=graph-summary.js.map

package/dist/graph/graph-summary.js.map

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

package/dist/graph/graphify-ignore.d.ts

@@ -0,0 +1,32 @@
+/**
+ * .graphifyignore parser — gitignore-compatible file exclusion for gate-keeper scans.
+ *
+ * Supports:
+ *   #  comment lines
+ *   !  negation (un-ignore a previously ignored path)
+ *   *  matches any character except /
+ *   ** matches any sequence including /
+ *   ?  matches any single character except /
+ *   Patterns without / match the basename at any depth (same as .gitignore).
+ *   Patterns with / are anchored relative to the repo root.
+ *
+ * Usage:
+ *   const rules = loadGraphifyIgnore(repoRoot);
+ *   if (shouldIgnoreByGraphifyIgnore('/repo/src/gen/foo.ts', '/repo', rules)) skip();
+ */
+export interface IgnoreRule {
+    pattern: string;
+    negate: boolean;
+    anchored: boolean;
+    regex: RegExp;
+}
+/** Parse the text content of a .graphifyignore file into rules. */
+export declare function parseGraphifyIgnore(content: string): IgnoreRule[];
+/** Load .graphifyignore from the repo root; returns empty array if file missing. */
+export declare function loadGraphifyIgnore(repoRoot: string): IgnoreRule[];
+/**
+ * Returns true if `filePath` should be excluded according to `rules`.
+ * Rules are evaluated in order; the last matching rule wins (gitignore semantics).
+ */
+export declare function shouldIgnoreByGraphifyIgnore(filePath: string, repoRoot: string, rules: IgnoreRule[]): boolean;
+//# sourceMappingURL=graphify-ignore.d.ts.map

package/dist/graph/graphify-ignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphify-ignore.d.ts","sourceRoot":"","sources":["../../src/graph/graphify-ignore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAiBjE;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CAQjE;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,UAAU,EAAE,GAClB,OAAO,CAeT"}

package/dist/graph/graphify-ignore.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * .graphifyignore parser — gitignore-compatible file exclusion for gate-keeper scans.
+ *
+ * Supports:
+ *   #  comment lines
+ *   !  negation (un-ignore a previously ignored path)
+ *   *  matches any character except /
+ *   ** matches any sequence including /
+ *   ?  matches any single character except /
+ *   Patterns without / match the basename at any depth (same as .gitignore).
+ *   Patterns with / are anchored relative to the repo root.
+ *
+ * Usage:
+ *   const rules = loadGraphifyIgnore(repoRoot);
+ *   if (shouldIgnoreByGraphifyIgnore('/repo/src/gen/foo.ts', '/repo', rules)) skip();
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseGraphifyIgnore = parseGraphifyIgnore;
+exports.loadGraphifyIgnore = loadGraphifyIgnore;
+exports.shouldIgnoreByGraphifyIgnore = shouldIgnoreByGraphifyIgnore;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** Parse the text content of a .graphifyignore file into rules. */
+function parseGraphifyIgnore(content) {
+    const rules = [];
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const negate = line.startsWith('!');
+        const raw = negate ? line.slice(1).trim() : line;
+        const isDir = raw.endsWith('/');
+        // Strip trailing / (directory marker — we match its contents)
+        const pattern = isDir ? raw.slice(0, -1) : raw;
+        // "anchored" = pattern originally had a / (including a trailing one)
+        const anchored = raw.includes('/');
+        rules.push({ pattern, negate, anchored, regex: buildRegex(pattern, anchored) });
+    }
+    return rules;
+}
+/** Load .graphifyignore from the repo root; returns empty array if file missing. */
+function loadGraphifyIgnore(repoRoot) {
+    const ignoreFile = path.join(repoRoot, '.graphifyignore');
+    try {
+        const content = fs.readFileSync(ignoreFile, 'utf8');
+        return parseGraphifyIgnore(content);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Returns true if `filePath` should be excluded according to `rules`.
+ * Rules are evaluated in order; the last matching rule wins (gitignore semantics).
+ */
+function shouldIgnoreByGraphifyIgnore(filePath, repoRoot, rules) {
+    if (rules.length === 0)
+        return false;
+    const rel = path.relative(repoRoot, filePath).replace(/\\/g, '/'); // normalise on Windows
+    const base = path.basename(rel);
+    let ignored = false;
+    for (const rule of rules) {
+        const subject = rule.anchored ? rel : base;
+        if (rule.regex.test(subject)) {
+            ignored = !rule.negate;
+        }
+    }
+    return ignored;
+}
+// ── Helpers ────────────────────────────────────────────────
+function buildRegex(pattern, anchored) {
+    // Escape special regex chars except * and ?
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        // Multi-level wildcard ** must be replaced before single-level *
+        // Use sentinel to avoid double-matching * inside **
+        .replace(/\*\*/g, '\x00GLOBSTAR\x00')
+        .replace(/\*/g, '[^/]*') // single-level wildcard
+        .replace(/\x00GLOBSTAR\x00/g, '.*') // multi-level wildcard
+        .replace(/\?/g, '[^/]'); // single char wildcard
+    if (anchored) {
+        // Anchored patterns: match from the start of the relative path
+        return new RegExp(`^${escaped}(?:/.*)?$`);
+    }
+    else {
+        // Un-anchored: match the basename only (exact or prefix for directories)
+        return new RegExp(`^${escaped}(?:/.*)?$`);
+    }
+}
+//# sourceMappingURL=graphify-ignore.js.map

package/dist/graph/graphify-ignore.js.map

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

package/dist/graph/question-suggester.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Auto-generates suggested questions about the codebase knowledge graph.
+ *
+ * Graphify-style: identifies god nodes (highest centrality) and worst-rated
+ * files, then generates 4-5 questions an agent is well-positioned to answer
+ * using the existing graph tools.
+ */
+interface GNode {
+    id: string;
+    label: string;
+    rating: number;
+}
+interface GEdge {
+    source: string;
+    target: string;
+}
+export type QuestionType = 'impact' | 'dependency' | 'path' | 'health' | 'explanation' | 'callers';
+export interface SuggestedQuestion {
+    question: string;
+    type: QuestionType;
+    tool: string;
+    params: Record<string, string | number>;
+}
+/**
+ * Generate up to `maxQuestions` suggested questions from the graph topology.
+ * Questions are ordered by estimated usefulness.
+ */
+export declare function suggestQuestions(nodes: ReadonlyArray<GNode>, edges: ReadonlyArray<GEdge>, repoRoot: string, maxQuestions?: number): SuggestedQuestion[];
+export {};
+//# sourceMappingURL=question-suggester.d.ts.map

package/dist/graph/question-suggester.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-suggester.d.ts","sourceRoot":"","sources":["../../src/graph/question-suggester.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,UAAU,KAAK;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAC7D,UAAU,KAAK;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAElD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,aAAa,GAAG,SAAS,CAAC;AAEnG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAC3B,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAC3B,QAAQ,EAAE,MAAM,EAChB,YAAY,SAAI,GACf,iBAAiB,EAAE,CAmErB"}

package/dist/graph/question-suggester.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Auto-generates suggested questions about the codebase knowledge graph.
+ *
+ * Graphify-style: identifies god nodes (highest centrality) and worst-rated
+ * files, then generates 4-5 questions an agent is well-positioned to answer
+ * using the existing graph tools.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.suggestQuestions = suggestQuestions;
+const path = __importStar(require("path"));
+const graph_algorithms_1 = require("./graph-algorithms");
+const surprising_connections_1 = require("./surprising-connections");
+/**
+ * Generate up to `maxQuestions` suggested questions from the graph topology.
+ * Questions are ordered by estimated usefulness.
+ */
+function suggestQuestions(nodes, edges, repoRoot, maxQuestions = 5) {
+    if (nodes.length === 0)
+        return [];
+    const questions = [];
+    const centrality = (0, graph_algorithms_1.computeCentrality)(nodes, edges);
+    const godNodes = centrality.slice(0, 3);
+    const worstNode = [...nodes].sort((a, b) => a.rating - b.rating)[0];
+    const modules = new Set(nodes.map(n => (0, surprising_connections_1.getModule)(n.id, repoRoot)));
+    // Impact questions for god nodes
+    for (const god of godNodes.slice(0, 2)) {
+        const label = path.relative(repoRoot, god.path);
+        questions.push({
+            question: `What would break if ${label} changed?`,
+            type: 'impact',
+            tool: 'get_impact_set',
+            params: { file_path: god.path, depth: 3 },
+        });
+    }
+    // Dependency question for the most-imported node
+    const topByInDegree = centrality.sort((a, b) => b.inDegree - a.inDegree)[0];
+    if (topByInDegree) {
+        const label = path.relative(repoRoot, topByInDegree.path);
+        questions.push({
+            question: `What depends on ${label}?`,
+            type: 'dependency',
+            tool: 'get_impact_set',
+            params: { file_path: topByInDegree.path, depth: 1 },
+        });
+    }
+    // Path question: god node → worst rated file
+    if (godNodes[0] && worstNode && worstNode.id !== godNodes[0]?.path) {
+        const srcLabel = path.relative(repoRoot, godNodes[0].path);
+        const tgtLabel = path.relative(repoRoot, worstNode.id);
+        questions.push({
+            question: `How does ${srcLabel} connect to ${tgtLabel} (lowest-rated file)?`,
+            type: 'path',
+            tool: 'trace_path',
+            params: { source: godNodes[0].path, target: worstNode.id },
+        });
+    }
+    // Health question for worst-rated file
+    if (worstNode && worstNode.rating < 7) {
+        const label = path.relative(repoRoot, worstNode.id);
+        questions.push({
+            question: `How unhealthy is ${label} and what should be fixed first?`,
+            type: 'health',
+            tool: 'suggest_refactoring',
+            params: { file_path: worstNode.id },
+        });
+    }
+    // Module-level question if multiple modules exist
+    if (modules.size > 2 && godNodes[0]) {
+        const label = path.relative(repoRoot, godNodes[0].path);
+        questions.push({
+            question: `Which modules does ${label} bridge, and is that coupling intentional?`,
+            type: 'explanation',
+            tool: 'explain_node',
+            params: { file_path: godNodes[0].path },
+        });
+    }
+    return questions.slice(0, maxQuestions);
+}
+//# sourceMappingURL=question-suggester.js.map

package/dist/graph/question-suggester.js.map

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

package/dist/graph/relationship-extractor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * AST-based semantic relationship extractor.
+ *
+ * Piggybacks on the TypeScript Compiler API (ts.createSourceFile) to extract
+ * relationships the existing import-only dependency graph misses:
+ *
+ *   FUNCTION_CALL   — file A calls an imported function from file B
+ *   CLASS_EXTENDS   — file A's class extends an imported class from file B
+ *   IMPLEMENTS      — file A's class implements an imported interface from file B
+ *   COMMENTS_ABOUT  — "why:", "rationale:", JSDoc summaries embedded as WhyNodes
+ *
+ * Confidence is always EXTRACTED (direct AST evidence) for calls/heritage and
+ * INFERRED for JSDoc (not always a hard relationship).
+ *
+ * Usage:
+ *   const extractor = new RelationshipExtractor();
+ *   const result = extractor.extractFromFile(filePath, knownFilesSet);
+ */
+import { EnrichedEdge, WhyNode } from './relationship-types';
+export interface ExtractionResult {
+    enrichedEdges: EnrichedEdge[];
+    whyComments: WhyNode[];
+}
+export declare class RelationshipExtractor {
+    /**
+     * Extract semantic relationships from a single file.
+     *
+     * @param filePath   Absolute path to analyze.
+     * @param knownFiles Set of absolute paths already tracked in the graph.
+     *                   Only imports resolving to known files generate edges.
+     */
+    extractFromFile(filePath: string, knownFiles: ReadonlySet<string>): ExtractionResult;
+    private buildImportMap;
+    private extractFunctionCalls;
+    private resolveCalleeName;
+    private extractClassRelations;
+    private extractWhyComments;
+    private resolveModule;
+}
+//# sourceMappingURL=relationship-extractor.d.ts.map

package/dist/graph/relationship-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-extractor.d.ts","sourceRoot":"","sources":["../../src/graph/relationship-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EAAE,YAAY,EAAE,OAAO,EAA0C,MAAM,sBAAsB,CAAC;AAErG,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,WAAW,EAAE,OAAO,EAAE,CAAC;CACxB;AAUD,qBAAa,qBAAqB;IAChC;;;;;;OAMG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,gBAAgB;IAsBpF,OAAO,CAAC,cAAc;IA8CtB,OAAO,CAAC,oBAAoB;IAmC5B,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,qBAAqB;IAoC7B,OAAO,CAAC,kBAAkB;IA0C1B,OAAO,CAAC,aAAa;CAYtB"}