cgraphx 2.0.2 → 2.0.3

package/dist/core/code/engine/core/ingestion/route-extractors/spring.js

@@ -0,0 +1,441 @@
+"use strict";
+/**
+ * Spring route annotation extractor for the ingestion pipeline.
+ *
+ * Extracts `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`,
+ * `@PatchMapping`, and `@RequestMapping` annotations from Java source files
+ * and returns `ExtractedDecoratorRoute[]` with class-level `@RequestMapping`
+ * prefixes already resolved per-class.
+ *
+ * This module is the ingestion-layer counterpart of
+ * `group/extractors/http-patterns/java.ts` (which extracts HTTP contracts
+ * for cross-repo matching). It uses the same tree-sitter capture approach:
+ * a single predicate-free query matches all route annotations generically,
+ * then a for-loop discriminates class-level prefixes from method-level routes
+ * by reading `@node.type` and the annotation name.
+ *
+ * The query is predicate-free to avoid the tree-sitter 0.21.x hazard where
+ * `#match?` / `#eq?` predicates in a top-level `[...]` alternation silently
+ * drop sibling-branch matches (see group-layer `JAVA_ROUTE_ANNOTATION_PATTERNS`
+ * header comment for details).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSpringRoutes = extractSpringRoutes;
+exports.extractSpringTypes = extractSpringTypes;
+const tree_sitter_1 = __importDefault(require("tree-sitter"));
+const tree_sitter_java_1 = __importDefault(require("tree-sitter-java"));
+const spring_shared_js_1 = require("./spring-shared.js");
+/**
+ * Single predicate-free tree-sitter query that captures all route annotations
+ * on classes and methods. Discrimination by annotation name and node type
+ * happens in the loop below.
+ *
+ * Captures:
+ *   @ann   → annotation name identifier (RequestMapping, GetMapping, etc.)
+ *   @node  → enclosing declaration (class_declaration | method_declaration)
+ *   @value → the string-literal argument
+ *   @key   → the named-argument member key (absent for positional form)
+ *
+ * Method-level routes accept both the bare string form `@GetMapping("/x")` and
+ * the array form `@GetMapping({"/a","/b"})` (positional or `path =`/`value =`):
+ * a multi-element array yields one match per element, so the Phase 2 loop emits
+ * one route per path with no special-casing. This mirrors the group-layer
+ * `java.ts` query so the two Spring extractors stay in parity (#2138 follow-up;
+ * the divergence here was the root of the #2265 array-form gap). The class-level
+ * `@RequestMapping` branches also match the array form, but only to *detect* it:
+ * an array-form class prefix can't be resolved to a single string, so Phase 2
+ * suppresses that class's method-level array routes rather than emit them with a
+ * dropped prefix (a wrong route). Full class-array cross-product support is left
+ * to a follow-up (#2280).
+ */
+const ROUTE_ANNOTATION_QUERY = new tree_sitter_1.default.Query(tree_sitter_java_1.default, `
+  [
+    (class_declaration
+      (modifiers
+        (annotation
+          name: [(identifier) (scoped_identifier)] @ann
+          arguments: (annotation_argument_list
+            [(string_literal) @value
+             (element_value_array_initializer (string_literal) @value)])))) @node
+    (class_declaration
+      (modifiers
+        (annotation
+          name: [(identifier) (scoped_identifier)] @ann
+          arguments: (annotation_argument_list
+            (element_value_pair
+              key: (identifier) @key
+              value: [(string_literal) @value
+                      (element_value_array_initializer (string_literal) @value)]))))) @node
+    (method_declaration
+      (modifiers
+        (annotation
+          name: [(identifier) (scoped_identifier)] @ann
+          arguments: (annotation_argument_list
+            [(string_literal) @value
+             (element_value_array_initializer (string_literal) @value)])))) @node
+    (method_declaration
+      (modifiers
+        (annotation
+          name: [(identifier) (scoped_identifier)] @ann
+          arguments: (annotation_argument_list
+            (element_value_pair
+              key: (identifier) @key
+              value: [(string_literal) @value
+                      (element_value_array_initializer (string_literal) @value)]))))) @node
+  ]
+`);
+/**
+ * Extract Spring route annotations from a parsed Java file.
+ *
+ * Uses a single tree-sitter query pass to capture all annotations, then
+ * discriminates class-level prefixes from method-level routes in a loop.
+ * Handles multiple classes per file, each with its own prefix.
+ *
+ * @param tree - tree-sitter parse tree
+ * @param filePath - relative file path (for `ExtractedDecoratorRoute.filePath`)
+ * @param lineOffset - line offset for pre-processing (usually 0)
+ * @returns Decorator routes with prefix already set per-class
+ */
+function extractSpringRoutes(tree, filePath, lineOffset = 0) {
+    const matches = ROUTE_ANNOTATION_QUERY.matches(tree.rootNode);
+    // Phase 1: collect class-level @RequestMapping prefixes keyed by node id.
+    // A scalar prefix (`@RequestMapping("/base")`) is stored in prefixByClassId.
+    // A class whose @RequestMapping uses the array form (`@RequestMapping({...})`)
+    // is instead recorded in classesWithArrayPrefix: there is no single prefix to
+    // store, and Phase 2 uses this to suppress that class's method-level array
+    // routes rather than emit them unprefixed (a wrong route — see #2280). Full
+    // class-array cross-product support is out of scope here.
+    const prefixByClassId = new Map();
+    const classesWithArrayPrefix = new Set();
+    const classHttpMethodsById = new Map();
+    for (const match of TYPE_DECLARATION_QUERY.matches(tree.rootNode)) {
+        const typeNode = match.captures.find((capture) => capture.name === 'type')?.node;
+        if (typeNode?.type === 'class_declaration') {
+            classHttpMethodsById.set(typeNode.id, typeRequestMethods(typeNode));
+        }
+    }
+    for (const match of matches) {
+        const caps = {};
+        for (const { name, node } of match.captures) {
+            caps[name] = node;
+        }
+        const annNode = caps['ann'];
+        const node = caps['node'];
+        const valueNode = caps['value'];
+        const keyNode = caps['key'];
+        if (!annNode || !node || !valueNode)
+            continue;
+        const capturedAnnotationName = annNode.text.split('.').pop() ?? annNode.text;
+        if (node.type === 'class_declaration' && capturedAnnotationName === 'RequestMapping') {
+            if (!(0, spring_shared_js_1.isRouteMemberKey)(keyNode))
+                continue;
+            if (valueNode.parent?.type === 'element_value_array_initializer') {
+                classesWithArrayPrefix.add(node.id);
+                continue;
+            }
+            const prefix = (0, spring_shared_js_1.unquoteSpringLiteral)(valueNode.text);
+            if (prefix !== null)
+                prefixByClassId.set(node.id, prefix);
+        }
+    }
+    // Phase 2: collect method-level routes and resolve their class prefix
+    const routes = [];
+    const httpMethodsByAnnotationId = new Map();
+    for (const match of matches) {
+        const caps = {};
+        for (const { name, node } of match.captures) {
+            caps[name] = node;
+        }
+        const annNode = caps['ann'];
+        const node = caps['node'];
+        const valueNode = caps['value'];
+        const keyNode = caps['key'];
+        if (!annNode || !node || !valueNode)
+            continue;
+        if (node.type !== 'method_declaration')
+            continue;
+        const ann = annNode.text.split('.').pop() ?? annNode.text;
+        const annotationNode = annNode.parent;
+        if (!annotationNode)
+            continue;
+        let methodMethods = httpMethodsByAnnotationId.get(annotationNode.id);
+        if (!methodMethods) {
+            methodMethods = (0, spring_shared_js_1.springAnnotationHttpMethods)(ann, annotationNode.text);
+            httpMethodsByAnnotationId.set(annotationNode.id, methodMethods);
+        }
+        if (methodMethods.length === 0)
+            continue;
+        if (!(0, spring_shared_js_1.isRouteMemberKey)(keyNode))
+            continue;
+        const routePath = (0, spring_shared_js_1.unquoteSpringLiteral)(valueNode.text);
+        if (routePath === null)
+            continue;
+        const enclosingType = (0, spring_shared_js_1.findEnclosingType)(node);
+        // Interface-declared `@*Mapping`s are not concrete routes on their own — the
+        // implementing controller inherits them. Skip here; the cross-file
+        // inheritance pass (#2288) re-emits them attributed to the controller, with
+        // both the interface's and the controller's class prefixes resolved. Emitting
+        // the interface route directly would be wrong (unprefixed, wrong owner).
+        if (enclosingType?.kind === 'interface')
+            continue;
+        const enclosingClass = enclosingType?.kind === 'class' ? enclosingType.node : null;
+        const httpMethods = (0, spring_shared_js_1.intersectSpringHttpMethods)(enclosingClass ? (classHttpMethodsById.get(enclosingClass.id) ?? ['*']) : ['*'], methodMethods);
+        if (httpMethods.length === 0)
+            continue;
+        // Suppress a method-level *array-form* route nested under a class-level
+        // array-form @RequestMapping. The class prefix is one of several values that
+        // cannot be resolved to a single string here, so emitting the route would
+        // drop the prefix and yield a wrong unprefixed Route (a false signal, worse
+        // than a missing one). Skipping keeps ingestion a strict subset of the group
+        // scan — safe under routeCoverage:'partial'. Full class-array cross-product
+        // support is tracked in #2280. (Scalar method paths under an array class
+        // prefix are left unchanged: that pre-existing divergence is out of scope.)
+        const isArrayElement = valueNode.parent?.type === 'element_value_array_initializer';
+        if (isArrayElement && enclosingClass && classesWithArrayPrefix.has(enclosingClass.id)) {
+            continue;
+        }
+        const classPrefix = enclosingClass ? (prefixByClassId.get(enclosingClass.id) ?? '') : '';
+        // `node` is the annotated `method_declaration`; its name field is the
+        // handler method name (resolved to a symbol UID later by the routes phase).
+        const handlerName = node.childForFieldName('name')?.text;
+        for (const httpMethod of httpMethods) {
+            routes.push({
+                filePath,
+                routePath,
+                httpMethod,
+                decoratorName: ann,
+                lineNumber: annNode.startPosition.row + lineOffset,
+                ...(classPrefix ? { prefix: classPrefix } : {}),
+                ...(handlerName ? { handlerName } : {}),
+            });
+        }
+    }
+    // Mapping annotations without a path bind to the enclosing class prefix.
+    for (const match of TYPE_DECLARATION_QUERY.matches(tree.rootNode)) {
+        const typeNode = match.captures.find((capture) => capture.name === 'type')?.node;
+        if (typeNode?.type !== 'class_declaration')
+            continue;
+        const classPrefix = prefixByClassId.get(typeNode.id) ?? '';
+        const classMethods = classHttpMethodsById.get(typeNode.id) ?? ['*'];
+        for (const methodNode of directMethods(typeNode)) {
+            const handlerName = methodNode.childForFieldName('name')?.text;
+            if (!handlerName)
+                continue;
+            for (const annotationNode of declarationAnnotations(methodNode)) {
+                const ann = annotationName(annotationNode) ?? '';
+                if (annotationHasRouteMember(annotationNode))
+                    continue;
+                const methodMethods = (0, spring_shared_js_1.springAnnotationHttpMethods)(ann, annotationNode.text);
+                const httpMethods = (0, spring_shared_js_1.intersectSpringHttpMethods)(classMethods, methodMethods);
+                if (httpMethods.length === 0)
+                    continue;
+                for (const httpMethod of httpMethods) {
+                    routes.push({
+                        filePath,
+                        routePath: '',
+                        httpMethod,
+                        decoratorName: ann,
+                        lineNumber: annotationNode.startPosition.row + lineOffset,
+                        ...(classPrefix ? { prefix: classPrefix } : {}),
+                        handlerName,
+                    });
+                }
+            }
+        }
+    }
+    return routes;
+}
+/**
+ * Tree-sitter query capturing every Java type declaration (class + interface),
+ * used by `extractSpringTypes` to build the project-wide `SharedSpringType`
+ * view the cross-file interface-inheritance pass consumes (#2288).
+ */
+const TYPE_DECLARATION_QUERY = new tree_sitter_1.default.Query(tree_sitter_java_1.default, `[(class_declaration) @type (interface_declaration) @type]`);
+/** Direct annotations on a type/method declaration (reads its `modifiers` child). */
+function declarationAnnotations(node) {
+    // `modifiers` is a NAMED CHILD of the declaration (not a named field) in
+    // tree-sitter-java — matching the group layer's `hasAnnotation`.
+    const modifiers = node.namedChildren.find((c) => c.type === 'modifiers');
+    if (!modifiers)
+        return [];
+    return modifiers.namedChildren.filter((c) => c.type === 'annotation' || c.type === 'marker_annotation');
+}
+const annotationName = (ann) => {
+    // Trailing segment of a possibly fully-qualified annotation name
+    // (`org.springframework.web.bind.annotation.GetMapping` → `GetMapping`), so a
+    // FQN annotation is classified the same as its simple form — matching the
+    // group layer's `simpleName` normalization. A simple name maps to itself.
+    const text = ann.childForFieldName('name')?.text;
+    return text?.split('.').pop() ?? text;
+};
+/**
+ * Collect the route path(s) carried by an annotation's argument list, honoring
+ * both positional and `path =`/`value =` named arguments and both the bare
+ * string and array forms. Non-route named args (`consumes`, `produces`, …) are
+ * dropped via `isRouteMemberKey`. Returns one entry per string element.
+ */
+function annotationRoutePaths(ann) {
+    const args = ann.childForFieldName('arguments');
+    if (!args)
+        return [];
+    const out = [];
+    const pushLiteral = (lit) => {
+        const v = (0, spring_shared_js_1.unquoteSpringLiteral)(lit.text);
+        if (v !== null)
+            out.push(v);
+    };
+    const pushFromValue = (valueNode) => {
+        if (valueNode.type === 'string_literal')
+            pushLiteral(valueNode);
+        else if (valueNode.type === 'element_value_array_initializer') {
+            for (const el of valueNode.namedChildren)
+                if (el.type === 'string_literal')
+                    pushLiteral(el);
+        }
+    };
+    for (const child of args.namedChildren) {
+        if (child.type === 'string_literal' || child.type === 'element_value_array_initializer') {
+            pushFromValue(child); // positional
+        }
+        else if (child.type === 'element_value_pair') {
+            const key = child.childForFieldName('key');
+            if (!(0, spring_shared_js_1.isRouteMemberKey)(key ?? undefined))
+                continue;
+            const value = child.childForFieldName('value');
+            if (value)
+                pushFromValue(value);
+        }
+    }
+    return out;
+}
+/** Whether an annotation explicitly supplies a positional or path/value member. */
+function annotationHasRouteMember(ann) {
+    const args = ann.childForFieldName('arguments');
+    if (!args)
+        return false;
+    for (const child of args.namedChildren) {
+        if (child.type !== 'element_value_pair')
+            return true;
+        const key = child.childForFieldName('key');
+        if ((0, spring_shared_js_1.isRouteMemberKey)(key ?? undefined))
+            return true;
+    }
+    return false;
+}
+/** Static class/interface-level RequestMapping method constraint, or wildcard by default. */
+function typeRequestMethods(typeNode) {
+    const mappings = declarationAnnotations(typeNode).filter((ann) => annotationName(ann) === 'RequestMapping');
+    if (mappings.length === 0)
+        return ['*'];
+    if (mappings.length !== 1)
+        return [];
+    return (0, spring_shared_js_1.springAnnotationHttpMethods)('RequestMapping', mappings[0].text);
+}
+function annotationRoutePathsOrDefault(ann) {
+    const paths = annotationRoutePaths(ann);
+    if (paths.length > 0)
+        return paths;
+    return annotationHasRouteMember(ann) ? [] : [''];
+}
+/** Class-level `@RequestMapping` prefixes for a type (array-aware; may be []). */
+function typeClassPrefixes(typeNode) {
+    const prefixes = [];
+    for (const ann of declarationAnnotations(typeNode)) {
+        if (annotationName(ann) === 'RequestMapping')
+            prefixes.push(...annotationRoutePaths(ann));
+    }
+    return prefixes;
+}
+/** The simple names of the interfaces a class declares via `implements`. */
+function implementedInterfaceNames(typeNode) {
+    const interfacesNode = typeNode.childForFieldName('interfaces');
+    if (!interfacesNode)
+        return [];
+    const out = [];
+    const visit = (node) => {
+        if (node.type === 'type_identifier' || node.type === 'scoped_type_identifier') {
+            out.push(node.text.split('.').pop() ?? node.text);
+            return;
+        }
+        for (const child of node.namedChildren)
+            visit(child);
+    };
+    visit(interfacesNode);
+    return out;
+}
+/** Direct `method_declaration` children of a type (not methods of nested types). */
+function directMethods(typeNode) {
+    const out = [];
+    const visit = (node) => {
+        for (const child of node.namedChildren) {
+            if (child.type === 'method_declaration') {
+                out.push(child);
+                continue;
+            }
+            // Don't descend into a nested type — its methods aren't this type's.
+            if (child !== typeNode &&
+                (child.type === 'class_declaration' || child.type === 'interface_declaration')) {
+                continue;
+            }
+            visit(child);
+        }
+    };
+    visit(typeNode);
+    return out;
+}
+/**
+ * Build the project-wide `SharedSpringType` view for one Java file: every class
+ * and interface with its class prefixes, implemented interfaces, controller
+ * flag, and per-method route annotations. The cross-file inheritance pass
+ * (#2288) feeds these into the shared `resolveInheritedSpringRoutes` so a
+ * concrete controller inherits the `@*Mapping`s declared on its interfaces.
+ *
+ * This is the ingestion counterpart of the group layer's `collectSpringTypes`
+ * (`group/extractors/http-patterns/java.ts`); both produce the same neutral
+ * shape so the two layers resolve inheritance identically (#2078 parity).
+ */
+function extractSpringTypes(tree, filePath) {
+    const out = [];
+    for (const match of TYPE_DECLARATION_QUERY.matches(tree.rootNode)) {
+        const typeNode = match.captures.find((c) => c.name === 'type')?.node;
+        if (!typeNode)
+            continue;
+        const name = typeNode.childForFieldName('name')?.text;
+        if (!name)
+            continue;
+        const kind = typeNode.type === 'interface_declaration' ? 'interface' : 'class';
+        const annNames = declarationAnnotations(typeNode).map(annotationName);
+        const isController = kind === 'class' && (annNames.includes('RestController') || annNames.includes('Controller'));
+        const classMethods = typeRequestMethods(typeNode);
+        const methods = directMethods(typeNode)
+            .map((methodNode) => {
+            const methodName = methodNode.childForFieldName('name')?.text;
+            if (!methodName)
+                return null;
+            const routes = [];
+            for (const ann of declarationAnnotations(methodNode)) {
+                const methodMethods = (0, spring_shared_js_1.springAnnotationHttpMethods)(annotationName(ann) ?? '', ann.text);
+                const verbs = (0, spring_shared_js_1.intersectSpringHttpMethods)(classMethods, methodMethods);
+                for (const verb of verbs) {
+                    for (const path of annotationRoutePathsOrDefault(ann))
+                        routes.push({ method: verb, path });
+                }
+            }
+            return { name: methodName, routes };
+        })
+            .filter((m) => m !== null);
+        out.push({
+            filePath,
+            kind,
+            name,
+            classPrefixes: typeClassPrefixes(typeNode),
+            implementedInterfaces: kind === 'class' ? implementedInterfaceNames(typeNode) : [],
+            isController,
+            methods,
+        });
+    }
+    return out;
+}

