syncstaff-mcp 0.2.3

package/dist/lib/index/graph.js

@@ -0,0 +1,234 @@
+import { resolvePythonModule, resolveSpecifier } from "./resolve.js";
+import { byCodeUnit } from "./order.js";
+/**
+ * Build the graph. Pure: same index in, same graph out, byte for byte.
+ *
+ * Determinism is not tidiness here. The graph is summarised into a fingerprint
+ * that two machines compare to decide whether they are looking at the same
+ * repository; if iteration order could change the output, that comparison
+ * would fail for reasons that have nothing to do with the code.
+ */
+export function buildDependencyGraph(index) {
+    const known = new Set(index.files.map((file) => file.path));
+    /**
+     * Which Python file declares each exported name, where exactly one does.
+     *
+     * Built because specifier strings are the wrong primitive for a Python graph.
+     * `from sqlalchemy import create_engine` names a package, and resolving the
+     * string can only reach `sqlalchemy/__init__.py` — so every symbol imported
+     * through a facade collapsed onto the same handful of package files. Measured
+     * on that graph, expansion promoted the right file 6.8% of the time against
+     * 13.0% on TypeScript, and complete misses went up rather than down.
+     *
+     * The parser recorded the imported *names* alongside the specifier all along;
+     * the resolver discarded them. Binding a name to its declaring file turns a
+     * facade edge into a leaf edge: `create_engine` resolves to
+     * `lib/sqlalchemy/engine/create.py`, not to the package root.
+     *
+     * Only unambiguous names are indexed. A name defined in several files cannot
+     * be bound without knowing which one the importer meant, and guessing would
+     * invent an edge — the failure this graph exists to avoid. On sqlalchemy 55.3%
+     * of imported symbol references are uniquely defined; on pydantic 23.0%.
+     */
+    const pythonDeclarations = new Map();
+    for (const file of index.files) {
+        if (!file.path.endsWith(".py") && !file.path.endsWith(".pyi"))
+            continue;
+        for (const definition of file.result.definitions ?? []) {
+            if (!definition.exported)
+                continue;
+            const existing = pythonDeclarations.get(definition.name);
+            // null marks a name seen in more than one file: ambiguous, never bound.
+            pythonDeclarations.set(definition.name, existing === undefined ? file.path : existing === file.path ? existing : null);
+        }
+    }
+    const nodes = [];
+    const edges = [];
+    const unresolved = [];
+    const external = new Set();
+    for (const file of index.files) {
+        nodes.push({
+            path: file.path,
+            language: file.language,
+            exports: file.result.exports.map((exported) => ({
+                name: exported.name,
+                kind: exported.kind,
+                confidence: exported.confidence,
+            })),
+        });
+        for (const imported of file.result.imports) {
+            if (imported.dynamic) {
+                // Only a specifier *built* at runtime is unresolvable. `import("./x.js")`
+                // is a string literal and is as knowable as a static import — the
+                // parser already separates the two, marking a literal `probable` and a
+                // computed one `speculative`, and it records `<computed>` for the
+                // latter precisely so this can tell them apart.
+                //
+                // Treating both as unresolved dropped every lazily-loaded edge in the
+                // codebase. In this repository that removed 10 of the 27 edges out of
+                // `src/mcp/index.ts` — the highest fan-out file there is, and the one
+                // whose blast radius most needs to be right.
+                const resolution = imported.specifier === "<computed>"
+                    ? null
+                    : resolveSpecifier(imported.specifier, file.path, known, index.aliases ?? []);
+                if (resolution?.kind === "internal") {
+                    edges.push({
+                        from: file.path,
+                        to: resolution.path,
+                        names: [...imported.names].sort(),
+                        confidence: downgrade(imported.confidence, resolution.via),
+                        via: resolution.via,
+                        ...(imported.typeOnly ? { typeOnly: true } : {}),
+                        dynamic: true,
+                    });
+                    continue;
+                }
+                if (resolution?.kind === "external") {
+                    external.add(resolution.module);
+                    continue;
+                }
+                unresolved.push({
+                    from: file.path,
+                    specifier: imported.specifier,
+                    reason: resolution
+                        ? resolution.reason
+                        : "specifier is assembled at runtime",
+                    dynamic: true,
+                });
+                continue;
+            }
+            // A Python `from X import a, b` is resolved by its names first. Each name
+            // that binds uniquely becomes its own edge to the declaring file, and the
+            // module edge is not emitted — pointing at both would put the facade back.
+            const isPythonImporter = file.path.endsWith(".py") || file.path.endsWith(".pyi");
+            if (isPythonImporter && imported.names.length && !imported.specifier.startsWith(".")) {
+                const bound = new Set();
+                for (const name of imported.names) {
+                    const declaredIn = pythonDeclarations.get(name);
+                    if (declaredIn && declaredIn !== file.path)
+                        bound.add(declaredIn);
+                }
+                if (bound.size) {
+                    for (const target of [...bound].sort(byCodeUnit)) {
+                        edges.push({
+                            from: file.path,
+                            to: target,
+                            names: [...imported.names].sort(),
+                            // A unique declaration is strong evidence, but the language
+                            // permits rebinding at runtime, so this is never "exact".
+                            confidence: "probable",
+                            via: "exact",
+                            ...(imported.typeOnly ? { typeOnly: true } : {}),
+                        });
+                    }
+                    continue;
+                }
+                // Nothing bound. Try the module itself — `from pkg import submodule` is
+                // a real module reference — but without the parent fallback, which is
+                // the step that manufactured the facade edges in the first place.
+                const asModule = resolvePythonModule(imported.specifier, known, { parentFallback: false });
+                if (asModule?.kind === "internal") {
+                    edges.push({
+                        from: file.path,
+                        to: asModule.path,
+                        names: [...imported.names].sort(),
+                        confidence: downgrade(imported.confidence, asModule.via),
+                        via: asModule.via,
+                        ...(imported.typeOnly ? { typeOnly: true } : {}),
+                    });
+                    continue;
+                }
+                external.add(imported.specifier);
+                continue;
+            }
+            const resolution = resolveSpecifier(imported.specifier, file.path, known, index.aliases ?? []);
+            if (resolution.kind === "internal") {
+                edges.push({
+                    from: file.path,
+                    to: resolution.path,
+                    names: [...imported.names].sort(),
+                    // An edge is never more trustworthy than the fact it came from, and
+                    // a directory-index match is a convention rather than a certainty.
+                    confidence: downgrade(imported.confidence, resolution.via),
+                    via: resolution.via,
+                    ...(imported.typeOnly ? { typeOnly: true } : {}),
+                });
+            }
+            else if (resolution.kind === "external") {
+                external.add(resolution.module);
+            }
+            else {
+                unresolved.push({
+                    from: file.path,
+                    specifier: imported.specifier,
+                    reason: resolution.reason,
+                    dynamic: false,
+                });
+            }
+        }
+    }
+    const byPath = (a, b) => byCodeUnit(a.path, b.path);
+    const byEdge = (a, b) => byCodeUnit(a.from, b.from) || byCodeUnit(a.to, b.to) || byCodeUnit(a.names.join(), b.names.join());
+    const byUnresolved = (a, b) => byCodeUnit(a.from, b.from) || byCodeUnit(a.specifier, b.specifier);
+    return {
+        fingerprint: index.fingerprint,
+        nodes: nodes.sort(byPath),
+        edges: edges.sort(byEdge),
+        unresolved: unresolved.sort(byUnresolved),
+        external: [...external].sort(),
+        blindSpots: [...index.blindSpots].sort(byPath),
+    };
+}
+function downgrade(confidence, via) {
+    // An alias is a declared mapping in a config file, not a guess, so it keeps
+    // the fact's confidence. A directory-index match is a convention and does not.
+    if (via === "exact" || via === "alias")
+        return confidence;
+    if (confidence === "exact")
+        return "probable";
+    return confidence;
+}
+/**
+ * Who depends on these paths.
+ *
+ * Transitive by default, because the question an intent actually asks is "what
+ * can my change reach", and a caller two hops away is still a caller. Cycles
+ * are normal in real code and terminate on the visited set.
+ */
+export function dependentsOf(graph, targets) {
+    const importers = new Map();
+    for (const edge of graph.edges) {
+        const list = importers.get(edge.to);
+        if (list)
+            list.push(edge.from);
+        else
+            importers.set(edge.to, [edge.from]);
+    }
+    const targetSet = new Set(targets);
+    const direct = new Set();
+    const seen = new Set();
+    const queue = [...targets];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        for (const importer of importers.get(current) ?? []) {
+            if (targetSet.has(current))
+                direct.add(importer);
+            if (seen.has(importer) || targetSet.has(importer))
+                continue;
+            seen.add(importer);
+            queue.push(importer);
+        }
+    }
+    const caveats = [];
+    // An unresolved import is a file that might import the target; we cannot say
+    // it does, and we must not imply it does not.
+    const unresolvedCount = graph.unresolved.length;
+    if (unresolvedCount > 0) {
+        caveats.push(`${unresolvedCount} import${unresolvedCount === 1 ? "" : "s"} could not be resolved; ` +
+            "any of them may reference these paths");
+    }
+    if (graph.blindSpots.length > 0) {
+        caveats.push(`${graph.blindSpots.length} file${graph.blindSpots.length === 1 ? "" : "s"} could not be fully parsed`);
+    }
+    return { paths: [...seen].sort(), direct: [...direct].sort(), caveats };
+}

