@codragraph/cli 1.6.2

package/dist/core/ingestion/resolve-references.js

@@ -0,0 +1,175 @@
+/**
+ * `resolveReferenceSites` — drain `ReferenceSite[]` from a finalized
+ * `ScopeResolutionIndexes` into a `ReferenceIndex` by routing each site
+ * through the appropriate scope-aware `Registry.lookup` (RFC §3.2 Phase 4).
+ *
+ * This is the missing producer that `emit-references.ts` (#925) was
+ * waiting on. The two together form the registry-primary resolution
+ * pipeline:
+ *
+ *     ScopeResolutionIndexes.referenceSites
+ *        │  resolveReferenceSites
+ *        ▼
+ *     ReferenceIndex
+ *        │  emitReferencesToGraph
+ *        ▼
+ *     graph: CALLS / ACCESSES / INHERITS / USES edges
+ *
+ * ## What this module does
+ *
+ *   - For each `ReferenceSite`, picks the registry by `kind`:
+ *     · `call` / `inherits`        → MethodRegistry / ClassRegistry (call-form aware)
+ *     · `read` / `write`           → FieldRegistry  (falls through to MethodRegistry for free names)
+ *     · `type-reference`           → ClassRegistry
+ *     · `import-use`               → all three (best-effort name-lookup)
+ *   - Calls `Registry.lookup` with the site's `inScope`, optional
+ *     explicit receiver, and arity.
+ *   - Takes the top-ranked `Resolution` (best by confidence + tie-break
+ *     cascade); folds it into a `Reference` record and bins by source scope.
+ *
+ * ## What this module does NOT do
+ *
+ *   - No AST walks. The `ReferenceSite[]` is already extracted.
+ *   - No language switches. Per-language behavior flows through
+ *     `RegistryProviders.arityCompatibility` (see `RegistryContext`).
+ *   - No multi-candidate fan-out. We pick `[0]` per RFC §4.3 ("one-shot
+ *     answer"). The full ranked list is preserved in the per-site
+ *     resolution but not emitted as multiple edges; callers that want
+ *     branch-on-ambiguity behavior should consume the registries directly.
+ */
+import { buildClassRegistry, buildFieldRegistry, buildMethodRegistry, CLASS_KINDS, FIELD_KINDS, METHOD_KINDS, } from '../../_shared/index.js';
+/**
+ * Resolve every `ReferenceSite` in `scopes.referenceSites` against the
+ * matching registry and produce a `ReferenceIndex` keyed by source scope
+ * + target def.
+ */
+export function resolveReferenceSites(input) {
+    const { scopes } = input;
+    const providers = input.providers ?? {};
+    const ctx = {
+        scopes: scopes.scopeTree,
+        defs: scopes.defs,
+        qualifiedNames: scopes.qualifiedNames,
+        moduleScopes: scopes.moduleScopes,
+        methodDispatch: scopes.methodDispatch,
+        providers,
+    };
+    const classRegistry = buildClassRegistry(ctx);
+    const methodRegistry = buildMethodRegistry(ctx);
+    const fieldRegistry = buildFieldRegistry(ctx);
+    // bySourceScope is the canonical index; byTargetDef is derived from it.
+    const bySourceScope = new Map();
+    const byTargetDef = new Map();
+    let sitesProcessed = 0;
+    let referencesEmitted = 0;
+    let unresolved = 0;
+    for (const site of scopes.referenceSites) {
+        sitesProcessed++;
+        const resolutions = lookupForSite(site, classRegistry, methodRegistry, fieldRegistry);
+        if (resolutions.length === 0) {
+            unresolved++;
+            continue;
+        }
+        const top = resolutions[0];
+        const ref = buildReference(site, top);
+        referencesEmitted++;
+        let bySource = bySourceScope.get(site.inScope);
+        if (bySource === undefined) {
+            bySource = [];
+            bySourceScope.set(site.inScope, bySource);
+        }
+        bySource.push(ref);
+        let byTarget = byTargetDef.get(top.def.nodeId);
+        if (byTarget === undefined) {
+            byTarget = [];
+            byTargetDef.set(top.def.nodeId, byTarget);
+        }
+        byTarget.push(ref);
+    }
+    // Freeze inner arrays so consumers don't accidentally mutate.
+    const frozenBySource = new Map();
+    for (const [k, v] of bySourceScope)
+        frozenBySource.set(k, Object.freeze([...v]));
+    const frozenByTarget = new Map();
+    for (const [k, v] of byTargetDef)
+        frozenByTarget.set(k, Object.freeze([...v]));
+    return {
+        referenceIndex: { bySourceScope: frozenBySource, byTargetDef: frozenByTarget },
+        stats: { sitesProcessed, referencesEmitted, unresolved },
+    };
+}
+// ─── Internal ───────────────────────────────────────────────────────────────
+/**
+ * Pick the right registry for the site's `kind` and call `lookup`.
+ *
+ * The kind→registry mapping mirrors `mapKindToType` in `emit-references.ts`:
+ *
+ *   | site.kind        | primary registry  | acceptedKinds source         |
+ *   |------------------|-------------------|------------------------------|
+ *   | `call`           | MethodRegistry    | METHOD_KINDS (Method/Func/Ctor)
+ *   | `inherits`       | ClassRegistry     | CLASS_KINDS                  |
+ *   | `type-reference` | ClassRegistry     | CLASS_KINDS                  |
+ *   | `read`/`write`   | FieldRegistry     | FIELD_KINDS                  |
+ *   | `import-use`     | tiered fallback   | METHOD ∪ CLASS ∪ FIELD       |
+ *
+ * `import-use` doesn't have a single registry — the imported name might
+ * be a class, a function, or a constant. Try each in priority order and
+ * return the first non-empty result. Provenance still flows through the
+ * scope's `bindings` (Step 1 lexical hit), so the lookup is correct
+ * regardless of which registry surfaces the def.
+ */
+function lookupForSite(site, classRegistry, methodRegistry, fieldRegistry) {
+    switch (site.kind) {
+        case 'call': {
+            const opts = {
+                ...(site.arity !== undefined ? { callsite: { arity: site.arity } } : {}),
+                ...(site.explicitReceiver !== undefined ? { explicitReceiver: site.explicitReceiver } : {}),
+            };
+            return methodRegistry.lookup(site.name, site.inScope, opts);
+        }
+        case 'inherits':
+        case 'type-reference': {
+            return classRegistry.lookup(site.name, site.inScope);
+        }
+        case 'read':
+        case 'write': {
+            // Try field first; fall through to method then class so bare-name
+            // reads of a function (e.g. `cb = save`) still resolve.
+            const fieldHits = fieldRegistry.lookup(site.name, site.inScope);
+            if (fieldHits.length > 0)
+                return fieldHits;
+            const methodHits = methodRegistry.lookup(site.name, site.inScope);
+            if (methodHits.length > 0)
+                return methodHits;
+            return classRegistry.lookup(site.name, site.inScope);
+        }
+        case 'import-use': {
+            // Try class, method, then field. The lexical-hit Step 1 in
+            // `lookupCore` handles the actual binding lookup; the choice of
+            // registry only narrows `acceptedKinds`.
+            const classHits = classRegistry.lookup(site.name, site.inScope);
+            if (classHits.length > 0)
+                return classHits;
+            const methodHits = methodRegistry.lookup(site.name, site.inScope);
+            if (methodHits.length > 0)
+                return methodHits;
+            return fieldRegistry.lookup(site.name, site.inScope);
+        }
+    }
+}
+/** Compose a `Reference` record from a site + its top resolution. */
+function buildReference(site, top) {
+    return {
+        fromScope: site.inScope,
+        toDef: top.def.nodeId,
+        atRange: site.atRange,
+        kind: site.kind,
+        confidence: top.confidence,
+        evidence: top.evidence,
+    };
+}
+// Re-export the kind sets so consumers don't have to import them
+// separately when constructing custom resolution flows. The mappings
+// stay in `@codragraph/shared` (single source of truth); this is a
+// convenience pass-through only.
+export { CLASS_KINDS, METHOD_KINDS, FIELD_KINDS };

