@sean.holung/minicode 0.3.2 → 0.3.3

package/dist/src/agent/editable-config.js

@@ -0,0 +1,314 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { loadConfigFile, MINICODE_HOME, resolveConfigEnv, } from "./config.js";
+const REASONING_VALUES = [
+    "xhigh",
+    "high",
+    "medium",
+    "low",
+    "minimal",
+    "none",
+];
+export const EDITABLE_CONFIG_DEFINITIONS = [
+    {
+        key: "modelProvider",
+        fileKey: "modelProvider",
+        envVar: "MODEL_PROVIDER",
+        type: "enum",
+        values: ["anthropic", "openai-compatible"],
+        description: "Provider backend used to create the model client",
+    },
+    {
+        key: "model",
+        fileKey: "model",
+        envVar: "MODEL",
+        type: "string",
+        description: "Default model id for new sessions",
+    },
+    {
+        key: "maxSteps",
+        fileKey: "maxSteps",
+        envVar: "MAX_STEPS",
+        type: "number",
+        description: "Turn call limit before the agent pauses and waits for another prompt",
+    },
+    {
+        key: "maxTokens",
+        fileKey: "maxTokens",
+        envVar: "MAX_TOKENS",
+        type: "number",
+        description: "Maximum completion tokens per model response",
+    },
+    {
+        key: "maxContextTokens",
+        fileKey: "maxContextTokens",
+        envVar: "MAX_CONTEXT_TOKENS",
+        type: "number",
+        description: "Estimated prompt-context budget before compaction",
+    },
+    {
+        key: "commandTimeoutMs",
+        fileKey: "commandTimeout",
+        envVar: "COMMAND_TIMEOUT_MS",
+        type: "number",
+        description: "Shell command timeout in milliseconds",
+    },
+    {
+        key: "maxFileSizeBytes",
+        fileKey: "maxFileSizeBytes",
+        envVar: "MAX_FILE_SIZE_BYTES",
+        type: "number",
+        description: "Maximum file size allowed for read/edit tools",
+    },
+    {
+        key: "confirmDestructive",
+        fileKey: "confirmDestructive",
+        envVar: "CONFIRM_DESTRUCTIVE",
+        type: "boolean",
+        description: "Whether destructive commands require confirmation",
+    },
+    {
+        key: "keepRecentMessages",
+        fileKey: "keepRecentMessages",
+        envVar: "KEEP_RECENT_MESSAGES",
+        type: "number",
+        description: "Recent messages preserved when trimming session history",
+    },
+    {
+        key: "loopDetectionWindow",
+        fileKey: "loopDetectionWindow",
+        envVar: "LOOP_DETECTION_WINDOW",
+        type: "number",
+        description: "Window size for repeated-tool-call loop detection",
+    },
+    {
+        key: "maxToolOutputChars",
+        fileKey: "maxToolOutputChars",
+        envVar: "MAX_TOOL_OUTPUT_CHARS",
+        type: "number",
+        description: "Maximum tool output retained before truncation",
+    },
+    {
+        key: "openAiBaseUrl",
+        fileKey: "openAiBaseUrl",
+        envVar: "OPENAI_BASE_URL",
+        type: "string",
+        description: "Base URL for OpenAI-compatible providers",
+    },
+    {
+        key: "enableFileReadDedup",
+        fileKey: "enableFileReadDedup",
+        envVar: "ENABLE_FILE_READ_DEDUP",
+        type: "boolean",
+        description: "Deduplicate repeated file reads in prompt context",
+    },
+    {
+        key: "enableAdaptiveKeepRecent",
+        fileKey: "enableAdaptiveKeepRecent",
+        envVar: "ENABLE_ADAPTIVE_KEEP_RECENT",
+        type: "boolean",
+        description: "Adjust recent-message retention based on context pressure",
+    },
+    {
+        key: "enableToolOutputTruncation",
+        fileKey: "enableToolOutputTruncation",
+        envVar: "ENABLE_TOOL_OUTPUT_TRUNCATION",
+        type: "boolean",
+        description: "Truncate oversized tool output before storing it in session history",
+    },
+    {
+        key: "compactionThreshold",
+        fileKey: "compactionThreshold",
+        envVar: "COMPACTION_THRESHOLD",
+        type: "number",
+        description: "Compaction threshold ratio used before a turn starts",
+    },
+    {
+        key: "compactionModel",
+        fileKey: "compactionModel",
+        envVar: "COMPACTION_MODEL",
+        type: "string",
+        description: "Optional model id used for LLM-based compaction",
+    },
+    {
+        key: "reasoningEffort",
+        fileKey: "reasoningEffort",
+        envVar: "REASONING_EFFORT",
+        type: "enum",
+        values: REASONING_VALUES,
+        description: "Reasoning effort sent to supported model providers",
+    },
+    {
+        key: "enableDynamicPrompt",
+        fileKey: "enableDynamicPrompt",
+        envVar: "ENABLE_DYNAMIC_PROMPT",
+        type: "boolean",
+        description: "Toggle project-aware dynamic prompt generation",
+    },
+];
+const definitionByKey = new Map(EDITABLE_CONFIG_DEFINITIONS.map((definition) => [definition.key, definition]));
+function parseBoolean(value) {
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized)) {
+        return true;
+    }
+    if (["0", "false", "no", "off"].includes(normalized)) {
+        return false;
+    }
+    return undefined;
+}
+function parseEditableValue(definition, rawValue) {
+    if (definition.type === "number") {
+        const value = Number(rawValue);
+        if (!Number.isFinite(value)) {
+            throw new Error(`Expected a number for "${definition.key}".`);
+        }
+        return value;
+    }
+    if (definition.type === "boolean") {
+        const value = parseBoolean(rawValue);
+        if (value === undefined) {
+            throw new Error(`Expected a boolean for "${definition.key}" (true/false, yes/no, on/off).`);
+        }
+        return value;
+    }
+    if (definition.type === "enum") {
+        const normalized = rawValue.trim().toLowerCase();
+        const match = definition.values?.find((value) => value.toLowerCase() === normalized);
+        if (!match) {
+            throw new Error(`Expected one of: ${definition.values?.join(", ")}`);
+        }
+        return match;
+    }
+    const trimmed = rawValue.trim();
+    if (trimmed.length === 0) {
+        throw new Error(`Expected a non-empty value for "${definition.key}".`);
+    }
+    return trimmed;
+}
+function normalizePersistedValue(value) {
+    if (value === undefined)
+        return null;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return value;
+    }
+    return null;
+}
+function isEmptyConfigFile(config) {
+    return Object.keys(config).length === 0;
+}
+export function listEditableConfigDefinitions() {
+    return EDITABLE_CONFIG_DEFINITIONS;
+}
+export function isEditableConfigKey(value) {
+    return definitionByKey.has(value);
+}
+export function getEditableConfigDefinition(key) {
+    const definition = definitionByKey.get(key);
+    if (!definition) {
+        throw new Error(`Unknown editable config key "${key}".`);
+    }
+    return definition;
+}
+export function getEffectiveEditableConfigValue(config, key) {
+    return formatPersistedConfigValue(config[key]);
+}
+export function formatPersistedConfigValue(value) {
+    if (value === undefined)
+        return "(unset)";
+    if (value === null)
+        return "(unset)";
+    if (typeof value === "string")
+        return value;
+    return String(value);
+}
+export function getGlobalConfigPath(minicodeHome = MINICODE_HOME) {
+    return path.join(minicodeHome, "agent.config.json");
+}
+export async function loadPersistedConfig(minicodeHome = MINICODE_HOME) {
+    return loadConfigFile(getGlobalConfigPath(minicodeHome));
+}
+export async function buildStructuredConfigPayload(config, minicodeHome = MINICODE_HOME) {
+    const configPath = getGlobalConfigPath(minicodeHome);
+    const persisted = await loadPersistedConfig(minicodeHome);
+    const env = await resolveConfigEnv({ minicodeHome });
+    return {
+        configPath,
+        entries: EDITABLE_CONFIG_DEFINITIONS.map((definition) => {
+            const envValue = env.values[definition.envVar];
+            const envSource = env.sources[definition.envVar] ?? null;
+            const envSourcePath = envSource === "home-dotenv"
+                ? env.homeEnvPath
+                : null;
+            return {
+                key: definition.key,
+                type: definition.type,
+                description: definition.description,
+                envVar: definition.envVar,
+                ...(definition.values ? { values: definition.values } : {}),
+                effectiveValue: normalizePersistedValue(config[definition.key]),
+                persistedValue: normalizePersistedValue(persisted[definition.fileKey]),
+                envValue: envValue ?? null,
+                envSource,
+                envSourcePath,
+                overriddenByEnv: envValue !== undefined,
+            };
+        }),
+    };
+}
+export async function setPersistedConfigValue(options) {
+    const minicodeHome = options.minicodeHome ?? MINICODE_HOME;
+    const definition = getEditableConfigDefinition(options.key);
+    const configPath = getGlobalConfigPath(minicodeHome);
+    const nextFile = await loadConfigFile(configPath);
+    const storedValue = parseEditableValue(definition, options.rawValue);
+    nextFile[definition.fileKey] = storedValue;
+    await mkdir(path.dirname(configPath), { recursive: true });
+    await writeFile(configPath, JSON.stringify(nextFile, null, 2) + "\n", "utf8");
+    return { path: configPath, storedValue };
+}
+export async function unsetPersistedConfigValue(options) {
+    const minicodeHome = options.minicodeHome ?? MINICODE_HOME;
+    const definition = getEditableConfigDefinition(options.key);
+    const configPath = getGlobalConfigPath(minicodeHome);
+    const nextFile = await loadConfigFile(configPath);
+    delete nextFile[definition.fileKey];
+    if (isEmptyConfigFile(nextFile)) {
+        await rm(configPath, { force: true });
+    }
+    else {
+        await mkdir(path.dirname(configPath), { recursive: true });
+        await writeFile(configPath, JSON.stringify(nextFile, null, 2) + "\n", "utf8");
+    }
+    return { path: configPath };
+}
+export async function applyPersistedConfigUpdates(options) {
+    const minicodeHome = options.minicodeHome ?? MINICODE_HOME;
+    const planned = Object.entries(options.updates).map(([rawKey, value]) => {
+        if (!isEditableConfigKey(rawKey)) {
+            throw new Error(`Unknown editable config key "${rawKey}".`);
+        }
+        return { key: rawKey, value };
+    });
+    const saved = [];
+    for (const item of planned) {
+        if (item.value === null) {
+            await unsetPersistedConfigValue({
+                key: item.key,
+                minicodeHome,
+            });
+            saved.push({ key: item.key, value: null });
+            continue;
+        }
+        await setPersistedConfigValue({
+            key: item.key,
+            rawValue: String(item.value),
+            minicodeHome,
+        });
+        saved.push({ key: item.key, value: item.value });
+    }
+    return {
+        path: getGlobalConfigPath(minicodeHome),
+        saved,
+    };
+}

