syncstaff-mcp 0.2.3

package/dist/lib/index/surfaces.js

@@ -0,0 +1,27 @@
+/** Discover useful non-TypeScript relationships without executing application code. */
+export function discoverSurfaceEdges(sources) {
+    const edges = [];
+    const css = new Set(sources.filter((source) => /\.(?:css|scss|less)$/.test(source.path)).map((source) => source.path));
+    const tokens = new Set();
+    for (const source of sources) {
+        for (const match of source.content.matchAll(/--([A-Za-z0-9_-]+)\s*:/g))
+            tokens.add(`--${match[1]}`);
+    }
+    for (const source of sources) {
+        for (const match of source.content.matchAll(/(?:import|require)\s*\(?\s*["']([^"']+\.(?:css|scss|less))["']/g)) {
+            const targetPath = join(dirname(source.path), match[1]).replaceAll("\\", "/");
+            const target = sources.find((candidate) => candidate.path === targetPath)?.path ?? targetPath;
+            edges.push({ from: source.path, to: target, kind: "stylesheet", evidence: match[0] });
+        }
+        for (const match of source.content.matchAll(/var\(\s*(--[A-Za-z0-9_-]+)/g)) {
+            if (tokens.has(match[1]))
+                edges.push({ from: source.path, to: match[1], kind: "token", evidence: match[0] });
+        }
+        for (const match of source.content.matchAll(/(?:app|router)\.(?:get|post|put|patch|delete)\(\s*["']([^"']+)["']\s*,\s*([A-Za-z_$][\w$]*)/g)) {
+            edges.push({ from: source.path, to: `${match[1]} -> ${match[2]}`, kind: "route-handler", evidence: match[0] });
+        }
+    }
+    return edges.sort((a, b) => byCodeUnit(`${a.from}\0${a.kind}\0${a.to}`, `${b.from}\0${b.kind}\0${b.to}`));
+}
+import { dirname, join } from "node:path";
+import { byCodeUnit } from "./order.js";

package/dist/lib/index/symbols.js

@@ -0,0 +1,426 @@
+import { resolveSpecifier } from "./resolve.js";
+import { byCodeUnit } from "./order.js";
+import { tokenize } from "./embedding.js";
+/** Index the bindings visible in each file. Pure. */
+export function buildSymbolTable(index) {
+    const known = new Set(index.files.map((file) => file.path));
+    const table = new Map();
+    /** path -> files it re-exports wholesale via `export *`. */
+    const starReExports = new Map();
+    /** path -> specifiers that were star re-exports, from the parser's diagnostic. */
+    const starTargets = new Map();
+    for (const file of index.files) {
+        const stars = file.result.diagnostics.filter((d) => d.code === "star-reexport");
+        if (stars.length === 0)
+            continue;
+        // The parser records a star re-export as a diagnostic on the same line as
+        // the import it also emitted; match them by line so the right specifier is
+        // expanded rather than every specifier in the file.
+        const lines = new Set(stars.map((d) => d.line));
+        starTargets.set(file.path, new Set(file.result.imports.filter((i) => lines.has(i.line)).map((i) => i.specifier)));
+    }
+    for (const file of index.files) {
+        const defined = new Map();
+        for (const definition of file.result.definitions ?? []) {
+            // First definition wins. A duplicate name in one file is either an
+            // overload or shadowing, and picking arbitrarily between them would make
+            // the table depend on parse order.
+            if (!defined.has(definition.name))
+                defined.set(definition.name, definition);
+        }
+        const imported = new Map();
+        for (const importRef of file.result.imports) {
+            if (importRef.dynamic)
+                continue; // recorded as unresolved by the graph
+            const resolution = resolveSpecifier(importRef.specifier, file.path, known, index.aliases ?? []);
+            const resolvedPath = resolution.kind === "internal" ? resolution.path : null;
+            for (const name of importRef.names) {
+                imported.set(name, {
+                    specifier: importRef.specifier,
+                    resolvedPath,
+                    exportedAs: importRef.aliases?.[name] ?? name,
+                    confidence: importRef.confidence,
+                });
+            }
+        }
+        const exported = new Map();
+        for (const exportRef of file.result.exports) {
+            if (!exported.has(exportRef.name))
+                exported.set(exportRef.name, exportRef);
+        }
+        // `export * from "./x.js"` names nothing the parser can see — the names
+        // live in x. Recorded here so the second pass below can expand them once
+        // every file's own exports are known.
+        starReExports.set(file.path, file.result.imports
+            .filter((i) => !i.dynamic && starTargets.get(file.path)?.has(i.specifier))
+            .map((i) => resolveSpecifier(i.specifier, file.path, known, index.aliases ?? []))
+            .flatMap((r) => (r.kind === "internal" ? [r.path] : [])));
+        table.set(file.path, {
+            path: file.path,
+            defined,
+            imported,
+            exported,
+            extractsDefinitions: file.result.definitions !== undefined,
+            extractsCalls: file.result.calls !== undefined,
+        });
+    }
+    // Expand `export *` now that every file's own exports are known. Bounded
+    // depth: barrels legitimately chain, and a cycle would otherwise spin.
+    for (let pass = 0; pass < 4; pass += 1) {
+        let grew = false;
+        for (const [path, targets] of starReExports) {
+            const entry = table.get(path);
+            if (!entry)
+                continue;
+            for (const target of targets) {
+                const source = table.get(target);
+                if (!source)
+                    continue;
+                for (const [name, ref] of source.exported) {
+                    if (name === "default")
+                        continue; // `export *` never re-exports default
+                    if (entry.exported.has(name))
+                        continue;
+                    entry.exported.set(name, {
+                        ...ref,
+                        from: target,
+                        // The name is certainly exported by the barrel; which file
+                        // ultimately owns it took a hop this pass did not verify.
+                        confidence: "probable",
+                    });
+                    grew = true;
+                }
+            }
+        }
+        if (!grew)
+            break;
+    }
+    return table;
+}
+/**
+ * Resolve every recorded call site against the symbol table.
+ *
+ * Deterministic: edges and unresolved entries are sorted, so two machines with
+ * the same index produce the same bytes.
+ */
+export function resolveCallEdges(index, table) {
+    const edges = [];
+    const unresolved = [];
+    const unanalyzed = [];
+    for (const file of index.files) {
+        const entry = table.get(file.path);
+        if (!entry)
+            continue;
+        if (!entry.extractsCalls) {
+            // Only worth reporting for files a backend actually read. A markdown
+            // file having no call extraction is not a gap in the call graph.
+            if (file.parser)
+                unanalyzed.push(file.path);
+            continue;
+        }
+        for (const call of file.result.calls ?? []) {
+            const resolvedEdge = resolveOne(call.callee, call.receiver, entry, table, call.ownerClass);
+            if (resolvedEdge.kind === "resolved") {
+                edges.push({
+                    from: file.path,
+                    to: resolvedEdge.to,
+                    symbol: resolvedEdge.symbol,
+                    scope: resolvedEdge.scope,
+                    ...(call.enclosing ? { enclosing: call.enclosing } : {}),
+                    // An edge inherits the weaker of the call's confidence and the
+                    // binding's. A speculative import cannot yield an exact call.
+                    confidence: weaker(call.confidence, resolvedEdge.confidence),
+                    line: call.line,
+                });
+            }
+            else {
+                unresolved.push({
+                    from: file.path,
+                    callee: call.callee,
+                    ...(call.receiver ? { receiver: call.receiver } : {}),
+                    reason: resolvedEdge.reason,
+                    line: call.line,
+                });
+            }
+        }
+    }
+    const byCall = (a, b) => byCodeUnit(a.from, b.from) || byCodeUnit(a.to, b.to) || byCodeUnit(a.symbol, b.symbol) ||
+        (a.line ?? 0) - (b.line ?? 0);
+    const byUnresolved = (a, b) => byCodeUnit(a.from, b.from) || byCodeUnit(a.callee, b.callee) || (a.line ?? 0) - (b.line ?? 0);
+    return {
+        edges: edges.sort(byCall),
+        unresolved: unresolved.sort(byUnresolved),
+        unanalyzed: unanalyzed.sort(),
+    };
+}
+/**
+ * Resolve every recorded reference site — reads, `new`, types, JSX, imports and
+ * calls — against the symbol table.
+ *
+ * This is the answer to "what would break if I changed this symbol", and it is
+ * the single path both blast-radius surfaces read. Before it existed, the graph
+ * could name every caller of a function and not one user of a constant: the
+ * extractor only fired inside `isCallExpression`, so `KEEL_RELEASE_VERSION`,
+ * read in four files, resolved to silence.
+ *
+ * Deterministic, for the same reason as resolveCallEdges: two machines with the
+ * same index must produce the same bytes.
+ */
+export function resolveReferenceEdges(index, table) {
+    const edges = [];
+    const unresolved = [];
+    const unanalyzed = [];
+    // Names defined anywhere in the index. See ReferenceResolution.unresolved.
+    const definedAnywhere = new Set();
+    for (const file of index.files) {
+        for (const definition of file.result.definitions ?? [])
+            definedAnywhere.add(definition.name);
+    }
+    for (const file of index.files) {
+        const entry = table.get(file.path);
+        if (!entry)
+            continue;
+        if (file.result.references === undefined) {
+            if (file.parser)
+                unanalyzed.push(file.path);
+            continue;
+        }
+        for (const reference of file.result.references) {
+            const resolved = resolveOne(reference.name, reference.receiver, entry, table, reference.ownerClass);
+            if (resolved.kind === "resolved") {
+                edges.push({
+                    from: file.path,
+                    to: resolved.to,
+                    symbol: resolved.symbol,
+                    scope: resolved.scope,
+                    kind: reference.kind,
+                    ...(reference.enclosing ? { enclosing: reference.enclosing } : {}),
+                    confidence: weaker(reference.confidence, resolved.confidence),
+                    line: reference.line,
+                });
+            }
+            else if (definedAnywhere.has(reference.name)) {
+                unresolved.push({
+                    from: file.path,
+                    callee: reference.name,
+                    ...(reference.receiver ? { receiver: reference.receiver } : {}),
+                    reason: resolved.reason,
+                    line: reference.line,
+                });
+            }
+        }
+    }
+    const byReference = (a, b) => byCodeUnit(a.from, b.from) || byCodeUnit(a.to, b.to) || byCodeUnit(a.symbol, b.symbol) ||
+        (a.line ?? 0) - (b.line ?? 0) || byCodeUnit(a.kind, b.kind);
+    const byUnresolved = (a, b) => byCodeUnit(a.from, b.from) || byCodeUnit(a.callee, b.callee) || (a.line ?? 0) - (b.line ?? 0);
+    return {
+        edges: edges.sort(byReference),
+        unresolved: unresolved.sort(byUnresolved),
+        unanalyzed: unanalyzed.sort(),
+    };
+}
+function resolveOne(callee, receiver, entry, table, ownerClass) {
+    const dot = callee.indexOf(".");
+    if (dot > 0 || receiver) {
+        const base = receiver ?? callee.slice(0, dot);
+        const member = callee.slice(callee.indexOf(".") + 1);
+        // `this.flush()` inside class Store needs no type inference: the class is
+        // in the AST at the call site. Resolve against a method that class defines
+        // in this same file. Inherited methods are not followed — that needs the
+        // heritage chain, and guessing across it would invent edges.
+        if (base === "this" && ownerClass) {
+            const method = entry.defined.get(member);
+            if (method && method.owner === ownerClass) {
+                return { kind: "resolved", to: entry.path, symbol: member, scope: "local", confidence: "exact" };
+            }
+            return {
+                kind: "unresolved",
+                reason: `"this.${member}" is not defined on ${ownerClass} in this file (inherited, or assigned at runtime)`,
+            };
+        }
+        // A namespace import is the one member call that is statically knowable:
+        // `import * as db from "./db.js"; db.query()`. Everything else needs the
+        // receiver's type, which this layer deliberately does not infer.
+        const binding = entry.imported.get(base);
+        if (binding?.resolvedPath) {
+            const target = table.get(binding.resolvedPath);
+            if (target?.exported.has(member)) {
+                return {
+                    kind: "resolved",
+                    to: binding.resolvedPath,
+                    symbol: member,
+                    scope: "imported",
+                    // Probable, not exact: the base could have been reassigned between
+                    // the import and the call, and nothing here proves it was not.
+                    confidence: "probable",
+                };
+            }
+        }
+        return {
+            kind: "unresolved",
+            reason: `member call on "${base}" whose type is not tracked`,
+        };
+    }
+    const local = entry.defined.get(callee);
+    if (local) {
+        return { kind: "resolved", to: entry.path, symbol: callee, scope: "local", confidence: "exact" };
+    }
+    const binding = entry.imported.get(callee);
+    if (binding) {
+        if (!binding.resolvedPath) {
+            return {
+                kind: "unresolved",
+                reason: `imported from "${binding.specifier}", which is outside the index`,
+            };
+        }
+        const target = table.get(binding.resolvedPath);
+        if (target?.exported.has(binding.exportedAs)) {
+            return {
+                kind: "resolved",
+                to: binding.resolvedPath,
+                // The TARGET's name for it. `import { query as run }` then `run()`
+                // reaches `query`, and reporting `run` would name a symbol the target
+                // does not have.
+                symbol: binding.exportedAs,
+                scope: "imported",
+                confidence: binding.confidence,
+            };
+        }
+        // Imported by this name, but the target does not export it. An alias or a
+        // re-export through a barrel. Both are real edges this layer cannot follow,
+        // and guessing which file behind the barrel owns the symbol is exactly the
+        // guess that produces wrong leases.
+        return {
+            kind: "unresolved",
+            reason: `"${callee}" is imported from ${binding.resolvedPath} as "${binding.exportedAs}", which that file does not export (re-export through a barrel)`,
+        };
+    }
+    // Not bound in this file. A global, a builtin, or a name this backend saw
+    // without seeing its declaration. Emphatically not "the function of the same
+    // name over in some other directory".
+    return { kind: "unresolved", reason: `"${callee}" is not defined in this file and not imported into it` };
+}
+function weaker(a, b) {
+    const rank = { exact: 2, probable: 1, speculative: 0 };
+    return rank[a] <= rank[b] ? a : b;
+}
+export function extractContracts(index) {
+    const contracts = [];
+    for (const file of index.files) {
+        for (const exported of file.result.exports) {
+            contracts.push({
+                path: file.path,
+                name: exported.name,
+                kind: exported.kind,
+                confidence: exported.confidence,
+            });
+        }
+    }
+    return contracts.sort((a, b) => byCodeUnit(a.path, b.path) || byCodeUnit(a.name, b.name) || byCodeUnit(a.kind, b.kind));
+}
+/** Files that export a given symbol name. Used to explain a blast radius. */
+export function definersOf(index, symbol) {
+    return index.files
+        .filter((file) => file.result.exports.some((e) => e.name === symbol))
+        .map((file) => file.path)
+        .sort();
+}
+const symbolCorpusCache = new WeakMap();
+function corpusFor(index) {
+    const cached = symbolCorpusCache.get(index);
+    if (cached)
+        return cached;
+    const byKey = new Map();
+    for (const file of index.files) {
+        const names = [
+            ...(file.result.definitions ?? []).map((definition) => definition.name),
+            ...file.result.exports.map((exported) => exported.name),
+        ];
+        for (const symbol of new Set(names)) {
+            const terms = new Set(tokenize(symbol));
+            if (terms.size === 0)
+                continue;
+            const key = `${file.path}\0${symbol}`;
+            byKey.set(key, {
+                path: file.path,
+                symbol,
+                terms,
+                leaf: [...terms].at(-1) ?? symbol.toLowerCase(),
+            });
+        }
+    }
+    const candidates = [...byKey.values()].sort((a, b) => byCodeUnit(a.path, b.path) || byCodeUnit(a.symbol, b.symbol));
+    const postings = new Map();
+    for (const candidate of candidates) {
+        for (const term of candidate.terms) {
+            const matches = postings.get(term) ?? [];
+            matches.push(candidate);
+            postings.set(term, matches);
+        }
+    }
+    const corpus = { candidates, postings };
+    symbolCorpusCache.set(index, corpus);
+    return corpus;
+}
+/**
+ * Search the local symbol table from prose without an embedding model.
+ *
+ * This deliberately uses per-term candidate windows. A common word such as
+ * "update" should contribute a quarter-weight signal when it matches many
+ * symbols, while a pair of less-saturated terms can corroborate a candidate.
+ * A leaf-name match is sufficient on its own because it is the strongest
+ * evidence available without type inference.
+ */
+export function searchSymbols(index, query, options = {}) {
+    const limit = options.limit ?? 20;
+    const maxFiles = options.maxFiles ?? 8;
+    const candidateWindow = options.candidateWindow ?? 20;
+    if (limit < 1 || maxFiles < 1 || candidateWindow < 1)
+        return [];
+    const { candidates, postings } = corpusFor(index);
+    const queryTerms = [...new Set(tokenize(query))];
+    const scored = [];
+    for (const candidate of candidates) {
+        let score = 0;
+        let unsaturatedMatches = 0;
+        let exactLeaf = false;
+        const matched = new Set();
+        for (const term of queryTerms) {
+            if (!candidate.terms.has(term))
+                continue;
+            const matches = postings.get(term) ?? [];
+            const saturated = matches.length >= candidateWindow;
+            const weight = saturated ? 0.25 : 1;
+            const leaf = candidate.leaf === term;
+            score += weight * (leaf ? 2 : 1);
+            if (!saturated)
+                unsaturatedMatches += 1;
+            if (leaf)
+                exactLeaf = true;
+            matched.add(term);
+        }
+        // Corroboration prevents one broad prose term from producing a noisy
+        // symbol leg; a direct leaf-name mention is the intentional exception.
+        if (!exactLeaf && unsaturatedMatches < 2)
+            continue;
+        scored.push({
+            path: candidate.path,
+            symbol: candidate.symbol,
+            score,
+            matched_terms: [...matched].sort(byCodeUnit),
+        });
+    }
+    scored.sort((a, b) => b.score - a.score || b.matched_terms.length - a.matched_terms.length ||
+        byCodeUnit(a.path, b.path) || byCodeUnit(a.symbol, b.symbol));
+    const paths = new Set();
+    const results = [];
+    for (const hit of scored) {
+        if (!paths.has(hit.path) && paths.size >= maxFiles)
+            continue;
+        paths.add(hit.path);
+        results.push(hit);
+        if (results.length >= limit)
+            break;
+    }
+    return results;
+}

package/dist/lib/index/transformers-embedder.js

@@ -0,0 +1,73 @@
+/**
+ * A local sentence embedding model running on CPU using @xenova/transformers.
+ * Fulfills R4.1.
+ */
+export class TransformersEmbedder {
+    modelId;
+    queryPrefix;
+    documentPrefix;
+    _dimensions = 0;
+    pipelinePromise = null;
+    constructor(modelId = "Xenova/bge-small-en-v1.5", queryPrefix = "", documentPrefix = "") {
+        this.modelId = modelId;
+        this.queryPrefix = queryPrefix;
+        this.documentPrefix = documentPrefix;
+    }
+    get dimensions() {
+        return this._dimensions;
+    }
+    get id() {
+        return `transformers:${this.modelId}:${this.queryPrefix}:${this.documentPrefix}`;
+    }
+    async getPipeline() {
+        if (!this.pipelinePromise) {
+            this.pipelinePromise = (async () => {
+                try {
+                    // Dynamic import allows Keel to run if the dependency is missing (R4.2)
+                    const { pipeline } = await import("@xenova/transformers");
+                    return await pipeline("feature-extraction", this.modelId, {
+                        quantized: true // Use INT8 quantization for smaller size and faster CPU inference
+                    });
+                }
+                catch (error) {
+                    throw new Error("Failed to load @xenova/transformers. Vector leg will be disabled.", { cause: error });
+                }
+            })();
+        }
+        return this.pipelinePromise;
+    }
+    async embedText(text) {
+        const extractor = await this.getPipeline();
+        const output = await extractor(text, { pooling: "mean", normalize: true });
+        const vector = Array.from(output.data);
+        this._dimensions = vector.length;
+        return vector;
+    }
+    async embed(text) {
+        return this.embedText(text);
+    }
+    async embedQuery(text) {
+        return this.embedText(`${this.queryPrefix}${text}`);
+    }
+    async embedDocument(text) {
+        return this.embedText(`${this.documentPrefix}${text}`);
+    }
+}
+export async function createTransformersEmbedder(modelId = "Xenova/bge-small-en-v1.5") {
+    const asymmetric = modelId.includes("bge-small-en-v1.5")
+        ? { query: "Represent this sentence for searching relevant passages: ", document: "" }
+        : modelId.includes("nomic-embed-text")
+            ? { query: "search_query: ", document: "search_document: " }
+            : modelId.includes("embeddinggemma")
+                ? { query: "task: search result | query: ", document: "title: none | text: " }
+                : { query: "", document: "" };
+    const embedder = new TransformersEmbedder(modelId, asymmetric.query, asymmetric.document);
+    try {
+        // Eagerly try to load the pipeline. If it fails, degrade cleanly to null.
+        await embedder.embed("warmup");
+        return embedder;
+    }
+    catch (err) {
+        return null;
+    }
+}