weavatrix 0.2.13 → 0.2.14

package/src/analysis/source-correctness.js

@@ -0,0 +1,225 @@
+// Conservative source-level correctness review signals. These checks deliberately recognize only
+// a few grounded patterns with local evidence; they are not a compiler, race detector, or proof that
+// the surrounding behavior is wrong.
+import { makeFinding } from "./findings.js";
+import {retryFindings} from './source-correctness/retry-patterns.js'
+
+const lineAt = (text, index) => {
+  let line = 1;
+  for (let i = 0; i < index && i < text.length; i++) if (text[i] === "\n") line++;
+  return line;
+};
+
+const lineText = (text, index) => {
+  const start = text.lastIndexOf("\n", Math.max(0, index - 1)) + 1;
+  const end = text.indexOf("\n", index);
+  return text.slice(start, end < 0 ? text.length : end).trim().slice(0, 300);
+};
+
+// Preserve byte offsets/newlines while removing comments and string contents from regex input.
+function maskNonCode(text, { hashComments = false } = {}) {
+  const chars = String(text || "").split("");
+  let quote = "", escaped = false, lineComment = false, blockComment = false;
+  for (let i = 0; i < chars.length; i++) {
+    const ch = chars[i], next = chars[i + 1];
+    if (lineComment) {
+      if (ch === "\n" || ch === "\r") lineComment = false;
+      else chars[i] = " ";
+      continue;
+    }
+    if (blockComment) {
+      if (ch === "*" && next === "/") { chars[i] = chars[i + 1] = " "; i++; blockComment = false; }
+      else if (ch !== "\n" && ch !== "\r") chars[i] = " ";
+      continue;
+    }
+    if (quote) {
+      if (ch !== "\n" && ch !== "\r") chars[i] = " ";
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === quote) quote = "";
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") { quote = ch; chars[i] = " "; continue; }
+    if (hashComments && ch === "#") { chars[i] = " "; lineComment = true; continue; }
+    if (ch === "/" && next === "/") { chars[i] = chars[i + 1] = " "; i++; lineComment = true; continue; }
+    if (ch === "/" && next === "*") { chars[i] = chars[i + 1] = " "; i++; blockComment = true; }
+  }
+  return chars.join("");
+}
+
+function balancedEnd(text, openAt) {
+  if (text[openAt] !== "{") return -1;
+  let depth = 0;
+  for (let i = openAt; i < text.length; i++) {
+    if (text[i] === "{") depth++;
+    else if (text[i] === "}" && --depth === 0) return i + 1;
+  }
+  return -1;
+}
+
+const escapeRegex = (value) => String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const upperSnake = (value) => String(value || "")
+  .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+  .replace(/[^A-Za-z0-9]+/g, "_")
+  .replace(/^_+|_+$/g, "")
+  .toUpperCase();
+
+function goFunctions(masked) {
+  const functions = [];
+  const re = /\bfunc\s+(?:\([^)]*\)\s*)?([A-Za-z_]\w*)\s*\(([^)]*)\)[^{]*\{/g;
+  let match;
+  while ((match = re.exec(masked))) {
+    const open = re.lastIndex - 1;
+    const end = balancedEnd(masked, open);
+    if (end < 0) continue;
+    functions.push({ name: match[1], params: match[2], open, end, body: masked.slice(open + 1, end - 1) });
+    re.lastIndex = end;
+  }
+  return functions;
+}
+
+function goSliceFindings(text, masked, file) {
+  const findings = [];
+  for (const fn of goFunctions(masked)) {
+    const sliceParams = [...fn.params.matchAll(/(?:^|,)\s*([A-Za-z_]\w*)\s+\[\][^,)]*/g)].map((match) => match[1]);
+    for (const parameter of sliceParams) {
+      const slice = new RegExp(`\\b${escapeRegex(parameter)}\\s*\\[\\s*(?:0\\s*)?:\\s*(\\d+)\\s*\\]`, "g").exec(fn.body);
+      if (!slice || Number(slice[1]) < 1) continue;
+      const before = fn.body.slice(0, slice.index);
+      const lenGuard = new RegExp(`\\blen\\s*\\(\\s*${escapeRegex(parameter)}\\s*\\)`).test(before);
+      if (lenGuard) continue;
+      const index = fn.open + 1 + slice.index;
+      findings.push(makeFinding({
+        category: "structure",
+        rule: "go-unguarded-fixed-slice",
+        severity: "medium",
+        confidence: "high",
+        title: `Potential slice-bounds panic in ${fn.name}: ${parameter}[:${slice[1]}]`,
+        detail: `The slice parameter "${parameter}" is read to a fixed upper bound before any visible len(${parameter}) guard in this function. Confirm every caller guarantees at least ${slice[1]} element(s), or guard the access locally.`,
+        file,
+        line: lineAt(text, index),
+        symbol: `${fn.name}()`,
+        evidence: [{ file, line: lineAt(text, index), snippet: lineText(text, index) }],
+        fixHint: `validate len(${parameter}) >= ${slice[1]} before slicing`,
+      }));
+    }
+  }
+  return findings;
+}
+
+function goConstructorTypeFindings(text, masked, file) {
+  const findings = [];
+  for (const fn of goFunctions(masked)) {
+    if (!/^New[A-Z]/.test(fn.name)) continue;
+    const suffix = upperSnake(fn.name.slice(3));
+    if (!suffix) continue;
+    const assigned = /\b(?:Type|Kind)\s*:\s*([A-Z][A-Z0-9_]*(?:_TYPE_|_KIND_)[A-Z0-9_]+)\b/g.exec(fn.body);
+    if (!assigned) continue;
+    const markerAt = Math.max(assigned[1].lastIndexOf("_TYPE_"), assigned[1].lastIndexOf("_KIND_"));
+    const markerLength = 6;
+    const expected = `${assigned[1].slice(0, markerAt + markerLength)}${suffix}`;
+    if (expected === assigned[1] || !new RegExp(`\\b${escapeRegex(expected)}\\b`).test(masked)) continue;
+    const index = fn.open + 1 + assigned.index;
+    findings.push(makeFinding({
+      category: "structure",
+      rule: "constructor-enum-mismatch",
+      severity: "medium",
+      confidence: "high",
+      title: `Constructor/type discriminator mismatch: ${fn.name} uses ${assigned[1]}`,
+      detail: `The constructor name corresponds to the declared discriminator ${expected}, but the returned literal assigns ${assigned[1]}. This is a focused copy/paste review signal; confirm the intended wire type before changing it.`,
+      file,
+      line: lineAt(text, index),
+      symbol: `${fn.name}()`,
+      evidence: [{ file, line: lineAt(text, index), snippet: lineText(text, index) }],
+      fixHint: `verify whether the discriminator should be ${expected}`,
+    }));
+  }
+  return findings;
+}
+
+function javaInterruptFindings(text, masked, file) {
+  const findings = [];
+  const re = /\bcatch\s*\(\s*InterruptedException\s+([A-Za-z_]\w*)\s*\)\s*\{/g;
+  let match;
+  while ((match = re.exec(masked))) {
+    const open = re.lastIndex - 1;
+    const end = balancedEnd(masked, open);
+    if (end < 0) continue;
+    const body = masked.slice(open + 1, end - 1);
+    const restores = /\bThread\s*\.\s*currentThread\s*\(\s*\)\s*\.\s*interrupt\s*\(/.test(body);
+    const rethrows = new RegExp(`\\bthrow\\s+${escapeRegex(match[1])}\\s*;`).test(body)
+      || /\bthrow\s+new\s+InterruptedException\b/.test(body);
+    if (restores || rethrows) continue;
+    findings.push(makeFinding({
+      category: "structure",
+      rule: "java-interrupt-status-not-restored",
+      severity: "medium",
+      confidence: "high",
+      title: "InterruptedException caught without a visible interrupt restore",
+      detail: "The catch block neither directly rethrows InterruptedException nor calls Thread.currentThread().interrupt(). A helper may restore it indirectly, so review before changing; otherwise cancellation can be lost.",
+      file,
+      line: lineAt(text, match.index),
+      evidence: [{ file, line: lineAt(text, match.index), snippet: lineText(text, match.index) }],
+      fixHint: "restore the interrupt status or propagate the interruption according to the method contract",
+    }));
+    re.lastIndex = end;
+  }
+  return findings;
+}
+
+export function analyzeSourceCorrectness(sources, { isNonProductPath = () => false } = {}) {
+  const findings = [];
+  const supportedRuntimeFiles = new Set();
+  const concurrencyFiles = new Set();
+  const checks = {
+    goFixedSlice: { supportedFiles: 0, findings: 0 },
+    constructorDiscriminator: { supportedFiles: 0, findings: 0 },
+    javaInterrupt: { supportedFiles: 0, findings: 0 },
+    retryTermination: { supportedFiles: 0, findings: 0 },
+  };
+  for (const [file, source] of sources || []) {
+    if (isNonProductPath(file)) continue;
+    const text = String(source || "");
+    const go = /\.go$/i.test(file), java = /\.java$/i.test(file), python = /\.py$/i.test(file);
+    const masked = maskNonCode(text, { hashComments: python });
+    const retrySupported = /\.(?:[cm]?[jt]sx?|java|go|py)$/i.test(file);
+    if (go) {
+      supportedRuntimeFiles.add(file);
+      checks.goFixedSlice.supportedFiles++;
+      checks.constructorDiscriminator.supportedFiles++;
+      const slice = goSliceFindings(text, masked, file);
+      const discriminator = goConstructorTypeFindings(text, masked, file);
+      findings.push(...slice, ...discriminator);
+      checks.goFixedSlice.findings += slice.length;
+      checks.constructorDiscriminator.findings += discriminator.length;
+    }
+    if (java) {
+      supportedRuntimeFiles.add(file);
+      concurrencyFiles.add(file);
+      checks.javaInterrupt.supportedFiles++;
+      const interruption = javaInterruptFindings(text, masked, file);
+      findings.push(...interruption);
+      checks.javaInterrupt.findings += interruption.length;
+    }
+    if (retrySupported) {
+      supportedRuntimeFiles.add(file);
+      checks.retryTermination.supportedFiles++;
+      const retry = retryFindings(text, masked, file, {python});
+      findings.push(...retry);
+      checks.retryTermination.findings += retry.length;
+    }
+  }
+  return {
+    findings,
+    coverage: {
+      runtimeCorrectnessFiles: supportedRuntimeFiles.size,
+      concurrencyFiles: concurrencyFiles.size,
+      checks,
+      limitations: [
+        "bounded source patterns only",
+        "no compiler or runtime execution",
+        "no race detector; race freedom is not claimed",
+      ],
+    },
+  };
+}

package/src/analysis/structure/dependency-graph.js

@@ -0,0 +1,156 @@
+import {ENTRY_FILE} from '../dead-check.js'
+
+const TEST_FILE_RE = /(^|[/])(test|tests|__tests__|spec|e2e|__mocks__)([/]|$)|[._-](test|spec)\.[a-z0-9]+$/i
+const NON_CODE_RE = /\.(json|ya?ml|sh|ps1|md|txt|html?|css|scss|less)$|(^|[/])(dockerfile|containerfile)/i
+const endpoint = (value) => String(value && typeof value === 'object' ? value.id : value)
+const fileOf = (value) => {
+    const id = endpoint(value)
+    const hash = id.indexOf('#')
+    return hash < 0 ? id : id.slice(0, hash)
+}
+const dirOf = (file) => file.includes('/') ? file.slice(0, file.lastIndexOf('/')) : ''
+
+export function buildFileImportGraph(graph, {includeTypeOnly = false, includeCompileOnly = false} = {}) {
+    const fileIds = new Set()
+    for (const node of graph.nodes || []) if (!String(node.id).includes('#')) fileIds.add(String(node.id))
+    const runtimeAdj = new Map(), allAdj = new Map()
+    const edges = [], allEdges = [], typeOnlyEdges = [], compileOnlyEdges = [], compileTimeEdges = []
+    const runtimeSeen = new Set(), allSeen = new Set(), typeSeen = new Set(), compileSeen = new Set(), compileTimeSeen = new Set()
+    const add = (map, source, target) => {
+        let targets = map.get(source)
+        if (!targets) map.set(source, (targets = new Set()))
+        targets.add(target)
+    }
+    for (const link of graph.links || []) {
+        if (link.relation !== 'imports' && link.relation !== 're_exports') continue
+        const source = endpoint(link.source), target = endpoint(link.target)
+        if (!fileIds.has(source) || !fileIds.has(target) || source === target) continue
+        if (source.endsWith('.go') && target.endsWith('.go') && dirOf(source) === dirOf(target)) continue
+        const key = `${source}\0${target}`
+        if (!allSeen.has(key)) { allSeen.add(key); add(allAdj, source, target); allEdges.push([source, target]) }
+        if (link.typeOnly === true || link.compileOnly === true) {
+            if (link.typeOnly === true && !typeSeen.has(key)) { typeSeen.add(key); typeOnlyEdges.push([source, target]) }
+            if (link.compileOnly === true && !compileSeen.has(key)) { compileSeen.add(key); compileOnlyEdges.push([source, target]) }
+            if (!compileTimeSeen.has(key)) { compileTimeSeen.add(key); compileTimeEdges.push([source, target]) }
+            continue
+        }
+        if (!runtimeSeen.has(key)) { runtimeSeen.add(key); add(runtimeAdj, source, target); edges.push([source, target]) }
+    }
+    return {
+        fileIds,
+        adj: includeTypeOnly || includeCompileOnly ? allAdj : runtimeAdj,
+        edges: includeTypeOnly || includeCompileOnly ? allEdges : edges,
+        runtimeAdj,
+        runtimeEdges: edges,
+        allAdj,
+        allEdges,
+        typeOnlyEdges: typeOnlyEdges.filter(([a, b]) => !runtimeSeen.has(`${a}\0${b}`)),
+        compileOnlyEdges: compileOnlyEdges.filter(([a, b]) => !runtimeSeen.has(`${a}\0${b}`)),
+        compileTimeEdges: compileTimeEdges.filter(([a, b]) => !runtimeSeen.has(`${a}\0${b}`)),
+    }
+}
+
+// Iterative Tarjan: repository graphs can be deep enough to overflow recursive JavaScript.
+export function findSccs(adjacency) {
+    const index = new Map(), low = new Map(), onStack = new Set(), nodes = []
+    let counter = 0
+    const components = []
+    for (const root of adjacency.keys()) {
+        if (index.has(root)) continue
+        index.set(root, counter); low.set(root, counter); counter++
+        nodes.push(root); onStack.add(root)
+        const stack = [{value: root, child: 0, neighbors: [...(adjacency.get(root) || [])]}]
+        while (stack.length) {
+            const frame = stack[stack.length - 1]
+            if (frame.child < frame.neighbors.length) {
+                const next = frame.neighbors[frame.child++]
+                if (!index.has(next)) {
+                    index.set(next, counter); low.set(next, counter); counter++
+                    nodes.push(next); onStack.add(next)
+                    stack.push({value: next, child: 0, neighbors: [...(adjacency.get(next) || [])]})
+                } else if (onStack.has(next)) low.set(frame.value, Math.min(low.get(frame.value), index.get(next)))
+                continue
+            }
+            stack.pop()
+            if (stack.length) {
+                const parent = stack[stack.length - 1]
+                low.set(parent.value, Math.min(low.get(parent.value), low.get(frame.value)))
+            }
+            if (low.get(frame.value) !== index.get(frame.value)) continue
+            const component = []
+            let value
+            do { value = nodes.pop(); onStack.delete(value); component.push(value) } while (value !== frame.value)
+            if (component.length > 1) components.push(component)
+        }
+    }
+    return components
+}
+
+export function representativeCycle(adjacency, component) {
+    const members = new Set(component)
+    const start = [...component].sort()[0]
+    const previous = new Map([[start, null]])
+    const queue = [start]
+    while (queue.length) {
+        const current = queue.shift()
+        for (const next of [...(adjacency.get(current) || [])].sort()) {
+            if (next === start) {
+                const path = []
+                for (let value = current; value != null; value = previous.get(value)) path.push(value)
+                return [...path.reverse(), start]
+            }
+            if (!members.has(next) || previous.has(next)) continue
+            previous.set(next, current)
+            queue.push(next)
+        }
+    }
+    const fallback = [...component].sort()
+    return [...fallback, fallback[0]]
+}
+
+export function findOrphans(graph, {entrySet = new Set(), externalImportFiles = new Set()} = {}) {
+    const degree = new Map()
+    for (const link of graph.links || []) {
+        if (link.relation === 'contains') continue
+        const source = fileOf(link.source), target = fileOf(link.target)
+        if (source === target) continue
+        degree.set(source, (degree.get(source) || 0) + 1)
+        degree.set(target, (degree.get(target) || 0) + 1)
+    }
+    const out = []
+    for (const node of graph.nodes || []) {
+        const id = String(node.id)
+        if (id.includes('#') || (degree.get(id) || 0) > 0) continue
+        const file = node.source_file
+        if (entrySet.has(file) || ENTRY_FILE.test(file) || TEST_FILE_RE.test(file) || NON_CODE_RE.test(file)) continue
+        out.push({file, importsExternals: externalImportFiles.has(file)})
+    }
+    return out
+}
+
+export function globToRe(glob) {
+    const parts = String(glob).split('**').map((part) => part
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]'))
+    let source = parts.join('.*')
+    source = source.replace(/\/\.\*\//g, '/(?:.*/)?').replace(/^\.\*\//, '(?:.*/)?')
+    return new RegExp(`^${source}$`)
+}
+
+export function checkBoundaries(edges, rules = {}) {
+    const violations = []
+    const forbidden = (rules.forbidden || []).map((rule) => ({...rule, fromRe: globToRe(rule.from), toRe: globToRe(rule.to)}))
+    const allowedOnly = (rules.allowedOnly || []).map((rule) => ({
+        ...rule,
+        fromRe: globToRe(rule.from),
+        toRes: (Array.isArray(rule.to) ? rule.to : [rule.to]).map(globToRe),
+    }))
+    for (const [source, target] of edges) {
+        for (const rule of forbidden) if (rule.fromRe.test(source) && rule.toRe.test(target)) {
+            violations.push({name: rule.name, comment: rule.comment || '', severity: rule.severity, from: source, to: target, kind: 'forbidden'})
+        }
+        for (const rule of allowedOnly) if (rule.fromRe.test(source) && !rule.toRes.some((regexp) => regexp.test(target))) {
+            violations.push({name: rule.name, comment: rule.comment || '', severity: rule.severity, from: source, to: target, kind: 'allowedOnly'})
+        }
+    }
+    return violations
+}

package/src/analysis/structure/findings.js

@@ -0,0 +1,142 @@
+import {makeFinding} from '../findings.js'
+import {formatRepresentativeCycle} from '../cycle-route.js'
+import {
+    buildFileImportGraph,
+    checkBoundaries,
+    findOrphans,
+    findSccs,
+    representativeCycle,
+} from './dependency-graph.js'
+
+const MAX_CYCLE_FINDINGS = 50
+const MAX_BOUNDARY_FINDINGS = 100
+
+const edgeCountIn = (component, edges) => {
+    const inside = new Set(component)
+    return edges.reduce((count, [source, target]) => count + (inside.has(source) && inside.has(target) ? 1 : 0), 0)
+}
+
+function runtimeCycleFinding(adjacency, component) {
+    const cycle = representativeCycle(adjacency, component)
+    const cycleRoute = formatRepresentativeCycle(cycle)
+    return makeFinding({
+        category: 'structure',
+        rule: 'circular-dep',
+        severity: component.length > 4 ? 'high' : 'medium',
+        confidence: 'high',
+        title: `Circular dependency: ${component.length} files`,
+        detail: `${cycleRoute}${component.length + 1 > cycle.length ? ` (representative loop; the tangle spans ${component.length} files)` : ''}. Break the cycle by extracting the shared piece or inverting one import.`,
+        cycleRoute,
+        cycleMembers: [...component].sort(),
+        file: cycle[0],
+        graphNodeId: cycle[0],
+        evidence: cycle.map((file) => ({file, line: 0, snippet: ''})),
+        source: 'internal',
+        fixHint: 'extract the shared code into a module both sides import, or invert the weaker dependency',
+    })
+}
+
+function compileTimeFinding(adjacency, component, runtimeComponents, edges) {
+    const cycle = representativeCycle(adjacency, component)
+    const cycleRoute = formatRepresentativeCycle(cycle)
+    const runtimeInside = edgeCountIn(component, edges.runtime)
+    const typeInside = edgeCountIn(component, edges.typeOnly)
+    const compileInside = edgeCountIn(component, edges.compileOnly)
+    const containsRuntimeCycle = runtimeComponents.some((runtime) => runtime.every((file) => component.includes(file)))
+    const typeSpecific = compileInside === 0
+    return makeFinding({
+        category: 'structure',
+        rule: typeSpecific ? 'type-coupling' : 'compile-time-coupling',
+        severity: 'info',
+        confidence: 'high',
+        title: `${containsRuntimeCycle
+            ? (typeSpecific ? 'Type imports expand dependency coupling' : 'Compile-time edges expand dependency coupling')
+            : (typeSpecific ? 'Type-induced dependency cycle (no runtime cycle)' : 'Compile-time dependency cycle (no runtime cycle)')}: ${component.length} files`,
+        detail: `${cycleRoute}. This strongly-connected group needs compile-time-only edges to close; it contains ${runtimeInside} runtime edge(s), ${typeInside} type-only edge(s), and ${compileInside} compile-only edge(s)${containsRuntimeCycle ? ', with a smaller runtime cycle reported separately' : ', while its runtime import graph is acyclic'}. Treat this as design coupling, not an initialization-order failure.`,
+        cycleRoute,
+        cycleMembers: [...component].sort(),
+        file: cycle[0],
+        graphNodeId: cycle[0],
+        evidence: cycle.map((file) => ({file, line: 0, snippet: ''})),
+        source: 'internal',
+        fixHint: 'review the compile-time ownership only if the coupling impedes changes; no runtime-cycle fix is required',
+    })
+}
+
+export function computeStructureFindings(graph, {rules = {}, entrySet = new Set(), externalImportFiles = new Set()} = {}) {
+    const imports = buildFileImportGraph(graph)
+    const findings = []
+    const runtimeComponents = findSccs(imports.adj).sort((a, b) => b.length - a.length)
+    for (const component of runtimeComponents.slice(0, MAX_CYCLE_FINDINGS)) {
+        findings.push(runtimeCycleFinding(imports.adj, component))
+    }
+
+    const runtimeKeys = new Set(runtimeComponents.map((component) => [...component].sort().join('\0')))
+    const allComponents = findSccs(imports.allAdj).sort((a, b) => b.length - a.length)
+    const compileTimeCouplings = allComponents.filter((component) => !runtimeKeys.has([...component].sort().join('\0')))
+    for (const component of compileTimeCouplings.slice(0, MAX_CYCLE_FINDINGS)) {
+        findings.push(compileTimeFinding(imports.allAdj, component, runtimeComponents, {
+            runtime: imports.edges,
+            typeOnly: imports.typeOnlyEdges,
+            compileOnly: imports.compileOnlyEdges,
+        }))
+    }
+    if (runtimeComponents.length > MAX_CYCLE_FINDINGS) findings.push(makeFinding({
+        category: 'structure', rule: 'circular-dep', severity: 'info', confidence: 'high',
+        title: `…and ${runtimeComponents.length - MAX_CYCLE_FINDINGS} more dependency cycles`,
+        detail: `Cycle findings are capped at ${MAX_CYCLE_FINDINGS}; ${runtimeComponents.length} strongly-connected groups exist in total.`,
+        source: 'internal',
+    }))
+
+    for (const orphan of findOrphans(graph, {entrySet, externalImportFiles})) findings.push(makeFinding({
+        category: 'structure',
+        rule: 'orphan-file',
+        severity: 'info',
+        confidence: orphan.importsExternals ? 'low' : 'medium',
+        title: `Orphan file: ${orphan.file}`,
+        detail: `No repo file imports it and it imports/calls nothing in the repo${orphan.importsExternals ? ' (it does use npm packages — possibly a standalone script or tool)' : ''}. Possibly dead, possibly an undeclared entry point.`,
+        file: orphan.file,
+        graphNodeId: orphan.file,
+        source: 'internal',
+    }))
+
+    const violations = checkBoundaries(imports.edges, rules)
+    for (const item of violations.slice(0, MAX_BOUNDARY_FINDINGS)) findings.push(makeFinding({
+        category: 'structure',
+        rule: 'boundary-violation',
+        severity: ['critical', 'high', 'medium', 'low', 'info'].includes(item.severity) ? item.severity : 'medium',
+        confidence: 'high',
+        title: `Boundary violation (${item.name}): ${item.from} → ${item.to}`,
+        detail: `${item.kind === 'allowedOnly' ? 'Import leaves the allowed set' : 'Forbidden import'}${item.comment ? `: ${item.comment}` : ''}.`,
+        file: item.from,
+        graphNodeId: item.from,
+        evidence: [{file: item.from, line: 0, snippet: `imports ${item.to}`}],
+        source: 'internal',
+    }))
+    if (violations.length > MAX_BOUNDARY_FINDINGS) findings.push(makeFinding({
+        category: 'structure', rule: 'boundary-violation', severity: 'info', confidence: 'high',
+        title: `…and ${violations.length - MAX_BOUNDARY_FINDINGS} more boundary violations`,
+        detail: `Boundary findings are capped at ${MAX_BOUNDARY_FINDINGS}; ${violations.length} edges violate the rules in total.`,
+        source: 'internal',
+    }))
+
+    return {
+        findings,
+        stats: {
+            importEdges: imports.allEdges.length,
+            runtimeImportEdges: imports.edges.length,
+            typeOnlyImportEdges: imports.typeOnlyEdges.length,
+            compileOnlyImportEdges: imports.compileOnlyEdges.length,
+            compileTimeImportEdges: imports.compileTimeEdges.length,
+            cycles: runtimeComponents.length,
+            runtimeCycles: runtimeComponents.length,
+            largestCycle: runtimeComponents[0]?.length || 0,
+            typeCouplings: compileTimeCouplings.length,
+            largestTypeCoupling: compileTimeCouplings[0]?.length || 0,
+            compileTimeCouplings: compileTimeCouplings.length,
+            largestCompileTimeCoupling: compileTimeCouplings[0]?.length || 0,
+            orphans: findings.filter((finding) => finding.rule === 'orphan-file').length,
+            boundaryViolations: violations.length,
+        },
+    }
+}

package/src/graph/builder/go-receiver-resolution.js

@@ -0,0 +1,112 @@
+import {goTypeName} from './lang-go.js'
+
+const dirOf = (file) => file.includes('/') ? file.slice(0, file.lastIndexOf('/')) : ''
+
+export function createGoReceiverResolution({resolution, nodeById, importedLocals}) {
+    const {dirSymbols, dirMethods, dirMethodsByName, dirTypes, resolveCall} = resolution
+    const typeRef = (rawType, contextFile, fallbackDir = dirOf(contextFile)) => {
+        const raw = String(rawType || '').trim()
+        if (!raw) return null
+        const dot = raw.indexOf('.')
+        if (dot > 0) {
+            const imported = importedLocals.get(contextFile)?.get(raw.slice(0, dot))
+            return imported?.targetDir ? {dir: imported.targetDir, name: raw.slice(dot + 1)} : null
+        }
+        return {dir: fallbackDir, name: raw}
+    }
+    const fieldType = (receiver, fieldName) => {
+        if (!receiver?.name || !fieldName) return null
+        const typeId = dirTypes.get(receiver.dir)?.get(receiver.name)
+        const typeNode = typeId && nodeById.get(typeId)
+        const rawFieldType = typeNode?.field_types?.[fieldName]
+        return rawFieldType ? typeRef(rawFieldType, typeNode.source_file, receiver.dir) : null
+    }
+    const exactMethod = (receiver, methodName) => {
+        const candidates = receiver && dirMethods.get(receiver.dir)?.get(receiver.name)?.get(methodName)
+        return candidates?.length === 1 ? candidates[0] : null
+    }
+    const uniqueMethod = (dir, methodName) => {
+        const candidates = dirMethodsByName.get(dir)?.get(methodName) || []
+        return candidates.length === 1 ? candidates[0] : null
+    }
+    const returnType = (targetId, callerFile) => {
+        const target = targetId && nodeById.get(targetId)
+        return target?.return_type
+            ? typeRef(target.return_type, target.source_file || callerFile, dirOf(target.source_file || callerFile))
+            : null
+    }
+    const fieldChildren = (node, name) => {
+        const children = node?.childrenForFieldName?.(name)
+        if (Array.isArray(children) && children.length) return children
+        const child = node?.childForFieldName?.(name)
+        return child ? [child] : []
+    }
+    const receiverBindings = (selector, file) => {
+        const bindings = new Map()
+        let scope = selector
+        while (scope?.parent && !['function_declaration', 'method_declaration'].includes(scope.type)) scope = scope.parent
+        if (!scope || !['function_declaration', 'method_declaration'].includes(scope.type)) return bindings
+        const callRow = selector.startPosition.row
+        const containsCall = (node) => node.startIndex <= selector.startIndex && node.endIndex >= selector.endIndex
+        const expressionType = (node) => {
+            if (!node) return null
+            const declared = goTypeName(node)
+            if (declared) return typeRef(declared, file)
+            if (['parenthesized_expression', 'unary_expression'].includes(node.type)) {
+                return expressionType(node.childForFieldName?.('operand') || node.namedChildren?.[0])
+            }
+            if (node.type === 'composite_literal') return typeRef(goTypeName(node.childForFieldName?.('type')), file)
+            if (node.type === 'identifier') return bindings.get(node.text) || null
+            if (node.type === 'selector_expression') return fieldType(expressionType(node.childForFieldName?.('operand')), node.childForFieldName?.('field')?.text)
+            if (node.type !== 'call_expression') return null
+            const fn = node.childForFieldName?.('function')
+            if (fn?.type === 'identifier') {
+                const returned = returnType(resolveCall(fn.text, file), file)
+                if (returned) return returned
+                if (dirTypes.get(dirOf(file))?.has(fn.text)) return typeRef(fn.text, file)
+                if (/^New[A-Z_]/.test(fn.text)) return typeRef(fn.text.slice(3), file)
+            }
+            if (fn?.type === 'selector_expression') {
+                const operand = fn.childForFieldName?.('operand'), member = fn.childForFieldName?.('field')?.text
+                const imported = operand?.type === 'identifier' && importedLocals.get(file)?.get(operand.text)
+                if (imported?.targetDir && member) {
+                    const returned = returnType(dirSymbols.get(imported.targetDir)?.get(member), file)
+                    if (returned) return returned
+                    if (/^New[A-Z_]/.test(member)) return {dir: imported.targetDir, name: member.slice(3)}
+                }
+            }
+            return null
+        }
+        const bindTyped = (node) => {
+            const reference = typeRef(goTypeName(node.childForFieldName?.('type')), file)
+            const names = fieldChildren(node, 'name').filter((name) => ['identifier', 'field_identifier'].includes(name.type))
+            if (reference) for (const name of names) bindings.set(name.text, reference)
+            else if (node.type === 'var_spec') {
+                const values = node.childForFieldName?.('value')?.namedChildren || []
+                for (let index = 0; index < Math.min(names.length, values.length); index++) {
+                    const inferred = expressionType(values[index])
+                    if (inferred) bindings.set(names[index].text, inferred)
+                }
+            }
+        }
+        const bindAssignment = (node) => {
+            const left = node.childForFieldName?.('left')?.namedChildren || []
+            const right = node.childForFieldName?.('right')?.namedChildren || []
+            for (let index = 0; index < Math.min(left.length, right.length); index++) {
+                if (left[index].type !== 'identifier') continue
+                const inferred = expressionType(right[index])
+                if (inferred) bindings.set(left[index].text, inferred)
+            }
+        }
+        const visit = (node) => {
+            if (!node || node.startPosition.row > callRow) return
+            if (node !== scope && ['function_declaration', 'method_declaration', 'func_literal'].includes(node.type) && !containsCall(node)) return
+            if (['parameter_declaration', 'var_spec'].includes(node.type)) bindTyped(node)
+            else if (['short_var_declaration', 'assignment_statement'].includes(node.type)) bindAssignment(node)
+            for (const child of node.namedChildren || []) visit(child)
+        }
+        visit(scope)
+        return bindings
+    }
+    return {dirOf, fieldType, exactMethod, uniqueMethod, receiverBindings}
+}