package/dist/lib/index/impact.js

@@ -0,0 +1,174 @@
+import { coverageForRadius } from "./coverage.js";
+import { byCodeUnit } from "./order.js";
+/**
+ * Default depth.
+ *
+ * Transitive reachability in a real codebase converges on "most of the
+ * repository" within a few hops, and a radius naming most of the repository is
+ * the same useless artefact as a radius naming a random 38 files — it cannot
+ * be checked, so it gets ignored. Three hops keeps the answer reviewable while
+ * covering the cases that actually break builds: a direct importer, its
+ * importer, and the entry point that ties them together. The limit is stated
+ * in the caveats whenever it truncates, so a caller is never quietly handed a
+ * partial traversal.
+ */
+const DEFAULT_MAX_DISTANCE = 3;
+export function computeImpact(graph, calls, declared, options = {}) {
+    const maxDistance = options.maxDistance ?? DEFAULT_MAX_DISTANCE;
+    const declaredSet = new Set(declared);
+    // Reverse adjacency, built once. Import edges and call edges are kept apart
+    // because they justify a path differently: importing a changed file is a
+    // compile-time relationship, calling a changed symbol is a behavioural one,
+    // and a reviewer reads them differently.
+    const importersOf = new Map();
+    for (const edge of graph.edges) {
+        push(importersOf, edge.to, { from: edge.from, confidence: edge.confidence });
+    }
+    const callersOf = new Map();
+    for (const edge of calls.edges) {
+        if (edge.from === edge.to)
+            continue; // a file calling itself is not impact
+        push(callersOf, edge.to, {
+            from: edge.from,
+            symbol: edge.symbol,
+            ...(edge.enclosing ? { enclosing: edge.enclosing } : {}),
+            confidence: edge.confidence,
+            line: edge.line,
+        });
+    }
+    const found = new Map();
+    for (const path of declared) {
+        found.set(path, {
+            path,
+            declared: true,
+            distance: 0,
+            confidence: "exact",
+            reasons: [{ kind: "declared", explanation: "declared by the agent" }],
+        });
+    }
+    let frontier = [...declaredSet];
+    let truncated = false;
+    for (let distance = 1; distance <= maxDistance && frontier.length > 0; distance += 1) {
+        const next = [];
+        for (const target of frontier.sort()) {
+            for (const caller of (callersOf.get(target) ?? []).sort(byFrom)) {
+                // Name the calling function when the backend knew it. "handler() calls
+                // query() at line 41" can be checked without opening the file; "calls
+                // query()" cannot.
+                const site = caller.enclosing ? `${caller.enclosing}() ` : "";
+                const at = caller.line === undefined ? "" : ` at line ${caller.line}`;
+                const reason = {
+                    kind: distance === 1 ? "calls" : "transitive",
+                    explanation: distance === 1
+                        ? `${site}calls ${caller.symbol}() defined in ${target}${at}`
+                        : `reaches ${target} in ${distance} steps, via ${caller.symbol}()`,
+                    through: target,
+                    symbol: caller.symbol,
+                    line: caller.line,
+                };
+                if (record(found, caller.from, distance, caller.confidence, reason, declaredSet, options, () => (truncated = true))) {
+                    next.push(caller.from);
+                }
+            }
+            for (const importer of (importersOf.get(target) ?? []).sort(byFrom)) {
+                const reason = {
+                    kind: distance === 1 ? "imports" : "transitive",
+                    explanation: distance === 1
+                        ? `imports ${target}`
+                        : `reaches ${target} in ${distance} steps, through imports`,
+                    through: target,
+                };
+                if (record(found, importer.from, distance, importer.confidence, reason, declaredSet, options, () => (truncated = true))) {
+                    next.push(importer.from);
+                }
+            }
+        }
+        frontier = [...new Set(next)];
+    }
+    const caveats = [];
+    if (graph.unresolved.length > 0) {
+        caveats.push(`${graph.unresolved.length} import${plural(graph.unresolved.length)} could not be resolved; ` +
+            "any of them may reach these paths");
+    }
+    if (calls.unresolved.length > 0) {
+        caveats.push(`${calls.unresolved.length} call${plural(calls.unresolved.length)} could not be bound to a definition`);
+    }
+    if (calls.unanalyzed.length > 0) {
+        caveats.push(`${calls.unanalyzed.length} file${plural(calls.unanalyzed.length)} had no call analysis available`);
+    }
+    if (graph.blindSpots.length > 0) {
+        caveats.push(`${graph.blindSpots.length} file${plural(graph.blindSpots.length)} could not be fully parsed`);
+    }
+    if (truncated) {
+        caveats.push(`the result was capped at ${options.maxPaths} added paths`);
+    }
+    const paths = [...found.values()].sort((a, b) => Number(b.declared) - Number(a.declared) || a.distance - b.distance || byCodeUnit(a.path, b.path));
+    return {
+        paths,
+        added: paths.filter((p) => !p.declared).map((p) => p.path).sort(),
+        caveats,
+        complete: caveats.length === 0,
+        // Scoped to the radius, and only when the caller supplied the facts. Note
+        // this is computed over the paths actually returned, so a truncated result
+        // reports coverage for what it returned rather than for what it would have.
+        ...(options.coverage
+            ? { coverage: coverageForRadius(options.coverage, paths.map((p) => p.path)) }
+            : {}),
+    };
+}
+/** Returns true when the path is newly reached and should be traversed onward. */
+function record(found, path, distance, confidence, reason, declared, options, onTruncate) {
+    const existing = found.get(path);
+    if (existing) {
+        // Already reached. Keep the extra reason — two independent routes to the
+        // same file is exactly the evidence a reviewer wants — but do not re-walk.
+        if (!existing.reasons.some((r) => r.explanation === reason.explanation)) {
+            existing.reasons.push(reason);
+        }
+        return false;
+    }
+    if (options.maxPaths !== undefined) {
+        const addedSoFar = [...found.values()].filter((p) => !p.declared).length;
+        if (addedSoFar >= options.maxPaths) {
+            onTruncate();
+            return false;
+        }
+    }
+    found.set(path, {
+        path,
+        declared: declared.has(path),
+        distance,
+        confidence,
+        reasons: [reason],
+    });
+    return true;
+}
+function push(map, key, value) {
+    const list = map.get(key);
+    if (list)
+        list.push(value);
+    else
+        map.set(key, [value]);
+}
+const byFrom = (a, b) => byCodeUnit(a.from, b.from);
+const plural = (n) => (n === 1 ? "" : "s");
+/**
+ * The impact as lines a human can scan.
+ *
+ * Deliberately part of this module rather than left to each caller. The reason
+ * a path is in the radius is the product; a caller that renders only the paths
+ * has thrown away the thing that distinguishes this from grep-v1, and making
+ * the readable form the easy default is how that is prevented.
+ */
+export function explainImpact(impact) {
+    const lines = impact.paths
+        .filter((path) => !path.declared)
+        .map((path) => `${path.path} — ${path.reasons.map((r) => r.explanation).join("; ")} [${path.confidence}]`);
+    if (impact.caveats.length > 0) {
+        lines.push(`incomplete: ${impact.caveats.join("; ")}`);
+    }
+    else if (lines.length === 0) {
+        lines.push("no other files reach the declared paths, and the graph resolved everything it saw");
+    }
+    return lines;
+}