@opencodehub/ingestion 0.1.0

package/dist/extract/property-access.js

@@ -0,0 +1,260 @@
+/**
+ * Shared property-access walker powering the ACCESSES-edge emitter.
+ *
+ * Per-function/method body, we scan the source text between `startLine` and
+ * `endLine` (inclusive, 1-indexed) and look for:
+ *   - Member expressions  (`a.b`)            → read
+ *   - Assignment targets  (`a.b = ...`)      → write
+ *   - Subscript accesses  (`a["b"]`)         → read (also "b" when LHS)
+ *
+ * We deliberately do not consume the tree-sitter parse tree: the unified
+ * query does not surface member/attribute/assignment/subscript nodes. A
+ * source-text walker that first strips comments + string literals via
+ * {@link stripComments} is deterministic, language-agnostic, and avoids a
+ * round-trip through the worker pool.
+ *
+ * Per-language providers pass a {@link PropertyAccessConfig} selecting which
+ * flavour of assignment operators to treat as writes (Python augments include
+ * `:=`; some languages use `=` only). The walker is careful to:
+ *   - Skip property names that collide with keywords (`this`, `self`, `if`...).
+ *   - Skip chained receivers (`a.b.c` → only the last segment is treated as
+ *     a property read anchored to the *most recent* identifier).
+ *   - Skip function-call members (`a.foo()` is a call, not a property read).
+ *   - Skip optional chaining (`a?.b`) is kept (TS/JS-only; detected).
+ *
+ * Flat property names only (v2 scope): `user.address.street` yields reads
+ * on `address` (for `user`) and `street` (for `address`). Qualified paths
+ * are a future extension.
+ */
+import { stripComments } from "../providers/extract-helpers.js";
+export const TS_ACCESS_CONFIG = {
+    commentStripped: true,
+    memberSeparator: ".",
+    // Per spec (ECMAScript + TS): `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `**=`,
+    // `<<=`, `>>=`, `>>>=`, `&=`, `|=`, `^=`, `&&=`, `||=`, `??=`.
+    assignmentOperators: [
+        "=",
+        "+=",
+        "-=",
+        "*=",
+        "/=",
+        "%=",
+        "**=",
+        "<<=",
+        ">>=",
+        ">>>=",
+        "&=",
+        "|=",
+        "^=",
+        "&&=",
+        "||=",
+        "??=",
+    ],
+};
+export const PYTHON_ACCESS_CONFIG = {
+    commentStripped: true,
+    memberSeparator: ".",
+    // Python augmented assignment ops + walrus.
+    assignmentOperators: [
+        "=",
+        "+=",
+        "-=",
+        "*=",
+        "/=",
+        "//=",
+        "%=",
+        "**=",
+        "&=",
+        "|=",
+        "^=",
+        ">>=",
+        "<<=",
+        ":=",
+    ],
+};
+/** Language keywords that may appear before a `.` but are not real receivers. */
+const KEYWORD_RECEIVERS = new Set([
+    "if",
+    "else",
+    "for",
+    "while",
+    "return",
+    "yield",
+    "await",
+    "throw",
+    "new",
+    "delete",
+    "typeof",
+    "void",
+    "in",
+    "of",
+    "from",
+    "as",
+    "is",
+    "and",
+    "or",
+    "not",
+    "class",
+    "function",
+    "def",
+    "lambda",
+    "import",
+    "export",
+    "const",
+    "let",
+    "var",
+    "true",
+    "false",
+    "null",
+    "None",
+    "True",
+    "False",
+    "undefined",
+]);
+/**
+ * Extract every property access inside the given function/method bodies.
+ *
+ * `enclosingDefs` is a filtered view of `definitions` (Function / Method /
+ * Constructor kinds only) with pre-resolved `NodeId`s so the walker doesn't
+ * re-derive them.
+ */
+export function extractPropertyAccesses(filePath, sourceText, enclosingDefs, config) {
+    if (enclosingDefs.length === 0)
+        return [];
+    const src = config.commentStripped === true ? stripComments(sourceText) : sourceText;
+    const lines = src.split("\n");
+    const out = [];
+    // Sort by innermost-first: when a method sits inside a class declaration
+    // (which itself might not be a Function/Method/Constructor), `findInnermost`
+    // picks the tightest containing span.
+    const sortedDefs = [...enclosingDefs].sort((a, b) => {
+        const spanA = a.endLine - a.startLine;
+        const spanB = b.endLine - b.startLine;
+        return spanA - spanB;
+    });
+    const sep = escapeRegExp(config.memberSeparator);
+    // Match `<receiver><sep><name>` where `<name>` is the bare identifier we
+    // attribute the access to. `<receiver>` captures everything up to the
+    // final separator so we can reject keyword-prefixed matches and chained
+    // calls (`obj.foo().bar` should not yield a `foo` read — we detect the
+    // `(` after `foo` below).
+    //
+    // `(?<![A-Za-z_$\w])` anchors the receiver to a fresh identifier start.
+    // Named-capture groups chosen to read naturally at the use site.
+    // Note the `[\w$]` lookbehind: `\w` already covers `[A-Za-z0-9_]`, so
+    // adding `A-Z`/`a-z` to the class would create the suspicious-overlapping
+    // ranges that triggered js/overly-large-range. The `$` is the only
+    // identifier character `\w` doesn't include in JS regex semantics.
+    const memberRe = new RegExp(`(?<![\\w$])(?<receiver>[A-Za-z_$][\\w$]*)\\s*\\??${sep}(?<name>[A-Za-z_$][\\w$]*)`, "g");
+    const subscriptRe = /(?<![\w$])(?<receiver>[A-Za-z_$][\w$]*)\s*\[\s*(?<quote>['"])(?<name>[A-Za-z_$][\w$]*)\k<quote>\s*\]/g;
+    // Pre-compile a regex that decides if the substring AFTER a member match
+    // begins with an assignment operator. Longest-match-first so `+=` wins
+    // over `=`.
+    const opsByLength = [...config.assignmentOperators].sort((a, b) => b.length - a.length);
+    const assignHead = new RegExp(`^\\s*(${opsByLength.map(escapeRegExp).join("|")})(?![<>=])`);
+    for (let i = 0; i < lines.length; i += 1) {
+        const lineNo = i + 1;
+        const enclosing = findInnermost(sortedDefs, lineNo);
+        if (enclosing === undefined)
+            continue;
+        const line = lines[i] ?? "";
+        // --- Member expressions (`a.b`, `a?.b`, `a.b = ...`). -------------------
+        for (const m of line.matchAll(memberRe)) {
+            const receiver = m.groups?.["receiver"];
+            const name = m.groups?.["name"];
+            if (receiver === undefined || name === undefined)
+                continue;
+            if (KEYWORD_RECEIVERS.has(receiver))
+                continue;
+            const matchEnd = (m.index ?? 0) + m[0].length;
+            const tail = line.slice(matchEnd);
+            // Skip calls: `a.b(` or `a.b<Type>(` (TS generics). We want to keep
+            // `a.b` as a property access ONLY when it is not the callee of a
+            // function call. Method invocations are already modelled by CALLS.
+            if (isCallTail(tail))
+                continue;
+            const reason = isAssignmentTail(tail, assignHead) ? "write" : "read";
+            out.push({
+                enclosingSymbolId: enclosing.id,
+                propertyName: name,
+                reason,
+                startLine: lineNo,
+                endLine: lineNo,
+                filePath,
+            });
+        }
+        // --- Subscript with string literal (`a["b"]`, `a['b'] = ...`). ---------
+        for (const m of line.matchAll(subscriptRe)) {
+            const receiver = m.groups?.["receiver"];
+            const name = m.groups?.["name"];
+            if (receiver === undefined || name === undefined)
+                continue;
+            if (KEYWORD_RECEIVERS.has(receiver))
+                continue;
+            const matchEnd = (m.index ?? 0) + m[0].length;
+            const tail = line.slice(matchEnd);
+            const reason = isAssignmentTail(tail, assignHead) ? "write" : "read";
+            out.push({
+                enclosingSymbolId: enclosing.id,
+                propertyName: name,
+                reason,
+                startLine: lineNo,
+                endLine: lineNo,
+                filePath,
+            });
+        }
+    }
+    return sortAccesses(out);
+}
+/** Stable ordering: (enclosingSymbolId, propertyName, startLine, reason). */
+export function sortAccesses(accesses) {
+    return [...accesses].sort((a, b) => {
+        if (a.enclosingSymbolId !== b.enclosingSymbolId) {
+            return a.enclosingSymbolId < b.enclosingSymbolId ? -1 : 1;
+        }
+        if (a.propertyName !== b.propertyName) {
+            return a.propertyName < b.propertyName ? -1 : 1;
+        }
+        if (a.startLine !== b.startLine)
+            return a.startLine - b.startLine;
+        if (a.reason !== b.reason)
+            return a.reason < b.reason ? -1 : 1;
+        return 0;
+    });
+}
+/** True when the character tail begins with `(` or `<...>(` (generic call). */
+function isCallTail(tail) {
+    // Direct call: `foo(` possibly with whitespace.
+    if (/^\s*\(/.test(tail))
+        return true;
+    // TS generic call: `foo<A, B>(` — approximate, we only look for `<` then
+    // bounded scan for `>(`.
+    if (/^\s*</.test(tail)) {
+        const close = tail.indexOf(">");
+        if (close !== -1 && /^\s*\(/.test(tail.slice(close + 1)))
+            return true;
+    }
+    return false;
+}
+function isAssignmentTail(tail, assignHead) {
+    return assignHead.test(tail);
+}
+function findInnermost(sortedDefs, line) {
+    for (const d of sortedDefs) {
+        if (line >= d.startLine && line <= d.endLine)
+            return d;
+    }
+    return undefined;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Convenience filter — providers call this to narrow the `ExtractedDefinition`
+ * list down to callable owners, then hand each through `idForDefinition` from
+ * the parse phase before invoking {@link extractPropertyAccesses}.
+ */
+export function callableDefs(defs) {
+    return defs.filter((d) => d.kind === "Function" || d.kind === "Method" || d.kind === "Constructor");
+}
+//# sourceMappingURL=property-access.js.map

package/dist/extract/property-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"property-access.js","sourceRoot":"","sources":["../../src/extract/property-access.ts"],"names":[],"mappings":"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"}

package/dist/extract/receiver-resolver.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Receiver resolver — shared helper used by the ORM and route detectors to
+ * confirm that a receiver identifier (e.g. `app.get(...)`, `prisma.user.findMany`)
+ * actually originates from a specific npm module before a detector emits an
+ * edge. Two paths are wired:
+ *
+ *   1. **Import-graph path** (fast, always available). Walks the per-file
+ *      `ExtractedImport[]` list populated by the parse phase and returns the
+ *      matched module when the identifier is declared as the `localAlias`
+ *      of, or is one of the `importedNames` of, an import declaration.
+ *
+ *   2. **Type-check path** (optional, opt-in). Only invoked when the
+ *      import-graph path misses AND a `ts-morph` project was passed in via
+ *      {@link TsMorphProject}. Uses
+ *      `getApparentType()` → `getSymbol()` → `getDeclarations()[0].getSourceFile()`
+ *      to recover the declaring source file for the receiver's inferred
+ *      type. If that file's path sits under a known `node_modules/<pkg>/`
+ *      segment the module is returned.
+ *
+ * The ts-morph dependency is declared as an `optionalDependencies` entry on
+ * `@opencodehub/ingestion` so repos that don't need type-check precision
+ * never pay for it. When ts-morph isn't wired — or when any step in its
+ * chain throws — the helper silently degrades to "no resolution" and the
+ * caller decides whether to emit heuristically or skip.
+ *
+ * The helper makes no filesystem calls and no network calls. It is pure
+ * over its inputs.
+ */
+import type { ExtractedImport } from "../providers/extraction-types.js";
+/**
+ * Per-symbol import record the resolver accepts. This is a structural
+ * subset of {@link ExtractedImport} so test fixtures can pass in plain
+ * objects without reaching for the full provider types.
+ */
+export interface ImportedSymbol {
+    /** Raw module specifier as written in source (e.g. `@prisma/client`). */
+    readonly source: string;
+    /** Names introduced by a named import, or `undefined` for default / namespace imports. */
+    readonly importedNames?: readonly string[];
+    /** Local alias (default / namespace import, or aliased named import). */
+    readonly localAlias?: string;
+}
+/**
+ * Light wrapper over a `ts-morph` project handle. We deliberately keep the
+ * shape structural so the resolver avoids a hard dependency on the ts-morph
+ * type surface — callers pass any object that can resolve a symbol at a
+ * `(filePath, identifier)` pair back to its declaring source file.
+ */
+export interface TsMorphProject {
+    /**
+     * Return the resolved module specifier (e.g. `@prisma/client`) for the
+     * identifier's apparent type, or `null` when ts-morph cannot figure it out
+     * (missing file, unresolved import, type alias to `any`, etc.).
+     */
+    resolveReceiverModule(filePath: string, identifier: string): ResolvedTypeInfo | null;
+}
+/** Output of {@link TsMorphProject.resolveReceiverModule}. */
+export interface ResolvedTypeInfo {
+    /** Module specifier recovered from the declaring source file's path. */
+    readonly moduleName: string;
+    /** Symbol name of the apparent type (e.g. `PrismaClient`). */
+    readonly typeName?: string;
+}
+/** The resolution outcome returned by {@link resolveReceiver}. */
+export interface ReceiverOrigin {
+    readonly identifier: string;
+    /** Module specifier the identifier is imported from, when known. */
+    readonly moduleName?: string;
+    /** Resolved type symbol name (ts-morph path only). */
+    readonly resolvedType?: string;
+    /** Which resolution path succeeded. */
+    readonly source: "import-graph" | "type-check";
+}
+/**
+ * Resolve the origin of `identifier` as used inside `filePath`. Returns
+ * `null` when neither the import-graph nor the ts-morph path produced a
+ * match.
+ */
+export declare function resolveReceiver(identifier: string, filePath: string, importsByFile: ReadonlyMap<string, readonly ImportedSymbol[]> | undefined, tsMorphProject?: TsMorphProject): ReceiverOrigin | null;
+/**
+ * Adapt a `ReadonlyMap<string, readonly ExtractedImport[]>` (the shape the
+ * parse phase actually populates) into the structural {@link ImportedSymbol}
+ * shape the resolver wants. This is a zero-cost view — no copies are made.
+ */
+export declare function importsMapFromExtracted(importsByFile: ReadonlyMap<string, readonly ExtractedImport[]>): ReadonlyMap<string, readonly ImportedSymbol[]>;
+//# sourceMappingURL=receiver-resolver.d.ts.map

package/dist/extract/receiver-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receiver-resolver.d.ts","sourceRoot":"","sources":["../../src/extract/receiver-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAExE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,yEAAyE;IACzE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;CACtF;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CAAC;CAChD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC,GAAG,SAAS,EACzE,cAAc,CAAC,EAAE,cAAc,GAC9B,cAAc,GAAG,IAAI,CAmCvB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC,GAC7D,WAAW,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC,CAEhD"}

package/dist/extract/receiver-resolver.js

@@ -0,0 +1,77 @@
+/**
+ * Receiver resolver — shared helper used by the ORM and route detectors to
+ * confirm that a receiver identifier (e.g. `app.get(...)`, `prisma.user.findMany`)
+ * actually originates from a specific npm module before a detector emits an
+ * edge. Two paths are wired:
+ *
+ *   1. **Import-graph path** (fast, always available). Walks the per-file
+ *      `ExtractedImport[]` list populated by the parse phase and returns the
+ *      matched module when the identifier is declared as the `localAlias`
+ *      of, or is one of the `importedNames` of, an import declaration.
+ *
+ *   2. **Type-check path** (optional, opt-in). Only invoked when the
+ *      import-graph path misses AND a `ts-morph` project was passed in via
+ *      {@link TsMorphProject}. Uses
+ *      `getApparentType()` → `getSymbol()` → `getDeclarations()[0].getSourceFile()`
+ *      to recover the declaring source file for the receiver's inferred
+ *      type. If that file's path sits under a known `node_modules/<pkg>/`
+ *      segment the module is returned.
+ *
+ * The ts-morph dependency is declared as an `optionalDependencies` entry on
+ * `@opencodehub/ingestion` so repos that don't need type-check precision
+ * never pay for it. When ts-morph isn't wired — or when any step in its
+ * chain throws — the helper silently degrades to "no resolution" and the
+ * caller decides whether to emit heuristically or skip.
+ *
+ * The helper makes no filesystem calls and no network calls. It is pure
+ * over its inputs.
+ */
+/**
+ * Resolve the origin of `identifier` as used inside `filePath`. Returns
+ * `null` when neither the import-graph nor the ts-morph path produced a
+ * match.
+ */
+export function resolveReceiver(identifier, filePath, importsByFile, tsMorphProject) {
+    // ---- Path 1: import graph --------------------------------------------
+    const imports = importsByFile?.get(filePath);
+    if (imports !== undefined) {
+        for (const imp of imports) {
+            if (imp.localAlias !== undefined && imp.localAlias === identifier) {
+                return { identifier, moduleName: imp.source, source: "import-graph" };
+            }
+            if (imp.importedNames?.includes(identifier)) {
+                return { identifier, moduleName: imp.source, source: "import-graph" };
+            }
+        }
+    }
+    // ---- Path 2: ts-morph type check -------------------------------------
+    if (tsMorphProject !== undefined) {
+        try {
+            const info = tsMorphProject.resolveReceiverModule(filePath, identifier);
+            if (info !== null) {
+                return {
+                    identifier,
+                    moduleName: info.moduleName,
+                    ...(info.typeName !== undefined ? { resolvedType: info.typeName } : {}),
+                    source: "type-check",
+                };
+            }
+        }
+        catch {
+            // DET-UN-001 — ts-morph may throw on a corrupt tsconfig / missing
+            // file / internal invariant. Silent degradation: the caller treats
+            // a `null` return as "unknown" and the strict-detectors flag decides
+            // whether to emit heuristically.
+        }
+    }
+    return null;
+}
+/**
+ * Adapt a `ReadonlyMap<string, readonly ExtractedImport[]>` (the shape the
+ * parse phase actually populates) into the structural {@link ImportedSymbol}
+ * shape the resolver wants. This is a zero-cost view — no copies are made.
+ */
+export function importsMapFromExtracted(importsByFile) {
+    return importsByFile;
+}
+//# sourceMappingURL=receiver-resolver.js.map

package/dist/extract/receiver-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receiver-resolver.js","sourceRoot":"","sources":["../../src/extract/receiver-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAoDH;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,UAAkB,EAClB,QAAgB,EAChB,aAAyE,EACzE,cAA+B;IAE/B,yEAAyE;IACzE,MAAM,OAAO,GAAG,aAAa,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,GAAG,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;gBAClE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;YACxE,CAAC;YACD,IAAI,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC5C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;YACxE,CAAC;QACH,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,cAAc,CAAC,qBAAqB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YACxE,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBAClB,OAAO;oBACL,UAAU;oBACV,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACvE,MAAM,EAAE,YAAY;iBACrB,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,kEAAkE;YAClE,mEAAmE;YACnE,qEAAqE;YACrE,iCAAiC;QACnC,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,aAA8D;IAE9D,OAAO,aAA+D,CAAC;AACzE,CAAC"}

package/dist/extract/route-detector-java.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Spring MVC / Spring WebFlux route detector.
+ *
+ * Covers the canonical annotation shapes:
+ *
+ *   @RequestMapping("/users")                              // class / method
+ *   @RequestMapping(value = "/users", method = RequestMethod.GET)
+ *   @GetMapping("/users/{id}")
+ *   @PostMapping("/users")
+ *   @PutMapping("/users/{id}")
+ *   @DeleteMapping("/users/{id}")
+ *   @PatchMapping("/users/{id}")
+ *
+ * Class-level `@RequestMapping` prefixes are concatenated with method-
+ * level prefixes when both are present on the same class declaration.
+ * WebFlux uses the same annotations; there is no separate dispatch.
+ *
+ * Profile-gated: route phase only dispatches when `java` participates
+ * and `spring-boot` (or any `spring-*` variant) is on the detected
+ * frameworks list.
+ */
+import type { ExtractedRoute, ExtractInput } from "./types.js";
+/**
+ * Detect Spring routes in a single Java file. Returns one entry per
+ * method-level mapping; class-level `@RequestMapping` path prefixes are
+ * prepended to each method's URL.
+ */
+export declare function detectSpringRoutes(input: ExtractInput): readonly ExtractedRoute[];
+//# sourceMappingURL=route-detector-java.d.ts.map

package/dist/extract/route-detector-java.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-detector-java.d.ts","sourceRoot":"","sources":["../../src/extract/route-detector-java.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAS/D;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,cAAc,EAAE,CA6DjF"}

package/dist/extract/route-detector-java.js

@@ -0,0 +1,190 @@
+/**
+ * Spring MVC / Spring WebFlux route detector.
+ *
+ * Covers the canonical annotation shapes:
+ *
+ *   @RequestMapping("/users")                              // class / method
+ *   @RequestMapping(value = "/users", method = RequestMethod.GET)
+ *   @GetMapping("/users/{id}")
+ *   @PostMapping("/users")
+ *   @PutMapping("/users/{id}")
+ *   @DeleteMapping("/users/{id}")
+ *   @PatchMapping("/users/{id}")
+ *
+ * Class-level `@RequestMapping` prefixes are concatenated with method-
+ * level prefixes when both are present on the same class declaration.
+ * WebFlux uses the same annotations; there is no separate dispatch.
+ *
+ * Profile-gated: route phase only dispatches when `java` participates
+ * and `spring-boot` (or any `spring-*` variant) is on the detected
+ * frameworks list.
+ */
+const METHOD_RE = /@\s*(GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping)\s*(?:\(\s*(?:value\s*=\s*)?(?:"([^"]*)"|\{\s*"([^"]*)"\s*\}))?/g;
+const REQUEST_MAPPING_RE = /@\s*RequestMapping\s*\(([\s\S]*?)\)/g;
+const CLASS_DECL_RE = /\bclass\s+([A-Za-z_][\w]*)/g;
+/**
+ * Detect Spring routes in a single Java file. Returns one entry per
+ * method-level mapping; class-level `@RequestMapping` path prefixes are
+ * prepended to each method's URL.
+ */
+export function detectSpringRoutes(input) {
+    const { filePath, content } = input;
+    const out = [];
+    // Collect class declarations + their class-level @RequestMapping prefix.
+    const classRanges = collectClassRanges(content);
+    // Method-specific shorthand annotations.
+    METHOD_RE.lastIndex = 0;
+    let m = METHOD_RE.exec(content);
+    while (m !== null) {
+        const verb = annotationToVerb(m[1]);
+        const url = normalizeUrl(m[2] ?? m[3] ?? "");
+        const atIdx = m.index;
+        m = METHOD_RE.exec(content);
+        if (verb === undefined)
+            continue;
+        const enclosing = findEnclosingClass(atIdx, classRanges);
+        const finalUrl = composeUrl(enclosing?.baseUrl ?? "", url);
+        out.push({
+            url: finalUrl,
+            method: verb,
+            handlerFile: filePath,
+            framework: "spring",
+        });
+    }
+    // Generic @RequestMapping — may carry `method = RequestMethod.GET` or a
+    // list `method = { RequestMethod.GET, RequestMethod.POST }`.
+    REQUEST_MAPPING_RE.lastIndex = 0;
+    let rm = REQUEST_MAPPING_RE.exec(content);
+    while (rm !== null) {
+        const body = rm[1] ?? "";
+        const atIdx = rm.index;
+        rm = REQUEST_MAPPING_RE.exec(content);
+        const url = readRequestMappingUrl(body);
+        const methods = readRequestMappingMethods(body);
+        if (url === undefined)
+            continue;
+        const enclosing = findEnclosingClass(atIdx, classRanges);
+        const finalUrl = composeUrl(enclosing?.baseUrl ?? "", normalizeUrl(url));
+        if (methods.length === 0) {
+            // No method filter — class-level mapping or a catch-all. Emit
+            // without `method` so the downstream phase stores `ANY`.
+            out.push({
+                url: finalUrl,
+                handlerFile: filePath,
+                framework: "spring",
+            });
+        }
+        else {
+            for (const verb of methods) {
+                out.push({
+                    url: finalUrl,
+                    method: verb,
+                    handlerFile: filePath,
+                    framework: "spring",
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Walk every `class Foo` declaration in the file and associate the
+ * character range `[startIdx, nextClass | eof)` with the class-level
+ * `@RequestMapping` path prefix that sits immediately above the class
+ * declaration. Classes without a class-level mapping get `baseUrl = ""`.
+ */
+function collectClassRanges(content) {
+    const ranges = [];
+    CLASS_DECL_RE.lastIndex = 0;
+    let m = CLASS_DECL_RE.exec(content);
+    while (m !== null) {
+        ranges.push({ startIdx: m.index, name: m[1] });
+        m = CLASS_DECL_RE.exec(content);
+    }
+    const out = [];
+    for (let i = 0; i < ranges.length; i++) {
+        const r = ranges[i];
+        if (r === undefined)
+            continue;
+        const endIdx = i + 1 < ranges.length ? (ranges[i + 1]?.startIdx ?? content.length) : content.length;
+        const baseUrl = readClassRequestMappingAbove(content, r.startIdx);
+        out.push({ startIdx: r.startIdx, endIdx, baseUrl });
+    }
+    return out;
+}
+function findEnclosingClass(idx, ranges) {
+    for (const r of ranges) {
+        if (idx >= r.startIdx && idx < r.endIdx)
+            return r;
+    }
+    return undefined;
+}
+/**
+ * Scan backwards from `classStart` looking for a `@RequestMapping(…)`
+ * annotation within the last ~400 characters (enough for the annotation
+ * block; Spring conventions keep class-level mappings terse).
+ */
+function readClassRequestMappingAbove(content, classStart) {
+    const from = Math.max(0, classStart - 400);
+    const window = content.slice(from, classStart);
+    const re = /@\s*RequestMapping\s*\(([\s\S]*?)\)/g;
+    let best = "";
+    let m = re.exec(window);
+    while (m !== null) {
+        const url = readRequestMappingUrl(m[1] ?? "");
+        if (url !== undefined)
+            best = normalizeUrl(url);
+        m = re.exec(window);
+    }
+    return best;
+}
+function readRequestMappingUrl(body) {
+    // `value = "/x"` or bare `"/x"` or `path = "/x"` or `{ "/a", "/b" }`.
+    const valueKw = /(?:value|path)\s*=\s*(?:"([^"]*)"|\{\s*"([^"]*)"\s*\})/.exec(body);
+    if (valueKw !== null)
+        return valueKw[1] ?? valueKw[2];
+    const first = /(?:^|[,\s(])(?:"([^"]*)"|\{\s*"([^"]*)"\s*\})/.exec(body);
+    return first?.[1] ?? first?.[2];
+}
+function readRequestMappingMethods(body) {
+    // `method = RequestMethod.GET` or `method = { RequestMethod.GET, ... }`.
+    const methodSection = /method\s*=\s*(?:\{([^}]*)\}|([^,)\s]+))/.exec(body);
+    if (methodSection === null)
+        return [];
+    const raw = methodSection[1] ?? methodSection[2] ?? "";
+    const out = [];
+    for (const m of raw.matchAll(/RequestMethod\.([A-Z]+)/g)) {
+        out.push(m[1]);
+    }
+    return out;
+}
+function annotationToVerb(annotation) {
+    switch (annotation) {
+        case "GetMapping":
+            return "GET";
+        case "PostMapping":
+            return "POST";
+        case "PutMapping":
+            return "PUT";
+        case "DeleteMapping":
+            return "DELETE";
+        case "PatchMapping":
+            return "PATCH";
+        default:
+            return undefined;
+    }
+}
+function normalizeUrl(u) {
+    if (u === "")
+        return "/";
+    return u.startsWith("/") ? u : `/${u}`;
+}
+function composeUrl(base, path) {
+    if (base === "")
+        return path;
+    const b = base.endsWith("/") ? base.slice(0, -1) : base;
+    const p = path === "/" ? "" : path;
+    const joined = `${b}${p}`;
+    return joined === "" ? "/" : joined;
+}
+//# sourceMappingURL=route-detector-java.js.map