syncstaff-mcp 0.2.3

package/dist/lib/index/typescript-parser.js

@@ -0,0 +1,532 @@
+const EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+/**
+ * Bump on any change to extraction rules.
+ *
+ * This is part of the index fingerprint by design: an index built by a smarter
+ * parser is a different index over identical bytes, and forgetting to bump
+ * would let the two claim equality.
+ */
+const PARSER_VERSION = "4";
+export function createTypeScriptParser(tsApi) {
+    return {
+        id: "keel-typescript",
+        version: PARSER_VERSION,
+        language: "typescript",
+        extensions: EXTENSIONS,
+        parse: (source, path) => parseSource(tsApi, source, path),
+    };
+}
+/**
+ * Load the backend if `typescript` is installed, or return null.
+ *
+ * The published adapter must stay installable with `npx` by someone who has
+ * never built a native module, and `typescript` is large. Rather than force it
+ * on everyone, the caller registers a backend only when one is available —
+ * and the registry already models a missing backend as `unsupported`, which is
+ * a gap in coverage rather than a failure. So an adapter without typescript
+ * still coordinates; it simply reports that it understood no files, honestly,
+ * instead of pretending to a graph it does not have.
+ */
+export async function loadTypeScriptParser() {
+    try {
+        const loaded = (await import("typescript"));
+        const api = loaded.default ?? loaded;
+        if (typeof api.createSourceFile !== "function")
+            return null;
+        return createTypeScriptParser(api);
+    }
+    catch {
+        return null;
+    }
+}
+function parseSource(tsApi, source, path) {
+    const imports = [];
+    const exports = [];
+    const definitions = [];
+    const calls = [];
+    const references = [];
+    const diagnostics = [];
+    const file = tsApi.createSourceFile(path, source, tsApi.ScriptTarget.Latest, 
+    /* setParentNodes */ true, scriptKind(tsApi, path));
+    const lineOf = (pos) => file.getLineAndCharacterOfPosition(pos).line + 1;
+    const columnOf = (pos) => file.getLineAndCharacterOfPosition(pos).character + 1;
+    // parseDiagnostics is internal but stable, and it is the only way to learn a
+    // syntactic parse recovered from errors. Guarded so a compiler upgrade that
+    // renames it degrades to "no diagnostics" rather than throwing.
+    const parseErrors = file
+        .parseDiagnostics ?? [];
+    for (const error of parseErrors.slice(0, 20)) {
+        diagnostics.push({
+            // The compiler's own code, never its message: TS messages routinely
+            // quote the offending source.
+            code: error.code === undefined ? "syntax" : `TS${error.code}`,
+            message: "syntax error recovered by the parser",
+            ...(error.start === undefined ? {} : { line: lineOf(error.start), column: columnOf(error.start) }),
+        });
+    }
+    /** Names of the functions/classes we are currently inside, outermost first. */
+    const scope = [];
+    const enclosing = () => (scope.length === 0 ? undefined : scope[scope.length - 1]);
+    /** Class names only, so `this` can be attributed without a type checker. */
+    const classes = [];
+    const enclosingClass = () => classes.length === 0 ? undefined : classes[classes.length - 1];
+    const isExported = (node) => {
+        const modifiers = node.modifiers;
+        return (modifiers ?? []).some((m) => m.kind === tsApi.SyntaxKind.ExportKeyword);
+    };
+    const addDefinition = (name, kind, node, owner) => {
+        const exported = isExported(node);
+        definitions.push({
+            name,
+            kind,
+            exported,
+            ...(owner ? { owner } : {}),
+            line: lineOf(node.getStart(file)),
+        });
+        if (exported) {
+            exports.push({ name, kind, confidence: "exact", line: lineOf(node.getStart(file)) });
+        }
+    };
+    const addReference = (name, kind, node, extra = {}) => {
+        references.push({
+            name,
+            kind,
+            ...(extra.receiver ? { receiver: extra.receiver } : {}),
+            ...(extra.ownerClass ? { ownerClass: extra.ownerClass } : {}),
+            ...(enclosing() ? { enclosing: enclosing() } : {}),
+            line: lineOf(node.getStart(file)),
+            confidence: extra.confidence ?? "exact",
+        });
+    };
+    const visit = (node) => {
+        // ---- imports -------------------------------------------------------
+        if (tsApi.isImportDeclaration(node)) {
+            const specifier = literalText(tsApi, node.moduleSpecifier);
+            if (specifier !== null) {
+                const names = [];
+                const aliases = {};
+                let confidence = "exact";
+                const clause = node.importClause;
+                // `import type { X }` and `import { type X }` are compile-time only.
+                let typeOnly = clause?.isTypeOnly === true;
+                if (clause?.name)
+                    names.push(clause.name.text);
+                const bindings = clause?.namedBindings;
+                if (bindings && tsApi.isNamedImports(bindings)) {
+                    // `import { a as b }` binds `b` locally while the target exports `a`.
+                    // Recording both is what lets resolution follow the alias instead of
+                    // failing to find `b` in the target and calling the edge unresolved.
+                    let allTypeOnly = bindings.elements.length > 0;
+                    for (const element of bindings.elements) {
+                        names.push(element.name.text);
+                        if (element.propertyName)
+                            aliases[element.name.text] = element.propertyName.text;
+                        if (!element.isTypeOnly)
+                            allTypeOnly = false;
+                        // The line a rename has to touch. Recorded under the LOCAL name,
+                        // exactly like a call: resolution owns the alias mapping and
+                        // reports the target's own name for the symbol, so writing the
+                        // target's name here would instead produce an unresolvable
+                        // reference to a binding this file does not have.
+                        addReference(element.name.text, "import", element);
+                    }
+                    if (allTypeOnly)
+                        typeOnly = true;
+                }
+                else if (bindings && tsApi.isNamespaceImport(bindings)) {
+                    names.push(bindings.name.text);
+                    // A namespace binding is one name standing for a whole module; a
+                    // call through it is knowable but not certain.
+                    confidence = "probable";
+                }
+                imports.push({
+                    specifier,
+                    names,
+                    ...(Object.keys(aliases).length > 0 ? { aliases } : {}),
+                    ...(typeOnly ? { typeOnly: true } : {}),
+                    dynamic: false,
+                    confidence,
+                    line: lineOf(node.getStart(file)),
+                });
+            }
+        }
+        // ---- re-exports ----------------------------------------------------
+        if (tsApi.isExportDeclaration(node)) {
+            const specifier = node.moduleSpecifier ? literalText(tsApi, node.moduleSpecifier) : null;
+            if (specifier !== null) {
+                const names = [];
+                if (node.exportClause && tsApi.isNamedExports(node.exportClause)) {
+                    for (const element of node.exportClause.elements) {
+                        names.push(element.name.text);
+                        addReference(element.name.text, "re-export", element);
+                        exports.push({
+                            name: element.name.text,
+                            kind: "re-export",
+                            from: specifier,
+                            // The name is certain; what it ultimately refers to is not.
+                            confidence: "probable",
+                            line: lineOf(element.getStart(file)),
+                        });
+                    }
+                }
+                else {
+                    // `export * from "./x.js"` — the names cannot be known without
+                    // reading the target, which this parser will not do. Recorded as a
+                    // diagnostic so coverage reflects the gap instead of hiding it.
+                    diagnostics.push({
+                        code: "star-reexport",
+                        message: "export * cannot be enumerated without cross-file resolution",
+                        line: lineOf(node.getStart(file)),
+                    });
+                }
+                imports.push({
+                    specifier,
+                    names,
+                    ...(node.isTypeOnly ? { typeOnly: true } : {}),
+                    dynamic: false,
+                    confidence: "probable",
+                    line: lineOf(node.getStart(file)),
+                });
+            }
+            else if (node.exportClause && tsApi.isNamedExports(node.exportClause)) {
+                // `export { a, b }` re-exporting local declarations.
+                for (const element of node.exportClause.elements) {
+                    addReference(element.propertyName?.text ?? element.name.text, "re-export", element);
+                    exports.push({
+                        name: element.name.text,
+                        kind: "binding",
+                        confidence: "exact",
+                        line: lineOf(element.getStart(file)),
+                    });
+                }
+            }
+        }
+        if (tsApi.isExportAssignment(node)) {
+            exports.push({
+                name: "default",
+                kind: node.isExportEquals ? "export=" : "default",
+                confidence: "exact",
+                line: lineOf(node.getStart(file)),
+            });
+        }
+        // ---- declarations ---------------------------------------------------
+        if (tsApi.isFunctionDeclaration(node) && node.name) {
+            addDefinition(node.name.text, "function", node);
+        }
+        else if (tsApi.isClassDeclaration(node) && node.name) {
+            addDefinition(node.name.text, "class", node);
+        }
+        else if (tsApi.isInterfaceDeclaration(node)) {
+            addDefinition(node.name.text, "interface", node);
+        }
+        else if (tsApi.isTypeAliasDeclaration(node)) {
+            addDefinition(node.name.text, "type", node);
+        }
+        else if (tsApi.isEnumDeclaration(node)) {
+            addDefinition(node.name.text, "enum", node);
+        }
+        else if (tsApi.isVariableStatement(node)) {
+            for (const declaration of node.declarationList.declarations) {
+                if (!tsApi.isIdentifier(declaration.name))
+                    continue;
+                const initializer = declaration.initializer;
+                const kind = initializer && (tsApi.isArrowFunction(initializer) || tsApi.isFunctionExpression(initializer))
+                    ? "function"
+                    : "const";
+                addDefinition(declaration.name.text, kind, node);
+            }
+        }
+        else if (tsApi.isMethodDeclaration(node) && tsApi.isIdentifier(node.name)) {
+            const owner = scope[scope.length - 1];
+            definitions.push({
+                name: node.name.text,
+                kind: "method",
+                exported: false,
+                ...(owner ? { owner } : {}),
+                line: lineOf(node.getStart(file)),
+            });
+        }
+        // ---- calls -----------------------------------------------------------
+        if (tsApi.isCallExpression(node)) {
+            const callee = node.expression;
+            if (callee.kind === tsApi.SyntaxKind.ImportKeyword) {
+                const argument = node.arguments[0];
+                const specifier = argument ? literalText(tsApi, argument) : null;
+                imports.push({
+                    // A dynamic import with a literal argument is still statically
+                    // knowable; one built from a variable is not. Both are marked
+                    // dynamic so graph.ts records rather than resolves them.
+                    specifier: specifier ?? "<computed>",
+                    names: [],
+                    dynamic: true,
+                    confidence: specifier === null ? "speculative" : "probable",
+                    line: lineOf(node.getStart(file)),
+                });
+            }
+            else if (tsApi.isIdentifier(callee)) {
+                if (callee.text === "require") {
+                    const argument = node.arguments[0];
+                    const specifier = argument ? literalText(tsApi, argument) : null;
+                    if (specifier !== null) {
+                        imports.push({
+                            specifier,
+                            names: [],
+                            dynamic: false,
+                            confidence: "probable",
+                            line: lineOf(node.getStart(file)),
+                        });
+                    }
+                }
+                else {
+                    calls.push({
+                        callee: callee.text,
+                        ...(enclosing() ? { enclosing: enclosing() } : {}),
+                        line: lineOf(node.getStart(file)),
+                        confidence: "exact",
+                    });
+                    addReference(callee.text, "call", node);
+                }
+            }
+            else if (tsApi.isPropertyAccessExpression(callee) && tsApi.isIdentifier(callee.name)) {
+                const receiver = tsApi.isIdentifier(callee.expression)
+                    ? callee.expression.text
+                    : callee.expression.kind === tsApi.SyntaxKind.ThisKeyword
+                        ? "this"
+                        : undefined;
+                // `this` needs no type inference: the enclosing class is in the AST.
+                const owner = receiver === "this" ? enclosingClass() : undefined;
+                calls.push({
+                    callee: receiver ? `${receiver}.${callee.name.text}` : callee.name.text,
+                    ...(receiver ? { receiver } : {}),
+                    ...(owner ? { ownerClass: owner } : {}),
+                    ...(enclosing() ? { enclosing: enclosing() } : {}),
+                    line: lineOf(node.getStart(file)),
+                    // A this-call is exact once the class is known; any other receiver
+                    // would need the type checker this backend deliberately avoids.
+                    confidence: owner ? "exact" : "probable",
+                });
+                addReference(receiver ? `${receiver}.${callee.name.text}` : callee.name.text, "call", node, { ...(receiver ? { receiver } : {}), ...(owner ? { ownerClass: owner } : {}), confidence: owner ? "exact" : "probable" });
+            }
+            // Anything else — an IIFE, a call on a call — is not attributable to a
+            // name, and inventing one would be the whole failure this avoids.
+        }
+        // ---- construction ------------------------------------------------------
+        // `new Store()` is a NewExpression, not a CallExpression, so a backend
+        // looking only for calls never saw a single instantiation in this
+        // repository. Nothing about it is less of a use than an invocation.
+        if (tsApi.isNewExpression(node)) {
+            const constructed = node.expression;
+            if (tsApi.isIdentifier(constructed)) {
+                addReference(constructed.text, "new", node);
+            }
+            else if (tsApi.isPropertyAccessExpression(constructed) &&
+                tsApi.isIdentifier(constructed.name) &&
+                tsApi.isIdentifier(constructed.expression)) {
+                addReference(`${constructed.expression.text}.${constructed.name.text}`, "new", node, {
+                    receiver: constructed.expression.text,
+                    // The receiver could have been reassigned between the import and
+                    // here, exactly as for a member call.
+                    confidence: "probable",
+                });
+            }
+        }
+        // ---- type positions ----------------------------------------------------
+        // `x: Config` and `class A extends Base` are compile-time references, and
+        // changing the target's shape breaks this file's build. `import type` is
+        // already carried as typeOnly on the edge, so the distinction survives
+        // downstream; what did not survive was the site itself.
+        if (tsApi.isTypeReferenceNode(node)) {
+            const named = node.typeName;
+            if (tsApi.isIdentifier(named)) {
+                addReference(named.text, "type", node);
+            }
+            else if (tsApi.isQualifiedName(named) && tsApi.isIdentifier(named.left)) {
+                addReference(`${named.left.text}.${named.right.text}`, "type", node, {
+                    receiver: named.left.text,
+                    confidence: "probable",
+                });
+            }
+        }
+        else if (tsApi.isExpressionWithTypeArguments(node) && tsApi.isIdentifier(node.expression)) {
+            // The heritage clause of `extends`/`implements`.
+            addReference(node.expression.text, "type", node);
+        }
+        else if (tsApi.isTypeQueryNode(node) && tsApi.isIdentifier(node.exprName)) {
+            // `typeof CONFIG` reads the binding to talk about its type.
+            addReference(node.exprName.text, "type", node);
+        }
+        // ---- JSX ---------------------------------------------------------------
+        // <Editor /> invokes the component; React calls it. It is not a
+        // CallExpression, so a backend looking only for calls sees nothing, which
+        // left every component use in this repo's web app invisible. Lowercase
+        // names are intrinsic elements (<div>) and reference nothing.
+        if (tsApi.isJsxOpeningElement(node) || tsApi.isJsxSelfClosingElement(node)) {
+            const tag = node.tagName;
+            const name = tsApi.isIdentifier(tag)
+                ? tag.text
+                : tsApi.isPropertyAccessExpression(tag) && tsApi.isIdentifier(tag.name)
+                    ? tag.name.text
+                    : null;
+            if (name && /^[A-Z]/.test(name)) {
+                const receiver = tsApi.isPropertyAccessExpression(tag) && tsApi.isIdentifier(tag.expression)
+                    ? tag.expression.text
+                    : undefined;
+                calls.push({
+                    callee: receiver ? `${receiver}.${name}` : name,
+                    ...(receiver ? { receiver } : {}),
+                    jsx: true,
+                    ...(enclosing() ? { enclosing: enclosing() } : {}),
+                    line: lineOf(node.getStart(file)),
+                    confidence: "exact",
+                });
+                addReference(receiver ? `${receiver}.${name}` : name, "jsx", node, {
+                    ...(receiver ? { receiver } : {}),
+                });
+            }
+        }
+        // ---- plain reads -------------------------------------------------------
+        // The branch that was missing entirely. `KEEL_RELEASE_VERSION` is read in
+        // four files and invoked in none, so every extractor above walks straight
+        // past it and the graph reports that nothing uses a constant three modules
+        // depend on. Everything already handled above is excluded here rather than
+        // recorded twice — see isPlainRead.
+        if (tsApi.isIdentifier(node) && isPlainRead(tsApi, node)) {
+            addReference(node.text, "read", node);
+        }
+        // ---- descend, tracking scope -----------------------------------------
+        const scopeName = scopeNameOf(tsApi, node);
+        if (scopeName)
+            scope.push(scopeName);
+        const className = tsApi.isClassDeclaration(node) || tsApi.isClassExpression(node)
+            ? node.name?.text ?? "(anonymous class)"
+            : null;
+        if (className)
+            classes.push(className);
+        tsApi.forEachChild(node, visit);
+        if (className)
+            classes.pop();
+        if (scopeName)
+            scope.pop();
+    };
+    tsApi.forEachChild(file, visit);
+    // `partial`, not `failed`: declarations either side of a syntax error are
+    // real, and discarding them would lose most of a file over one bad line.
+    // `failed` is reserved for a parse that yielded nothing usable.
+    const recovered = imports.length + exports.length + definitions.length + calls.length > 0;
+    const status = parseErrors.length === 0 ? "parsed" : recovered ? "partial" : "failed";
+    return { status, imports, exports, definitions, calls, references, diagnostics };
+}
+/**
+ * Whether an identifier is a *use* of some binding, rather than the place a
+ * binding is introduced or a member name that belongs to someone else's type.
+ *
+ * Written as an exclusion list because the inclusive version is unbounded and
+ * the exclusive one is checkable: every case below is a position where treating
+ * the identifier as a reference would produce a claim the parser cannot
+ * support. Two categories, and they fail differently:
+ *
+ *   Declaration names (`function parse`, `const parse`, a parameter named
+ *   `parse`) would make every file that happens to declare the name look like a
+ *   file that uses it. That is `grep-v1` again, wearing an AST.
+ *
+ *   Member names (`obj.parse`, `A.B` in a type, `{ parse: fn }`) name a
+ *   property of a value whose type this backend does not infer. Resolving
+ *   `obj.parse` against a local function called `parse` is a guess, and the
+ *   member-call path already refuses that same guess deliberately.
+ *
+ * Everything the walk records under another kind — calls, `new`, type
+ * references, JSX tags, import and export specifiers — is excluded here too, so
+ * a site is reported exactly once with the most specific kind that fits.
+ */
+function isPlainRead(tsApi, id) {
+    const parent = id.parent;
+    if (!parent)
+        return false;
+    // The name side of any declaration: `function f`, `const f`, `class F`,
+    // `f(param)`, `{ key: value }`, `interface I`, `<T>`, `enum E { Member }`.
+    // Object shorthand is the one exception — in `{ VERSION }` the identifier is
+    // both the key and a genuine read of the binding, and shorthand is one of the
+    // ordinary ways a constant travels between modules.
+    const named = parent.name;
+    if (named === id)
+        return tsApi.isShorthandPropertyAssignment(parent);
+    // `const { a: b } = x` — `a` is a property of x, not a binding in scope.
+    if (tsApi.isBindingElement(parent) && parent.propertyName === id)
+        return false;
+    // `config.timeout` is two halves and only one of them is knowable. The
+    // member needs the receiver's type, which this backend does not infer — but
+    // the receiver itself is an ordinary binding, and it is frequently the
+    // imported constant somebody is actually asking about. Dropping both halves
+    // would lose the reference the whole phase exists to find.
+    if (tsApi.isPropertyAccessExpression(parent))
+        return parent.name !== id;
+    if (tsApi.isQualifiedName(parent))
+        return parent.right !== id;
+    switch (parent.kind) {
+        // Recorded above with a more specific kind.
+        case tsApi.SyntaxKind.ImportSpecifier:
+        case tsApi.SyntaxKind.ExportSpecifier:
+        case tsApi.SyntaxKind.ImportClause:
+        case tsApi.SyntaxKind.NamespaceImport:
+        case tsApi.SyntaxKind.NamespaceExport:
+        case tsApi.SyntaxKind.TypeReference:
+        case tsApi.SyntaxKind.ExpressionWithTypeArguments:
+        case tsApi.SyntaxKind.TypeQuery:
+        case tsApi.SyntaxKind.JsxOpeningElement:
+        case tsApi.SyntaxKind.JsxClosingElement:
+        case tsApi.SyntaxKind.JsxSelfClosingElement:
+            return false;
+        // Not references to anything: labels, and `import.meta`.
+        case tsApi.SyntaxKind.LabeledStatement:
+        case tsApi.SyntaxKind.BreakStatement:
+        case tsApi.SyntaxKind.ContinueStatement:
+        case tsApi.SyntaxKind.MetaProperty:
+            return false;
+        default:
+            break;
+    }
+    // The callee of `f()` and the constructor of `new F()` are already recorded
+    // as "call" and "new". Arguments to either are ordinary reads and fall
+    // through, which is the point of testing the position rather than the parent.
+    if (tsApi.isCallExpression(parent) && parent.expression === id)
+        return false;
+    if (tsApi.isNewExpression(parent) && parent.expression === id)
+        return false;
+    return true;
+}
+/** The text of a string literal, or null for anything computed. */
+function literalText(tsApi, node) {
+    if (tsApi.isStringLiteral(node))
+        return node.text;
+    if (tsApi.isNoSubstitutionTemplateLiteral(node))
+        return node.text;
+    return null;
+}
+/** The name a node contributes to the enclosing-scope stack, if any. */
+function scopeNameOf(tsApi, node) {
+    if (tsApi.isFunctionDeclaration(node) && node.name)
+        return node.name.text;
+    if (tsApi.isClassDeclaration(node) && node.name)
+        return node.name.text;
+    if (tsApi.isMethodDeclaration(node) && tsApi.isIdentifier(node.name))
+        return node.name.text;
+    if (tsApi.isConstructorDeclaration(node))
+        return "constructor";
+    if ((tsApi.isArrowFunction(node) || tsApi.isFunctionExpression(node)) &&
+        node.parent &&
+        tsApi.isVariableDeclaration(node.parent) &&
+        tsApi.isIdentifier(node.parent.name)) {
+        return node.parent.name.text;
+    }
+    return null;
+}
+function scriptKind(tsApi, path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".tsx"))
+        return tsApi.ScriptKind.TSX;
+    if (lower.endsWith(".jsx"))
+        return tsApi.ScriptKind.JSX;
+    if (lower.endsWith(".js") || lower.endsWith(".mjs") || lower.endsWith(".cjs"))
+        return tsApi.ScriptKind.JS;
+    return tsApi.ScriptKind.TS;
+}