package/dist/core/ingestion/route-extractors/expo.d.ts

@@ -0,0 +1 @@
+export declare function expoFileToRouteURL(filePath: string): string | null;

package/dist/core/ingestion/route-extractors/expo.js

@@ -0,0 +1,36 @@
+// Expo Router route extraction utilities.
+export function expoFileToRouteURL(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    // Skip TypeScript declaration files
+    if (/\.d\.tsx?$/.test(normalized))
+        return null;
+    // Must be inside an app/ directory
+    const appMatch = normalized.match(/app\/(.+)\.(tsx?|jsx?)$/);
+    if (!appMatch)
+        return null;
+    const segments = appMatch[1];
+    const fileName = segments.split('/').pop() || '';
+    // Skip layout files (_layout.tsx)
+    if (fileName.startsWith('_'))
+        return null;
+    // Skip special Expo files (+not-found.tsx, +html.tsx) — but NOT +api files
+    if (fileName.startsWith('+') && !fileName.startsWith('+api'))
+        return null;
+    // Handle Expo API routes: users+api.ts → /users
+    if (fileName.endsWith('+api')) {
+        const apiSegments = segments.replace(/\+api$/, '');
+        const route = '/' + stripRouteGroups(apiSegments);
+        return stripIndex(route);
+    }
+    // Regular screen route
+    const route = '/' + stripRouteGroups(segments);
+    return stripIndex(route);
+}
+function stripRouteGroups(path) {
+    return path.replace(/\([^)]+\)\/?/g, '');
+}
+function stripIndex(route) {
+    if (route === '/index')
+        return '/';
+    return route.replace(/\/index$/, '') || '/';
+}