package/dist/src/analysis/structural-analysis.js

@@ -0,0 +1,379 @@
+function quantile(values, percentile) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const position = Math.max(0, Math.min(sorted.length - 1, Math.ceil((sorted.length - 1) * percentile)));
+    return sorted[position] ?? 0;
+}
+function thresholdFor(values, minimum, percentile = 0.9) {
+    const activeValues = values.filter((value) => value > 0);
+    return Math.max(minimum, Math.ceil(quantile(activeValues, percentile)));
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((a, b) => a.localeCompare(b));
+}
+function buildAdjacencyFrom(edges) {
+    const adjacency = new Map();
+    for (const edge of edges) {
+        const list = adjacency.get(edge.from);
+        if (list) {
+            list.push(edge.to);
+        }
+        else {
+            adjacency.set(edge.from, [edge.to]);
+        }
+    }
+    return adjacency;
+}
+function findStronglyConnectedComponents(symbols, edges) {
+    const adjacency = buildAdjacencyFrom(edges);
+    const indexByNode = new Map();
+    const lowLink = new Map();
+    const stack = [];
+    const onStack = new Set();
+    const components = [];
+    let currentIndex = 0;
+    function strongConnect(node) {
+        indexByNode.set(node, currentIndex);
+        lowLink.set(node, currentIndex);
+        currentIndex += 1;
+        stack.push(node);
+        onStack.add(node);
+        for (const next of adjacency.get(node) ?? []) {
+            if (!symbols.has(next))
+                continue;
+            if (!indexByNode.has(next)) {
+                strongConnect(next);
+                lowLink.set(node, Math.min(lowLink.get(node) ?? 0, lowLink.get(next) ?? 0));
+            }
+            else if (onStack.has(next)) {
+                lowLink.set(node, Math.min(lowLink.get(node) ?? 0, indexByNode.get(next) ?? 0));
+            }
+        }
+        if ((lowLink.get(node) ?? -1) !== (indexByNode.get(node) ?? -2)) {
+            return;
+        }
+        const component = [];
+        while (stack.length > 0) {
+            const popped = stack.pop();
+            onStack.delete(popped);
+            component.push(popped);
+            if (popped === node)
+                break;
+        }
+        components.push(component.sort((a, b) => a.localeCompare(b)));
+    }
+    for (const node of symbols.keys()) {
+        if (!indexByNode.has(node)) {
+            strongConnect(node);
+        }
+    }
+    return components;
+}
+function severityRank(severity) {
+    switch (severity) {
+        case "high":
+            return 0;
+        case "warning":
+            return 1;
+        case "info":
+            return 2;
+    }
+}
+function compareFindings(a, b) {
+    const severityDiff = severityRank(a.severity) - severityRank(b.severity);
+    if (severityDiff !== 0)
+        return severityDiff;
+    const metricA = Number(a.metrics.score ?? a.metrics.totalDegree ?? a.metrics.cycleSize ?? a.metrics.totalCoupling ?? 0);
+    const metricB = Number(b.metrics.score ?? b.metrics.totalDegree ?? b.metrics.cycleSize ?? b.metrics.totalCoupling ?? 0);
+    if (metricB !== metricA)
+        return metricB - metricA;
+    return a.title.localeCompare(b.title);
+}
+function shouldSuppressSymbolFinding(metric) {
+    return metric.kind === "interface" || metric.kind === "type";
+}
+function isSmallCompositionRootSymbol(metric) {
+    return ((metric.kind === "function" || metric.kind === "method") &&
+        metric.spanLines <= 40 &&
+        metric.fanIn <= 3 &&
+        metric.fanOut >= 8);
+}
+function isContractModule(fileSymbols, fileMetric) {
+    return (fileSymbols.length > 0 &&
+        fileMetric.efferentCoupling === 0 &&
+        fileSymbols.every((symbol) => symbol.kind === "interface" || symbol.kind === "type"));
+}
+function isCompositionRootFile(fileSymbols, fileMetric) {
+    const hasConcreteRuntimeSymbol = fileSymbols.some((symbol) => symbol.kind === "function" ||
+        symbol.kind === "class" ||
+        symbol.kind === "method" ||
+        symbol.kind === "variable");
+    return (hasConcreteRuntimeSymbol &&
+        fileMetric.symbolCount <= 6 &&
+        fileMetric.afferentCoupling <= 3 &&
+        fileMetric.instability >= 0.8);
+}
+export function analyzeProjectStructure(projectIndex) {
+    const symbols = [...projectIndex.symbols.values()].sort((a, b) => a.qualifiedName.localeCompare(b.qualifiedName));
+    const symbolMap = new Map(symbols.map((symbol) => [symbol.qualifiedName, symbol]));
+    const edges = projectIndex.dependencyEdges.filter((edge) => symbolMap.has(edge.from) && symbolMap.has(edge.to));
+    const inbound = new Map();
+    const outbound = new Map();
+    for (const edge of edges) {
+        const outList = outbound.get(edge.from);
+        if (outList) {
+            outList.push(edge);
+        }
+        else {
+            outbound.set(edge.from, [edge]);
+        }
+        const inList = inbound.get(edge.to);
+        if (inList) {
+            inList.push(edge);
+        }
+        else {
+            inbound.set(edge.to, [edge]);
+        }
+    }
+    const symbolMetrics = symbols.map((symbol) => {
+        const incoming = inbound.get(symbol.qualifiedName) ?? [];
+        const outgoing = outbound.get(symbol.qualifiedName) ?? [];
+        return {
+            qualifiedName: symbol.qualifiedName,
+            name: symbol.name,
+            kind: symbol.kind,
+            filePath: symbol.filePath,
+            spanLines: Math.max(1, symbol.endLine - symbol.startLine + 1),
+            fanIn: incoming.length,
+            fanOut: outgoing.length,
+            totalDegree: incoming.length + outgoing.length,
+            inboundKinds: uniqueSorted(incoming.map((edge) => edge.kind)),
+            outboundKinds: uniqueSorted(outgoing.map((edge) => edge.kind)),
+        };
+    });
+    const fileAccumulators = new Map();
+    for (const symbol of symbols) {
+        const existing = fileAccumulators.get(symbol.filePath);
+        if (existing) {
+            existing.symbolCount += 1;
+        }
+        else {
+            fileAccumulators.set(symbol.filePath, {
+                filePath: symbol.filePath,
+                symbolCount: 1,
+                incomingEdgeCount: 0,
+                outgoingEdgeCount: 0,
+                internalEdgeCount: 0,
+                inboundFiles: new Set(),
+                outboundFiles: new Set(),
+            });
+        }
+    }
+    for (const edge of edges) {
+        const fromSymbol = symbolMap.get(edge.from);
+        const toSymbol = symbolMap.get(edge.to);
+        if (!fromSymbol || !toSymbol)
+            continue;
+        const fromFile = fileAccumulators.get(fromSymbol.filePath);
+        const toFile = fileAccumulators.get(toSymbol.filePath);
+        if (!fromFile || !toFile)
+            continue;
+        fromFile.outgoingEdgeCount += 1;
+        toFile.incomingEdgeCount += 1;
+        if (fromSymbol.filePath === toSymbol.filePath) {
+            fromFile.internalEdgeCount += 1;
+            continue;
+        }
+        fromFile.outboundFiles.add(toSymbol.filePath);
+        toFile.inboundFiles.add(fromSymbol.filePath);
+    }
+    const fileMetrics = [...fileAccumulators.values()]
+        .map((fileMetric) => {
+        const afferentCoupling = fileMetric.inboundFiles.size;
+        const efferentCoupling = fileMetric.outboundFiles.size;
+        const totalCoupling = afferentCoupling + efferentCoupling;
+        const denominator = afferentCoupling + efferentCoupling;
+        const instability = denominator === 0 ? 0 : Number((efferentCoupling / denominator).toFixed(3));
+        return {
+            filePath: fileMetric.filePath,
+            symbolCount: fileMetric.symbolCount,
+            incomingEdgeCount: fileMetric.incomingEdgeCount,
+            outgoingEdgeCount: fileMetric.outgoingEdgeCount,
+            internalEdgeCount: fileMetric.internalEdgeCount,
+            afferentCoupling,
+            efferentCoupling,
+            totalCoupling,
+            instability,
+        };
+    })
+        .sort((a, b) => a.filePath.localeCompare(b.filePath));
+    const thresholds = {
+        fanIn: thresholdFor(symbolMetrics.map((metric) => metric.fanIn), 3, 0.98),
+        fanOut: thresholdFor(symbolMetrics.map((metric) => metric.fanOut), 3, 0.98),
+        hotspot: thresholdFor(symbolMetrics.map((metric) => metric.totalDegree), 4, 0.99),
+        fileCoupling: thresholdFor(fileMetrics.map((metric) => metric.totalCoupling), 3, 0.95),
+    };
+    const fileSymbolsByPath = new Map();
+    for (const symbol of symbols) {
+        const list = fileSymbolsByPath.get(symbol.filePath);
+        if (list) {
+            list.push(symbol);
+        }
+        else {
+            fileSymbolsByPath.set(symbol.filePath, [symbol]);
+        }
+    }
+    const findings = [];
+    const components = findStronglyConnectedComponents(symbolMap, edges);
+    for (const component of components) {
+        const componentSet = new Set(component);
+        const cycleEdges = edges.filter((edge) => componentSet.has(edge.from) && componentSet.has(edge.to));
+        if (component.length < 2) {
+            continue;
+        }
+        const files = uniqueSorted(component
+            .map((qualifiedName) => symbolMap.get(qualifiedName)?.filePath)
+            .filter((value) => Boolean(value)));
+        findings.push({
+            id: `cycle:${component.join("->")}`,
+            type: "cycle",
+            severity: component.length >= 3 ? "high" : "warning",
+            title: `Cycle across ${component.length} symbols`,
+            summary: `${component.length} symbols participate in a strongly connected component.`,
+            symbols: component,
+            files,
+            metrics: {
+                cycleSize: component.length,
+                edgeCount: cycleEdges.length,
+                fileCount: files.length,
+            },
+            rationale: [
+                "Strongly connected component detected using deterministic cycle analysis.",
+                `Cycle includes ${cycleEdges.length} internal dependency edges across ${files.length} file(s).`,
+            ],
+        });
+    }
+    for (const metric of symbolMetrics) {
+        if (shouldSuppressSymbolFinding(metric) || isSmallCompositionRootSymbol(metric)) {
+            continue;
+        }
+        const isHotspot = metric.totalDegree >= thresholds.hotspot && metric.totalDegree > 0;
+        if (!isHotspot && metric.fanIn >= thresholds.fanIn && metric.fanIn > 0) {
+            findings.push({
+                id: `fanin:${metric.qualifiedName}`,
+                type: "fanInOutlier",
+                severity: metric.fanIn >= thresholds.hotspot ? "warning" : "info",
+                title: `${metric.qualifiedName} has unusually high fan-in`,
+                summary: `${metric.qualifiedName} is referenced by ${metric.fanIn} inbound dependencies.`,
+                symbols: [metric.qualifiedName],
+                files: [metric.filePath],
+                metrics: {
+                    fanIn: metric.fanIn,
+                    threshold: thresholds.fanIn,
+                },
+                rationale: [
+                    `Inbound dependency count (${metric.fanIn}) meets or exceeds the current fan-in threshold (${thresholds.fanIn}).`,
+                    "High fan-in can indicate a central dependency or change hotspot.",
+                ],
+            });
+        }
+        if (!isHotspot && metric.fanOut >= thresholds.fanOut && metric.fanOut > 0) {
+            findings.push({
+                id: `fanout:${metric.qualifiedName}`,
+                type: "fanOutOutlier",
+                severity: metric.fanOut >= thresholds.hotspot ? "warning" : "info",
+                title: `${metric.qualifiedName} has unusually high fan-out`,
+                summary: `${metric.qualifiedName} depends on ${metric.fanOut} outbound symbols.`,
+                symbols: [metric.qualifiedName],
+                files: [metric.filePath],
+                metrics: {
+                    fanOut: metric.fanOut,
+                    threshold: thresholds.fanOut,
+                },
+                rationale: [
+                    `Outbound dependency count (${metric.fanOut}) meets or exceeds the current fan-out threshold (${thresholds.fanOut}).`,
+                    "High fan-out can indicate orchestration logic or a symbol with broad coupling.",
+                ],
+            });
+        }
+        if (isHotspot) {
+            findings.push({
+                id: `hotspot:${metric.qualifiedName}`,
+                type: "hotspot",
+                severity: metric.totalDegree >= thresholds.hotspot + 2 ? "warning" : "info",
+                title: `${metric.qualifiedName} is a structural hotspot`,
+                summary: `${metric.qualifiedName} has total degree ${metric.totalDegree} (${metric.fanIn} in / ${metric.fanOut} out).`,
+                symbols: [metric.qualifiedName],
+                files: [metric.filePath],
+                metrics: {
+                    totalDegree: metric.totalDegree,
+                    fanIn: metric.fanIn,
+                    fanOut: metric.fanOut,
+                    threshold: thresholds.hotspot,
+                    score: metric.totalDegree,
+                },
+                rationale: [
+                    `Total graph degree (${metric.totalDegree}) meets or exceeds the hotspot threshold (${thresholds.hotspot}).`,
+                    "High total degree suggests a node that concentrates incoming and outgoing dependencies.",
+                ],
+            });
+        }
+    }
+    for (const metric of fileMetrics) {
+        if (metric.totalCoupling < thresholds.fileCoupling || metric.totalCoupling === 0) {
+            continue;
+        }
+        const fileSymbolEntries = fileSymbolsByPath.get(metric.filePath) ?? [];
+        if (isContractModule(fileSymbolEntries, metric) ||
+            isCompositionRootFile(fileSymbolEntries, metric)) {
+            continue;
+        }
+        const fileSymbols = fileSymbolEntries.map((symbol) => symbol.qualifiedName);
+        findings.push({
+            id: `file-coupling:${metric.filePath}`,
+            type: "fileCoupling",
+            severity: metric.totalCoupling >= thresholds.fileCoupling + 2 ? "warning" : "info",
+            title: `${metric.filePath} has elevated file-level coupling`,
+            summary: `${metric.filePath} has afferent coupling ${metric.afferentCoupling}, efferent coupling ${metric.efferentCoupling}, and instability ${metric.instability}.`,
+            symbols: fileSymbols,
+            files: [metric.filePath],
+            metrics: {
+                afferentCoupling: metric.afferentCoupling,
+                efferentCoupling: metric.efferentCoupling,
+                totalCoupling: metric.totalCoupling,
+                instability: metric.instability,
+                threshold: thresholds.fileCoupling,
+                score: metric.totalCoupling,
+            },
+            rationale: [
+                `Distinct file coupling count (${metric.totalCoupling}) meets or exceeds the file-coupling threshold (${thresholds.fileCoupling}).`,
+                "Instability is computed as efferent / (afferent + efferent) using cross-file edges only.",
+            ],
+        });
+    }
+    findings.sort(compareFindings);
+    return {
+        version: 1,
+        findings,
+        symbolMetrics: [...symbolMetrics].sort((a, b) => {
+            if (b.totalDegree !== a.totalDegree)
+                return b.totalDegree - a.totalDegree;
+            return a.qualifiedName.localeCompare(b.qualifiedName);
+        }),
+        fileMetrics: [...fileMetrics].sort((a, b) => {
+            if (b.totalCoupling !== a.totalCoupling)
+                return b.totalCoupling - a.totalCoupling;
+            return a.filePath.localeCompare(b.filePath);
+        }),
+        summary: {
+            symbolCount: symbolMetrics.length,
+            edgeCount: edges.length,
+            fileCount: fileMetrics.length,
+            findingCount: findings.length,
+            cycleCount: findings.filter((finding) => finding.type === "cycle").length,
+            hotspotCount: findings.filter((finding) => finding.type === "hotspot").length,
+            thresholds,
+        },
+    };
+}