package/dist/core/code/engine/core/ingestion/scope-extractor-bridge.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Bridge between a language provider's `emitScopeCaptures` hook and the
+ * `ScopeExtractor` (RFC #909 Ring 2 PKG #920).
+ *
+ * Extracted into its own module so it can be imported by test code
+ * without pulling in `parse-worker.ts` — which has a top-level
+ * `parentPort!.on('message', ...)` call that assumes a worker-thread
+ * context and throws on direct import.
+ *
+ * The bridge:
+ *
+ *   1. Short-circuits when the provider has NOT implemented
+ *      `emitScopeCaptures`. Returns `undefined`; zero work done. This is
+ *      the state of every language today — `ParsedFile` production stays
+ *      dormant until a language migrates.
+ *   2. Short-circuits empty / whitespace-only files. There is no scope
+ *      content to extract, and some tree-sitter queries do not match an
+ *      otherwise valid empty root node.
+ *   3. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
+ *   4. **Swallows exceptions from either side.** A failure here returns
+ *      `undefined` and emits a warning via `onWarn`; legacy parsing on
+ *      the same file continues unaffected by the scope-extraction miss.
+ *      Scope-based resolution is the new path under construction — it
+ *      must not destabilize the legacy DAG.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractParsedFile = extractParsedFile;
+const scope_extractor_js_1 = require("./scope-extractor.js");
+const logger_js_1 = require("../logger.js");
+/**
+ * Produce a `ParsedFile` for the given file, or `undefined` when the
+ * provider hasn't migrated / the extractor throws. Never propagates
+ * exceptions.
+ */
+function extractParsedFile(provider, sourceText, filePath, onWarn, cachedTree, sourceKind = 'full-file') {
+    if (provider.emitScopeCaptures === undefined)
+        return undefined;
+    if (sourceText.trim().length === 0)
+        return undefined;
+    try {
+        // A provider that rewrites source before parsing must see the same text
+        // here that the parse worker fed tree-sitter, or the two halves of the
+        // pipeline analyze different programs. Only the cache-miss path re-parses;
+        // with a cached tree the emitter ignores the text. The transform is
+        // length-preserving, so every offset still indexes the original.
+        const parseText = cachedTree === undefined
+            ? (provider.preprocessSource?.(sourceText, filePath) ?? sourceText)
+            : sourceText;
+        const captures = provider.emitScopeCaptures(parseText, filePath, cachedTree, { sourceKind });
+        return (0, scope_extractor_js_1.extract)(captures, filePath, provider);
+    }
+    catch (err) {
+        const message = `scope extraction failed for ${filePath}: ${err instanceof Error ? err.message : String(err)}`;
+        if (onWarn !== undefined)
+            onWarn(message);
+        logger_js_1.logger.warn(message);
+        return undefined;
+    }
+}