package/dist/core/ingestion/route-extractors/middleware.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Middleware chain extraction from route handler file content.
+ * Detects wrapper patterns like: export const POST = withA(withB(withC(handler)))
+ */
+/** Keywords that terminate middleware chain walking (not wrapper function names) */
+export declare const MIDDLEWARE_STOP_KEYWORDS: Set<string>;
+/**
+ * Extract middleware wrapper chain from a route handler file.
+ * Detects patterns like: export const POST = withA(withB(withC(handler)))
+ * Returns an object with the wrapper function names (outermost-first) and the
+ * HTTP method they were captured from, or undefined if no chain found.
+ */
+export declare function extractMiddlewareChain(content: string): {
+    chain: string[];
+    method: string;
+} | undefined;
+export interface NextjsMiddlewareConfig {
+    matchers: string[];
+    exportedName: string;
+    wrappedFunctions: string[];
+}
+/**
+ * Parse a Next.js project-level middleware.ts file and extract:
+ * - config.matcher patterns (string or string[])
+ * - the exported middleware function name
+ * - wrapper composition (e.g. chain([withAuth, withI18n]))
+ */
+export declare function extractNextjsMiddlewareConfig(content: string): NextjsMiddlewareConfig | undefined;
+/** Pre-compiled matcher for efficient per-route testing. */
+export type CompiledMatcher = {
+    type: 'prefix';
+    prefix: string;
+} | {
+    type: 'regex';
+    re: RegExp;
+} | {
+    type: 'exact';
+    value: string;
+};
+/**
+ * Compile a Next.js middleware matcher pattern into a reusable matcher.
+ * Call once per pattern, then use compiledMatcherMatchesRoute per route.
+ */
+export declare function compileMatcher(matcher: string): CompiledMatcher | null;
+/** Test a route URL against a pre-compiled matcher. */
+export declare function compiledMatcherMatchesRoute(cm: CompiledMatcher, routeURL: string): boolean;
+export declare function middlewareMatcherMatchesRoute(matcher: string, routeURL: string): boolean;

package/dist/core/ingestion/route-extractors/middleware.js

