@sean.holung/minicode 0.3.2 → 0.3.3

package/dist/tests/serve.integration.test.js

@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
 import { test, afterEach } from "node:test";
 import { createServer } from "node:http";
 import { mkdirSync, writeFileSync, rmSync } from "node:fs";
-import { createRequestHandler } from "../src/serve/server.js";
+import { createRequestHandler, shutdownServe } from "../src/serve/server.js";
 import { AgentBridge } from "../src/serve/agent-bridge.js";
 import { createTestAgentConfig } from "./test-utils.js";
 /**
@@ -11,6 +11,7 @@ import { createTestAgentConfig } from "./test-utils.js";
  */
 class MockBridge extends AgentBridge {
     _busy = false;
+    _currentSessionId = "sess-1";
     turnHistory = [];
     constructor() {
         super(() => { }, false);
@@ -66,6 +67,9 @@ class MockBridge extends AgentBridge {
             return null;
         return { session: {}, label };
     }
+    getCurrentSessionId() {
+        return this._currentSessionId;
+    }
     setBusy(busy) {
         this._busy = busy;
     }
@@ -113,6 +117,71 @@ class MockBridge extends AgentBridge {
             edges: [{ from: "foo", to: "Bar", kind: "calls" }],
         };
     }
+    getStructuralAnalysis() {
+        return {
+            version: 1,
+            findings: [
+                {
+                    id: "hotspot:foo",
+                    type: "hotspot",
+                    severity: "warning",
+                    title: "foo is a structural hotspot",
+                    summary: "foo has total degree 4.",
+                    symbols: ["foo"],
+                    files: ["src/foo.ts"],
+                    metrics: {
+                        totalDegree: 4,
+                        fanIn: 1,
+                        fanOut: 3,
+                        threshold: 4,
+                        score: 4,
+                    },
+                    rationale: ["Total degree exceeds the deterministic hotspot threshold."],
+                },
+            ],
+            symbolMetrics: [
+                {
+                    qualifiedName: "foo",
+                    name: "foo",
+                    kind: "function",
+                    filePath: "src/foo.ts",
+                    spanLines: 12,
+                    fanIn: 1,
+                    fanOut: 3,
+                    totalDegree: 4,
+                    inboundKinds: ["calls"],
+                    outboundKinds: ["calls"],
+                },
+            ],
+            fileMetrics: [
+                {
+                    filePath: "src/foo.ts",
+                    symbolCount: 1,
+                    incomingEdgeCount: 1,
+                    outgoingEdgeCount: 3,
+                    internalEdgeCount: 0,
+                    afferentCoupling: 1,
+                    efferentCoupling: 2,
+                    totalCoupling: 3,
+                    instability: 0.667,
+                },
+            ],
+            summary: {
+                symbolCount: 2,
+                edgeCount: 1,
+                fileCount: 2,
+                findingCount: 1,
+                cycleCount: 0,
+                hotspotCount: 1,
+                thresholds: {
+                    fanIn: 3,
+                    fanOut: 3,
+                    hotspot: 4,
+                    fileCoupling: 3,
+                },
+            },
+        };
+    }
     getPinnedSymbols() {
         return [...this._pinned];
     }
@@ -170,6 +239,13 @@ class MockBridge extends AgentBridge {
         onEvent({ type: "streaming_chunk", content: `Explaining ${name}...` });
         return `Explaining ${name}...`;
     }
+    async explainStructuralFinding(findingId, onEvent) {
+        if (findingId !== "hotspot:foo") {
+            throw new Error(`Structural finding "${findingId}" not found`);
+        }
+        onEvent({ type: "streaming_chunk", content: `Interpreting ${findingId}...` });
+        return `Interpreting ${findingId}...`;
+    }
 }
 // ── Test harness ──
 let activeServer;
@@ -220,7 +296,7 @@ test("GET /api/status returns busy when agent is busy", async () => {
     const body = (await res.json());
     assert.equal(body.status, "busy");
 });
