@tyroneross/navgator 0.2.2 → 0.10.0

package/dist/scanners/connections/import-scanner.js

@@ -0,0 +1,756 @@
+/**
+ * NavGator Import Scanner
+ * Fast regex-based file-level import graph builder.
+ * Extracts import/require/export-from statements and resolves to actual file paths.
+ * Covers TS/JS (this file) and Python (delegated to `python-imports.ts`) —
+ * see the Python branch in `scanImports` below for why the two paths stay
+ * separate rather than sharing one abstraction today.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { generateComponentId, generateConnectionId, } from '../../types.js';
+import { MAX_FILE_SIZE_BYTES, capLongLines, collapseWhitespaceRuns } from '../scan-limits.js';
+import { extractPythonImports, resolvePythonImport, pythonPackageHead, } from './python-imports.js';
+// Extensions to try when resolving bare imports (order matters)
+const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+const INDEX_FILES = RESOLVE_EXTENSIONS.map(ext => `index${ext}`);
+// Module specifier patterns. Candidates are filtered to relative paths or
+// aliases configured by the nearest owning tsconfig/jsconfig.
+//
+// SEC-012. `import` plus a long whitespace run drives this clause into
+// quadratic backtracking, because with no closing quote the engine retries
+// every clause split at every start offset.
+//
+// BOUNDING THE QUANTIFIER DID NOT FIX IT, and the earlier version of this
+// comment claimed otherwise. Re-measured with `{0,4096}?` in place: 2,000
+// chars = 4,311 ms, 4,000 = 50,501 ms, 8,000 = 391,597 ms. The unbounded
+// clause it replaced cost 4,171 ms at 2,000 — statistically the same. A cap
+// only removes inputs longer than the cap, so a 4,000-character line sits
+// under MAX_LINE_LENGTH and still costs 50 seconds.
+//
+// What actually defeats it is `collapseWhitespaceRuns` in scan-limits.ts: a
+// specifier is always quoted, so a line with no quote never reaches the engine.
+// That takes the same input to 0 ms at 200,000 chars. The bound stays because
+// it is free and narrows the window for any quoted pathological line.
+const IMPORT_CLAUSE = '[\\s\\S]{0,4096}?';
+const ES_IMPORT_RE = new RegExp(`(?:import\\s+(?:${IMPORT_CLAUSE}\\s+from\\s+)?['"]([^'"]+)['"])`, 'g');
+const ES_REEXPORT_RE = /export\s+(?:type\s+)?(?:\{[^}]*\}|\*(?:\s+as\s+\w+)?)\s+from\s+['"]([^'"]+)['"]/g;
+const REQUIRE_RE = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+const DYNAMIC_IMPORT_RE = /import\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+// Bare specifier patterns — npm package imports (NOT relative, NOT alias).
+// Captures anything not starting with ./ ../ @/ ~/ — includes @scope/name and bare names.
+// Excludes node: protocol (built-ins) and data: / http: protocols.
+const BARE_SPEC = `(?!\\.\\.?\\/|@\\/|~\\/|node:|data:|http:|https:|file:)([a-zA-Z0-9@][a-zA-Z0-9@_./-]*)`;
+const ES_IMPORT_BARE_RE = new RegExp(`import\\s+(?:${IMPORT_CLAUSE}\\s+from\\s+)?['\"]${BARE_SPEC}['\"]`, 'g');
+const ES_REEXPORT_BARE_RE = new RegExp(`export\\s+(?:\\{[^}]*\\}|\\*(?:\\s+as\\s+\\w+)?)\\s+from\\s+['\"]${BARE_SPEC}['\"]`, 'g');
+const REQUIRE_BARE_RE = new RegExp(`require\\s*\\(\\s*['\"]${BARE_SPEC}['\"]\\s*\\)`, 'g');
+const DYNAMIC_IMPORT_BARE_RE = new RegExp(`import\\s*\\(\\s*['\"]${BARE_SPEC}['\"]\\s*\\)`, 'g');
+// Map .js/.jsx extensions to their TypeScript equivalents
+// (TS convention: `import './foo.js'` resolves to `./foo.ts`)
+const JS_TO_TS = [
+    ['.js', '.ts'],
+    ['.js', '.tsx'],
+    ['.jsx', '.tsx'],
+    ['.jsx', '.ts'],
+];
+function normalizeProjectPath(file) {
+    return file.split(path.sep).join('/');
+}
+function isOutsideProject(relativePath) {
+    return relativePath === '..' ||
+        relativePath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativePath);
+}
+function matchPathAlias(specifier, pattern) {
+    const wildcardIndex = pattern.indexOf('*');
+    if (wildcardIndex === -1) {
+        return specifier === pattern ? '' : null;
+    }
+    const prefix = pattern.slice(0, wildcardIndex);
+    const suffix = pattern.slice(wildcardIndex + 1);
+    if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix))
+        return null;
+    if (specifier.length < prefix.length + suffix.length)
+        return null;
+    return specifier.slice(prefix.length, specifier.length - suffix.length);
+}
+function resolveAliasTargets(specifier, pathAliases) {
+    for (const alias of pathAliases) {
+        const wildcardValue = matchPathAlias(specifier, alias.pattern);
+        if (wildcardValue === null)
+            continue;
+        return alias.absoluteTargets.map(target => target.replace('*', wildcardValue));
+    }
+    return [];
+}
+function isConfiguredAlias(specifier, pathAliases) {
+    return pathAliases.some(alias => matchPathAlias(specifier, alias.pattern) !== null);
+}
+/**
+ * Resolve a relative import specifier to an actual file path.
+ * Uses a known-files set for fast validation instead of fs.existsSync.
+ */
+function resolveImport(specifier, importerDir, projectRoot, knownFiles, pathAliases = []) {
+    const absoluteTargets = specifier.startsWith('.')
+        ? [path.resolve(importerDir, specifier)]
+        : resolveAliasTargets(specifier, pathAliases);
+    for (const absTarget of absoluteTargets) {
+        const relativeTarget = path.relative(projectRoot, absTarget);
+        // Don't resolve outside project.
+        if (isOutsideProject(relativeTarget))
+            continue;
+        const relTarget = normalizeProjectPath(relativeTarget);
+        // Try exact path.
+        if (knownFiles.has(relTarget))
+            return relTarget;
+        // Try .js → .ts mapping (TS convention: import './foo.js' → ./foo.ts).
+        for (const [jsExt, tsExt] of JS_TO_TS) {
+            if (relTarget.endsWith(jsExt)) {
+                const candidate = relTarget.slice(0, -jsExt.length) + tsExt;
+                if (knownFiles.has(candidate))
+                    return candidate;
+            }
+        }
+        // Try adding extensions.
+        for (const ext of RESOLVE_EXTENSIONS) {
+            const candidate = relTarget + ext;
+            if (knownFiles.has(candidate))
+                return candidate;
+        }
+        // Try as directory with index file.
+        for (const indexFile of INDEX_FILES) {
+            const candidate = normalizeProjectPath(path.join(relTarget, indexFile));
+            if (knownFiles.has(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Load aliases from one owning tsconfig/jsconfig. Targets are made absolute
+ * relative to that config's baseUrl (or config directory by default).
+ */
+function loadPathAliasesFromConfig(configPath) {
+    const configDir = path.dirname(configPath);
+    try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        let config;
+        try {
+            config = JSON.parse(raw);
+        }
+        catch {
+            const stripped = raw
+                .replace(/^\s*\/\/.*$/gm, '')
+                .replace(/\/\*[\s\S]*?\*\//g, '')
+                .replace(/,\s*([}\]])/g, '$1');
+            config = JSON.parse(stripped);
+        }
+        const paths = config?.compilerOptions?.paths;
+        const baseUrl = typeof config?.compilerOptions?.baseUrl === 'string'
+            ? config.compilerOptions.baseUrl
+            : '.';
+        const baseDir = path.resolve(configDir, baseUrl);
+        const aliases = [];
+        if (paths && typeof paths === 'object') {
+            for (const [pattern, targets] of Object.entries(paths)) {
+                if (!Array.isArray(targets) || targets.length === 0)
+                    continue;
+                const absoluteTargets = targets
+                    .filter((target) => typeof target === 'string')
+                    .map(target => path.resolve(baseDir, target));
+                if (absoluteTargets.length > 0)
+                    aliases.push({ pattern, absoluteTargets });
+            }
+        }
+        if (aliases.length > 0) {
+            return aliases.sort((a, b) => {
+                const aSpecificity = a.pattern.replace('*', '').length;
+                const bSpecificity = b.pattern.replace('*', '').length;
+                if (aSpecificity !== bSpecificity)
+                    return bSpecificity - aSpecificity;
+                return Number(a.pattern.includes('*')) - Number(b.pattern.includes('*'));
+            });
+        }
+    }
+    catch {
+        return [];
+    }
+    // Preserve the Next.js @/ convention when a local config has no paths.
+    const nextConfigExists = ['next.config.js', 'next.config.mjs', 'next.config.ts']
+        .some(file => fs.existsSync(path.join(configDir, file)));
+    return nextConfigExists
+        ? [{ pattern: '@/*', absoluteTargets: [path.join(configDir, '*')] }]
+        : [];
+}
+function loadPathAliasesForImporter(importerFile, projectRoot, cache) {
+    const root = path.resolve(projectRoot);
+    let currentDir = path.dirname(path.resolve(projectRoot, importerFile));
+    const visited = [];
+    while (true) {
+        const cached = cache.get(currentDir);
+        if (cached) {
+            for (const dir of visited)
+                cache.set(dir, cached);
+            return cached;
+        }
+        visited.push(currentDir);
+        const configPath = ['tsconfig.json', 'jsconfig.json']
+            .map(file => path.join(currentDir, file))
+            .find(file => fs.existsSync(file));
+        if (configPath) {
+            const aliases = loadPathAliasesFromConfig(configPath);
+            for (const dir of visited)
+                cache.set(dir, aliases);
+            return aliases;
+        }
+        if (currentDir === root)
+            break;
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir || isOutsideProject(path.relative(root, parentDir)))
+            break;
+        currentDir = parentDir;
+    }
+    const fallback = ['next.config.js', 'next.config.mjs', 'next.config.ts']
+        .some(file => fs.existsSync(path.join(root, file)))
+        ? [{ pattern: '@/*', absoluteTargets: [path.join(root, '*')] }]
+        : [];
+    for (const dir of visited)
+        cache.set(dir, fallback);
+    return fallback;
+}
+/**
+ * Read one source file with SEC-012 input bounds applied.
+ *
+ * An untrusted tree (`navgator scan-remote`) chooses its own file contents, so
+ * the input is bounded BEFORE any regex touches it: oversized files are
+ * skipped outright, and long lines are blanked in place. Blanking preserves
+ * the line COUNT, so every `file:line` this scanner reports stays correct.
+ * Returns null when the file is unreadable or over the size cap — callers
+ * already skip nulls.
+ */
+async function readBoundedFile(projectRoot, file) {
+    try {
+        const absolute = path.join(projectRoot, file);
+        const stat = await fs.promises.stat(absolute);
+        if (!stat.isFile() || stat.size > MAX_FILE_SIZE_BYTES)
+            return null;
+        const raw = await fs.promises.readFile(absolute, 'utf-8');
+        // Order matters only for cost, not correctness: collapsing runs removes
+        // the pathological input outright, the length cap catches minified blobs
+        // that carry no absurd run but are still enormous.
+        return { file, content: capLongLines(collapseWhitespaceRuns(raw)) };
+    }
+    catch {
+        return null;
+    }
+}
+function extractImports(content, pathAliases) {
+    const specifiers = new Map();
+    const patterns = [
+        ES_IMPORT_RE, ES_REEXPORT_RE, REQUIRE_RE, DYNAMIC_IMPORT_RE,
+    ];
+    for (const pattern of patterns) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+            const specifier = match[1];
+            if (specifier && (specifier.startsWith('.') || isConfiguredAlias(specifier, pathAliases))) {
+                const typeOnly = (pattern === ES_IMPORT_RE && /^\s*import\s+type\b/.test(match[0])) ||
+                    (pattern === ES_REEXPORT_RE && /^\s*export\s+type\b/.test(match[0]));
+                // Runtime use wins if the same specifier appears in both forms.
+                specifiers.set(specifier, (specifiers.get(specifier) ?? true) && typeOnly);
+            }
+        }
+    }
+    return [...specifiers].map(([specifier, typeOnly]) => ({ specifier, typeOnly }));
+}
+/**
+ * Extract bare package specifiers from file content.
+ * Returns raw specifiers before subpath stripping (e.g. "react/jsx-runtime").
+ */
+function extractBareImports(content) {
+    const specifiers = [];
+    const patterns = [
+        ES_IMPORT_BARE_RE, ES_REEXPORT_BARE_RE, REQUIRE_BARE_RE, DYNAMIC_IMPORT_BARE_RE,
+    ];
+    for (const pattern of patterns) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+            if (match[1])
+                specifiers.push(match[1]);
+        }
+    }
+    return [...new Set(specifiers)];
+}
+/**
+ * Strip subpath from a bare specifier to get the package root.
+ *   "react"                       → "react"
+ *   "react/jsx-runtime"           → "react"
+ *   "@radix-ui/react-dialog"      → "@radix-ui/react-dialog"
+ *   "@radix-ui/react-dialog/Root" → "@radix-ui/react-dialog"
+ */
+function stripSubpath(specifier) {
+    if (specifier.startsWith('@')) {
+        // Scoped package: keep first two segments
+        const parts = specifier.split('/');
+        if (parts.length < 2)
+            return specifier;
+        return `${parts[0]}/${parts[1]}`;
+    }
+    // Unscoped: keep first segment
+    const idx = specifier.indexOf('/');
+    return idx === -1 ? specifier : specifier.slice(0, idx);
+}
+/**
+ * Find the line number where a specifier appears in the content.
+ */
+function findImportLine(content, specifier) {
+    const idx = content.indexOf(specifier);
+    if (idx === -1)
+        return 1;
+    // Count newlines before the match
+    let line = 1;
+    for (let i = 0; i < idx; i++) {
+        if (content[i] === '\n')
+            line++;
+    }
+    return line;
+}
+function componentNameFromFile(file) {
+    const normalized = file.replace(/\\/g, '/');
+    const withoutExtension = normalized.replace(/\.[^.]+$/, '');
+    const segments = withoutExtension.split('/').filter(Boolean);
+    if (segments[0] === 'src' || segments[0] === 'app' || segments[0] === 'lib') {
+        segments.shift();
+    }
+    if (segments[segments.length - 1] === 'index' && segments.length > 1) {
+        segments.pop();
+    }
+    return segments.join('/') || path.basename(withoutExtension);
+}
+function inferLayerFromFile(file) {
+    const normalized = file.replace(/\\/g, '/').toLowerCase();
+    if (/(^|\/)(ui|components|views|pages|frontend|web)(\/|$)/.test(normalized))
+        return 'frontend';
+    if (/(^|\/)(db|database|prisma|drizzle|migrations)(\/|$)/.test(normalized))
+        return 'database';
+    if (/(^|\/)(queue|queues|jobs|workers)(\/|$)/.test(normalized))
+        return 'queue';
+    if (/(^|\/)(infra|infrastructure|terraform|k8s|docker)(\/|$)/.test(normalized))
+        return 'infra';
+    return 'backend';
+}
+function buildFileComponent(file, timestamp) {
+    const name = componentNameFromFile(file);
+    return {
+        component_id: generateComponentId('component', name),
+        name,
+        type: 'component',
+        role: {
+            purpose: `Internal module at ${file}`,
+            layer: inferLayerFromFile(file),
+            critical: false,
+        },
+        source: {
+            detection_method: 'auto',
+            config_files: [file],
+            confidence: 0.95,
+        },
+        connects_to: [],
+        connected_from: [],
+        status: 'active',
+        tags: ['internal', 'module'],
+        metadata: {
+            file,
+            kind: 'source-file',
+        },
+        timestamp,
+        last_updated: timestamp,
+    };
+}
+/**
+ * Scan source files and build file-level import connections.
+ * Accepts the already-discovered source file list from the main scanner
+ * to avoid redundant glob and ensure consistent file coverage.
+ *
+ * When `knownPackages` is provided, bare imports (e.g. `import X from "react"`)
+ * are emitted as `uses-package` edges from the source file component to the
+ * matching npm package component. Bare specifiers with no matching known
+ * package are skipped silently (no ghost nodes).
+ *
+ * Python files run through a parallel branch lower down (extraction and
+ * resolution delegated to `python-imports.ts`) using the same
+ * `buildFileComponent` / `readBoundedFile` machinery, so `imports` and
+ * `uses-package` edges come out in the identical shape either language
+ * produces them in. The TS/JS file set and the Python file set never mix —
+ * each resolves only against its own `knownFiles`.
+ */
+export async function scanImports(projectRoot, sourceFiles, knownPackages) {
+    const components = [];
+    const connections = [];
+    // Filter to TS/JS files only
+    let files;
+    if (sourceFiles) {
+        files = sourceFiles
+            .map(file => path.isAbsolute(file)
+            ? normalizeProjectPath(path.relative(projectRoot, file))
+            : file.replace(/\\/g, '/'))
+            .filter(f => f.endsWith('.ts') || f.endsWith('.tsx') ||
+            f.endsWith('.js') || f.endsWith('.jsx') ||
+            f.endsWith('.mjs') || f.endsWith('.cjs'));
+        // Exclude .d.ts files
+        files = files.filter(f => !f.endsWith('.d.ts'));
+    }
+    else {
+        // Fallback: use glob (shouldn't happen in normal flow)
+        const { glob } = await import('glob');
+        files = await glob('**/*.{ts,tsx,js,jsx,mjs,cjs}', {
+            cwd: projectRoot,
+            ignore: [
+                '**/node_modules/**', '**/dist/**', '**/build/**', '**/.next/**',
+                '**/.git/**', '**/*.d.ts', '**/coverage/**',
+            ],
+        });
+    }
+    // Same source, filtered to Python instead. Kept as a fully separate list —
+    // see the "Python import graph" pass below for why it stays out of `files`
+    // and `knownFiles`.
+    let pythonFiles;
+    if (sourceFiles) {
+        pythonFiles = sourceFiles
+            .map(file => path.isAbsolute(file)
+            ? normalizeProjectPath(path.relative(projectRoot, file))
+            : file.replace(/\\/g, '/'))
+            .filter(f => f.endsWith('.py'));
+    }
+    else {
+        // Fallback: use glob (shouldn't happen in normal flow)
+        const { glob } = await import('glob');
+        pythonFiles = await glob('**/*.py', {
+            cwd: projectRoot,
+            ignore: [
+                '**/node_modules/**', '**/dist/**', '**/build/**', '**/.next/**',
+                '**/.git/**', '**/coverage/**', '**/venv/**', '**/.venv/**',
+                '**/__pycache__/**',
+            ],
+        });
+    }
+    // Build a Set of known files for O(1) resolution lookups
+    const knownFiles = new Set(files);
+    // Separate known-files set for Python resolution. TS/JS specifiers never
+    // resolve against Python files and vice versa — the two languages don't
+    // share a module namespace, so mixing the sets would produce wrong edges.
+    const pythonKnownFiles = new Set(pythonFiles);
+    const pathAliasCache = new Map();
+    const now = Date.now();
+    const componentIdByFile = new Map();
+    // Build a Map<packageName, component_id> for O(1) bare-import resolution.
+    // Only populated when caller provided knownPackages; otherwise bare-import
+    // edges are not emitted (backwards-compatible with callers that don't pass
+    // the package list).
+    const packageIdByName = new Map();
+    if (knownPackages) {
+        for (const pkg of knownPackages) {
+            packageIdByName.set(pkg.name, pkg.component_id);
+        }
+    }
+    for (const file of files) {
+        const component = buildFileComponent(file, now);
+        components.push(component);
+        componentIdByFile.set(file, component.component_id);
+    }
+    for (const file of pythonFiles) {
+        const component = buildFileComponent(file, now);
+        components.push(component);
+        componentIdByFile.set(file, component.component_id);
+    }
+    // Read files in batches
+    const batchSize = 100;
+    for (let i = 0; i < files.length; i += batchSize) {
+        const batch = files.slice(i, i + batchSize);
+        const results = await Promise.all(batch.map(file => readBoundedFile(projectRoot, file)));
+        for (const result of results) {
+            if (!result)
+                continue;
+            const { file, content } = result;
+            const importerDir = path.dirname(path.join(projectRoot, file));
+            const pathAliases = loadPathAliasesForImporter(file, projectRoot, pathAliasCache);
+            const specifiers = extractImports(content, pathAliases);
+            for (const spec of specifiers) {
+                const resolved = resolveImport(spec.specifier, importerDir, projectRoot, knownFiles, pathAliases);
+                if (!resolved)
+                    continue;
+                const line = findImportLine(content, spec.specifier);
+                connections.push({
+                    connection_id: generateConnectionId('imports'),
+                    from: {
+                        component_id: componentIdByFile.get(file) || `FILE:${file}`,
+                        location: { file, line },
+                    },
+                    to: {
+                        component_id: componentIdByFile.get(resolved) || `FILE:${resolved}`,
+                        location: { file: resolved, line: 1 },
+                    },
+                    connection_type: 'imports',
+                    code_reference: {
+                        file,
+                        symbol: spec.specifier,
+                        symbol_type: 'import',
+                        line_start: line,
+                    },
+                    detected_from: 'import-scanner',
+                    ...(spec.typeOnly ? { runtime_relevance: 'type-only' } : {}),
+                    confidence: 1.0,
+                    timestamp: now,
+                    last_verified: now,
+                });
+            }
+            // Bare-package edges: `import X from "react"` → file uses-package react.
+            // Only emitted when the caller provided a knownPackages set; bare
+            // specifiers that don't match a known package are skipped silently
+            // (no ghost nodes).
+            if (packageIdByName.size > 0) {
+                const bareSpecs = extractBareImports(content);
+                const emitted = new Set(); // dedupe per-file: one edge per package
+                for (const rawSpec of bareSpecs) {
+                    // TypeScript path aliases take precedence over packages with the same
+                    // leading segment.
+                    if (isConfiguredAlias(rawSpec, pathAliases))
+                        continue;
+                    const pkgName = stripSubpath(rawSpec);
+                    const targetId = packageIdByName.get(pkgName);
+                    if (!targetId)
+                        continue;
+                    if (emitted.has(pkgName))
+                        continue;
+                    emitted.add(pkgName);
+                    const line = findImportLine(content, rawSpec);
+                    connections.push({
+                        connection_id: generateConnectionId('uses-package'),
+                        from: {
+                            component_id: componentIdByFile.get(file) || `FILE:${file}`,
+                            location: { file, line },
+                        },
+                        to: {
+                            component_id: targetId,
+                        },
+                        connection_type: 'uses-package',
+                        code_reference: {
+                            file,
+                            symbol: pkgName,
+                            symbol_type: 'import',
+                            line_start: line,
+                        },
+                        description: `${file} uses ${pkgName}`,
+                        detected_from: 'import-scanner (bare)',
+                        confidence: 1.0,
+                        timestamp: now,
+                        last_verified: now,
+                    });
+                }
+            }
+        }
+    }
+    // Python import graph. A parallel branch, not a refactor of the TS/JS
+    // path above — extraction/resolution live in `python-imports.ts`, but the
+    // edge shapes below are written out by hand to match the TS/JS block
+    // exactly (`imports` connection, optional `uses-package` per package).
+    for (let i = 0; i < pythonFiles.length; i += batchSize) {
+        const batch = pythonFiles.slice(i, i + batchSize);
+        const results = await Promise.all(batch.map(file => readBoundedFile(projectRoot, file)));
+        for (const result of results) {
+            if (!result)
+                continue;
+            const { file, content } = result;
+            const specs = extractPythonImports(content);
+            const emittedPackages = new Set(); // dedupe per-file: one edge per package
+            for (const spec of specs) {
+                const resolved = resolvePythonImport(spec, file, pythonKnownFiles);
+                if (resolved) {
+                    const line = findImportLine(content, spec.specifier);
+                    connections.push({
+                        connection_id: generateConnectionId('imports'),
+                        from: {
+                            component_id: componentIdByFile.get(file) || `FILE:${file}`,
+                            location: { file, line },
+                        },
+                        to: {
+                            component_id: componentIdByFile.get(resolved) || `FILE:${resolved}`,
+                            location: { file: resolved, line: 1 },
+                        },
+                        connection_type: 'imports',
+                        code_reference: {
+                            file,
+                            symbol: spec.specifier,
+                            symbol_type: 'import',
+                            line_start: line,
+                        },
+                        detected_from: 'python-import-scanner',
+                        // No `runtime_relevance` field here: unlike TS/JS, Python has no
+                        // type-only import form for this scanner to distinguish.
+                        confidence: 0.9,
+                        timestamp: now,
+                        last_verified: now,
+                    });
+                }
+                // Third-party edge: only for absolute imports whose head isn't
+                // stdlib and matches a package the caller already knows about (e.g.
+                // parsed from requirements.txt) — same `knownPackages` contract as
+                // the TS/JS bare-import block above. No match → no edge, no ghost
+                // nodes.
+                if (packageIdByName.size === 0)
+                    continue;
+                const pkgHead = pythonPackageHead(spec);
+                if (!pkgHead)
+                    continue;
+                const targetId = packageIdByName.get(pkgHead);
+                if (!targetId)
+                    continue;
+                if (emittedPackages.has(pkgHead))
+                    continue;
+                emittedPackages.add(pkgHead);
+                const line = findImportLine(content, spec.specifier);
+                connections.push({
+                    connection_id: generateConnectionId('uses-package'),
+                    from: {
+                        component_id: componentIdByFile.get(file) || `FILE:${file}`,
+                        location: { file, line },
+                    },
+                    to: {
+                        component_id: targetId,
+                    },
+                    connection_type: 'uses-package',
+                    code_reference: {
+                        file,
+                        symbol: pkgHead,
+                        symbol_type: 'import',
+                        line_start: line,
+                    },
+                    description: `${file} uses ${pkgHead}`,
+                    detected_from: 'python-import-scanner (bare)',
+                    confidence: 0.9,
+                    timestamp: now,
+                    last_verified: now,
+                });
+            }
+        }
+    }
+    // Second pass: detect fetch('/api/...') patterns — Next.js runtime data flow
+    // Matches: fetch('/api/graph'), fetch(`/api/${path}`), fetchWithTimeout('/api/...')
+    const FETCH_API_RE = /fetch\s*\(\s*['"`](\/api\/[^'"`\s?]+)/g;
+    const FETCH_TEMPLATE_RE = /fetch\s*\(\s*`(\/api\/[^`]*)`/g;
+    const FETCH_WRAPPER_RE = /(?:fetchWith\w+|apiFetch|fetchJSON|fetcher)\s*\(\s*['"`](\/api\/[^'"`\s?]+)/g;
+    for (let i = 0; i < files.length; i += batchSize) {
+        const batch = files.slice(i, i + batchSize);
+        const results = await Promise.all(batch.map(file => readBoundedFile(projectRoot, file)));
+        for (const result of results) {
+            if (!result)
+                continue;
+            const { file, content } = result;
+            // Only scan frontend files (pages, components, app/ routes).
+            // Anchor on segment boundaries OR project-root start so top-level
+            // `app/page.js`, `app/canvas/page.js`, `pages/index.js`, `components/Foo.js`,
+            // `hooks/useX.js` (no leading slash) match the same as nested `src/app/...`.
+            const isFrontend = file.startsWith('app/') || file.includes('/app/') ||
+                file.startsWith('pages/') || file.includes('/pages/') ||
+                file.startsWith('components/') || file.includes('/components/') ||
+                file.startsWith('hooks/') || file.includes('/hooks/');
+            if (!isFrontend)
+                continue;
+            // Run all fetch patterns
+            const fetchPatterns = [FETCH_API_RE, FETCH_TEMPLATE_RE, FETCH_WRAPPER_RE];
+            const foundApiPaths = new Set();
+            for (const pattern of fetchPatterns) {
+                pattern.lastIndex = 0;
+                let fetchMatch;
+                while ((fetchMatch = pattern.exec(content)) !== null) {
+                    let apiPath = fetchMatch[1];
+                    // For template literals, extract the static prefix: /api/graph/${id} → /api/graph
+                    if (apiPath.includes('$')) {
+                        apiPath = apiPath.split('$')[0].replace(/\/+$/, '');
+                    }
+                    if (apiPath.startsWith('/api/') && apiPath.length > 5) {
+                        foundApiPaths.add(apiPath);
+                    }
+                }
+            }
+            for (const apiPath of foundApiPaths) {
+                // Resolve to Next.js route file
+                const routeFile = resolveApiRoute(apiPath, knownFiles);
+                if (!routeFile)
+                    continue;
+                const line = findImportLine(content, `'${apiPath}'`) || findImportLine(content, `"${apiPath}"`) || findImportLine(content, apiPath);
+                connections.push({
+                    connection_id: generateConnectionId('frontend-calls-api'),
+                    from: {
+                        component_id: componentIdByFile.get(file) || `FILE:${file}`,
+                        location: { file, line },
+                    },
+                    to: {
+                        component_id: componentIdByFile.get(routeFile) || `FILE:${routeFile}`,
+                        location: { file: routeFile, line: 1 },
+                    },
+                    connection_type: 'frontend-calls-api',
+                    code_reference: {
+                        file,
+                        symbol: `fetch('${apiPath}')`,
+                        symbol_type: 'function',
+                        line_start: line,
+                    },
+                    description: `${file} fetches ${apiPath}`,
+                    detected_from: 'import-scanner (fetch)',
+                    confidence: 0.9,
+                    timestamp: now,
+                    last_verified: now,
+                });
+            }
+        }
+    }
+    return {
+        components,
+        connections,
+        warnings: [],
+    };
+}
+/**
+ * Resolve a Next.js API path to its route file.
+ * /api/graph → app/api/graph/route.ts or pages/api/graph.ts
+ */
+function resolveApiRoute(apiPath, knownFiles) {
+    // App Router: /api/graph → app/api/graph/route.ts
+    const appRouterCandidates = [
+        `app${apiPath}/route.ts`,
+        `app${apiPath}/route.tsx`,
+        `app${apiPath}/route.js`,
+        `app${apiPath}/route.jsx`,
+        `app${apiPath}/route.mjs`,
+        `app${apiPath}/route.cjs`,
+        `src/app${apiPath}/route.ts`,
+        `src/app${apiPath}/route.tsx`,
+        `src/app${apiPath}/route.js`,
+        `src/app${apiPath}/route.mjs`,
+        `src/app${apiPath}/route.cjs`,
+    ];
+    for (const candidate of appRouterCandidates) {
+        if (knownFiles.has(candidate))
+            return candidate;
+    }
+    // Pages Router: /api/graph → pages/api/graph.ts
+    const pagesRouterCandidates = [
+        `pages${apiPath}.ts`,
+        `pages${apiPath}.tsx`,
+        `pages${apiPath}.js`,
+        `pages${apiPath}.jsx`,
+        `pages${apiPath}.mjs`,
+        `pages${apiPath}.cjs`,
+        `src/pages${apiPath}.ts`,
+        `src/pages${apiPath}.js`,
+    ];
+    for (const candidate of pagesRouterCandidates) {
+        if (knownFiles.has(candidate))
+            return candidate;
+    }
+    return null;
+}
+//# sourceMappingURL=import-scanner.js.map