@@ -0,0 +1,167 @@
+/**
+ * Middleware chain extraction from route handler file content.
+ * Detects wrapper patterns like: export const POST = withA(withB(withC(handler)))
+ */
+/** Keywords that terminate middleware chain walking (not wrapper function names) */
+/** Names that are composition wrappers, not middleware functions themselves. */
+const COMPOSER_NAMES = new Set(['middleware', 'default', 'chain', 'compose']);
+/** Keywords that terminate middleware chain walking (not wrapper function names) */
+export const MIDDLEWARE_STOP_KEYWORDS = new Set([
+    'async',
+    'await',
+    'function',
+    'new',
+    'return',
+    'if',
+    'for',
+    'while',
+    'switch',
+    'class',
+    'const',
+    'let',
+    'var',
+    'req',
+    'res',
+    'request',
+    'response',
+    'event',
+    'ctx',
+    'context',
+    'next',
+]);
+/** Walk nested wrapper calls starting at `pos` in `content`, returning function names. */
+function walkNestedWrappers(content, pos) {
+    const names = [];
+    const nestedRe = /^\s*(\w+)\s*\(/;
+    let remaining = content.slice(pos);
+    let nested;
+    while ((nested = nestedRe.exec(remaining)) !== null) {
+        if (MIDDLEWARE_STOP_KEYWORDS.has(nested[1]))
+            break;
+        names.push(nested[1]);
+        pos += nested[0].length;
+        remaining = content.slice(pos);
+    }
+    return names;
+}
+/**
+ * Extract middleware wrapper chain from a route handler file.
+ * Detects patterns like: export const POST = withA(withB(withC(handler)))
+ * Returns an object with the wrapper function names (outermost-first) and the
+ * HTTP method they were captured from, or undefined if no chain found.
+ */
+export function extractMiddlewareChain(content) {
+    const mwPattern = /export\s+(?:const\s+(POST|GET|PUT|DELETE|PATCH|HEAD|OPTIONS)\s*=|default)\s+(\w+)\s*\(/g;
+    let mwMatch;
+    while ((mwMatch = mwPattern.exec(content)) !== null) {
+        const method = mwMatch[1] ?? 'default';
+        const firstWrapper = mwMatch[2];
+        const chain = [firstWrapper];
+        chain.push(...walkNestedWrappers(content, mwMatch.index + mwMatch[0].length));
+        if (chain.length >= 2 || (chain.length === 1 && /^with[A-Z]/.test(chain[0]))) {
+            return { chain, method };
+        }
+    }
+    return undefined;
+}
+/**
+ * Parse a Next.js project-level middleware.ts file and extract:
+ * - config.matcher patterns (string or string[])
+ * - the exported middleware function name
+ * - wrapper composition (e.g. chain([withAuth, withI18n]))
+ */
+export function extractNextjsMiddlewareConfig(content) {
+    const matchers = [];
+    const matcherArrayRe = /config\s*=\s*\{[^}]*matcher\s*:\s*\[([^\]]*)\]/s;
+    const matcherStringRe = /config\s*=\s*\{[^}]*matcher\s*:\s*(['"`])([^'"`]+)\1/s;
+    const arrMatch = matcherArrayRe.exec(content);
+    if (arrMatch) {
+        const items = arrMatch[1];
+        const strRe = /(['"`])((?:[^'"`\\\\]|\\\\.)*)\1/g;
+        let m;
+        while ((m = strRe.exec(items)) !== null) {
+            matchers.push(m[2]);
+        }
+    }
+    else {
+        const strMatch = matcherStringRe.exec(content);
+        if (strMatch) {
+            matchers.push(strMatch[2]);
+        }
+    }
+    let exportedName = 'middleware';
+    const isNamedMw = /export\s+(?:async\s+)?function\s+middleware\b/.test(content);
+    const isConstMw = /export\s+const\s+middleware\s*=/.test(content);
+    const defaultFunctionMatch = /export\s+default\s+(?:async\s+)?function(?:\s+(\w+))?/.exec(content);
+    const defaultIdentifierMatch = /export\s+default\s+(?!function\b)(\w+)/.exec(content);
+    if (!isNamedMw && !isConstMw) {
+        if (defaultFunctionMatch) {
+            exportedName = defaultFunctionMatch[1] ?? 'middleware';
+        }
+        else if (defaultIdentifierMatch) {
+            exportedName = defaultIdentifierMatch[1];
+        }
+    }
+    // --- wrapper composition ---
+    const wrappedFunctions = [];
+    // Pattern: chain([fn1, fn2]) or compose(fn1, fn2)
+    const chainRe = /(?:chain|compose)\s*\(\s*\[([^\]]+)\]/;
+    const chainMatch = chainRe.exec(content);
+    if (chainMatch) {
+        const fns = chainMatch[1]
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        wrappedFunctions.push(...fns);
+    }
+    // Pattern: export default withA(withB(handler))
+    const wrapperRe = /export\s+default\s+(\w+)\s*\(/;
+    const wrapperMatch = wrapperRe.exec(content);
+    if (wrapperMatch && wrappedFunctions.length === 0) {
+        const name = wrapperMatch[1];
+        if (name !== 'function' && name !== 'async') {
+            wrappedFunctions.push(name);
+            wrappedFunctions.push(...walkNestedWrappers(content, wrapperMatch.index + wrapperMatch[0].length));
+        }
+    }
+    if (!COMPOSER_NAMES.has(exportedName) && !wrappedFunctions.includes(exportedName)) {
+        wrappedFunctions.unshift(exportedName);
+    }
+    const hasExport = isNamedMw || isConstMw || !!defaultFunctionMatch || !!defaultIdentifierMatch;
+    if (!hasExport && matchers.length === 0 && wrappedFunctions.length === 0)
+        return undefined;
+    return { matchers, exportedName, wrappedFunctions };
+}
+/**
+ * Compile a Next.js middleware matcher pattern into a reusable matcher.
+ * Call once per pattern, then use compiledMatcherMatchesRoute per route.
+ */
+export function compileMatcher(matcher) {
+    const paramWild = matcher.replace(/\/:path\*$/, '');
+    if (paramWild !== matcher)
+        return { type: 'prefix', prefix: paramWild };
+    if (matcher.includes('(')) {
+        try {
+            return { type: 'regex', re: new RegExp('^' + matcher + '$') };
+        }
+        catch {
+            return null;
+        }
+    }
+    return { type: 'exact', value: matcher };
+}
+/** Test a route URL against a pre-compiled matcher. */
+export function compiledMatcherMatchesRoute(cm, routeURL) {
+    switch (cm.type) {
+        case 'prefix':
+            return routeURL === cm.prefix || routeURL.startsWith(cm.prefix + '/');
+        case 'regex':
+            return cm.re.test(routeURL);
+        case 'exact':
+            return routeURL === cm.value;
+    }
+}
+export function middlewareMatcherMatchesRoute(matcher, routeURL) {
+    const cm = compileMatcher(matcher);
+    return cm ? compiledMatcherMatchesRoute(cm, routeURL) : false;
+}

package/dist/core/ingestion/route-extractors/nextjs.d.ts

@@ -0,0 +1,3 @@
+export declare function nextjsFileToRouteURL(filePath: string): string | null;
+export declare function normalizeFetchURL(rawURL: string): string | null;
+export declare function routeMatches(fetchURL: string, routeURL: string): boolean;

package/dist/core/ingestion/route-extractors/nextjs.js

@@ -0,0 +1,76 @@
+// Next.js route extraction utilities.
+//
+// Converts file paths to route URLs, extracts HTTP methods from App Router
+// route handlers, normalises fetch URLs, and matches fetch calls to routes.
+// Convert a Next.js file path to its API route URL.
+// Supports both App Router (app/**/route.ts) and Pages Router
+// (pages/api/**/*.ts) conventions.
+// Returns the route URL (e.g. /api/grants) or null if the path is not a
+// recognised route handler.
+export function nextjsFileToRouteURL(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    // App Router: app/**/api/**/route.ts (restrict to API routes to avoid noise
+    // from page-level route handlers that fetch() calls won't match anyway).
+    // Route groups like (admin) may appear before api/.
+    const appMatch = normalized.match(/app\/(.+?)\/route\.(ts|js|tsx|jsx)$/);
+    if (appMatch) {
+        // Strip route groups: (admin), (marketing) etc. are not URL segments
+        const stripped = appMatch[1].replace(/\([^)]+\)\/?/g, '');
+        // Only match if the path contains an api/ segment
+        if (!stripped.startsWith('api/') && stripped !== 'api')
+            return null;
+        return '/' + stripped;
+    }
+    // Pages Router: pages/api/**/*.ts
+    const pagesMatch = normalized.match(/pages\/(api\/.+?)\.(ts|js|tsx|jsx)$/);
+    if (pagesMatch) {
+        let route = '/' + pagesMatch[1];
+        route = route.replace(/\/index$/, '');
+        return route;
+    }
+    return null;
+}
+// Normalise a fetch URL so it can be matched against route patterns.
+// - Strips query strings (?page=1)
+// - Replaces template-literal expressions (${slug}) with [param]
+// - Returns null for URLs that cannot be statically resolved (string
+//   concatenation, function calls, non-API paths).
+export function normalizeFetchURL(rawURL) {
+    let url = rawURL.split('?')[0];
+    url = url.replace(/\$\{[^}]+\}/g, '[param]');
+    url = url.replace(/^`|`$/g, '');
+    // Strip file extensions from URLs (PHP projects use /api/upload.php but routes are /api/upload)
+    url = url.replace(/\.(php|asp|aspx|jsp|cgi)$/, '');
+    if (url.includes('+') || url.includes('('))
+        return null;
+    // Must be an absolute path
+    if (!url.startsWith('/'))
+        return null;
+    return url;
+}
+// Check whether a (normalised) fetch URL matches a Next.js route pattern.
+// Dynamic segments on either side (e.g. [param], [slug]) are treated as
+// wildcards that match any single path segment.
+export function routeMatches(fetchURL, routeURL) {
+    const fetchParts = fetchURL.split('/').filter(Boolean);
+    const routeParts = routeURL.split('/').filter(Boolean);
+    // Check for catch-all route: [...param] or optional catch-all [[...param]]
+    const lastRoutePart = routeParts[routeParts.length - 1];
+    if (lastRoutePart?.startsWith('[...') || lastRoutePart?.startsWith('[[...')) {
+        // Catch-all: match if fetch has at least as many segments as route (minus catch-all)
+        if (fetchParts.length < routeParts.length - 1)
+            return false;
+        return routeParts.slice(0, -1).every((part, i) => {
+            if (part.startsWith('[') || fetchParts[i].startsWith('['))
+                return true;
+            return part === fetchParts[i];
+        });
+    }
+    if (fetchParts.length !== routeParts.length)
+        return false;
+    return fetchParts.every((part, i) => {
+        if (part.startsWith('[') || routeParts[i].startsWith('['))
+            return true;
+        return part === routeParts[i];
+    });
+}

package/dist/core/ingestion/route-extractors/php.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Convert a PHP file path to its route URL.
+ * Handles direct file-based routing (no framework).
+ * api/upload.php → /api/upload
+ * api/next_sign.php → /api/next_sign
+ */
+export declare function phpFileToRouteURL(filePath: string): string | null;

package/dist/core/ingestion/route-extractors/php.js

@@ -0,0 +1,22 @@
+/**
+ * Convert a PHP file path to its route URL.
+ * Handles direct file-based routing (no framework).
+ * api/upload.php → /api/upload
+ * api/next_sign.php → /api/next_sign
+ */
+export function phpFileToRouteURL(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    // Only match files in api/ directory
+    const apiMatch = normalized.match(/^(api\/.+?)\.php$/);
+    if (apiMatch) {
+        const fileName = normalized.split('/').pop().replace('.php', '');
+        // Skip non-handler files — use word-boundary matching to avoid false negatives
+        // on names like "contest", "attestation", "base64_encode"
+        if (fileName.startsWith('_') ||
+            /(?:^|_)(helper|config|test|fixture|mock|setup|bootstrap)(?:_|$)/.test(fileName)) {
+            return null;
+        }
+        return '/' + apiMatch[1];
+    }
+    return null;
+}

package/dist/core/ingestion/route-extractors/response-shapes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Response shape extraction from route handler file content.
+ * Detects .json() calls (JS/TS) and json_encode() calls (PHP),
+ * extracts top-level keys, and classifies by HTTP status code.
+ */
+/**
+ * Detect an HTTP status code associated with a .json() call.
+ */
+export declare function detectStatusCode(content: string, jsonMatchPos: number, closingBracePos: number): number | undefined;
+/**
+ * Extract response shapes from JS/TS handler file content.
+ */
+export declare function extractResponseShapes(content: string): {
+    responseKeys?: string[];
+    errorKeys?: string[];
+};
+export declare function extractPHPResponseShapes(content: string): {
+    responseKeys?: string[];
+    errorKeys?: string[];
+};