-test("GET /api/config returns formatted config", async () => {
+test("GET /api/config returns formatted config plus structured settings", async () => {
     const bridge = new MockBridge();
     const base = await startTestServer(bridge);
     const res = await fetch(`${base}/api/config`);
@@ -228,6 +304,10 @@ test("GET /api/config returns formatted config", async () => {
     const body = (await res.json());
     assert.ok(body.config.includes("workspaceRoot"));
     assert.ok(body.config.includes("test-model"));
+    assert.equal(body.restartRequired, true);
+    assert.equal(body.secretsUiSupported, false);
+    assert.ok(body.settings.configPath.endsWith("/.minicode/agent.config.json"));
+    assert.ok(body.settings.entries.some((entry) => entry.key === "maxSteps"));
 });
 test("GET /api/sessions returns session list", async () => {
     const bridge = new MockBridge();
@@ -236,6 +316,8 @@ test("GET /api/sessions returns session list", async () => {
     assert.equal(res.status, 200);
     const body = (await res.json());
     assert.equal(body.sessions.length, 1);
+    assert.equal(body.currentSessionId, "sess-1");
+    assert.equal(body.sessions[0].id, "sess-1");
     assert.equal(body.sessions[0].label, "test-session");
 });
 test("POST /api/sessions/save saves a session", async () => {
@@ -526,6 +608,59 @@ test("GET /api/graph returns nodes and edges", async () => {
     assert.equal(body.edges[0].to, "Bar");
     assert.equal(body.edges[0].kind, "calls");
 });
+test("GET /api/analysis returns deterministic structural findings", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/analysis`);
+    assert.equal(res.status, 200);
+    const body = (await res.json());
+    assert.equal(body.version, 1);
+    assert.equal(body.summary.hotspotCount, 1);
+    assert.equal(body.summary.findingCount, 1);
+    assert.equal(body.findings[0]?.type, "hotspot");
+    assert.deepEqual(body.findings[0]?.symbols, ["foo"]);
+});
+test("POST /api/analysis/explain returns SSE stream", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/analysis/explain`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ findingId: "hotspot:foo" }),
+    });
+    assert.equal(res.status, 200);
+    assert.equal(res.headers.get("content-type"), "text/event-stream");
+    const text = await res.text();
+    assert.ok(text.includes("Interpreting hotspot:foo"));
+    assert.ok(text.includes("[DONE]"));
+});
+test("POST /api/analysis/explain rejects missing finding id", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/analysis/explain`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({}),
+    });
+    assert.equal(res.status, 400);
+    assert.deepEqual(await res.json(), { error: "findingId is required" });
+});
+test("POST /api/analysis/explain streams error event for unknown finding", async () => {
+    const bridge = new MockBridge();
+    const base = await startTestServer(bridge);
+    const res = await fetch(`${base}/api/analysis/explain`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ findingId: "missing" }),
+    });
+    assert.equal(res.status, 200);
+    const text = await res.text();
+    const errorLine = text.split("\n").find((line) => line.startsWith("data: {") && line.includes('"type":"error"'));
+    assert.ok(errorLine);
+    const payload = JSON.parse(errorLine.slice(6));
+    assert.equal(payload.type, "error");
+    assert.equal(payload.message, 'Structural finding "missing" not found');
+});
 test("GET /api/focus returns pinned symbols", async () => {
     const bridge = new MockBridge();
     const base = await startTestServer(bridge);
@@ -757,3 +892,84 @@ test("GET /api/symbols/:name/explain returns error for unknown symbol", async ()
     const text = await res.text();
     assert.ok(text.includes("error"));
 });
+// ── Graceful shutdown tests ──
+test("shutdownServe terminates WebSocket clients and calls exit(0)", async () => {
+    const bridge = new MockBridge();
+    const handler = createRequestHandler(bridge);
+    const server = createServer(handler);
+    const { WebSocketServer, WebSocket } = await import("ws");
+    const wss = new WebSocketServer({ server });
+    const openSockets = new Set();
+    server.on("connection", (socket) => {
+        openSockets.add(socket);
+        socket.on("close", () => openSockets.delete(socket));
+    });
+    // Start server on random port
+    await new Promise((resolve) => {
+        server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const addr = server.address();
+    // Connect a WebSocket client (simulates browser tab)
+    const ws = new WebSocket(`ws://127.0.0.1:${addr.port}`);
+    await new Promise((resolve) => ws.on("open", resolve));
+    assert.ok(wss.clients.size >= 1, "Should have at least 1 WS client connected");
+    assert.ok(openSockets.size >= 1, "Should have at least 1 open socket");
+    // Call shutdownServe with a mock exit function
+    let exitCode;
+    shutdownServe(server, wss, openSockets, (code) => {
+        exitCode = code;
+    });
+    // Wait a tick for async cleanup to propagate
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    assert.equal(exitCode, 0, "Should have called exit with code 0");
+    assert.equal(openSockets.size, 0, "All sockets should be cleared");
+    assert.equal(wss.clients.size, 0, "All WS clients should be removed");
+});
+test("shutdownServe works when no clients are connected", async () => {
+    const bridge = new MockBridge();
+    const handler = createRequestHandler(bridge);
+    const server = createServer(handler);
+    const { WebSocketServer } = await import("ws");
+    const wss = new WebSocketServer({ server });
+    const openSockets = new Set();
+    await new Promise((resolve) => {
+        server.listen(0, "127.0.0.1", () => resolve());
+    });
+    let exitCode;
+    shutdownServe(server, wss, openSockets, (code) => {
+        exitCode = code;
+    });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    assert.equal(exitCode, 0, "Should exit cleanly with no clients");
+});
+test("shutdownServe terminates multiple WebSocket clients", async () => {
+    const bridge = new MockBridge();
+    const handler = createRequestHandler(bridge);
+    const server = createServer(handler);
+    const { WebSocketServer, WebSocket } = await import("ws");
+    const wss = new WebSocketServer({ server });
+    const openSockets = new Set();
+    server.on("connection", (socket) => {
+        openSockets.add(socket);
+        socket.on("close", () => openSockets.delete(socket));
+    });
+    await new Promise((resolve) => {
+        server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const addr = server.address();
+    // Connect 3 WebSocket clients
+    const clients = [];
+    for (let i = 0; i < 3; i++) {
+        const ws = new WebSocket(`ws://127.0.0.1:${addr.port}`);
+        await new Promise((resolve) => ws.on("open", resolve));
+        clients.push(ws);
+    }
+    assert.equal(wss.clients.size, 3, "Should have 3 WS clients connected");
+    let exitCode;
+    shutdownServe(server, wss, openSockets, (code) => {
+        exitCode = code;
+    });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    assert.equal(exitCode, 0, "Should have called exit with code 0");
+    assert.equal(openSockets.size, 0, "All sockets should be cleared");
+});

package/dist/tests/session-ui.test.js

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { test } from "node:test";
+const distWeb = join(import.meta.dirname, "..", "dist", "src", "web");
+test("built HTML contains update action for the current saved session", () => {
+    const html = readFileSync(join(distWeb, "index.html"), "utf8");
+    assert.ok(html.includes('id="session-update-row"'), "HTML should contain the session update row");
+    assert.ok(html.includes('id="session-update-btn"'), "HTML should contain the session update button");
+});
+test("built CSS contains active-session styling", () => {
+    const css = readFileSync(join(distWeb, "style.css"), "utf8");
+    assert.ok(css.includes(".session-item.active"), "CSS should style the active saved session row");
+    assert.ok(css.includes(".session-active-badge"), "CSS should style the active session badge");
+});
+test("built JS contains active saved session update logic", () => {
+    const js = readFileSync(join(distWeb, "app.js"), "utf8");
+    assert.ok(js.includes("activeSavedSession"), "JS should track the active saved session");
+    assert.ok(js.includes("currentSessionId"), "JS should read the current session id from the sessions API");
+    assert.ok(js.includes("Session updated:"), "JS should emit the update confirmation message");
+});

package/dist/tests/session.test.js

@@ -35,3 +35,53 @@ test("trim keeps recent messages while reducing token estimate", () => {
     assert.equal(messages[1]?.role, "tool");
     assert.equal(messages[2]?.role, "assistant");
 });
+test("shrinkToolResults does not mutate original message objects", () => {
+    const session = new Session("test");
+    session.addMessage({ role: "user", content: "go" });
+    session.addMessage({
+        role: "assistant",
+        content: "calling tool",
+        toolCalls: [{ id: "t1", name: "read_file", input: { path: "x" } }],
+    });
+    const toolMsg = {
+        role: "tool",
+        toolCallId: "t1",
+        toolName: "read_file",
+        content: "original-tool-output-that-is-long-enough-to-be-summarized",
+    };
+    session.addMessage(toolMsg);
+    session.addMessage({ role: "assistant", content: "done" });
+    // Get a reference to the messages before trimming
+    const beforeTrim = session.getMessages();
+    const toolBefore = beforeTrim.find((m) => m.role === "tool");
+    assert.ok(toolBefore);
+    const originalContent = toolBefore.content;
+    // Trim to trigger shrinkToolResults
+    session.trim(30, 2);
+    // The original message object captured before trim should be unchanged
+    assert.equal(toolBefore.content, originalContent, "original message object should not be mutated");
+});
+test("shrinkToolResults replaces message in array instead of mutating", () => {
+    const session = new Session("test");
+    session.addMessage({ role: "user", content: "go" });
+    session.addMessage({
+        role: "assistant",
+        content: "calling tool",
+        toolCalls: [{ id: "t1", name: "search", input: { query: "foo" } }],
+    });
+    session.addMessage({
+        role: "tool",
+        toolCallId: "t1",
+        toolName: "search",
+        content: "a]".repeat(500),
+    });
+    session.addMessage({ role: "user", content: "thanks" });
+    session.addMessage({ role: "assistant", content: "ok" });
+    session.trim(50, 2);
+    const after = session.getMessages();
+    const toolAfter = after.find((m) => m.role === "tool");
+    // If the tool message survived trimming, its content should be summarized
+    if (toolAfter) {
+        assert.ok(toolAfter.content.startsWith("[summary:"), "tool result should be summarized after trim");
+    }
+});

package/dist/tests/settings-ui.test.js

@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { test } from "node:test";
+const distWeb = join(import.meta.dirname, "..", "dist", "src", "web");
+test("built HTML contains settings entry point and modal shell", () => {
+    const html = readFileSync(join(distWeb, "index.html"), "utf8");
+    assert.ok(html.includes('id="settings-btn"'), "HTML should contain the settings button");
+    assert.ok(html.includes('id="settings-modal"'), "HTML should contain the settings modal");
+    assert.ok(!html.includes('id="settings-scope"'), "HTML should no longer contain the settings scope selector");
+    assert.ok(html.includes('id="settings-save"'), "HTML should contain the settings save action");
+});
+test("built CSS contains modal and settings layout styles", () => {
+    const css = readFileSync(join(distWeb, "style.css"), "utf8");
+    assert.ok(css.includes(".modal-panel"), "CSS should contain modal panel styles");
+    assert.ok(css.includes(".settings-list"), "CSS should contain settings list styles");
+    assert.ok(css.includes(".settings-item-meta"), "CSS should contain settings metadata grid styles");
+    assert.ok(css.includes(".settings-help-warning"), "CSS should contain warning styling for env overrides");
+    assert.ok(css.includes("body.modal-open"), "CSS should lock scroll while the settings modal is open");
+});
+test("built JS contains config loading and saving logic for settings", () => {
+    const js = readFileSync(join(distWeb, "app.js"), "utf8");
+    assert.ok(js.includes("/api/config"), "JS should fetch the config API");
+    assert.ok(js.includes("Save settings"), "JS should contain the settings save action text");
+    assert.ok(js.includes("settingsPayload"), "JS should track settings payload state");
+    assert.ok(js.includes("persistedValue"), "JS should wire persisted settings behavior");
+    assert.ok(js.includes("settings-help settings-help-warning"), "JS should mark env override help as warning text");
+    assert.ok(js.includes("home-dotenv"), "JS should distinguish home dotenv overrides");
+    assert.ok(js.includes("manage this setting here"), "JS should explain how to resolve env overrides");
+});

package/dist/tests/structural-analysis.test.js

@@ -0,0 +1,218 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { analyzeProjectStructure } from "../src/analysis/structural-analysis.js";
+import { createProjectIndex } from "../src/indexer/project-index.js";
+function makeSymbol(qualifiedName, filePath, kind = "function", startLine = 1, endLine = 5) {
+    const shortName = qualifiedName.includes(".")
+        ? qualifiedName.slice(qualifiedName.lastIndexOf(".") + 1)
+        : qualifiedName;
+    return {
+        name: shortName,
+        qualifiedName,
+        kind,
+        filePath,
+        startLine,
+        endLine,
+        signature: `${kind} ${qualifiedName}`,
+        exported: true,
+        dependencies: [],
+    };
+}
+function buildTestIndex(symbols, edges) {
+    const symbolMap = new Map();
+    const fileMap = new Map();
+    for (const symbol of symbols) {
+        symbolMap.set(symbol.qualifiedName, symbol);
+        const list = fileMap.get(symbol.filePath);
+        if (list) {
+            list.push(symbol);
+        }
+        else {
+            fileMap.set(symbol.filePath, [symbol]);
+        }
+    }
+    return createProjectIndex(symbolMap, fileMap, edges, [], new Map(), "/tmp/test-workspace");
+}
+test("analyzeProjectStructure reports cycles, symbol outliers, and file coupling", () => {
+    const symbols = [
+        makeSymbol("entry", "src/entry.ts"),
+        makeSymbol("service", "src/service.ts"),
+        makeSymbol("repo", "src/repo.ts"),
+        makeSymbol("util", "src/util.ts"),
+        makeSymbol("cycleA", "src/cycle.ts"),
+        makeSymbol("cycleB", "src/cycle.ts"),
+    ];
+    const edges = [
+        { from: "entry", to: "service", kind: "calls" },
+        { from: "entry", to: "util", kind: "calls" },
+        { from: "service", to: "repo", kind: "calls" },
+        { from: "service", to: "util", kind: "calls" },
+        { from: "service", to: "cycleA", kind: "calls" },
+        { from: "repo", to: "util", kind: "calls" },
+        { from: "repo", to: "cycleA", kind: "calls" },
+        { from: "cycleA", to: "cycleB", kind: "calls" },
+        { from: "cycleB", to: "cycleA", kind: "calls" },
+    ];
+    const report = analyzeProjectStructure(buildTestIndex(symbols, edges));
+    assert.equal(report.version, 1);
+    assert.equal(report.summary.symbolCount, 6);
+    assert.equal(report.summary.edgeCount, 9);
+    assert.equal(report.summary.fileCount, 5);
+    assert.ok(report.summary.findingCount >= 5);
+    assert.equal(report.summary.cycleCount, 1);
+    assert.equal(report.summary.thresholds.fanIn, 3);
+    assert.equal(report.summary.thresholds.fanOut, 3);
+    assert.equal(report.summary.thresholds.hotspot, 4);
+    assert.equal(report.summary.thresholds.fileCoupling, 4);
+    const cycleFinding = report.findings.find((finding) => finding.type === "cycle");
+    assert.ok(cycleFinding);
+    assert.deepEqual(cycleFinding?.symbols, ["cycleA", "cycleB"]);
+    assert.equal(cycleFinding?.severity, "warning");
+    const fanInFinding = report.findings.find((finding) => finding.type === "fanInOutlier" && finding.symbols.includes("util"));
+    assert.ok(fanInFinding);
+    assert.equal(fanInFinding?.metrics.fanIn, 3);
+    const hotspotFinding = report.findings.find((finding) => finding.type === "hotspot" && finding.symbols.includes("service"));
+    assert.ok(hotspotFinding);
+    assert.equal(hotspotFinding?.metrics.totalDegree, 4);
+    assert.ok(!report.findings.some((finding) => finding.type === "fanOutOutlier" && finding.symbols.includes("service")), "hotspot findings should absorb overlapping fan-out outliers for the same symbol");
+    const fileFinding = report.findings.find((finding) => finding.type === "fileCoupling" && finding.files.includes("src/service.ts"));
+    assert.ok(fileFinding);
+    assert.equal(fileFinding?.metrics.totalCoupling, 4);
+    assert.equal(fileFinding?.metrics.instability, 0.75);
+    const serviceMetric = report.symbolMetrics.find((metric) => metric.qualifiedName === "service");
+    assert.ok(serviceMetric);
+    assert.equal(serviceMetric?.totalDegree, 4);
+    const serviceFileMetric = report.fileMetrics.find((metric) => metric.filePath === "src/service.ts");
+    assert.ok(serviceFileMetric);
+    assert.equal(serviceFileMetric?.totalCoupling, 4);
+});
+test("analyzeProjectStructure stays empty for disconnected graphs", () => {
+    const symbols = [
+        makeSymbol("alpha", "src/alpha.ts"),
+        makeSymbol("beta", "src/beta.ts"),
+    ];
+    const report = analyzeProjectStructure(buildTestIndex(symbols, []));
+    assert.equal(report.findings.length, 0);
+    assert.equal(report.summary.cycleCount, 0);
+    assert.equal(report.fileMetrics.length, 2);
+    assert.equal(report.symbolMetrics[0]?.totalDegree, 0);
+});
+test("analyzeProjectStructure avoids flagging routine fan-out in skewed graphs", () => {
+    const symbols = [makeSymbol("sharedUtil", "src/shared.ts")];
+    const edges = [];
+    for (let i = 0; i < 40; i += 1) {
+        const worker = `worker${i}`;
+        symbols.push(makeSymbol(worker, `src/workers/${worker}.ts`));
+        edges.push({ from: worker, to: "sharedUtil", kind: "calls" });
+    }
+    for (let i = 0; i < 5; i += 1) {
+        const orchestrator = `orchestrator${i}`;
+        symbols.push(makeSymbol(orchestrator, `src/orchestrators/${orchestrator}.ts`, "function", 1, 80));
+        for (let j = 0; j < 10; j += 1) {
+            const leaf = `${orchestrator}.leaf${j}`;
+            symbols.push(makeSymbol(leaf, `src/orchestrators/${orchestrator}.ts`));
+            edges.push({ from: orchestrator, to: leaf, kind: "calls" });
+        }
+    }
+    const report = analyzeProjectStructure(buildTestIndex(symbols, edges));
+    assert.equal(report.summary.thresholds.fanOut, 10);
+    const fanOutFindings = report.findings.filter((finding) => finding.type === "fanOutOutlier");
+    assert.equal(fanOutFindings.length, 5);
+    assert.ok(fanOutFindings.every((finding) => finding.symbols[0]?.startsWith("orchestrator")));
+    assert.ok(report.findings.every((finding) => !finding.symbols.includes("worker0")));
+});
+test("analyzeProjectStructure keeps fan-out findings for non-hotspot orchestrators", () => {
+    const symbols = [
+        makeSymbol("orchestrator", "src/orchestrator.ts", "function", 1, 80),
+    ];
+    const edges = [];
+    for (let i = 0; i < 3; i += 1) {
+        const shared = `shared${i}`;
+        symbols.push(makeSymbol(shared, `src/shared/${shared}.ts`));
+        edges.push({ from: "orchestrator", to: shared, kind: "calls" });
+    }
+    const report = analyzeProjectStructure(buildTestIndex(symbols, edges));
+    const fanOutFinding = report.findings.find((finding) => finding.type === "fanOutOutlier" && finding.symbols.includes("orchestrator"));
+    assert.ok(fanOutFinding, "high fan-out should still surface when the symbol is not also a hotspot");
+    assert.ok(!report.findings.some((finding) => finding.type === "hotspot" && finding.symbols.includes("orchestrator")), "fan-out only orchestrators should not be forced into hotspot findings");
+});
+test("analyzeProjectStructure ignores self-recursive loops and suppresses shared type hubs", () => {
+    const symbols = [
+        makeSymbol("SharedConfig", "src/types.ts", "interface"),
+        makeSymbol("loadConfig", "src/load.ts"),
+        makeSymbol("saveConfig", "src/save.ts"),
+        makeSymbol("runConfigFlow", "src/flow.ts"),
+        makeSymbol("walk", "src/walk.ts"),
+    ];
+    const edges = [
+        { from: "loadConfig", to: "SharedConfig", kind: "references" },
+        { from: "saveConfig", to: "SharedConfig", kind: "references" },
+        { from: "runConfigFlow", to: "SharedConfig", kind: "references" },
+        { from: "walk", to: "walk", kind: "calls" },
+    ];
+    const report = analyzeProjectStructure(buildTestIndex(symbols, edges));
+    assert.ok(!report.findings.some((finding) => finding.type === "cycle"), "self-recursion should not surface as a cycle finding");
+    assert.ok(!report.findings.some((finding) => finding.type !== "fileCoupling" && finding.symbols.includes("SharedConfig")), "shared type/interface hubs should not produce symbol-level findings by default");
+});
+test("analyzeProjectStructure suppresses contract modules and composition roots at the file level", () => {
+    const symbols = [
+        makeSymbol("SharedConfig", "src/types.ts", "interface"),
+        makeSymbol("SharedEvent", "src/types.ts", "type"),
+        makeSymbol("loadConfig", "src/load.ts"),
+        makeSymbol("saveConfig", "src/save.ts"),
+        makeSymbol("runWorkflow", "src/run.ts"),
+        makeSymbol("auditWorkflow", "src/audit.ts"),
+        makeSymbol("bridgeRuntime", "src/bridge.ts"),
+        makeSymbol("buildShell", "src/bootstrap.ts"),
+        makeSymbol("helperA", "src/helpers/a.ts"),
+        makeSymbol("helperB", "src/helpers/b.ts"),
+        makeSymbol("helperC", "src/helpers/c.ts"),
+        makeSymbol("helperD", "src/helpers/d.ts"),
+    ];
+    const edges = [
+        { from: "loadConfig", to: "SharedConfig", kind: "references" },
+        { from: "saveConfig", to: "SharedConfig", kind: "references" },
+        { from: "runWorkflow", to: "SharedConfig", kind: "references" },
+        { from: "auditWorkflow", to: "SharedEvent", kind: "references" },
+        { from: "loadConfig", to: "bridgeRuntime", kind: "calls" },
+        { from: "saveConfig", to: "bridgeRuntime", kind: "calls" },
+        { from: "bridgeRuntime", to: "helperA", kind: "calls" },
+        { from: "bridgeRuntime", to: "helperB", kind: "calls" },
+        { from: "buildShell", to: "helperA", kind: "calls" },
+        { from: "buildShell", to: "helperB", kind: "calls" },
+        { from: "buildShell", to: "helperC", kind: "calls" },
+        { from: "buildShell", to: "helperD", kind: "calls" },
+    ];
+    const report = analyzeProjectStructure(buildTestIndex(symbols, edges));
+    const fileCouplingFiles = report.findings
+        .filter((finding) => finding.type === "fileCoupling")
+        .flatMap((finding) => finding.files);
+    assert.ok(!fileCouplingFiles.includes("src/types.ts"), "pure contract modules should not surface as file-coupling smells");
+    assert.ok(!fileCouplingFiles.includes("src/bootstrap.ts"), "obvious composition roots should not surface as file-coupling smells");
+    assert.ok(fileCouplingFiles.includes("src/bridge.ts"), "runtime bridge files with meaningful inbound and outbound coupling should still surface");
+});
+test("analyzeProjectStructure suppresses small composition-root hotspot symbols but keeps long orchestrators", () => {
+    const symbols = [
+        makeSymbol("composeTools", "src/registry.ts", "function", 1, 28),
+        makeSymbol("runRuntime", "src/runtime.ts", "function", 1, 120),
+    ];
+    const edges = [];
+    for (let i = 0; i < 3; i += 1) {
+        const caller = `caller${i}`;
+        symbols.push(makeSymbol(caller, `src/callers/${caller}.ts`));
+        edges.push({ from: caller, to: "composeTools", kind: "calls" });
+    }
+    for (let i = 0; i < 12; i += 1) {
+        const dep = `dep${i}`;
+        symbols.push(makeSymbol(dep, `src/deps/${dep}.ts`));
+        edges.push({ from: "composeTools", to: dep, kind: "calls" });
+    }
+    for (let i = 0; i < 16; i += 1) {
+        const dep = `runtimeDep${i}`;
+        symbols.push(makeSymbol(dep, `src/runtime/deps/${dep}.ts`));
+        edges.push({ from: "runRuntime", to: dep, kind: "calls" });
+    }
+    const report = analyzeProjectStructure(buildTestIndex(symbols, edges));
+    assert.ok(!report.findings.some((finding) => finding.symbols.includes("composeTools")), "small composition-root helpers should not surface as structural outliers by default");
+    assert.ok(report.findings.some((finding) => finding.symbols.includes("runRuntime")), "long orchestrators should still surface when they fan out broadly");
+});