archsync 1.0.0

package/src/core/relationshipEngine.js

@@ -0,0 +1,917 @@
+import path from 'path';
+import fs from 'fs';
+
+/**
+ * Relationship Engine — post-process phase that connects entities.
+ *
+ * This runs AFTER all files are parsed and entities collected.
+ * It builds edges by analyzing:
+ *   1. Route → Controller (from handler references in route files)
+ *   2. Controller → Service (from service instantiation/calls in controller files)
+ *   3. Service → Model/DB (from DB calls in service files)
+ *   4. Route mounting (app.use prefix + sub-router)
+ *   5. Middleware attachments
+ *   6. Frontend → API (matching endpoints across systems)
+ */
+
+// ─── PATTERN: import resolution ────────────────────────────────────
+// Try a base path with every known source extension (and index files).
+function tryResolveFile(base) {
+    const extensions = ['.ts', '.js', '.tsx', '.jsx', '.dart', ''];
+    for (const ext of extensions) {
+        const candidate = base + ext;
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
+        const indexCandidate = path.join(base, 'index' + ext);
+        if (fs.existsSync(indexCandidate)) return indexCandidate;
+    }
+    return null;
+}
+
+// Resolves `import { X } from '../controllers/foo.controller'` to an absolute path.
+function resolveImportPath(importSource, fromFile) {
+    if (!importSource.startsWith('.')) return null;
+    const dir = path.dirname(fromFile);
+    return tryResolveFile(path.resolve(dir, importSource));
+}
+
+// Resolves aliased imports like `@/components/Button` or `~/lib/utils`
+// against candidate src roots (detected from the scanned file set).
+function resolveAliasImport(importSource, srcRoots) {
+    const m = importSource.match(/^[@~]\/(.+)$/);
+    if (!m) return null;
+    for (const root of srcRoots) {
+        const resolved = tryResolveFile(path.join(root, m[1]));
+        if (resolved) return resolved;
+    }
+    return null;
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// UNIVERSAL MODULE RESOLUTION
+// Language-specific import statements all reduce to a module path, and
+// every module path resolves the same way: match it against the suffix
+// of a scanned file. No per-language manifest parsing required —
+// `package:app/foo/bar.dart`, `from app.services.user import X`,
+// `import com.foo.Bar;`, `"mymodule/internal/auth"` all land on the
+// scanned file whose path ends with the candidate.
+// ═══════════════════════════════════════════════════════════════════
+
+/** Index scanned files by basename for fast suffix matching. */
+function buildSuffixIndex(parsedFiles) {
+    const byBase = new Map(); // basename → [normalized absolute paths]
+    for (const f of parsedFiles) {
+        const norm = path.resolve(f.filePath).replace(/\\/g, '/');
+        const base = norm.split('/').pop();
+        if (!byBase.has(base)) byBase.set(base, []);
+        byBase.get(base).push(norm);
+    }
+    return byBase;
+}
+
+/** Find a scanned file whose path ends with `/cand`. Dir candidates (no
+ *  extension) match any file directly inside that directory. */
+function resolveBySuffix(cand, suffixIndex) {
+    if (!cand) return null;
+    const norm = cand.replace(/\\/g, '/').replace(/^\/+/, '');
+    const base = norm.split('/').pop();
+
+    if (base.includes('.')) {
+        // File candidate
+        const matches = suffixIndex.get(base) || [];
+        for (const p of matches) {
+            if (p.endsWith('/' + norm) || p === norm) return p;
+        }
+        return null;
+    }
+    // Directory candidate (Go packages, Java wildcard imports)
+    for (const paths of suffixIndex.values()) {
+        for (const p of paths) {
+            const dir = p.slice(0, p.lastIndexOf('/'));
+            if (dir.endsWith('/' + norm)) return p;
+        }
+    }
+    return null;
+}
+
+// Common source extensions tried when an import omits the extension
+const MODULE_EXTS = ['.js', '.ts', '.jsx', '.tsx', '.dart', '.py', '.go', '.java'];
+
+/**
+ * Turn a raw import specifier into candidate path suffixes, based on the
+ * importing file's language. Unknown languages fall through to the generic
+ * "path with or without extension" treatment.
+ */
+function moduleCandidates(spec, fromExt) {
+    if (!spec) return [];
+
+    // Dart / Swift-style package URI: strip the scheme + package segment
+    const pkg = spec.match(/^[a-z]+:[^/]+\/(.+)$/i);
+    if (pkg) return [pkg[1]];
+
+    // Dotted module path (Python, Java, Kotlin, …)
+    if (fromExt === '.py') {
+        const p = spec.replace(/\./g, '/');
+        return [`${p}.py`, `${p}/__init__.py`];
+    }
+    if (fromExt === '.java') {
+        if (spec.endsWith('.*')) return [spec.slice(0, -2).replace(/\./g, '/')];
+        return [spec.replace(/\./g, '/') + '.java'];
+    }
+
+    // Path-style specifier (Go modules, monorepo deep imports). The module
+    // prefix often isn't a directory on disk ("mymodule/internal/auth" where
+    // "mymodule" comes from go.mod), so progressively strip leading segments
+    // and retry — keeping at least two segments to avoid false positives.
+    // Bare single-word JS imports ('react', 'lodash') are external packages —
+    // never resolved to local files.
+    if (spec.includes('/')) {
+        const out = [];
+        const parts = spec.split('/');
+        for (let i = 0; i <= parts.length - 2; i++) {
+            const sub = parts.slice(i).join('/');
+            out.push(sub);
+            if (!/\.\w+$/.test(sub)) {
+                for (const ext of MODULE_EXTS) out.push(sub + ext);
+            }
+        }
+        return out;
+    }
+    return [];
+}
+
+/**
+ * Universal import resolution chain:
+ *   1. relative path (any language)
+ *   2. JS-style alias roots (@/, ~/)
+ *   3. language-aware candidates suffix-matched against the scanned file set
+ */
+function resolveModuleImport(imp, fromFile, ctx) {
+    if (imp.resolvedFile) return imp.resolvedFile;
+
+    const alias = resolveAliasImport(imp.sourcePath, ctx.srcRoots);
+    if (alias) return alias;
+
+    const fromExt = path.extname(fromFile).toLowerCase();
+    for (const cand of moduleCandidates(imp.sourcePath, fromExt)) {
+        const hit = resolveBySuffix(cand, ctx.suffixIndex);
+        if (hit) return hit;
+    }
+    return null;
+}
+
+// ─── EXTRACT imports from a source file ────────────────────────────
+const IMPORT_ES = /import\s+(?:\{([^}]+)\}|(\w+)|\*\s+as\s+(\w+))\s*(?:,\s*\{([^}]+)\})?\s+from\s+['"`]([^'"`]+)['"`]/g;
+const REQUIRE_CJS = /(?:const|let|var)\s+(?:\{([^}]+)\}|(\w+))\s*=\s*require\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g;
+// Side-effect imports (`import './styles.css'`, Dart `import 'foo.dart';`)
+const IMPORT_BARE = /(?:^|[^\w.])import\s+['"`]([^'"`]+)['"`]/g;
+// Re-exports (`export * from './x'`, `export { A } from './x'`)
+const EXPORT_FROM = /export\s+(?:\*(?:\s+as\s+\w+)?|\{[^}]*\})\s+from\s+['"`]([^'"`]+)['"`]/g;
+
+function extractImports(source, filePath) {
+    const imports = []; // { localName, importedName, sourcePath, resolvedFile }
+    let m;
+
+    IMPORT_ES.lastIndex = 0;
+    while ((m = IMPORT_ES.exec(source)) !== null) {
+        const namedImports = m[1] || m[4]; // { A, B }  (or `Default, { A, B }`)
+        const defaultImport = m[2]; // X
+        const namespaceImport = m[3]; // * as Y
+        const sourcePath = m[5];
+
+        if (namedImports) {
+            for (const part of namedImports.split(',')) {
+                const [imported, local] = part.trim().split(/\s+as\s+/).map(s => s.trim());
+                if (imported) {
+                    imports.push({
+                        localName: local || imported,
+                        importedName: imported,
+                        sourcePath,
+                        resolvedFile: resolveImportPath(sourcePath, filePath),
+                    });
+                }
+            }
+        }
+        if (defaultImport) {
+            imports.push({ localName: defaultImport, importedName: 'default', sourcePath, resolvedFile: resolveImportPath(sourcePath, filePath) });
+        }
+        if (namespaceImport) {
+            imports.push({ localName: namespaceImport, importedName: '*', sourcePath, resolvedFile: resolveImportPath(sourcePath, filePath) });
+        }
+    }
+
+    REQUIRE_CJS.lastIndex = 0;
+    while ((m = REQUIRE_CJS.exec(source)) !== null) {
+        const destructured = m[1];
+        const varName = m[2];
+        const sourcePath = m[3];
+
+        if (destructured) {
+            for (const part of destructured.split(',')) {
+                const name = part.trim().split(/\s+as\s+/)[0]?.trim();
+                if (name) {
+                    imports.push({ localName: name, importedName: name, sourcePath, resolvedFile: resolveImportPath(sourcePath, filePath) });
+                }
+            }
+        }
+        if (varName) {
+            imports.push({ localName: varName, importedName: 'default', sourcePath, resolvedFile: resolveImportPath(sourcePath, filePath) });
+        }
+    }
+
+    // Side-effect imports + re-exports — no local binding, but still a
+    // file-level dependency (needed for the import graph pass).
+    const already = new Set(imports.map(i => i.sourcePath));
+    const pushModule = (sourcePath) => {
+        if (!sourcePath || already.has(sourcePath)) return;
+        already.add(sourcePath);
+        imports.push({ localName: null, importedName: '*', sourcePath, resolvedFile: resolveImportPath(sourcePath, filePath) });
+    };
+    for (const regex of [IMPORT_BARE, EXPORT_FROM]) {
+        regex.lastIndex = 0;
+        while ((m = regex.exec(source)) !== null) pushModule(m[1]);
+    }
+
+    // ── Language-specific import syntax (universal module paths) ────
+    const ext = path.extname(filePath).toLowerCase();
+
+    if (ext === '.py') {
+        const PY_FROM = /^\s*from\s+([\w.]+)\s+import\b/gm;
+        const PY_IMPORT = /^\s*import\s+([\w.]+(?:\s*,\s*[\w.]+)*)/gm;
+        PY_FROM.lastIndex = 0;
+        while ((m = PY_FROM.exec(source)) !== null) pushModule(m[1]);
+        PY_IMPORT.lastIndex = 0;
+        while ((m = PY_IMPORT.exec(source)) !== null) {
+            for (const mod of m[1].split(',')) pushModule(mod.trim());
+        }
+    }
+
+    if (ext === '.go') {
+        // Single import + grouped import blocks
+        const GO_SINGLE = /import\s+(?:\w+\s+)?"([^"]+)"/g;
+        const GO_BLOCK = /import\s*\(([\s\S]*?)\)/g;
+        GO_SINGLE.lastIndex = 0;
+        while ((m = GO_SINGLE.exec(source)) !== null) pushModule(m[1]);
+        GO_BLOCK.lastIndex = 0;
+        while ((m = GO_BLOCK.exec(source)) !== null) {
+            const inner = m[1];
+            const Q = /"([^"]+)"/g;
+            let q;
+            while ((q = Q.exec(inner)) !== null) pushModule(q[1]);
+        }
+    }
+
+    if (ext === '.java' || ext === '.kt' || ext === '.kts') {
+        const JAVA_IMPORT = /^\s*import\s+(?:static\s+)?([\w.]+(?:\.\*)?)\s*;?/gm;
+        JAVA_IMPORT.lastIndex = 0;
+        while ((m = JAVA_IMPORT.exec(source)) !== null) pushModule(m[1]);
+    }
+
+    return imports;
+}
+
+// Join an app.use() mount prefix with a route's local path:
+// joinPaths('/api/users', '/:id') → '/api/users/:id'
+function joinPaths(prefix, routePath) {
+    const p = String(prefix || '').replace(/\/+$/, '');
+    const r = String(routePath || '').replace(/^\/+/, '');
+    return r ? `${p}/${r}` : (p || '/');
+}
+
+// Frontend parsers capture absolute URLs (https://api.example.com/api/login);
+// only the pathname is comparable to backend route paths.
+function stripOrigin(urlOrPath) {
+    return String(urlOrPath || '').replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i, '') || '/';
+}
+
+// ─── MAIN ENGINE ───────────────────────────────────────────────────
+export function buildRelationships(parsedFiles, debug = false) {
+    const relations = [];
+    const log = debug ? (...args) => console.log('  [rel]', ...args) : () => { };
+
+    // ═══════════════════════════════════════════════════════════
+    // PASS 0 — Compose externally-visible route paths from mounts
+    // app.use('/api/users', userRoutes) + router.get('/:id', …)
+    //   → route "GET /api/users/:id"
+    // Mutates route entities (data.fullPath + name) BEFORE the node
+    // map is built, so every later pass and the schema builder see
+    // the public path. Renames are recorded so PASS 1's source-regex
+    // route names stay resolvable.
+    // ═══════════════════════════════════════════════════════════
+    const routeRenames = new Map(); // `${filePath}|${oldName}` → newName
+
+    for (const file of parsedFiles) {
+        const mounts = (file.entities || []).filter(e => e.entityType === 'mount');
+        if (!mounts.length) continue;
+
+        let source;
+        try { source = fs.readFileSync(file.filePath, 'utf-8'); } catch { continue; }
+        const imports = extractImports(source, file.filePath);
+
+        for (const mount of mounts) {
+            const routerVar = mount.data?.routerVariable;
+            const prefix = mount.data?.prefix;
+            if (!routerVar || !prefix) continue;
+
+            const imp = imports.find(i => i.localName === routerVar);
+            if (!imp?.resolvedFile) continue;
+
+            const routedFile = parsedFiles.find(
+                f => path.resolve(f.filePath) === path.resolve(imp.resolvedFile)
+            );
+            if (!routedFile) continue;
+
+            for (const e of routedFile.entities || []) {
+                if (e.entityType !== 'route' || !e.data?.path || e.data.fullPath) continue;
+                const fullPath = joinPaths(prefix, e.data.path);
+                const oldName = e.name;
+                e.data.fullPath = fullPath;
+                e.name = `${e.data.method || ''} ${fullPath}`.trim();
+                routeRenames.set(`${routedFile.filePath}|${oldName}`, e.name);
+                log(`Mount: "${mount.name}" composes "${oldName}" → "${e.name}"`);
+                relations.push({
+                    source: mount.name,
+                    target: e.name,
+                    sourceType: 'mount',
+                    targetType: 'route',
+                    sourceSystem: mount.system || 'backend',
+                    targetSystem: e.system || 'backend',
+                    relation: 'mounts',
+                });
+            }
+        }
+    }
+
+    // Resolve a route name derived from raw source (local path) to its
+    // post-PASS-0 public name.
+    const renamedRoute = (filePath, routeName) =>
+        routeRenames.get(`${filePath}|${routeName}`) || routeName;
+
+    // ── Collect all entities into lookups ─────────────────────
+    // entityByFile: filePath → [entities]
+    // entityByName: name → entity (first match)
+    // entityByTypeAndName: "controller:getRoutes" → entity
+    const entityByFile = new Map();
+    const entityByName = new Map();
+    const entityByTypeAndName = new Map();
+    const allEntities = [];
+
+    for (const file of parsedFiles) {
+        const fileEntities = file.entities || [];
+        entityByFile.set(file.filePath, fileEntities);
+        for (const e of fileEntities) {
+            allEntities.push({ ...e, _filePath: file.filePath });
+            if (!entityByName.has(e.name)) entityByName.set(e.name, e);
+            const key = `${e.entityType}:${e.name}`;
+            if (!entityByTypeAndName.has(key)) entityByTypeAndName.set(key, e);
+        }
+    }
+
+    // Pre-index: which files are controllers, services, etc.
+    const controllerFiles = new Set();
+    const serviceFiles = new Set();
+    const middlewareFiles = new Set();
+    const routeFiles = new Set();
+
+    for (const [filePath, ents] of entityByFile) {
+        for (const e of ents) {
+            if (e.entityType === 'controller') controllerFiles.add(filePath);
+            if (e.entityType === 'service') serviceFiles.add(filePath);
+            if (e.entityType === 'middleware') middlewareFiles.add(filePath);
+            if (e.entityType === 'route') routeFiles.add(filePath);
+        }
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    // PASS 1 — Route → Controller (from route file source code)
+    // ═══════════════════════════════════════════════════════════
+    for (const file of parsedFiles) {
+        const fp = file.filePath;
+        const isRouteFile = /routes?[/\\]/i.test(fp) || routeFiles.has(fp);
+        if (!isRouteFile) continue;
+
+        let source;
+        try { source = fs.readFileSync(fp, 'utf-8'); } catch { continue; }
+
+        const imports = extractImports(source, fp);
+        const routes = (file.entities || []).filter(e => e.entityType === 'route');
+
+        // Pattern 1: router.get('/path', controllerRef.method)
+        // Pattern 2: router.get('/path', namedImport)
+        // Pattern 3: router.get('/path', verifyToken, controllerRef.method)
+        const ROUTE_HANDLER = /(?:router|app)\.(get|post|put|patch|delete|all)\s*\(\s*['"`]([^'"`]+)['"`]\s*,([^)]+)\)/gi;
+        let match;
+        ROUTE_HANDLER.lastIndex = 0;
+        while ((match = ROUTE_HANDLER.exec(source)) !== null) {
+            const method = match[1].toUpperCase();
+            const routePath = match[2];
+            const handlerChain = match[3];
+            const routeName = renamedRoute(fp, `${method} ${routePath}`);
+
+            // Extract all identifiers from the handler chain (last one is the actual handler)
+            const identifiers = handlerChain.match(/\b(\w+(?:\.\w+)?)\b/g) || [];
+
+            // The actual handler is typically the last identifier that isn't middleware
+            for (const ident of identifiers) {
+                const parts = ident.split('.');
+                let resolvedControllerName = null;
+
+                if (parts.length === 2) {
+                    // e.g., routeController.createRoute
+                    const [objName, methodName] = parts;
+                    // Find what objName imports from
+                    const imp = imports.find(i => i.localName === objName);
+                    if (imp?.resolvedFile) {
+                        const fileEnts = entityByFile.get(imp.resolvedFile) || [];
+                        // Look for the method as a controller entity
+                        resolvedControllerName = fileEnts.find(e =>
+                            e.entityType === 'controller' && e.name === methodName
+                        )?.name;
+                        // If not found by name, the import target itself is the controller file
+                        if (!resolvedControllerName) {
+                            resolvedControllerName = fileEnts.find(e => e.entityType === 'controller')?.name;
+                        }
+                    }
+                    // Even if we can't resolve the file, create the relation using the method name
+                    if (!resolvedControllerName) resolvedControllerName = methodName;
+                } else if (parts.length === 1) {
+                    // e.g., getSubscriptionPlans (direct import)
+                    const funcName = parts[0];
+                    // Skip known middleware patterns and common non-handler identifiers
+                    if (/^(verify|decrypt|encrypt|auth|require|check|validate|cors|json|async|await|req|res|next|err|true|false|upload|single|array|fields|none)/i.test(funcName)) continue;
+                    // Skip known Express/middleware identifiers
+                    if (['Router', 'router', 'app', 'express', 'middleware', 'multer', 'upload'].includes(funcName)) continue;
+                    // Check if this is an imported controller function
+                    const imp = imports.find(i => i.localName === funcName);
+                    if (imp?.resolvedFile) {
+                        const fileEnts = entityByFile.get(imp.resolvedFile) || [];
+                        const isControllerFile = /controller/i.test(imp.resolvedFile);
+                        if (isControllerFile || fileEnts.some(e => e.entityType === 'controller')) {
+                            resolvedControllerName = funcName;
+                        }
+                    } else if (entityByTypeAndName.has(`controller:${funcName}`)) {
+                        resolvedControllerName = funcName;
+                    }
+                }
+
+                if (resolvedControllerName) {
+                    log(`Route→Controller: "${routeName}" → "${resolvedControllerName}"`);
+                    relations.push({
+                        source: routeName,
+                        target: resolvedControllerName,
+                        sourceType: 'route',
+                        targetType: 'controller',
+                        sourceSystem: 'backend',
+                        targetSystem: 'backend',
+                        relation: 'handles',
+                    });
+                }
+            }
+
+            // Also detect middleware in the chain
+            for (const ident of identifiers) {
+                const name = ident.split('.')[0];
+                if (/^(verify|decrypt|encrypt|auth|require|check|validate|optional)/i.test(name)) {
+                    log(`Route→Middleware: "${routeName}" → "${name}"`);
+                    relations.push({
+                        source: routeName,
+                        target: name,
+                        sourceType: 'route',
+                        targetType: 'middleware',
+                        sourceSystem: 'backend',
+                        targetSystem: 'backend',
+                        relation: 'protected_by',
+                    });
+                } else if (name === 'encryptedRoute' || /middleware/i.test(name)) {
+                    log(`Route→Middleware: "${routeName}" → "${name}"`);
+                    relations.push({
+                        source: routeName,
+                        target: name,
+                        sourceType: 'route',
+                        targetType: 'middleware',
+                        sourceSystem: 'backend',
+                        targetSystem: 'backend',
+                        relation: 'protected_by',
+                    });
+                }
+            }
+        }
+
+        // Pattern 4: inline handler — router.post('/path', async (req, res) => { ... })
+        // If route has NO controller relation yet, the handler is inline in the route file
+        for (const route of routes) {
+            const hasControllerEdge = relations.some(r =>
+                r.source === route.name && r.sourceType === 'route' && r.targetType === 'controller'
+            );
+            if (!hasControllerEdge) {
+                // Route file itself acts as controller — link to file-level controller entity if any
+                const fileControllers = (file.entities || []).filter(e => e.entityType === 'controller');
+                if (fileControllers.length > 0) {
+                    log(`Route→Controller (inline): "${route.name}" → "${fileControllers[0].name}"`);
+                    relations.push({
+                        source: route.name,
+                        target: fileControllers[0].name,
+                        sourceType: 'route',
+                        targetType: 'controller',
+                        sourceSystem: 'backend',
+                        targetSystem: 'backend',
+                        relation: 'handles',
+                    });
+                }
+            }
+        }
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    // PASS 2 — Controller → Service (from controller source code)
+    // ═══════════════════════════════════════════════════════════
+    for (const file of parsedFiles) {
+        const fp = file.filePath;
+        const isControllerFile = /controller/i.test(fp) || controllerFiles.has(fp);
+        if (!isControllerFile) continue;
+
+        let source;
+        try { source = fs.readFileSync(fp, 'utf-8'); } catch { continue; }
+
+        const imports = extractImports(source, fp);
+        const controllers = (file.entities || []).filter(e => e.entityType === 'controller');
+        const controllerName = controllers[0]?.name || path.basename(fp, path.extname(fp));
+
+        // Find service imports
+        for (const imp of imports) {
+            if (/service/i.test(imp.sourcePath) || /service/i.test(imp.localName)) {
+                // This controller imports a service
+                const serviceName = imp.importedName !== 'default' && imp.importedName !== '*'
+                    ? imp.importedName
+                    : imp.localName;
+
+                // Find actual service entity
+                const serviceEntity = entityByName.get(serviceName)
+                    || entityByTypeAndName.get(`service:${serviceName}`)
+                    || (imp.resolvedFile ? (entityByFile.get(imp.resolvedFile) || []).find(e => e.entityType === 'service') : null);
+
+                const targetName = serviceEntity?.name || serviceName;
+
+                // Create relation from each controller function → service
+                for (const ctrl of controllers) {
+                    log(`Controller→Service: "${ctrl.name}" → "${targetName}"`);
+                    relations.push({
+                        source: ctrl.name,
+                        target: targetName,
+                        sourceType: 'controller',
+                        targetType: 'service',
+                        sourceSystem: 'backend',
+                        targetSystem: 'backend',
+                        relation: 'uses',
+                    });
+                }
+
+                // If no individual controller functions found, use file-level
+                if (controllers.length === 0) {
+                    log(`Controller(file)→Service: "${controllerName}" → "${targetName}"`);
+                    relations.push({
+                        source: controllerName,
+                        target: targetName,
+                        sourceType: 'controller',
+                        targetType: 'service',
+                        sourceSystem: 'backend',
+                        targetSystem: 'backend',
+                        relation: 'uses',
+                    });
+                }
+            }
+        }
+
+        // Also detect service method calls: xxxService.method()
+        const SERVICE_CALL = /(\w+Service)\s*\.\s*(\w+)\s*\(/gi;
+        let scMatch;
+        const seenServiceCalls = new Set();
+        SERVICE_CALL.lastIndex = 0;
+        while ((scMatch = SERVICE_CALL.exec(source)) !== null) {
+            const svcVar = scMatch[1];
+            const svcMethod = scMatch[2];
+            const callKey = `${controllerName}→${svcVar}`;
+            if (seenServiceCalls.has(callKey)) continue;
+            seenServiceCalls.add(callKey);
+
+            // Resolve service variable to imported class
+            const imp = imports.find(i => i.localName === svcVar);
+            const serviceEntity = imp?.resolvedFile
+                ? (entityByFile.get(imp.resolvedFile) || []).find(e => e.entityType === 'service')
+                : entityByName.get(svcVar);
+
+            if (serviceEntity) {
+                for (const ctrl of controllers) {
+                    log(`Controller→Service (call): "${ctrl.name}" → "${serviceEntity.name}"`);
+                    relations.push({
+                        source: ctrl.name,
+                        target: serviceEntity.name,
+                        sourceType: 'controller',
+                        targetType: 'service',
+                        sourceSystem: 'backend',
+                        targetSystem: 'backend',
+                        relation: 'uses',
+                    });
+                }
+            }
+        }
+
+        // Detect `new XService(...)` constructor calls
+        const NEW_SERVICE = /new\s+(\w+Service)\s*\(/gi;
+        let nsMatch;
+        const seenNewService = new Set();
+        NEW_SERVICE.lastIndex = 0;
+        while ((nsMatch = NEW_SERVICE.exec(source)) !== null) {
+            const svcClass = nsMatch[1];
+            if (seenNewService.has(`${controllerName}→${svcClass}`)) continue;
+            seenNewService.add(`${controllerName}→${svcClass}`);
+
+            const serviceEntity = entityByName.get(svcClass) || entityByTypeAndName.get(`service:${svcClass}`);
+            const targetName = serviceEntity?.name || svcClass;
+
+            for (const ctrl of controllers) {
+                log(`Controller→Service (new): "${ctrl.name}" → "${targetName}"`);
+                relations.push({
+                    source: ctrl.name,
+                    target: targetName,
+                    sourceType: 'controller',
+                    targetType: 'service',
+                    sourceSystem: 'backend',
+                    targetSystem: 'backend',
+                    relation: 'uses',
+                });
+            }
+        }
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    // PASS 3 — Service → DB / Model (from service source code)
+    // ═══════════════════════════════════════════════════════════
+    for (const file of parsedFiles) {
+        const fp = file.filePath;
+        const isServiceFile = /service/i.test(fp) || serviceFiles.has(fp);
+        if (!isServiceFile) continue;
+
+        let source;
+        try { source = fs.readFileSync(fp, 'utf-8'); } catch { continue; }
+
+        const services = (file.entities || []).filter(e => e.entityType === 'service');
+        const serviceName = services[0]?.name || path.basename(fp, path.extname(fp));
+
+        // Detect Firestore collection access: db.collection('users'), .collection('routes')
+        const COLLECTION = /\.collection\s*\(\s*['"`](\w+)['"`]\s*\)/gi;
+        let cMatch;
+        const seenCollections = new Set();
+        COLLECTION.lastIndex = 0;
+        while ((cMatch = COLLECTION.exec(source)) !== null) {
+            const collection = cMatch[1];
+            if (seenCollections.has(collection)) continue;
+            seenCollections.add(collection);
+
+            const target = serviceName;
+            for (const svc of services) {
+                log(`Service→Database: "${svc.name}" → "collection:${collection}"`);
+                relations.push({
+                    source: svc.name,
+                    target: `collection:${collection}`,
+                    sourceType: 'service',
+                    targetType: 'database',
+                    sourceSystem: 'backend',
+                    targetSystem: 'backend',
+                    relation: 'queries',
+                });
+            }
+        }
+
+        // Detect Mongoose model calls: Model.find(), Model.findById(), new Model()
+        const MODEL_CALL = /(\b[A-Z]\w+)\.(find|findOne|findById|create|save|update|deleteOne|deleteMany|aggregate|count|distinct)\s*\(/gi;
+        let mMatch;
+        const seenModels = new Set();
+        MODEL_CALL.lastIndex = 0;
+        while ((mMatch = MODEL_CALL.exec(source)) !== null) {
+            const modelName = mMatch[1];
+            if (['Date', 'Math', 'JSON', 'Object', 'Array', 'String', 'Number', 'Promise', 'Error', 'Buffer', 'FieldValue', 'RegExp'].includes(modelName)) continue;
+            if (seenModels.has(`${serviceName}→${modelName}`)) continue;
+            seenModels.add(`${serviceName}→${modelName}`);
+
+            for (const svc of services) {
+                log(`Service→Model: "${svc.name}" → "${modelName}"`);
+                relations.push({
+                    source: svc.name,
+                    target: modelName,
+                    sourceType: 'service',
+                    targetType: 'model',
+                    sourceSystem: 'backend',
+                    targetSystem: 'backend',
+                    relation: 'queries',
+                });
+            }
+        }
+
+        // Detect getDatabase/getFirestore usage → database node
+        if (/getFirestore|getDatabase|mongoose\.connect|createPool|pg\.connect/i.test(source)) {
+            for (const svc of services) {
+                log(`Service→Database: "${svc.name}" → "Database"`);
+                relations.push({
+                    source: svc.name,
+                    target: 'Database',
+                    sourceType: 'service',
+                    targetType: 'database',
+                    sourceSystem: 'backend',
+                    targetSystem: 'backend',
+                    relation: 'stored_in',
+                });
+            }
+        }
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    // PASS 4 — Frontend → API matching
+    // ═══════════════════════════════════════════════════════════
+    // Server-side routes are anything with a concrete method+path that is
+    // not a frontend reference — the system label may be 'backend' or a
+    // workspace-specific name, so don't filter on it.
+    const backendRoutes = allEntities.filter(e =>
+        e.entityType === 'route' && e.data?.method && e.data?.path && e.data?.scope !== 'frontend-ref'
+    );
+    const frontendAPIs = allEntities.filter(e => e.entityType === 'api' && e.data?.scope === 'frontend-ref');
+
+    for (const feAPI of frontendAPIs) {
+        const apiPath = stripOrigin(feAPI.data?.path || '');
+        const apiMethod = feAPI.data?.method || 'GET';
+
+        // Find screen/widget that this API belongs to (same file)
+        const sameFileEntities = allEntities.filter(e =>
+            e._filePath === feAPI._filePath && (e.entityType === 'screen' || e.entityType === 'widget')
+        );
+        const screenName = sameFileEntities[0]?.name;
+
+        if (screenName) {
+            log(`Frontend→API: "${screenName}" → "${feAPI.name}"`);
+            relations.push({
+                source: screenName,
+                target: feAPI.name,
+                sourceType: sameFileEntities[0].entityType,
+                targetType: 'api',
+                sourceSystem: feAPI.system,
+                targetSystem: feAPI.system,
+                relation: 'consumes',
+            });
+        }
+
+        // Match to backend route — prefer the mount-composed public path
+        for (const beRoute of backendRoutes) {
+            const routePath = beRoute.data?.fullPath || beRoute.data?.path || '';
+            const routeMethod = beRoute.data?.method || 'GET';
+
+            if (routeMethod === apiMethod && pathsMatch(routePath, apiPath)) {
+                log(`API Match: Frontend "${feAPI.name}" ↔ Backend "${beRoute.name}"`);
+                relations.push({
+                    source: feAPI.name,
+                    target: beRoute.name,
+                    sourceType: 'api',
+                    targetType: 'route',
+                    sourceSystem: feAPI.system,
+                    targetSystem: beRoute.system || 'backend',
+                    relation: 'calls',
+                });
+            }
+        }
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    // PASS 5 — Route mount relationships (app.use prefix → sub-routes)
+    // ═══════════════════════════════════════════════════════════
+    // Handled by the nodeParser which detects app.use patterns.
+
+    // ═══════════════════════════════════════════════════════════
+    // PASS 6 — File-level import graph (CodeSee-style arrows)
+    // Every resolvable import between two scanned files becomes an
+    // `imports` edge connecting the files' primary entities. This is
+    // what makes arrows appear automatically across the whole map,
+    // exactly like CodeSee's codebase maps.
+    // ═══════════════════════════════════════════════════════════
+    const filePathIndex = new Map(
+        parsedFiles.map(f => [path.resolve(f.filePath), f])
+    );
+
+    // Detect alias roots (`@/x` → <project>/src/x) from the scanned file set.
+    const srcRoots = new Set();
+    for (const f of parsedFiles) {
+        const norm = path.resolve(f.filePath).replace(/\\/g, '/');
+        const i = norm.lastIndexOf('/src/');
+        if (i !== -1) srcRoots.add(norm.slice(0, i + 4));
+    }
+
+    // Universal module resolution context — works for any language whose
+    // imports name a module path (Dart package:, Python dotted, Java dotted,
+    // Go module paths, JS monorepo deep imports, …).
+    const resolveCtx = { srcRoots, suffixIndex: buildSuffixIndex(parsedFiles) };
+
+    // Primary entity of a file: name matching the filename wins, then the
+    // most "architectural" entity type, then the first one parsed.
+    const ENTITY_PRIORITY = ['screen', 'layout', 'widget', 'controller', 'service', 'route', 'api', 'mount', 'middleware', 'model', 'database', 'config'];
+    const priorityOf = (e) => {
+        const i = ENTITY_PRIORITY.indexOf(e.entityType);
+        return i === -1 ? ENTITY_PRIORITY.length : i;
+    };
+    const primaryEntityOf = (file) => {
+        const ents = file.entities || [];
+        if (ents.length === 0) return null;
+        const base = path.basename(file.filePath).replace(/\.[^.]+$/, '').toLowerCase();
+        return ents.find(e => (e.name || '').toLowerCase() === base)
+            || [...ents].sort((a, b) => priorityOf(a) - priorityOf(b))[0];
+    };
+
+    // Don't double-draw pairs already connected by a richer relation —
+    // including relations the per-file parsers emitted (merged in buildSchema).
+    const connectedPairs = new Set([
+        ...relations.map(r => `${r.source}→${r.target}`),
+        ...parsedFiles.flatMap(f => (f.relations || []).map(r => `${r.source}→${r.target}`)),
+    ]);
+    let importEdgeCount = 0;
+
+    for (const file of parsedFiles) {
+        const srcEntity = primaryEntityOf(file);
+        if (!srcEntity) continue;
+
+        let source;
+        try { source = fs.readFileSync(file.filePath, 'utf-8'); } catch { continue; }
+
+        const imports = extractImports(source, file.filePath);
+        const seenTargetFiles = new Set();
+
+        for (const imp of imports) {
+            const resolved = resolveModuleImport(imp, file.filePath, resolveCtx);
+            if (!resolved) continue;
+
+            const tgtFile = filePathIndex.get(path.resolve(resolved));
+            if (!tgtFile || tgtFile.filePath === file.filePath) continue;
+            if (seenTargetFiles.has(tgtFile.filePath)) continue; // one edge per file pair
+            seenTargetFiles.add(tgtFile.filePath);
+
+            const tgtEntity = primaryEntityOf(tgtFile);
+            if (!tgtEntity || tgtEntity.name === srcEntity.name) continue;
+
+            const pairKey = `${srcEntity.name}→${tgtEntity.name}`;
+            const reverseKey = `${tgtEntity.name}→${srcEntity.name}`;
+            if (connectedPairs.has(pairKey) || connectedPairs.has(reverseKey)) continue;
+            connectedPairs.add(pairKey);
+
+            importEdgeCount++;
+            log(`Import: "${srcEntity.name}" → "${tgtEntity.name}"`);
+            relations.push({
+                source: srcEntity.name,
+                target: tgtEntity.name,
+                sourceType: srcEntity.entityType,
+                targetType: tgtEntity.entityType,
+                sourceSystem: srcEntity.system,
+                targetSystem: tgtEntity.system,
+                // File scoping — disambiguates same-named entities (two
+                // `main` modules) when the schema builder resolves nodes.
+                sourceFile: file.filePath,
+                targetFile: tgtFile.filePath,
+                relation: 'imports',
+            });
+        }
+    }
+    if (importEdgeCount > 0) log(`Import graph: ${importEdgeCount} file-dependency edges`);
+
+    // Deduplicate relations. The system is part of identity — the admin and
+    // the mobile app may both call "POST /api/auth/login" and each deserves
+    // its own cross-system edge.
+    const seen = new Set();
+    const unique = [];
+    for (const rel of relations) {
+        const key = `${rel.sourceSystem || ''}:${rel.sourceType}:${rel.source}:${rel.sourceFile || ''}:${rel.targetSystem || ''}:${rel.targetType}:${rel.target}:${rel.targetFile || ''}:${rel.relation}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            unique.push(rel);
+        }
+    }
+
+    return unique;
+}
+
+// Check if two API paths match (handles path params like :id)
+function pathsMatch(backendPath, frontendPath) {
+    // Normalize both paths
+    const normalize = (p) => p.replace(/^\/+|\/+$/g, '').toLowerCase();
+    const bp = normalize(backendPath);
+    const fp = normalize(frontendPath);
+
+    if (bp === fp) return true;
+
+    // Handle path params: /routes/:routeId matches /routes/abc123
+    const bParts = bp.split('/');
+    const fParts = fp.split('/');
+
+    if (bParts.length !== fParts.length) return false;
+
+    for (let i = 0; i < bParts.length; i++) {
+        if (bParts[i].startsWith(':') || bParts[i].startsWith('{')) continue;
+        if (fParts[i].startsWith(':') || fParts[i].startsWith('{')) continue;
+        if (bParts[i] !== fParts[i]) return false;
+    }
+
+    return true;
+}