diff --git a/CHANGELOG.md b/CHANGELOG.md index 25a5509..641f2e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,8 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### New Features +- **The Steps tab follows a web app across its tiers.** A page's `fetch('/api/users', { method: 'POST' })` (or an `axios` / `ky` / `got` / `$fetch` call, including one through a project instance made with `axios.create({ baseURL })`) now reaches the route that serves it in the same index — drawn as a crossing to the server (`⇢ POST /api/users`) with the handler named on the box and the registration site in the panel, a boundary by default and entered with *Continue through*, so the picture reads page → handler → the endpoint → its database write → its response. A job put on a BullMQ / Bull queue lands on the `@Process` method, `Worker` or `queue.process` handler that consumes it; a NestJS `EventEmitter2` event lands on its `@OnEvent` listeners (globs included); a socket message crosses from a client's `socket.emit` to the gateway's `@SubscribeMessage` and back from the server's `emit` to the component that registered `socket.on`; and a Next.js server action called from a client file is a crossing to the server by its `'use server'` directive. Each of these is a synthesized hop — dashed, with where it was wired up — and `codegraph_explore`'s Flow section names them too. Only a literal path or event name pairs: a variable url, a path no route serves, or one two routes serve alike produce nothing. Re-index to pick the new edges up. + - **The Steps tab now draws an API as well as an app.** Anchor on an endpoint — `POST /users` in Express, NestJS, Fastify, FastAPI, Flask, Django, Spring (Java or Kotlin), ASP.NET, Vapor or Gin — and the viewer starts at the handler the route runs (or at the route itself when the handler is an inline arrow), says what fires it (`FIRES FROM POST /users · after authenticate, validate(…)` — the middleware arguments at the registration, or the guard decorators on the method and its class, or a FastAPI `dependencies=[…]`), and draws what the request sets in motion: the database calls with the model and whether they read or write (`prisma.user.create({ data })` · `database · user · write`), jobs put on a queue, emails, payments, cache reads, token checks, calls to other services, files and processes — and the **responses**, one box per handler whose label is the status codes it can send (`201 · 404`) and whose panel rows are the endpoint's contract as the code has it: `WHEN NOT user → 404 · NotFoundException('no such user')`, `always → 201 · res.status(201).json(user)`. A queue consumer or a scheduled job anchored by name says the decorator that fires it (`@Process('email')`). The legend, the panel and the chooser use the project's own words — endpoint, data call, another tier — and the bare Steps tab lists an API's endpoints by router file when there are no screens. Re-index is not needed: everything new is read from the source at request time. - **Calls are read as written, so the database is the database.** The index keeps only the last segment of a deep member call (`create` for `prisma.user.create`), and a bare name matches by name alone — often to the wrong `create`. The Steps walk now reads each call from the source as written, classifies `prisma.user.create`, `this.usersRepository.save`, `session.commit`, `owners.save` and `_context.TodoItems.Add` by the whole chain and by the receiver's declared type (`OwnerRepository owners`, `private readonly usersService: UsersService`, `val owners: OwnerRepository`, read from the class body), and follows `this.usersService.findByEmail(…)` into the class the type names instead of the name-only guess. A hop resolved this way says so in the panel. @@ -26,6 +28,14 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### Fixes +- **Express routes behind `app.use('/api', router)` are named by the path a request takes.** A router mounted at a prefix — through as many `router.use('/users', usersRouter)` levels as the app nests, by import or `require` — now names its routes `POST /api/users` instead of `POST /`, and the chained form `router.route('/:id').get(getProduct).put(protect, updateProduct)` (split across lines or not) registers one route per method. Entry points, the Steps tab and the client-to-route pairing all read the real paths. + +- **An Express handler written through a wrapper is the endpoint's handler.** `const authUser = asyncHandler(async (req, res) => { … })` — the `express-async-handler` idiom — now names the handler in Entry points and starts the Steps walk at it, with the database reads, the token check and the `401` row read from the arrow's body. + +- **A framework declared in a workspace's `package.json` is detected.** React, Next.js, Expo Router, Express and NestJS are found when their dependency lives in `frontend/`, `backend/`, `apps/web/` or `packages/api/` rather than at the repository root, so a monorepo's pages and endpoints exist in the index. + +- **Files under an `e2e/` directory count as tests.** Their calls no longer appear as production callers in Steps, dead-code and test badges. + - **Production code under a `samples` or `examples` package path is no longer treated as test code.** A Kotlin or Java project whose package path runs through `com/google/samples/…` (Now in Android, for one) had nearly every file counted as a fixture, so the Map opened on `build-logic`, the entry points hid the app, and dead-code and test badges were wrong. Only the project layout above a `src/` folder decides now; the package path below it never does. - **A FastAPI service that lives in one directory of a monorepo is detected.** `backend/pyproject.toml` and `backend/app/main.py` count, not only files at the repository root — the official full-stack template's routes now appear in Entry points and the Steps tab. diff --git a/CLAUDE.md b/CLAUDE.md index 7760949..1573d06 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -76,7 +76,7 @@ The public API surface is `src/index.ts` — the `CodeGraph` class wires all the - `src/index.ts` — `CodeGraph` class: `init`/`open`/`close`, `indexAll`, `sync`, `searchNodes`, `getCallers`/`getCallees`, `getImpactRadius`, `buildContext`, `watch`/`unwatch`. - `src/db/` — `DatabaseConnection`, `QueryBuilder` (prepared statements), `schema.sql`, `sqlite-adapter.ts`. Backed by Node's built-in **`node:sqlite`** (`DatabaseSync`) — real SQLite with WAL + FTS5, exposed through a thin better-sqlite3-shaped adapter. The bundled runtime always ships Node ≥22.5, so `node:sqlite` is always available: **no native build step and no wasm fallback**. (Running from source needs Node ≥22.5.) `codegraph status` reports the live backend (`node-sqlite`, the sole backend). - `src/extraction/` — `ExtractionOrchestrator`, tree-sitter wrappers, per-language extractors under `languages/` (one file per language), plus standalone extractors for non-tree-sitter formats (`svelte-extractor.ts`, `vue-extractor.ts`, `liquid-extractor.ts`, `dfm-extractor.ts` for Delphi). `parse-worker.ts` runs heavy parsing off the main thread. -- `src/resolution/` — `ReferenceResolver` orchestrates `import-resolver.ts` (with `path-aliases.ts` for tsconfig path aliases + cargo workspace member globs), `name-matcher.ts`, and `frameworks/` (Express, Laravel, Rails, FastAPI, Django, Flask, Spring, Gin, Axum, ASP.NET, Vapor, React Router, SvelteKit, Vue/Nuxt, Cargo workspaces). Frameworks emit `route` nodes and `references` edges. +- `src/resolution/` — `ReferenceResolver` orchestrates `import-resolver.ts` (with `path-aliases.ts` for tsconfig path aliases + cargo workspace member globs), `name-matcher.ts`, and `frameworks/` (Express, Laravel, Rails, FastAPI, Django, Flask, Spring, Gin, Axum, ASP.NET, Vapor, React Router, SvelteKit, Vue/Nuxt, Cargo workspaces). Frameworks emit `route` nodes and `references` edges. `callback-synthesizer.ts` holds the whole-graph synthesis passes (`SYNTH_PASSES`, merged in registry order — first-seen wins a duplicate pair) with the language gates; `tier-synthesizer.ts` is the cross-tier pass (a client's literal `fetch`/`axios` path onto its own route, a queue job onto its consumer, a bus / socket event onto its handler — `channel`, `tier`, `registeredAt` on every edge; registered before the in-process emitter pass so its more specific edge wins); `synth-utils.ts` has the helpers they share (`enclosingFn`, `enclosingValue`, `makeLineAt`). Express's `postExtract` composes `app.use('/prefix', router)` mounts onto a mounted file's route names, idempotently (the original path stays in `qualifiedName`). - `src/graph/` — `GraphTraverser` (BFS/DFS, impact radius, path finding) and `GraphQueryManager` (high-level queries), plus the shared query-time derivations more than one surface renders: `named-symbol-flow.ts` (the one path finder, behind `codegraph_explore`'s Flow section and the viewer's Flow strip), `dynamic-boundary-report.ts` (where the graph stops), `type-hierarchy.ts` (ancestors/subtypes and the implementation count explore prints and the viewer draws), `dead-code.ts` (unreferenced symbols, and every reason a candidate is NOT claimed). A derivation that two callers render must live here, not in `ToolHandler` — two derivations eventually disagree. - `src/context/` — `ContextBuilder` + formatter for markdown/JSON output. @@ -86,7 +86,7 @@ The public API surface is `src/index.ts` — the `CodeGraph` class wires all the - `src/installer/` — see below. - `src/bin/codegraph.ts` — CLI (commander). Subcommands: `install`, `init`, `uninit`, `index`, `sync`, `status`, `query`, `files`, `context`, `affected`, `serve --mcp`. - `src/ui/` — terminal UI (shimmer progress, worker). -- `src/ui-server/` — the `codegraph ui` browser viewer's read-only JSON API (`api/`: one module per endpoint — `node`, `flow`, `map`, `screens`, `steps`, `deadcode`, `trails`…) and static server; the Svelte viewer itself lives in `ui/` (see `docs/design/codegraph-ui-design-spec.md`). `api/screens.ts` (the app as screens and transitions) and `api/steps.ts` (what happens from a screen, an endpoint or a symbol, as typed steps — screens, handlers, native bridge calls and events, store actions, calls that leave the index) share one fold: everything between two boxes is `via`, and the branch guards along it join into `when` (`graph/branch-guards.ts`, read at request time). Two helpers sit beside them: `api/route-roots.ts` (where a route's code starts — the handler a resolver named, the page a screen file exports, or the route itself for an inline handler; one rule for every framework) and `api/effects.ts` (the curated table of calls that leave the index — database / response / queue / email / payments / cache / auth / process / network / storage / device / telemetry — matched on the call **as written**, per language family, plus the model / read-write and the response status). `graph/branch-guards.ts` reads, from one cached tree per file, the conditions a site runs under, what it passes, the call as written (the index keeps only the last segment of a deep member chain), the decorators on a definition and the declared types of a class's members — for JS/TS, Swift, Python, Java, Kotlin, C#, Go and C; a language without rules yields nothing, never a wrong label. +- `src/ui-server/` — the `codegraph ui` browser viewer's read-only JSON API (`api/`: one module per endpoint — `node`, `flow`, `map`, `screens`, `steps`, `deadcode`, `trails`…) and static server; the Svelte viewer itself lives in `ui/` (see `docs/design/codegraph-ui-design-spec.md`). `api/screens.ts` (the app as screens and transitions) and `api/steps.ts` (what happens from a screen, an endpoint or a symbol, as typed steps — screens, handlers, native bridge calls and events, store actions, calls that leave the index) share one fold: everything between two boxes is `via`, and the branch guards along it join into `when` (`graph/branch-guards.ts`, read at request time). Two helpers sit beside them: `api/route-roots.ts` (where a route's code starts — the handler a resolver named, the page a screen file exports, or the route itself for an inline handler; one rule for every framework) and `api/effects.ts` (the curated table of calls that leave the index — database / response / queue / email / payments / cache / auth / process / network / storage / device / telemetry — matched on the call **as written**, per language family, plus the model / read-write and the response status). `graph/branch-guards.ts` reads, from one cached tree per file, the conditions a site runs under, what it passes, the call as written (the index keeps only the last segment of a deep member chain), the decorators on a definition and the declared types of a class's members — for JS/TS, Swift, Python, Java, Kotlin, C#, Go and C; a language without rules yields nothing, never a wrong label. `steps.ts`'s `crossing()` reads an edge's `tier` / `channel` marker before the languages, so a synthesized cross-tier hop between two TS files draws as a bridge (an endpoint reached over HTTP — a boundary like another screen, entered with `through=1`) or an event (a job, an event, a message arriving); a Next server action is marked at request time from its `'use server'` directive (`api/when.ts`'s `directive`). ### NodeKind / EdgeKind diff --git a/__tests__/ui-steps-api-servers.test.ts b/__tests__/ui-steps-api-servers.test.ts index 93337d3..3087d59 100644 --- a/__tests__/ui-steps-api-servers.test.ts +++ b/__tests__/ui-steps-api-servers.test.ts @@ -273,8 +273,18 @@ describe('NestJS', () => { expect(db.effect).toMatchObject({ model: 'cats', access: 'write', by: { name: 'create' } }); const dbLink = p.links.find((l) => l.to === db.id)!; expect(dbLink.via.map((v) => v.name)).toEqual(['create']); - const queue = effect(p, 'queue')!; - expect(queue.label).toBe("this.catsQueue.add('index', { id })"); + // The job put on the `cats` queue lands on the processor that consumes it + // — an arrival, not a call outside the index; the site is the `add` as written. + expect(effect(p, 'queue')).toBeUndefined(); + const landing = p.steps.find((s) => s.kind === 'event' && s.node?.name === 'handleIndex')!; + expect(landing).toBeDefined(); + expect(landing.event).toBe('index'); + expect(landing.trigger).toEqual({ kind: 'decorator', name: 'Process', of: "'index'", in: 'cats.processor.ts' }); + const toLanding = p.links.find((l) => l.to === landing.id)!; + expect(toLanding.kind).toBe('event'); + expect(toLanding.synthesized).toBe(true); + expect(toLanding.sites[0]).toMatchObject({ text: 'this.catsQueue.add', args: "'index', { id }" }); + expect(toLanding.label).toBe('via queue-job · job index · queue cats · registered at src/nest/cats.processor.ts:4'); }); it('a thrown exception is the 404 the request gets', async () => { diff --git a/__tests__/ui-steps-cross-tier.test.ts b/__tests__/ui-steps-cross-tier.test.ts new file mode 100644 index 0000000..ba2c461 --- /dev/null +++ b/__tests__/ui-steps-cross-tier.test.ts @@ -0,0 +1,467 @@ +/** + * Cross-tier channels (`src/resolution/tier-synthesizer.ts`) and the Steps + * picture they make: a monorepo with a Next.js client (`apps/web`) and an + * Express + NestJS API (`apps/api`) in one indexed fixture. The page's form + * posts to its own route, a service puts a job on a queue that a processor + * consumes, a service emits an event a listener handles, and a chat component + * talks to a gateway over a socket in both directions. Mirrors + * `ui-steps-api-servers.test.ts` (the servers) and `ui-steps-api.test.ts` + * (the mobile app). + */ + +import { describe, it, expect, beforeAll, afterAll } from 'vitest'; +import * as fs from 'fs'; +import * as os from 'os'; +import * as path from 'path'; +import { CodeGraph } from '../src'; +import { initGrammars, loadAllGrammars } from '../src/extraction/grammars'; +import { buildSteps } from '../src/ui-server/api/steps'; +import type { Edge, Node } from '../src/types'; + +let tmpDir: string; +let cg: CodeGraph; + +function write(rel: string, content: string): void { + const full = path.join(tmpDir, rel); + fs.mkdirSync(path.dirname(full), { recursive: true }); + fs.writeFileSync(full, content); +} + +beforeAll(async () => { + await initGrammars(); + await loadAllGrammars(); + tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-ui-steps-tier-')); + write( + 'package.json', + JSON.stringify({ + name: 'mono', + workspaces: ['apps/*'], + dependencies: { + next: '15', + react: '19', + express: '4', + axios: '1', + bullmq: '5', + '@nestjs/common': '10', + '@nestjs/core': '10', + '@nestjs/bull': '10', + '@nestjs/event-emitter': '2', + '@nestjs/websockets': '10', + 'socket.io': '4', + 'socket.io-client': '4', + '@prisma/client': '5', + }, + }) + ); + + // ---- The web app: a page, a client form that posts to the API and calls a + // server action, a card that reads through an axios instance, a chat. + write( + 'apps/web/app/users/page.tsx', + "import { NewUserForm } from '../../components/new-user-form'\n" + + 'export default function UsersPage() {\n' + + ' return \n' + + '}\n' + ); + write( + 'apps/web/components/new-user-form.tsx', + "'use client'\n" + + "import { useCallback, useState } from 'react'\n" + + "import { createUserAction } from '../app/actions'\n" + + 'export function NewUserForm() {\n' + + " const [email, setEmail] = useState('')\n" + + ' const handleSubmit = useCallback(async (e) => {\n' + + ' e.preventDefault()\n' + + ' if (!email) return\n' + + " const res = await fetch('/api/users', { method: 'POST', body: JSON.stringify({ email }) })\n" + + ' if (res.ok) await createUserAction({ email })\n' + + ' }, [email])\n' + + ' return
setEmail(e.target.value)} />
\n' + + '}\n' + ); + write( + 'apps/web/app/actions.ts', + "'use server'\n" + + "import { prisma } from '../lib/db'\n" + + "import { redirect } from 'next/navigation'\n" + + 'export async function createUserAction(data) {\n' + + ' await prisma.user.create({ data })\n' + + " redirect('/users')\n" + + '}\n' + ); + write('apps/web/lib/db.ts', "import { PrismaClient } from '@prisma/client'\nexport const prisma = new PrismaClient()\n"); + write('apps/web/lib/api.ts', "import axios from 'axios'\nexport const api = axios.create({ baseURL: '/api' })\n"); + write( + 'apps/web/components/user-card.tsx', + "'use client'\n" + + "import { api } from '../lib/api'\n" + + 'export function UserCard({ id, url }) {\n' + + ' async function load() {\n' + + ' const { data } = await api.get(`/users/${id}`)\n' + + " const external = await fetch('https://api.stripe.com/v1/charges')\n" + + ' const dynamic = await fetch(url)\n' + + ' const orders = await fetch(`${process.env.API_URL}/api/users/${id}/orders`)\n' + + ' return [data, external, dynamic, orders]\n' + + ' }\n' + + ' return null\n' + + '}\n' + ); + write( + 'apps/web/components/chat.tsx', + "'use client'\n" + + "import { useEffect, useState } from 'react'\n" + + "import { io } from 'socket.io-client'\n" + + 'const socket = io()\n' + + 'export function Chat() {\n' + + ' const [messages, setMessages] = useState([])\n' + + ' useEffect(() => {\n' + + " socket.on('message', (m) => {\n" + + ' setMessages((prev) => [...prev, m])\n' + + ' })\n' + + ' }, [])\n' + + ' function send(text) {\n' + + " socket.emit('message', text)\n" + + ' }\n' + + ' return null\n' + + '}\n' + ); + + // ---- The API: Express routes, a queue and its Nest processor, a Nest + // service emitting an event and its listener, a gateway, a BullMQ worker. + write( + 'apps/api/src/app.ts', + "import express from 'express'\n" + + "import { createUser, getUser, listOrders } from './users'\n" + + 'const app = express()\n' + + "app.post('/api/users', createUser)\n" + + "app.get('/api/users/:id', getUser)\n" + + "app.get('/api/users/:id/orders', listOrders)\n" + + "const v1 = require('./v1')\n" + + "app.use('/api/v1', authenticate, v1)\n" + + 'export default app\n' + ); + // A mounted router, two levels deep: its routes are written relative to the mount. + write( + 'apps/api/src/v1/index.ts', + "import { Router } from 'express'\n" + + "import ordersRouter from '../orders.routes'\n" + + 'const router = Router()\n' + + "router.use('/orders', ordersRouter)\n" + + 'export default router\n' + ); + write( + 'apps/api/src/orders.routes.ts', + "import { Router } from 'express'\n" + + "import { prisma } from './db'\n" + + 'const router = Router()\n' + + "router.get('/', listAllOrders)\n" + + "router.post('/:id/refund', refund)\n" + + 'export async function listAllOrders(req, res) {\n' + + ' res.json(await prisma.order.findMany())\n' + + '}\n' + + 'export async function refund(req, res) {\n' + + ' res.status(202).end()\n' + + '}\n' + + 'export default router\n' + ); + write( + 'apps/web/components/orders.tsx', + "'use client'\n" + + 'export function Orders() {\n' + + ' async function loadOrders() {\n' + + " const res = await fetch('/api/v1/orders')\n" + + ' return res.json()\n' + + ' }\n' + + ' return null\n' + + '}\n' + ); + write( + 'apps/api/src/users.ts', + "import { prisma } from './db'\n" + + "import { emailQueue, reportQueue } from './queue'\n" + + 'export async function createUser(req, res) {\n' + + ' const user = await prisma.user.create({ data: req.body })\n' + + " await emailQueue.add('welcome', { userId: user.id })\n" + + ' if (req.body.plan) {\n' + + " await reportQueue.add('monthly', { userId: user.id })\n" + + ' }\n' + + ' res.status(201).json(user)\n' + + '}\n' + + 'export async function getUser(req, res) {\n' + + ' const user = await prisma.user.findUnique({ where: { id: req.params.id } })\n' + + ' res.json(user)\n' + + '}\n' + + 'export async function listOrders(req, res) {\n' + + ' res.json(await prisma.order.findMany({ where: { userId: req.params.id } }))\n' + + '}\n' + ); + write('apps/api/src/db.ts', "import { PrismaClient } from '@prisma/client'\nexport const prisma = new PrismaClient()\n"); + write('apps/api/src/queue.ts', "import { Queue } from 'bullmq'\nexport const emailQueue = new Queue('email')\nexport const reportQueue = new Queue('reports')\n"); + write( + 'apps/api/src/email.processor.ts', + "import { Processor, Process } from '@nestjs/bull'\n" + + "@Processor('email')\n" + + 'export class EmailProcessor {\n' + + ' constructor(private readonly mailer: MailerService) {}\n' + + " @Process('welcome')\n" + + ' async sendWelcome(job) {\n' + + ' await this.mailer.sendMail({ to: job.data.email })\n' + + ' }\n' + + '}\n' + ); + write( + 'apps/api/src/reports.worker.ts', + "import { Worker } from 'bullmq'\n" + + "export const reportWorker = new Worker('reports', async (job) => {\n" + + ' await buildReport(job.data)\n' + + '})\n' + + 'export async function buildReport(data) {\n' + + ' return data\n' + + '}\n' + ); + write( + 'apps/api/src/users.service.ts', + "import { Injectable } from '@nestjs/common'\n" + + "import { EventEmitter2 } from '@nestjs/event-emitter'\n" + + '@Injectable()\n' + + 'export class UsersService {\n' + + ' constructor(private readonly eventEmitter: EventEmitter2) {}\n' + + ' async create(dto) {\n' + + ' const user = { id: 1, ...dto }\n' + + " this.eventEmitter.emit('user.created', user)\n" + + ' return user\n' + + ' }\n' + + '}\n' + ); + write( + 'apps/api/src/notifications.listener.ts', + "import { Injectable } from '@nestjs/common'\n" + + "import { OnEvent } from '@nestjs/event-emitter'\n" + + '@Injectable()\n' + + 'export class NotificationsListener {\n' + + " @OnEvent('user.created')\n" + + ' handleUserCreated(user) {\n' + + ' return notify(user)\n' + + ' }\n' + + " @OnEvent('user.*')\n" + + ' audit(payload) {\n' + + ' return log(payload)\n' + + ' }\n' + + " @OnEvent('order.paid')\n" + + ' handleOrderPaid(order) {\n' + + ' return order\n' + + ' }\n' + + '}\n' + ); + write( + 'apps/api/src/chat.gateway.ts', + "import { WebSocketGateway, SubscribeMessage, WebSocketServer } from '@nestjs/websockets'\n" + + '@WebSocketGateway()\n' + + 'export class ChatGateway {\n' + + ' @WebSocketServer() server\n' + + " @SubscribeMessage('message')\n" + + ' handleMessage(client, payload) {\n' + + " this.server.emit('message', payload)\n" + + ' return payload\n' + + ' }\n' + + '}\n' + ); + // A test suite calling the API is the test's story: never a source. + write( + 'apps/api/src/__tests__/users.test.ts', + "import { it } from 'vitest'\n" + + "it('creates a user', async () => {\n" + + " await fetch('/api/users', { method: 'POST' })\n" + + '})\n' + ); + cg = CodeGraph.initSync(tmpDir); + await cg.indexAll(); +}); + +afterAll(() => { + cg?.close(); + if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true }); +}); + +const q = (params: Record) => new URLSearchParams(params); +const sym = (name: string, file?: string): Node => { + const found = cg.getNodesByName(name).filter((n) => n.kind !== 'route' && n.kind !== 'file' && (!file || n.filePath.endsWith(file))); + if (!found[0]) throw new Error(`no symbol ${name}`); + return found[0]; +}; +const route = (name: string): Node => { + const r = cg.getNodesByKind('route').find((r) => r.name === name); + if (!r) throw new Error(`no route ${name}: ${cg.getNodesByKind('route').map((r) => r.name).join(', ')}`); + return r; +}; +const synthesized = (from: Node, by: string): Edge[] => + cg.getOutgoingEdges(from.id).filter((e) => e.provenance === 'heuristic' && (e.metadata as Record)?.synthesizedBy === by); +const effect = (p: Awaited>, category: string) => p.steps.find((s) => s.kind === 'effect' && s.effect?.category === category); + +describe('http-client: a literal path in a client call reaches its own route', () => { + it('binds fetch("/api/users", { method: "POST" }) to POST /api/users, remembering the registration', () => { + const edges = synthesized(sym('handleSubmit'), 'http-client'); + expect(edges).toHaveLength(1); + expect(edges[0]!.target).toBe(route('POST /api/users').id); + expect(edges[0]!.kind).toBe('calls'); + expect(edges[0]!.line).toBe(9); + expect(edges[0]!.metadata).toEqual({ + synthesizedBy: 'http-client', + channel: 'http', + callee: 'fetch', + tier: 'client→server', + method: 'POST', + href: '/api/users', + registeredAt: 'apps/api/src/app.ts:4', + }); + }); + + it('joins an axios instance’s literal baseURL, matches a template hole to a :param, and a base-URL hole by the tail', () => { + const edges = synthesized(sym('load'), 'http-client'); + const byHref = new Map(edges.map((e) => [(e.metadata as Record).href, e])); + expect([...byHref.keys()].sort()).toEqual(['/api/users/${…}', '/api/users/${…}/orders']); + expect(byHref.get('/api/users/${…}')!.target).toBe(route('GET /api/users/:id').id); + expect((byHref.get('/api/users/${…}')!.metadata as Record).method).toBe('GET'); + expect(byHref.get('/api/users/${…}/orders')!.target).toBe(route('GET /api/users/:id/orders').id); + }); + + it('produces nothing for an external URL, a variable url, or a call in a test suite', () => { + // `load` makes four calls; only two name a route (asserted above). + expect(synthesized(sym('load'), 'http-client')).toHaveLength(2); + const testFns = cg.getNodesInFile('apps/api/src/__tests__/users.test.ts'); + for (const n of testFns) expect(synthesized(n, 'http-client')).toHaveLength(0); + const incoming = cg.getIncomingEdgesTo([route('POST /api/users').id], ['calls']).filter((e) => e.provenance === 'heuristic'); + expect(incoming.map((e) => e.source)).toEqual([sym('handleSubmit').id]); + }); +}); + +describe('express mounts: a mounted router’s routes are named by the path a request takes', () => { + it('composes app.use("/api/v1") and router.use("/orders") onto the routes, and a client path binds to the composed name', () => { + const names = cg.getNodesByKind('route').map((r) => r.name); + expect(names).toContain('GET /api/v1/orders'); + expect(names).toContain('POST /api/v1/orders/:id/refund'); + expect(names).not.toContain('GET /'); + const edges = synthesized(sym('loadOrders'), 'http-client'); + expect(edges).toHaveLength(1); + expect(edges[0]!.target).toBe(route('GET /api/v1/orders').id); + expect((edges[0]!.metadata as Record).registeredAt).toBe('apps/api/src/orders.routes.ts:4'); + }); +}); + +describe('queue-job: a job put on a named queue reaches its consumer', () => { + it('pairs emailQueue.add("welcome") with the @Process("welcome") method of the @Processor("email") class', () => { + const edges = synthesized(sym('createUser'), 'queue-job'); + const welcome = edges.find((e) => (e.metadata as Record).event === 'welcome')!; + expect(welcome).toBeDefined(); + expect(welcome.target).toBe(sym('sendWelcome').id); + expect(welcome.line).toBe(5); + expect(welcome.metadata).toEqual({ synthesizedBy: 'queue-job', channel: 'queue', callee: 'emailQueue.add', event: 'welcome', queue: 'email', registeredAt: 'apps/api/src/email.processor.ts:5' }); + }); + + it('pairs reportQueue.add("monthly") with the BullMQ Worker on that queue', () => { + const edges = synthesized(sym('createUser'), 'queue-job'); + const monthly = edges.find((e) => (e.metadata as Record).event === 'monthly')!; + expect(monthly).toBeDefined(); + const target = cg.getNode(monthly.target)!; + expect(target.filePath).toBe('apps/api/src/reports.worker.ts'); + expect((monthly.metadata as Record).queue).toBe('reports'); + expect((monthly.metadata as Record).registeredAt).toBe('apps/api/src/reports.worker.ts:2'); + }); +}); + +describe('event-bus: an emitted event reaches its listeners; a socket message crosses tiers both ways', () => { + it('pairs eventEmitter.emit("user.created") with @OnEvent("user.created") and the "user.*" glob, not "order.paid"', () => { + const edges = synthesized(sym('create', 'users.service.ts'), 'event-bus'); + const targets = edges.map((e) => cg.getNode(e.target)!.name).sort(); + expect(targets).toEqual(['audit', 'handleUserCreated']); + const direct = edges.find((e) => e.target === sym('handleUserCreated').id)!; + expect(direct.metadata).toEqual({ synthesizedBy: 'event-bus', channel: 'event', callee: 'this.eventEmitter.emit', event: 'user.created', registeredAt: 'apps/api/src/notifications.listener.ts:5' }); + }); + + it('a client’s socket.emit lands on the gateway’s @SubscribeMessage, client → server', () => { + const edges = synthesized(sym('send'), 'event-bus'); + expect(edges).toHaveLength(1); + expect(edges[0]!.target).toBe(sym('handleMessage').id); + expect(edges[0]!.metadata).toEqual({ synthesizedBy: 'event-bus', channel: 'socket', callee: 'socket.emit', event: 'message', tier: 'client→server', registeredAt: 'apps/api/src/chat.gateway.ts:5' }); + }); + + it('the gateway’s server.emit lands in the component that registered socket.on inline, server → client', () => { + const edges = synthesized(sym('handleMessage'), 'event-bus'); + expect(edges).toHaveLength(1); + expect(edges[0]!.target).toBe(sym('Chat').id); + expect(edges[0]!.metadata).toEqual({ synthesizedBy: 'event-bus', channel: 'socket', callee: 'this.server.emit', event: 'message', tier: 'server→client', registeredAt: 'apps/web/components/chat.tsx:8' }); + }); +}); + +describe('the Steps picture across the tiers', () => { + it('draws the route as a boundary the form crosses to (⇢), and enters it on request', async () => { + const boundary = await buildSteps(cg, tmpDir, q({ symbol: 'UsersPage' })); + expect(boundary.project).toBe('web'); + const handler = boundary.steps.find((s) => s.kind === 'trigger' && s.node?.name === 'handleSubmit')!; + expect(handler).toBeDefined(); + expect(handler.trigger).toMatchObject({ kind: 'prop', name: 'onSubmit', of: 'form' }); + const bridge = boundary.steps.find((s) => s.kind === 'bridge' && s.screen?.path === 'POST /api/users')!; + expect(bridge).toBeDefined(); + expect(bridge.cut).toBe('screen'); + expect(bridge.sub).toBe('createUser'); + expect(bridge.trigger).toEqual({ kind: 'request', name: 'POST', of: '/api/users', in: 'app.ts' }); + const link = boundary.links.find((l) => l.from === handler.id && l.to === bridge.id)!; + expect(link.kind).toBe('bridge'); + expect(link.synthesized).toBe(true); + expect(link.when).toBe('email'); + expect(link.sites[0]).toMatchObject({ text: 'fetch', args: "'/api/users', { method, body }", line: 9 }); + expect(link.label).toContain('POST /api/users'); + expect(link.label).toContain('to the server'); + expect(link.label).toContain('registered at apps/api/src/app.ts:4'); + // The fetch is the crossing, not also a network call outside the index; + // the route is not entered, so the handler's write is not drawn — the + // server action's is, since a function the code crosses to is walked. + expect(effect(boundary, 'network')).toBeUndefined(); + const writes = boundary.steps.filter((s) => s.kind === 'effect' && s.effect?.category === 'database'); + expect(writes.map((s) => s.effect!.by.name)).toEqual(['createUserAction']); + + const through = await buildSteps(cg, tmpDir, q({ symbol: 'UsersPage', through: '1' })); + const entered = through.steps.find((s) => s.kind === 'bridge' && s.screen?.path === 'POST /api/users')!; + expect(entered.cut).toBeNull(); + const db = through.steps.filter((s) => s.kind === 'effect' && s.effect?.category === 'database'); + expect(db.map((s) => s.effect!.by.name).sort()).toEqual(['createUser', 'createUserAction']); + const res = effect(through, 'response')!; + expect(res.label).toBe('201'); + expect(res.effect!.by.name).toBe('createUser'); + const welcome = through.steps.find((s) => s.kind === 'event' && s.event === 'welcome')!; + expect(welcome).toBeDefined(); + expect(welcome.node!.name).toBe('sendWelcome'); + expect(welcome.trigger).toEqual({ kind: 'decorator', name: 'Process', of: "'welcome'", in: 'email.processor.ts' }); + const toWelcome = through.links.find((l) => l.to === welcome.id)!; + expect(toWelcome.kind).toBe('event'); + expect(toWelcome.sites[0]).toMatchObject({ text: 'emailQueue.add', args: "'welcome', { userId }", line: 5 }); + expect(toWelcome.label).toBe('via queue-job · job welcome · queue email · registered at apps/api/src/email.processor.ts:5'); + expect(effect(through, 'queue')?.effect?.apis ?? []).not.toContain('emailQueue.add'); + const mail = effect(through, 'email')!; + expect(mail.effect!.by.name).toBe('sendWelcome'); + }); + + it('a server action called from a client component is a crossing to the server, by its directive', async () => { + const p = await buildSteps(cg, tmpDir, q({ symbol: 'NewUserForm' })); + const action = p.steps.find((s) => s.node?.name === 'createUserAction')!; + expect(action).toBeDefined(); + expect(action.kind).toBe('bridge'); + const link = p.links.find((l) => l.to === action.id)!; + expect(link.kind).toBe('bridge'); + expect(link.when).toBe('email && res.ok'); + expect(link.label).toContain('server action'); + expect(link.sites[0]).toMatchObject({ text: 'calls createUserAction', args: '{ email }' }); + expect(effect(p, 'database')?.effect?.by.name).toBe('createUserAction'); + }); + + it('a socket message arriving in a component is an event landing, drawn as a boundary', async () => { + const p = await buildSteps(cg, tmpDir, q({ symbol: 'handleMessage' })); + const chat = p.steps.find((s) => s.kind === 'event' && s.node?.name === 'Chat')!; + expect(chat).toBeDefined(); + expect(chat.event).toBe('message'); + expect(chat.cut).toBe('component'); + const link = p.links.find((l) => l.to === chat.id)!; + expect(link.kind).toBe('event'); + expect(link.label).toContain('from the server'); + }); +}); diff --git a/docs/design/callback-edge-synthesis.md b/docs/design/callback-edge-synthesis.md index bef8316..a03cfc7 100644 --- a/docs/design/callback-edge-synthesis.md +++ b/docs/design/callback-edge-synthesis.md @@ -38,7 +38,7 @@ We synthesize `dispatcher → callback` edges that static parsing misses. It wor npm run build rm -rf /tmp/codegraph-corpus/excalidraw/.codegraph ( cd /tmp/codegraph-corpus/excalidraw && codegraph init -i ) -# synthesized edges (provenance='heuristic', metadata.synthesizedBy in {callback,event-emitter}): +# synthesized edges (provenance='heuristic', metadata.synthesizedBy in {callback,event-emitter,…,http-client,queue-job,event-bus}): sqlite3 /tmp/codegraph-corpus/excalidraw/.codegraph/codegraph.db \ "select s.name||' → '||t.name||' '||coalesce(e.metadata,'') from edges e \ join nodes s on e.source=s.id join nodes t on e.target=t.id where e.provenance='heuristic';" @@ -51,6 +51,40 @@ fixture lives at `/tmp/cb-fixture/bus.js` (ephemeral — recreate or move into ` --- +## Cross-tier channels (`src/resolution/tier-synthesizer.ts`, 2026-08-28) + +The web's RN bridge: one pass, registered before the in-process emitter pass (the more specific edge wins a duplicate +`source>target` pair in the merge), gated on JS-family files, never sourced from a test suite or a generated file. +Three channels, each keyed on a literal on both sides, each edge `kind:'calls'`, `provenance:'heuristic'`, with +`synthesizedBy`, `channel` (`http` | `queue` | `event` | `socket`), `tier` (`client→server` / `server→client`) when the +direction is known, the `event` / `queue` / `method` / `href` it paired on, `line` + `column` of the call, and +`registeredAt` = the other side (route registration, decorator, `.on`): + +- **`http-client`** — `fetch` / `$fetch` / `ofetch` / `axios` / `ky` / `got` / `useFetch` / `useSWR`, `.get|post|…(` + where the receiver is a known client name or a binding made by `axios.create(…)` / `ky.extend(…)` (same file or the file it + is imported from — `resolveImportPath`, since import mappings carry no resolved path), with a literal / template first + argument (`new URL('/x', base)` and `{ url, method }` configs read too) → the ONE route `METHOD path` in the index it + denotes. A hole fills a `:param` / `{id}` / `[id]` / catch-all segment and never a literal one; a hole in front of the path + (`${API_URL}/users`) matches by the route's tail; a line a framework resolver made a route node on is a registration, not a + client call; a tie between routes is nothing. No fan-out cap — the match is exact. +- **`queue-job`** — `.add('job', …)` where the queue is named (`new Queue('email')`, `@InjectQueue('email') x`, in the + file or its import) or queue-shaped → the `@Process('job')` method of the `@Processor('email')` class (a WorkerHost's + `process` when there is none), `new Worker('email', handler)` (an inline handler → the enclosing function, else the + enclosing constant), Bull's `queue.process('job', handler)`. Most specific pairing wins (queue+job > job > the queue's + default); an unnamed queue pairs only on a unique job name. Fan-out cap 6. +- **`event-bus`** — `.emit|emitAsync('x')` on a bus-shaped receiver (`eventEmitter`, `bus`, `pubsub`, …) → `@OnEvent` + handlers, `*` / `**` globs honoured; on a socket-shaped receiver (`socket`, `io`, `server`, `client`, `.to(room)`, …) from a + file without a socket server → `@SubscribeMessage('x')` and server-side `socket.on('x')` (`client→server`); from a file + with one (`@WebSocketGateway`, `io.on('connection')`, `new Server`) → client-side `socket.on('x', …)`, named or inline + (→ the enclosing component) (`server→client`). Plain `.on` ↔ `.emit` stays the emitter pass's. Fan-out cap 6. + +The Steps view (`ui-server/api/steps.ts`) reads `tier` / `channel` before the languages in `crossing()`, so a hop between +two TS files draws as a bridge (`⇢ POST /api/users`, a boundary like another screen) or an event (`⇠ welcome`); explore's +Flow section labels them (`context/index.ts`, `mcp/tools.ts`). A Next `'use server'` action needs no edge: `steps.ts` marks +the call at request time from the directive. Validated on `bradtraversy/proshop_mern` (30 routes, 23 client→route edges, +all correct on inspection, after Express mounts + chained `router.route()` landed) and `nestjs/nest` (`sample/26-queues`, +`sample/30-event-emitter`); test `__tests__/ui-steps-cross-tier.test.ts`. + ## The hole ```ts diff --git a/docs/design/codegraph-ui-design-spec.md b/docs/design/codegraph-ui-design-spec.md index f8b5a46..209d4db 100644 --- a/docs/design/codegraph-ui-design-spec.md +++ b/docs/design/codegraph-ui-design-spec.md @@ -513,6 +513,29 @@ endpoints grouped by router file when there are no screens. A production walk ne and a repository-shaped method the walk cannot enter (an interface's, the ORM's) is the database. Conditions and arguments are read for Python, Java, Kotlin, C#, Go and C as for JS and Swift (§3.14); a language without rules yields nothing. +**Across the tiers (a web app, a monorepo).** A web app is two programs that talk over a wire the graph cannot see, and the +same picture wants the same evidence the RN bridge gives it: a string on both sides. `resolution/tier-synthesizer.ts` pairs them at +index time (`provenance: 'heuristic'`, `synthesizedBy`, `channel`, `tier`, `registeredAt`): a client call with a literal path — +`fetch('/api/users', { method: 'POST' })`, `axios.post`, `ky`, `got`, `$fetch`, `useFetch`, `useSWR`, or a project instance made by +`axios.create({ baseURL })` — onto the one route `METHOD path` it names (`http-client`, `tier: 'client→server'`; a template hole fills +a `:param` and never a literal segment, a hole in front of the path matches a route by its tail, a variable url or a path two routes +serve alike is nothing); `queue.add('welcome')` on a named queue onto the `@Process('welcome')` method of the `@Processor` class, a +WorkerHost's `process`, a `new Worker('email', handler)` or Bull's `queue.process` (`queue-job`, `channel: 'queue'`); +`eventEmitter.emit('user.created')` onto `@OnEvent` listeners, globs honoured (`event-bus`, `channel: 'event'`); a client's +`socket.emit('x')` onto the gateway's `@SubscribeMessage('x')` and the server's `server.emit('x')` back onto the component that +registered `socket.on('x', …)` inline (`channel: 'socket'`, the `tier` each way). A Next server action needs no edge: a call from a file +without the directive into a function whose file (or body) opens with `'use server'` is marked `client→server` at request time. +`crossing()` reads the marker before the languages, so a hop between two TypeScript files can be a **bridge** or an **event**: an +endpoint reached across a tier draws as a bridge box that keeps its endpoint face (`⇢ POST /api/users` over its handler's name, `FIRES +FROM POST /api/users · after …`) and is a boundary exactly as another screen is — `cut: 'screen'`, entered with `&through=1`, the walk +going on into the handler; a job, an event or a message arriving draws as `⇠ welcome` on its consumer, whose trigger already says +`@Process('welcome')`. The site of such a hop is the call as written (`fetch('/api/users', { method, body })`, `emailQueue.add('welcome', +{ userId })`) with its conditions, and the link's label says the channel, the way it crosses and where it was registered (`via http-client +· POST /api/users · to the server · registered at app.ts:4`). A call a channel follows is not also drawn as a call outside the index +— the crossing is the story — and a top-level `const worker = new Worker('q', async (job) => …)` lends its constant the file-scope calls +within its lines, so the landing walks on into what the handler does. Test suites and generated files are never sources: forty supertest +calls would make a route a hub. A mounted Express router (`app.use('/api', routes)`, nested) names its routes by the path a request takes. + Rows = distance from the anchor as the server counted it (first discovery), anchor on top with the entry mark. Boxes: the §3.12 screen box for a screen or a handler; **bridge / event** add a 3px `--accent` left rule (the language changes under the code) and lead with `⇢` / `⇠ `; **store** sits on `--paper-2`; **effect** is dashed diff --git a/docs/plans/2026-08-28-steps-and-screens-for-apis-and-web.md b/docs/plans/2026-08-28-steps-and-screens-for-apis-and-web.md index 30f6516..7a48312 100644 --- a/docs/plans/2026-08-28-steps-and-screens-for-apis-and-web.md +++ b/docs/plans/2026-08-28-steps-and-screens-for-apis-and-web.md @@ -2,8 +2,8 @@ **Status:** plan, written 2026-08-28 at the end of the session that built the Steps view and the readings it rests on (Expo + React Native app, `amniservices-mobile-app`). **Updated the same day, later -session: P0, P1, P2, P5 and P6 are built** (see the per-item notes marked *Built*); P3 (cross-tier -channels), P4 (Next.js as a Screens app) and P7's agent A/B numbers are open. Every claim about what a +sessions: P0, P1, P2, P3, P5 and P6 are built** (see the per-item notes marked *Built*); P4 (Next.js as a +Screens app) and P7's agent A/B numbers are open. Every claim about what a resolver emits *today* was verified against the source on this date — re-verify before building on it, the resolvers move. What was learned building it, beyond the plan: the index keeps only the LAST segment of a deep member call (`create` for `prisma.user.create`) and name-matches it — often to the @@ -280,6 +280,24 @@ consumer reads `FIRES FROM @Process('email')`. ### P3 — Cross-tier channels (the RN bridge, for the web) +*Built* (2026-08-28, later session) — `src/resolution/tier-synthesizer.ts` (one pass, three channels: `http-client` with +`tier: 'client→server'`, `queue-job`, `event-bus` for a bus and for sockets both ways; registered before the emitter pass), Next +server actions marked at request time from the `'use server'` directive (`api/when.ts` `directive`), `crossing()` in `steps.ts` +reading `tier` / `channel`, an endpoint reached across a tier drawn as a bridge box that is a boundary like a screen, a channel's +call never also an effect, a top-level `new Worker` landing on its constant with the file-scope calls lent to it; Express mounts +(`app.use('/api', router)`, nested, by import or `require`) composed onto route names in `postExtract`, and the chained +`router.route('/x').get(h).put(h2)` form extracted; `e2e/` counts as a test directory. Test: `__tests__/ui-steps-cross-tier.test.ts`. +Verified on `bradtraversy/proshop_mern` (30 routes, 23 client→route edges, every one correct on inspection; `login` reads +`login → ⇢ POST /api/users/login (authUser) → User.findOne({ email }) → 401 rows → jwt.sign via generateToken`, which needed +`routeRoots` to accept a function-valued constant — `const authUser = asyncHandler(async (req, res) => …)` — and the walk to lend +such a value the file-scope calls and unresolved refs within its lines; and framework detection to read a workspace's +`package.json` (`frameworks/package-deps.ts`), proshop keeping `react` in `frontend/`) and `nestjs/nest` +(`sample/26-queues` `transcode` → `@Process('transcode')`, `sample/30-event-emitter` → `@OnEvent`; the `integration/*/e2e` +helpers no longer count). **Not built:** tRPC (a procedure's inline handler is not a node — extractor work with the kernel twin). +**Gap found:** a nested `const handleSubmit = async (e) => …` inside a component is not a node (only `function` declarations and +`useCallback`-bound arrows are — `tree-sitter.ts` `reactHookBoundName`), so such a handler's `fetch` attributes to the component and +the link carries no FIRES FROM; the fix is an extractor rule for a nested arrow bound by a declarator, in TS and in the Rust kernel. + *Where:* new synthesizers in `resolution/callback-synthesizer.ts` (register in the channel list with a language gate), or a resolver for the resolvable ones; each tagged `provenance: 'heuristic'`, `synthesizedBy`, `registeredAt`. **Close both directions before shipping any of them** (playbook). diff --git a/src/context/index.ts b/src/context/index.ts index 30e3bf3..c819a55 100644 --- a/src/context/index.ts +++ b/src/context/index.ts @@ -412,6 +412,12 @@ export class ContextBuilder { ? `renders <${String(m.via || 'child')}>` : m.synthesizedBy === 'vue-handler' ? `Vue @${String(m.event || 'event')} handler` + : m.synthesizedBy === 'http-client' + ? `HTTP ${String(m.method || 'GET')} ${String(m.href || '')} — the client's call onto its own route${at}` + : m.synthesizedBy === 'queue-job' + ? `queue job ${m.event ? `\`${String(m.event)}\`` : ''}${m.queue ? ` on \`${String(m.queue)}\`` : ''}${at}` + : m.synthesizedBy === 'event-bus' && m.channel === 'socket' + ? `socket message ${m.event ? `\`${String(m.event)}\`` : ''}${m.tier === 'client→server' ? ' → server' : m.tier === 'server→client' ? ' → client' : ''}${at}` : `event ${m.event ? `\`${String(m.event)}\`` : ''}${at}`; synthByPair.set(`${e.source}>${e.target}`, label); } diff --git a/src/db/queries.ts b/src/db/queries.ts index f462637..4e2990c 100644 --- a/src/db/queries.ts +++ b/src/db/queries.ts @@ -1058,7 +1058,7 @@ export class QueryBuilder { JOIN nodes h ON e.target = h.id WHERE r.kind = 'route' AND e.kind IN ('references', 'calls') - AND h.kind IN ('function', 'method', 'class') + AND h.kind IN ('function', 'method', 'class', 'constant', 'variable') ORDER BY r.file_path, r.start_line LIMIT ? `); diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts index 83f8d16..b058574 100644 --- a/src/mcp/tools.ts +++ b/src/mcp/tools.ts @@ -2478,6 +2478,33 @@ export class ToolHandler { registeredAt, }; } + if (m?.synthesizedBy === 'http-client') { + const req = `${String(m.method ?? 'GET')} ${String(m.href ?? '')}`.trim(); + return { + label: `HTTP request \`${req}\` — the client's call onto its own route (cross-tier)`, + compact: `dynamic: HTTP ${req}${at}`, + registeredAt, + }; + } + if (m?.synthesizedBy === 'queue-job') { + const job = m.event ? `\`${String(m.event)}\`` : 'a job'; + const queue = m.queue ? ` on queue \`${String(m.queue)}\`` : ''; + return { + label: `queue job ${job}${queue} — producer → consumer (cross-tier)`, + compact: `dynamic: queue job ${job}${at}`, + registeredAt, + }; + } + if (m?.synthesizedBy === 'event-bus') { + const ev = m.event ? `\`${String(m.event)}\`` : 'an event'; + const what = m.channel === 'socket' ? 'socket message' : 'bus event'; + const dir = m.tier === 'client→server' ? ', client → server' : m.tier === 'server→client' ? ', server → client' : ''; + return { + label: `${what} ${ev} — emit → handler${dir} (dynamic dispatch)`, + compact: `dynamic: ${what} ${ev}${at}`, + registeredAt, + }; + } if (m?.synthesizedBy === 'event-emitter') { const ev = m.event ? `\`${String(m.event)}\`` : 'an event'; return { diff --git a/src/resolution/callback-synthesizer.ts b/src/resolution/callback-synthesizer.ts index c41562d..98167aa 100644 --- a/src/resolution/callback-synthesizer.ts +++ b/src/resolution/callback-synthesizer.ts @@ -30,6 +30,8 @@ import { cFnPointerDispatchEdges } from './c-fnptr-synthesizer'; import { goframeRouteEdges } from './goframe-synthesizer'; import { expoRouterReturnEdges } from './expo-router-synthesizer'; import { createYielder, type MaybeYield } from './cooperative-yield'; +import { crossTierEdges } from './tier-synthesizer'; +import { enclosingFn, makeLineAt } from './synth-utils'; const REGISTRAR_NAME = /^(on[A-Z]\w*|subscribe|addListener|addEventListener|register|watch|listen|addCallback)$/; const DISPATCHER_NAME = /(emit|trigger|notify|dispatch|fire|publish|flush)/i; @@ -110,33 +112,6 @@ function sliceLines(content: string, startLine?: number, endLine?: number): stri return content.split('\n').slice(startLine - 1, endLine).join('\n'); } -/** - * Per-match line resolver over `src`, 1-based at `baseLine`. The inline - * `src.slice(0, idx).split('\n').length` idiom is O(source-length) PER MATCH, - * which goes quadratic on a match-dense source (a generated function full of - * `.push(` calls re-scanned tens of thousands of times was most of the #1235 - * indexing wedge). Builds the newline index once — lazily, since most sources - * never produce a match — then answers each call with a binary search. - */ -function makeLineAt(src: string, baseLine: number): (idx: number) => number { - let nl: number[] | null = null; - return (idx: number) => { - if (!nl) { - nl = []; - for (let i = src.indexOf('\n'); i !== -1; i = src.indexOf('\n', i + 1)) nl.push(i); - } - // Count newlines strictly before idx. - let lo = 0; - let hi = nl.length; - while (lo < hi) { - const mid = (lo + hi) >> 1; - if (nl[mid]! < idx) lo = mid + 1; - else hi = mid; - } - return baseLine + lo; - }; -} - function registrarField(src: string): string | null { const m = src.match(/this\.(\w+)\.(?:add|push|set)\(/); return m ? m[1]! : null; @@ -150,21 +125,6 @@ function dispatcherField(src: string): string | null { return null; } -const FN_KINDS = new Set(['method', 'function', 'component']); - -/** Innermost function/method node whose line range contains `line`. */ -function enclosingFn(nodesInFile: Node[], line: number): Node | null { - let best: Node | null = null; - for (const n of nodesInFile) { - if (!FN_KINDS.has(n.kind)) continue; - const end = n.endLine ?? n.startLine; - if (n.startLine <= line && end >= line) { - if (!best || n.startLine >= best.startLine) best = n; // prefer the tightest (latest-starting) encloser - } - } - return best; -} - /** * Stream method + function nodes lazily. The synthesizers only scan-and-filter * down to a tiny matched subset, so materializing every function/method (which @@ -3578,6 +3538,11 @@ const ALWAYS = (): boolean => true; export const SYNTH_PASSES: SynthPassDef[] = [ { name: 'fieldEdges', gate: ALWAYS, run: (q, c, y) => fieldChannelEdges(q, c, y) }, { name: 'closureCollEdges', gate: ALWAYS, run: (q, c, y) => closureCollectionEdges(q, c, y) }, + // Cross-tier channels — a client's `fetch('/api/x')` onto its own route, + // a queue job onto its consumer, a bus / socket event onto its handler. + // Before the in-process emitter pass: the same (source, target) pair + // keeps the more specific edge — the one that says which tier it crosses. + { name: 'tierEdges', gate: (has) => has(...JS_FAMILY), run: (_q, c, y) => crossTierEdges(c, y) }, { name: 'emitterEdges', gate: ALWAYS, run: (_q, c, y) => eventEmitterEdges(c, y) }, { name: 'renderEdges', gate: ALWAYS, run: (q, c, y) => reactRenderEdges(q, c, y) }, { name: 'jsxEdges', gate: (has) => has(...JS_FAMILY), run: (_q, c, y) => reactJsxChildEdges(c, y) }, diff --git a/src/resolution/frameworks/expo-router.ts b/src/resolution/frameworks/expo-router.ts index 3195461..b2f04a9 100644 --- a/src/resolution/frameworks/expo-router.ts +++ b/src/resolution/frameworks/expo-router.ts @@ -44,6 +44,7 @@ import type { UnresolvedRef, } from '../types'; import { stripCommentsForRegex } from '../strip-comments'; +import { dependsOn } from './package-deps'; // ============================================================================= // Route files @@ -143,8 +144,8 @@ export function navVerb(name: string): string | null { /** Lines a single navigation call is allowed to span. */ const MAX_CALL_LINES = 12; -/** Placeholder for an interpolated `${…}` inside a template-literal href. */ -const HOLE = '\u0000'; +/** Placeholder for an interpolated `${…}` inside a template-literal href (shared with the cross-tier synthesizer). */ +export const HOLE = '\u0000'; /** Index of the `)` matching the `(` at `open`, skipping string bodies; -1 if unbalanced. */ function matchParen(s: string, open: number): number { @@ -573,16 +574,7 @@ export const expoRouterResolver: FrameworkResolver = { languages: [...ROUTE_LANGUAGES], detect(context: ResolutionContext): boolean { - const packageJson = context.readFile('package.json'); - if (packageJson) { - try { - const pkg = JSON.parse(packageJson); - const deps = { ...pkg.dependencies, ...pkg.devDependencies }; - if (deps['expo-router']) return true; - } catch { - // Not JSON — fall through to the layout check. - } - } + if (dependsOn(context, 'expo-router')) return true; const files = context.getAllFiles(); const hasLayout = files.some((f) => /(?:^|\/)(?:src\/)?app\/_layout\.(?:tsx|jsx|ts|js)$/.test(f)); const hasExpoConfig = files.some((f) => /^app\.(?:json|config\.(?:js|ts))$/.test(f)); diff --git a/src/resolution/frameworks/express.ts b/src/resolution/frameworks/express.ts index aff2c64..c529ba2 100644 --- a/src/resolution/frameworks/express.ts +++ b/src/resolution/frameworks/express.ts @@ -7,6 +7,8 @@ import { Node } from '../../types'; import { FrameworkResolver, UnresolvedRef, ResolvedRef, ResolutionContext } from '../types'; import { stripCommentsForRegex } from '../strip-comments'; +import { resolveImportPath } from '../import-resolver'; +import { dependsOn } from './package-deps'; function extractTailIdent(expr: string): string | null { const cleaned = expr.replace(/\s+/g, '').replace(/\(\)$/, ''); @@ -52,19 +54,8 @@ export const expressResolver: FrameworkResolver = { languages: ['javascript', 'typescript'], detect(context: ResolutionContext): boolean { - // Check for Express in package.json - const packageJson = context.readFile('package.json'); - if (packageJson) { - try { - const pkg = JSON.parse(packageJson); - const deps = { ...pkg.dependencies, ...pkg.devDependencies }; - if (deps.express || deps.fastify || deps.koa || deps.hapi) { - return true; - } - } catch { - // Invalid JSON - } - } + // Express in a package.json — the root's, or a workspace's (`backend/`, `apps/api/`). + if (dependsOn(context, 'express', 'fastify', 'koa', 'hapi', '@hapi/hapi')) return true; // Check for common Express patterns const allFiles = context.getAllFiles(); @@ -141,7 +132,7 @@ export const expressResolver: FrameworkResolver = { // Match the route head up to the first arg: (app|router).METHOD('/path', // (NOT the whole call — handlers are often inline arrows whose `)`/`{}` the // old single-regex couldn't span, so inline-handler routes connected to nothing.) - const head = /\b(app|router)\.(get|post|put|patch|delete|all|use)\s*\(\s*['"]([^'"]+)['"]\s*,/g; + const head = /\b(app|router)\s*\.\s*(get|post|put|patch|delete|all|use)\s*\(\s*['"]([^'"]+)['"]\s*,/g; let match: RegExpExecArray | null; while ((match = head.exec(safe)) !== null) { const method = match[2]!; @@ -217,10 +208,198 @@ export const expressResolver: FrameworkResolver = { } } } + // The chained form: `router.route('/:id').get(getProduct).put(protect, updateProduct)` + // — one path, several methods, each with its own handler. One route node + // per method, at the line of its `.method(`, bound like the plain form. + const chainHead = /\b(?:app|router)\s*\.\s*route\s*\(\s*['"]([^'"]+)['"]\s*\)/g; + while ((match = chainHead.exec(safe)) !== null) { + const routePath = match[1]!; + let at = match.index + match[0].length; + for (;;) { + const link = /^\s*\.\s*(get|post|put|patch|delete|all)\s*\(/.exec(safe.slice(at, at + 64)); + if (!link) break; + const openParen = at + link[0].length - 1; + const closeParen = matchDelim(safe, openParen, '(', ')'); + if (closeParen < 0) break; + const method = link[1]!; + const line = safe.slice(0, openParen).split('\n').length; + const args = safe.slice(openParen + 1, closeParen); + const routeNode: Node = { + id: `route:${filePath}:${line}:${method.toUpperCase()}:${routePath}`, + kind: 'route', + name: `${method.toUpperCase()} ${routePath}`, + qualifiedName: `${filePath}::${method.toUpperCase()}:${routePath}`, + filePath, + startLine: line, + endLine: line, + startColumn: 0, + endColumn: link[0].length, + language: lang, + updatedAt: now, + }; + nodes.push(routeNode); + if (args.includes('=>')) { + const callRe = /\b([A-Za-z_$][\w$]*)\s*\(/g; + const seen = new Set(); + let cm: RegExpExecArray | null; + while ((cm = callRe.exec(args)) !== null) { + const name = cm[1]!; + if (seen.has(name) || RESERVED_CALLS.has(name)) continue; + seen.add(name); + references.push({ fromNodeId: routeNode.id, referenceName: name, referenceKind: 'calls', line, column: 0, filePath, language: lang }); + } + } else { + const parts = splitTopLevel(args).map((s) => s.trim()).filter(Boolean); + const last = parts[parts.length - 1]; + const handlerName = last ? extractTailIdent(last) : null; + if (handlerName) { + references.push({ fromNodeId: routeNode.id, referenceName: handlerName, referenceKind: 'references', line, column: 0, filePath, language: lang }); + } + } + at = closeParen + 1; + } + } return { nodes, references }; }, + + /** + * Cross-file finalization for mounts. A router's routes are written + * relative to where it is mounted — + * + * app.use('/api', routes) // app.js + * router.use('/users', usersRouter) // routes/index.js + * router.post('/', createUser) // routes/users.js → POST /api/users + * + * — and per-file `extract()` can only see `POST /`. This pass reads every + * `X.use('/prefix', …, router)` whose last argument names a router file + * (an import, or an inline `require('./x')`), composes the prefixes down + * the mount tree, and renames the routes of each mounted file to the path + * a request actually takes. A file mounted at two different prefixes is + * left alone: one name cannot be two paths. + * + * The route node's `id` and `qualifiedName` are preserved (`qualifiedName` + * still encodes the in-file `METHOD:path`), so the pass is idempotent on + * every sync, exactly as the NestJS `RouterModule` pass is. + */ + postExtract(context: ResolutionContext): Node[] { + const files = context.getAllFiles().filter((f) => /\.(m?js|tsx?|cjs)$/.test(f)); + const mounts = new Map>(); + for (const file of files) { + const content = context.readFile(file); + if (!content || !content.includes('.use(')) continue; + const lang = detectLanguage(file); + const safe = stripCommentsForRegex(content, lang); + const mount = /\b[A-Za-z_$][\w$]*\.use\s*\(\s*(['"`])(\/[^'"`]*)\1\s*,/g; + let m: RegExpExecArray | null; + while ((m = mount.exec(safe)) !== null) { + const open = safe.indexOf('(', m.index); + const close = open >= 0 ? matchDelim(safe, open, '(', ')') : -1; + if (close < 0) continue; + const args = splitTopLevel(safe.slice(open + 1, close)); + const last = args[args.length - 1]?.trim() ?? ''; + const target = mountTarget(last, safe, file, lang, context); + if (!target || target === file) continue; + const list = mounts.get(file) ?? []; + list.push({ prefix: m[2]!, target }); + mounts.set(file, list); + } + } + if (mounts.size === 0) return []; + + // Compose prefixes down the mount tree until nothing changes; a file + // reached at two different paths is ambiguous and dropped. + let prefixOf = new Map(); + for (let round = 0; round < 8; round++) { + const next = new Map(); + const ambiguous = new Set(); + for (const [file, list] of mounts) { + const base = prefixOf.get(file) ?? ''; + for (const { prefix, target } of list) { + const full = joinPaths(base, prefix); + const seen = next.get(target); + if (seen !== undefined && seen !== full) ambiguous.add(target); + else next.set(target, full); + } + } + for (const a of ambiguous) next.delete(a); + let changed = next.size !== prefixOf.size; + if (!changed) for (const [k, v] of next) if (prefixOf.get(k) !== v) changed = true; + prefixOf = next; + if (!changed) break; + } + + const updates: Node[] = []; + for (const [file, prefix] of prefixOf) { + if (prefix === '' || prefix === '/') continue; + for (const route of context.getNodesInFile(file)) { + if (route.kind !== 'route') continue; + const sep = route.qualifiedName.indexOf('::'); + if (sep < 0) continue; + const colon = route.qualifiedName.indexOf(':', sep + 2); + if (colon < 0) continue; + const method = route.qualifiedName.slice(sep + 2, colon); + const original = route.qualifiedName.slice(colon + 1); + if (!original.startsWith('/')) continue; + const name = `${method} ${joinPaths(prefix, original)}`; + if (name !== route.name) updates.push({ ...route, name }); + } + } + return updates; + }, }; +/** Top-level comma split of an argument list, strings and brackets respected. */ +function splitTopLevel(args: string): string[] { + const out: string[] = []; + let depth = 0; + let start = 0; + for (let i = 0; i < args.length; i++) { + const ch = args[i]; + if (ch === '"' || ch === "'" || ch === '`') { + const q = ch; + i++; + while (i < args.length && args[i] !== q) { + if (args[i] === '\\') i++; + i++; + } + continue; + } + if (ch === '(' || ch === '[' || ch === '{') depth++; + else if (ch === ')' || ch === ']' || ch === '}') depth--; + else if (ch === ',' && depth === 0) { + out.push(args.slice(start, i)); + start = i + 1; + } + } + out.push(args.slice(start)); + return out; +} + +/** `/api` + `/users` → `/api/users`; `/api/` + `/` → `/api`. */ +function joinPaths(prefix: string, path: string): string { + const a = prefix.replace(/\/+$/, ''); + const b = path.replace(/^\/+/, ''); + const joined = b ? `${a}/${b}` : a; + return joined === '' ? '/' : joined; +} + +/** + * The file a mount's last argument names: an inline `require('./x')`, an + * identifier imported from a project file, or one bound to `require('./x')` + * in the same file. `x.default` / `x.router` count as `x`. + */ +function mountTarget(expr: string, safe: string, file: string, lang: 'typescript' | 'javascript', context: ResolutionContext): string | null { + const inline = /^require\s*\(\s*(['"])([^'"]+)\1\s*\)(?:\.\w+)?$/.exec(expr); + if (inline) return resolveImportPath(inline[2]!, file, lang, context); + const ident = /^([A-Za-z_$][\w$]*)(?:\.(?:default|router|routes))?$/.exec(expr); + if (!ident) return null; + const name = ident[1]!; + const mapping = context.getImportMappings(file, lang).find((im) => im.localName === name); + if (mapping) return resolveImportPath(mapping.source, file, lang, context); + const required = new RegExp(`\\b(?:const|let|var)\\s+${name.replace(/\$/g, '\\$')}\\s*=\\s*require\\s*\\(\\s*(['"])([^'"]+)\\1\\s*\\)`).exec(safe); + return required ? resolveImportPath(required[2]!, file, lang, context) : null; +} + /** * Check if a name looks like middleware */ diff --git a/src/resolution/frameworks/nestjs.ts b/src/resolution/frameworks/nestjs.ts index 2b52b24..6ea13f5 100644 --- a/src/resolution/frameworks/nestjs.ts +++ b/src/resolution/frameworks/nestjs.ts @@ -30,6 +30,7 @@ import { ResolutionContext, } from '../types'; import { stripCommentsForRegex } from '../strip-comments'; +import { declaredDependencies } from './package-deps'; // --------------------------------------------------------------------------- // Public surface — see comment at top of file. This file owns four NestJS @@ -47,19 +48,9 @@ export const nestjsResolver: FrameworkResolver = { languages: ['typescript', 'javascript'], detect(context: ResolutionContext): boolean { - // Primary, fast path: any @nestjs/* dependency in package.json. - const packageJson = context.readFile('package.json'); - if (packageJson) { - try { - const pkg = JSON.parse(packageJson); - const deps = { ...pkg.dependencies, ...pkg.devDependencies }; - if (Object.keys(deps).some((k) => k.startsWith('@nestjs/'))) { - return true; - } - } catch { - // Invalid JSON — fall through to the source scan. - } - } + // Primary, fast path: any @nestjs/* dependency in a package.json — the + // root's, or a workspace's (`apps/api/`, `server/`). + for (const name of declaredDependencies(context)) if (name.startsWith('@nestjs/')) return true; // Fallback: NestJS-specific decorators in conventionally named files. const allFiles = context.getAllFiles(); diff --git a/src/resolution/frameworks/package-deps.ts b/src/resolution/frameworks/package-deps.ts new file mode 100644 index 0000000..2e49ec1 --- /dev/null +++ b/src/resolution/frameworks/package-deps.ts @@ -0,0 +1,47 @@ +/** + * The dependencies a project declares — in its root `package.json` and in + * the ones one or two directories down (`apps/web/package.json`, + * `frontend/package.json`, `packages/api/package.json`). A framework detector + * that reads only the root misses every monorepo: proshop keeps `react` in + * `frontend/`, a Turborepo keeps `next` in `apps/web/`, and the resolver for + * that framework then never runs, so its routes never exist. + */ + +import type { ResolutionContext } from '../types'; + +/** Nested manifests read per project, at most — a monorepo with hundreds of packages is sampled, not scanned. */ +const MAX_MANIFESTS = 24; + +const cache = new WeakMap>(); + +/** Every dependency name declared at the root or up to two directories down, de-duplicated. */ +export function declaredDependencies(context: ResolutionContext): Set { + const cached = cache.get(context); + if (cached) return cached; + const names = new Set(); + const manifests = ['package.json']; + for (const file of context.getAllFiles()) { + if (manifests.length > MAX_MANIFESTS) break; + if (/^(?:[^/]+\/){1,2}package\.json$/.test(file) && !file.includes('node_modules/')) manifests.push(file); + } + for (const manifest of manifests) { + const content = context.readFile(manifest); + if (!content) continue; + try { + const pkg = JSON.parse(content) as { dependencies?: Record; devDependencies?: Record; peerDependencies?: Record }; + for (const group of [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies]) { + if (group && typeof group === 'object') for (const name of Object.keys(group)) names.add(name); + } + } catch { + // Not JSON — a template, a broken manifest; nothing to read. + } + } + cache.set(context, names); + return names; +} + +/** True when any of `deps` is declared anywhere the project's manifests are read. */ +export function dependsOn(context: ResolutionContext, ...deps: string[]): boolean { + const names = declaredDependencies(context); + return deps.some((d) => names.has(d)); +} diff --git a/src/resolution/frameworks/react.ts b/src/resolution/frameworks/react.ts index 13001c3..a871253 100644 --- a/src/resolution/frameworks/react.ts +++ b/src/resolution/frameworks/react.ts @@ -6,6 +6,7 @@ import { Node } from '../../types'; import { FrameworkResolver, UnresolvedRef, ResolvedRef, ResolutionContext } from '../types'; +import { dependsOn } from './package-deps'; export const reactResolver: FrameworkResolver = { name: 'react', @@ -17,19 +18,8 @@ export const reactResolver: FrameworkResolver = { languages: ['javascript', 'typescript', 'tsx', 'jsx'], detect(context: ResolutionContext): boolean { - // Check for React in package.json - const packageJson = context.readFile('package.json'); - if (packageJson) { - try { - const pkg = JSON.parse(packageJson); - const deps = { ...pkg.dependencies, ...pkg.devDependencies }; - if (deps.react || deps.next || deps['react-native']) { - return true; - } - } catch { - // Invalid JSON - } - } + // React in a package.json — the root's, or a workspace's (`frontend/`, `apps/web/`). + if (dependsOn(context, 'react', 'next', 'react-native')) return true; // Check for .jsx/.tsx files const allFiles = context.getAllFiles(); diff --git a/src/resolution/synth-utils.ts b/src/resolution/synth-utils.ts new file mode 100644 index 0000000..4e60f21 --- /dev/null +++ b/src/resolution/synth-utils.ts @@ -0,0 +1,67 @@ +/** + * Small helpers the dynamic-edge synthesizers share: a per-match line + * resolver over one source string, and "the function this line is in". + */ + +import type { Node } from '../types'; + +/** The kinds a call site can be attributed to. */ +export const FN_KINDS: ReadonlySet = new Set(['method', 'function', 'component']); + +/** + * Per-match line resolver over `src`, 1-based at `baseLine`. The inline + * `src.slice(0, idx).split('\n').length` idiom is O(source-length) PER MATCH, + * which goes quadratic on a match-dense source (a generated function full of + * `.push(` calls re-scanned tens of thousands of times was most of the #1235 + * indexing wedge). Builds the newline index once — lazily, since most sources + * never produce a match — then answers each call with a binary search. + */ +export function makeLineAt(src: string, baseLine: number): (idx: number) => number { + let nl: number[] | null = null; + return (idx: number) => { + if (!nl) { + nl = []; + for (let i = src.indexOf('\n'); i !== -1; i = src.indexOf('\n', i + 1)) nl.push(i); + } + // Count newlines strictly before idx. + let lo = 0; + let hi = nl.length; + while (lo < hi) { + const mid = (lo + hi) >> 1; + if (nl[mid]! < idx) lo = mid + 1; + else hi = mid; + } + return baseLine + lo; + }; +} + +/** Innermost function/method node whose line range contains `line`. */ +export function enclosingFn(nodesInFile: readonly Node[], line: number): Node | null { + let best: Node | null = null; + for (const n of nodesInFile) { + if (!FN_KINDS.has(n.kind)) continue; + const end = n.endLine ?? n.startLine; + if (n.startLine <= line && end >= line) { + if (!best || n.startLine >= best.startLine) best = n; // prefer the tightest (latest-starting) encloser + } + } + return best; +} + +/** + * The smallest `constant` / `variable` node whose lines contain `line` — the + * value a top-level registration is written inside (`const worker = new + * Worker('q', async (job) => …)`): what a caller imports and a walk can start + * from when no function encloses the site. + */ +export function enclosingValue(nodesInFile: readonly Node[], line: number): Node | null { + let best: Node | null = null; + for (const n of nodesInFile) { + if (n.kind !== 'constant' && n.kind !== 'variable') continue; + const end = n.endLine ?? n.startLine; + if (n.startLine <= line && end >= line) { + if (!best || n.startLine >= best.startLine) best = n; + } + } + return best; +} diff --git a/src/resolution/tier-synthesizer.ts b/src/resolution/tier-synthesizer.ts new file mode 100644 index 0000000..149dd1c --- /dev/null +++ b/src/resolution/tier-synthesizer.ts @@ -0,0 +1,938 @@ +/** + * Cross-tier channels — the web's equivalent of the React Native bridge. + * + * A web app is two programs that talk over a wire the graph cannot see: the + * page calls `fetch('/api/users', { method: 'POST' })` and the API's + * `app.post('/api/users', createUser)` answers; a service puts `'welcome'` on + * the `email` queue and a `@Process('welcome')` method picks it up; a + * gateway's `this.server.emit('message')` lands in the component that wrote + * `socket.on('message', …)`. Each hop is a string on both sides, which is the + * evidence that lets a synthesizer close it — exactly as the RN event channel + * pairs `sendEvent(withName: "x")` with `addListener('x')`. + * + * Three channels, one scan: + * + * 1. **`http-client`** — a literal path in a client call (`fetch`, `axios.post`, + * `ky`, `got`, `$fetch`, `useFetch`, `useSWR`, or a project instance made by + * `axios.create(…)` / `ky.extend(…)`) → the ONE route node `METHOD path` it + * denotes. Template holes match a `:param`; a hole in front of the path + * (`${API_URL}/users`) matches a route by its tail; a variable url, a path + * no route serves, or a path two routes serve alike produce nothing. + * Edge: enclosing function → route, `tier: 'client→server'`. + * 2. **`queue-job`** — `queue.add('job', …)` where the queue is named (`new + * Queue('email')`, `@InjectQueue('email')`) → the `@Process('job')` method + * of the `@Processor('email')` class, a WorkerHost's `process`, a + * `new Worker('email', handler)`, or Bull's `queue.process('job', handler)`. + * 3. **`event-bus`** — `eventEmitter.emit('user.created')` → `@OnEvent('user.created')` + * (globs honoured); and sockets in both directions: a client's + * `socket.emit('x')` → the server's `@SubscribeMessage('x')` / `socket.on('x')` + * (`tier: 'client→server'`), the server's `server.emit('x')` → the client's + * `socket.on('x', …)` (`tier: 'server→client'`). The in-process + * `.on('x', fn)` ↔ `.emit('x')` pairing stays the emitter pass's. + * + * Every edge is `kind: 'calls'`, `provenance: 'heuristic'`, and carries + * `synthesizedBy`, `channel` (`http` | `queue` | `event` | `socket`), the + * `tier` when the direction is known, the `event` / `queue` / `method` / + * `href` it was paired on, and `registeredAt` — the route registration, the + * decorator, the `.on` — so a reader can check the pairing. Fan-out is capped + * per event as the emitter pass caps it; an HTTP pairing needs no cap because + * it is exact. Test suites and generated files are never sources: a supertest + * call is the test's story, and forty of them would make the route a hub. + */ + +import type { Edge, Language, Node } from '../types'; +import type { ResolutionContext } from './types'; +import type { MaybeYield } from './cooperative-yield'; +import { stripCommentsForRegex } from './strip-comments'; +import { resolveImportPath } from './import-resolver'; +import { isGeneratedFile } from '../extraction/generated-detection'; +import { isTestPath } from '../search/query-utils'; +import { HOLE, readStringAt } from './frameworks/expo-router'; +import { enclosingFn, enclosingValue, makeLineAt } from './synth-utils'; + +const JS_FILE = /\.(?:[cm]?[jt]sx?)$/; + +/** Events with more handlers or dispatchers than this are too generic to pair without type information. */ +const EVENT_FANOUT_CAP = 6; + +const HTTP_VERBS: ReadonlySet = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'ALL', 'ANY']); + +export const TIER_CLIENT_TO_SERVER = 'client→server'; +export const TIER_SERVER_TO_CLIENT = 'server→client'; + +// ============================================================================= +// Source reading +// ============================================================================= + +/** Index just past the `)` that closes the `(` at `open`, skipping strings; -1 if unbalanced. */ +function closeParen(s: string, open: number): number { + let depth = 0; + for (let i = open; i < s.length; i++) { + const ch = s[i]; + if (ch === '"' || ch === "'") { + const q = ch; + i++; + while (i < s.length && s[i] !== q) { + if (s[i] === '\\') i++; + i++; + } + continue; + } + if (ch === '`') { + i = templateEnd(s, i); + continue; + } + if (ch === '(') depth++; + else if (ch === ')') { + depth--; + if (depth === 0) return i; + } + } + return -1; +} + +/** Index of the backtick closing the template opening at `open`. */ +function templateEnd(s: string, open: number): number { + let i = open + 1; + while (i < s.length) { + const ch = s[i]; + if (ch === '\\') { + i += 2; + continue; + } + if (ch === '`') return i; + if (ch === '$' && s[i + 1] === '{') { + let depth = 0; + for (i = i + 1; i < s.length; i++) { + if (s[i] === '{') depth++; + else if (s[i] === '}') { + depth--; + if (depth === 0) break; + } else if (s[i] === '`') i = templateEnd(s, i); + } + } + i++; + } + return s.length; +} + +/** The arguments of the call whose `(` is at `open`, split at depth-0 commas. */ +function argumentsAt(s: string, open: number): string[] | null { + const close = closeParen(s, open); + if (close < 0) return null; + const inner = s.slice(open + 1, close); + const out: string[] = []; + let depth = 0; + let start = 0; + for (let i = 0; i < inner.length; i++) { + const c = inner[i]; + if (c === '"' || c === "'") { + const q = c; + i++; + while (i < inner.length && inner[i] !== q) { + if (inner[i] === '\\') i++; + i++; + } + continue; + } + if (c === '`') { + i = templateEnd(inner, i); + continue; + } + if (c === '(' || c === '[' || c === '{') depth++; + else if (c === ')' || c === ']' || c === '}') depth--; + else if (c === ',' && depth === 0) { + out.push(inner.slice(start, i)); + start = i + 1; + } + } + out.push(inner.slice(start)); + return out.map((a) => a.trim()).filter((a, i) => a.length > 0 || i === 0); +} + +/** The first string literal in `text`, holes kept; null when it opens with anything else. */ +function leadingString(text: string): string | null { + const t = text.trim().replace(/^\(\s*/, ''); + // `new URL('/x', base)` — the path is the first argument of the URL. + const url = /^new\s+URL\s*\(/.exec(t); + if (url) { + const args = argumentsAt(t, url[0].length - 1); + return args && args[0] ? leadingString(args[0]) : null; + } + if (t[0] === '"' || t[0] === "'" || t[0] === '`') return readStringAt(t, 0); + return null; +} + +/** `method: 'POST'` inside an options object / config, upper-cased; null when absent or computed. */ +function methodIn(text: string): string | null { + const m = /\bmethod\s*:\s*(['"`])([A-Za-z]+)\1/.exec(text); + return m ? m[2]!.toUpperCase() : null; +} + +/** The first string literal anywhere in a decorator's arguments (`'x'`, `{ name: 'x' }`). */ +function firstLiteral(args: string): string | null { + const m = /(['"`])([^'"`]+)\1/.exec(args); + return m ? m[2]! : null; +} + +/** Every string literal in a decorator's arguments, for `@OnEvent(['a', 'b'])`. */ +function allLiterals(args: string): string[] { + const out: string[] = []; + const re = /(['"`])([^'"`]+)\1/g; + let m: RegExpExecArray | null; + while ((m = re.exec(args)) !== null) out.push(m[2]!); + return out; +} + +/** + * The name of the method a decorator sits on: skip further stacked decorators + * and modifiers after the decorator's `)`, then take the identifier before `(`. + */ +function methodNameAfter(safe: string, from: number): { name: string; index: number } | null { + let i = from; + const ws = /\s*/y; + const deco = /@[\w.]+/y; + const modifier = /(?:public|private|protected|async|static|readonly|override)\b/y; + const ident = /([A-Za-z_$][\w$]*)\s*[<(]/y; + const eat = (): void => { + ws.lastIndex = i; + if (ws.exec(safe)) i = ws.lastIndex; + }; + for (;;) { + eat(); + if (safe[i] !== '@') break; + deco.lastIndex = i; + if (!deco.exec(safe)) break; + i = deco.lastIndex; + eat(); + if (safe[i] === '(') { + const close = closeParen(safe, i); + if (close < 0) return null; + i = close + 1; + } + } + for (;;) { + eat(); + modifier.lastIndex = i; + if (modifier.exec(safe) && modifier.lastIndex > i) { + i = modifier.lastIndex; + continue; + } + break; + } + eat(); + ident.lastIndex = i; + const m = ident.exec(safe); + return m ? { name: m[1]!, index: i } : null; +} + +/** Every `@Name(` decorator in `safe` with its arguments and where it ends. */ +function decorators(safe: string, name: string): Array<{ args: string; index: number; end: number }> { + const out: Array<{ args: string; index: number; end: number }> = []; + const re = new RegExp(`@${name}\\s*\\(`, 'g'); + let m: RegExpExecArray | null; + while ((m = re.exec(safe)) !== null) { + const open = m.index + m[0].length - 1; + const close = closeParen(safe, open); + if (close < 0) continue; + out.push({ args: safe.slice(open + 1, close), index: m.index, end: close + 1 }); + re.lastIndex = close + 1; + } + return out; +} + +// ============================================================================= +// Per-file facts, read once +// ============================================================================= + +interface FileFacts { + file: string; + safe: string; + nodes: Node[]; + lineOf: (idx: number) => number; + /** The 0-based column of an index on its line — where the site reader looks for the call. */ + columnOf: (idx: number) => number; + /** Lines a framework resolver made a route node on — registrations, never client calls. */ + routeLines: Set; + /** Local names bound to an HTTP client instance, with their literal base URL when written. */ + clients: Map; + /** The module's default export is a client instance. */ + defaultClient: { baseURL: string | null } | null; + /** Local names bound to a named queue (`new Queue('email')`, `@InjectQueue('email') x`). */ + queues: Map; + /** The file holds a socket server (a gateway, `io.on('connection')`, `new Server(…)`). */ + socketServer: boolean; +} + +const CLIENT_FACTORY = + /\b(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=;]*?)?=\s*(?:await\s+)?(?:(?:axios|ky|got|ofetch|\$fetch|wretch|redaxios)\s*\.\s*(?:create|extend)|new\s+Axios|wretch)\s*\(/g; +const DEFAULT_CLIENT_FACTORY = /\bexport\s+default\s+(?:(?:axios|ky|got|ofetch|\$fetch|wretch|redaxios)\s*\.\s*(?:create|extend)|new\s+Axios|wretch)\s*\(/; +const QUEUE_BINDING = + /\b(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=;]*?)?=\s*(?:new\s+)?(?:Queue|Bull|BullQueue)\s*(?:<[^>]*>)?\s*\(\s*(['"`])([^'"`]+)\2/g; +const INJECT_QUEUE = /@InjectQueue\s*\(\s*(['"`])([^'"`]+)\1\s*\)\s*(?:(?:private|public|protected|readonly)\s+)*([A-Za-z_$][\w$]*)/g; +const SOCKET_SERVER_FILE = /@WebSocketGateway\s*\(|@SubscribeMessage\s*\(|@WebSocketServer\s*\(|\bnew\s+(?:Server|SocketIOServer|WebSocketServer|WebSocket\.Server|WSServer)\b|\.on\s*\(\s*['"]connection['"]/; + +function baseUrlIn(safe: string, open: number): string | null { + const args = argumentsAt(safe, open); + const config = args?.[0] ?? ''; + const m = /\b(?:baseURL|baseUrl|prefixUrl|baseURI)\s*:\s*/.exec(config); + if (!m) return null; + return readStringAt(config, m.index + m[0].length); +} + +function readFacts(ctx: ResolutionContext, file: string): FileFacts | null { + const content = ctx.readFile(file); + if (!content) return null; + const safe = stripCommentsForRegex(content, 'typescript'); + const nodes = ctx.getNodesInFile(file); + const routeLines = new Set(); + for (const n of nodes) if (n.kind === 'route') routeLines.add(n.startLine); + const clients = new Map(); + CLIENT_FACTORY.lastIndex = 0; + let m: RegExpExecArray | null; + while ((m = CLIENT_FACTORY.exec(safe)) !== null) { + clients.set(m[1]!, { baseURL: baseUrlIn(safe, m.index + m[0].length - 1) }); + } + const dm = DEFAULT_CLIENT_FACTORY.exec(safe); + const defaultClient = dm ? { baseURL: baseUrlIn(safe, dm.index + dm[0].length - 1) } : null; + const queues = new Map(); + QUEUE_BINDING.lastIndex = 0; + while ((m = QUEUE_BINDING.exec(safe)) !== null) queues.set(m[1]!, m[3]!); + INJECT_QUEUE.lastIndex = 0; + while ((m = INJECT_QUEUE.exec(safe)) !== null) queues.set(m[3]!, m[2]!); + return { + file, + safe, + nodes, + lineOf: makeLineAt(safe, 1), + columnOf: (idx: number) => idx - (safe.lastIndexOf('\n', idx - 1) + 1), + routeLines, + clients, + defaultClient, + queues, + socketServer: SOCKET_SERVER_FILE.test(safe), + }; +} + +/** Facts for the file a local name is imported from, when the import resolves to a project file. */ +function importedFacts( + ctx: ResolutionContext, + facts: FileFacts, + localName: string, + cache: Map +): { facts: FileFacts; exportedName: string; isDefault: boolean } | null { + const lang: Language = facts.file.endsWith('x') ? 'tsx' : 'typescript'; + const im = ctx.getImportMappings(facts.file, lang).find((i) => i.localName === localName); + if (!im) return null; + // The mappings name the module as written; the file it is comes from the + // same resolution the import resolver uses (aliases, extensions, index files). + const resolved = im.resolvedPath ?? resolveImportPath(im.source, facts.file, lang, ctx); + if (!resolved) return null; + let target = cache.get(resolved); + if (target === undefined) { + target = JS_FILE.test(resolved) ? readFacts(ctx, resolved) : null; + cache.set(resolved, target); + } + return target ? { facts: target, exportedName: im.exportedName, isDefault: im.isDefault } : null; +} + +// ============================================================================= +// 1. HTTP client → route +// ============================================================================= + +/** A receiver that is an HTTP client by name alone. */ +const CLIENT_NAMES = + /^(?:axios|ky|got|superagent|http|https|httpClient|httpService|api|apiClient|client|restClient|request|agent|fetcher|instance|\$api|\$http|\$axios|axiosInstance|Axios|HttpClient|backend|server)$/; +/** A receiver that registers routes, never a client — unless it was made by a client factory. */ +const SERVER_NAMES = /^(?:app|router|route|routes|express|fastify|koa|hono|elysia|apiRouter|v1|v2|r)$/; +const BARE_CLIENT_CALL = /(?:(?:window|globalThis|global)\s*\.\s*)?\b(fetch|\$fetch|ofetch|axios|ky|got|useFetch|useSWR)\s*\(/g; +const MEMBER_CLIENT_CALL = /((?:this\s*\.\s*)?[A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)*)\s*\.\s*(get|post|put|patch|delete|head|options|request|\$get|\$post|\$put|\$patch|\$delete)\s*\(/g; + +interface HttpRoute { + node: Node; + method: string; + segs: string[]; +} + +interface HttpSite { + fn: Node; + file: string; + line: number; + column: number; + /** The call as written, `fetch` / `api.get` — what the Steps walk must not also draw as an effect. */ + callee: string; + method: string; + segs: string[]; + /** The path began with a hole — a base URL — and matches a route by its tail. */ + suffix: boolean; + display: string; +} + +function httpRoutes(ctx: ResolutionContext): HttpRoute[] { + const out: HttpRoute[] = []; + for (const node of ctx.getNodesByKind('route')) { + const space = node.name.indexOf(' '); + if (space <= 0) continue; + const method = node.name.slice(0, space).toUpperCase(); + if (!HTTP_VERBS.has(method)) continue; + const path = node.name.slice(space + 1).trim(); + if (!path.startsWith('/')) continue; + out.push({ node, method, segs: path.split('/').filter((s) => s.length > 0) }); + } + return out; +} + +const PARAM_SEG = /^(?::|\{|\[|<|\*)|\?$/; +const CATCH_ALL = /^(?:\*|\[\.\.\.|\{\*|:[\w$]+\*$|\{[\w$]+:\*\}|\*[\w$]*$)/; + +/** How well the client's segments match a route's; null when they do not. A literal match beats a parameter's. */ +function scorePath(client: readonly string[], route: readonly string[]): number | null { + let score = 0; + let i = 0; + for (let r = 0; r < route.length; r++) { + const seg = route[r]!; + if (CATCH_ALL.test(seg)) { + if (i >= client.length) return null; + score += client.length - i; + i = client.length; + continue; + } + if (i >= client.length) return null; + const c = client[i]!; + // A hole (`${id}`) fills a route's parameter; it never stands in for a + // literal segment — `/api/products/${id}` is not `/api/products/top`. + if (PARAM_SEG.test(seg)) score += 2; + else if (c === seg) score += 3; + else return null; + i++; + } + return i === client.length ? score : null; +} + +function matchHttp(site: HttpSite, routes: readonly HttpRoute[]): HttpRoute | null { + let best: HttpRoute | null = null; + let bestScore = -1; + let tied = false; + for (const r of routes) { + if (r.method !== 'ALL' && r.method !== 'ANY' && r.method !== site.method) continue; + let score: number | null; + if (site.suffix) { + // A base URL hides a prefix the route may spell out (`${API}/users` for + // `GET /api/users`) — but a one-segment tail names half the routes in + // an index, and a long hidden prefix is a different API. Two segments + // of tail at least, two of prefix at most. + if (site.segs.length < 2 || r.segs.length < site.segs.length || r.segs.length - site.segs.length > 2) continue; + score = scorePath(site.segs, r.segs.slice(r.segs.length - site.segs.length)); + } else score = scorePath(site.segs, r.segs); + if (score === null) continue; + if (score > bestScore) { + best = r; + bestScore = score; + tied = false; + } else if (score === bestScore) tied = true; + } + return tied ? null : best; +} + +/** + * The path a client call names, as segments, with `${…}` as `*`; `suffix` + * when a base URL came first. Null when the path is not literal enough: a + * relative path with no base, or nothing but holes. + */ +function clientPath(raw: string, baseURL: string | null): { segs: string[]; suffix: boolean; display: string } | null { + let p = raw; + const cut = p.search(/[?#]/); + if (cut >= 0) p = p.slice(0, cut); + let suffix = false; + const absolute = /^(?:[a-z][a-z0-9+.-]*:)?\/\/[^/]*(\/.*)?$/i.exec(p); + if (absolute) p = absolute[1] ?? '/'; + else if (!p.startsWith('/')) { + if (p.startsWith(HOLE)) { + const rest = p.slice(1); + if (!rest.startsWith('/')) return null; + p = rest; + suffix = true; + } else if (baseURL !== null) { + const base = clientPath(baseURL, null); + if (!base) { + // A base that is itself a hole: match by the tail. + if (!baseURL.includes(HOLE)) return null; + suffix = true; + p = '/' + p; + } else { + suffix = base.suffix; + p = '/' + [...base.segs, ...p.split('/')].filter(Boolean).join('/'); + } + } else return null; + } else if (baseURL !== null) { + // An instance with a literal path base: axios joins `baseURL + url`. + const base = clientPath(baseURL, null); + if (base && base.segs.length > 0) { + suffix = base.suffix; + p = '/' + [...base.segs, ...p.split('/')].filter(Boolean).join('/'); + } else if (!base && baseURL.includes(HOLE)) suffix = true; + } + const segs = p + .split('/') + .filter((s) => s.length > 0) + .map((s) => (s.includes(HOLE) ? '*' : s)); + if (segs.length > 0 && segs.every((s) => s === '*')) return null; + return { segs, suffix, display: '/' + segs.map((s) => (s === '*' ? '${…}' : s)).join('/') }; +} + +/** What a member-call receiver is: a client (with its base URL), or nothing. */ +function clientFor( + ctx: ResolutionContext, + facts: FileFacts, + receiver: string, + cache: Map +): { baseURL: string | null } | null { + const chain = receiver.replace(/\s+/g, '').replace(/^this\./, '').split('.'); + const head = chain[0]!; + const last = chain[chain.length - 1]!; + const local = facts.clients.get(head); + if (local) return local; + const imported = importedFacts(ctx, facts, head, cache); + if (imported) { + const bound = imported.isDefault ? imported.facts.defaultClient : imported.facts.clients.get(imported.exportedName) ?? null; + if (bound) return bound; + } + if (SERVER_NAMES.test(last) || SERVER_NAMES.test(head)) return null; + if (CLIENT_NAMES.test(last)) return { baseURL: null }; + return null; +} + +function collectHttpSites(ctx: ResolutionContext, facts: FileFacts, sites: HttpSite[], cache: Map): void { + const { safe, nodes, lineOf } = facts; + const add = (index: number, open: number, verb: string | null, baseURL: string | null): void => { + const line = lineOf(index); + const callee = safe.slice(index, open).replace(/\s+/g, ''); + if (facts.routeLines.has(line)) return; // a registration the resolver already read + const fn = enclosingFn(nodes, line); + if (!fn) return; + const args = argumentsAt(safe, open); + if (!args || !args[0]) return; + let first = args[0]; + let method = verb; + // `axios({ url, method })`, `.request({ url, method })`, `ky(url, { method })`. + if (first.trimStart().startsWith('{')) { + const url = /\burl\s*:\s*/.exec(first); + if (!url) return; + method = method ?? methodIn(first) ?? 'GET'; + first = first.slice(url.index + url[0].length); + } else if (method === null) { + method = methodIn(args.slice(1).join(',')) ?? 'GET'; + } + const literal = leadingString(first); + if (literal === null) return; + const path = clientPath(literal, baseURL); + if (!path) return; + sites.push({ fn, file: facts.file, line, column: facts.columnOf(index), callee, method, segs: path.segs, suffix: path.suffix, display: path.display }); + }; + + BARE_CLIENT_CALL.lastIndex = 0; + let m: RegExpExecArray | null; + while ((m = BARE_CLIENT_CALL.exec(safe)) !== null) { + // `this.fetch(…)` / `repo.fetch(…)` is a project method, not the platform's. + const before = safe[m.index - 1]; + if (before === '.' && !/^(?:window|globalThis|global)\s*\./.test(m[0])) continue; + add(m.index, m.index + m[0].length - 1, null, null); + } + MEMBER_CLIENT_CALL.lastIndex = 0; + while ((m = MEMBER_CLIENT_CALL.exec(safe)) !== null) { + const client = clientFor(ctx, facts, m[1]!, cache); + if (!client) continue; + const verb = m[2]!.replace(/^\$/, '').toUpperCase(); + add(m.index, m.index + m[0].length - 1, verb === 'REQUEST' ? null : verb, client.baseURL); + } +} + +// ============================================================================= +// 2. Queue job → consumer +// ============================================================================= + +const QUEUE_ADD = /((?:this\s*\.\s*)?[A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)*)\s*\.\s*add\s*\(\s*(['"`])([^'"`]+)\2/g; +const QUEUE_SHAPED = /queue|jobs?$|worker|bull|flow|producer/i; +const NEW_WORKER = /\bnew\s+Worker\s*(?:<[^>]*>)?\s*\(\s*(['"`])([^'"`]+)\1\s*,\s*/g; +const QUEUE_PROCESS = /((?:this\s*\.\s*)?[A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)*)\s*\.\s*process\s*\(\s*(?:(['"`])([^'"`]+)\2\s*,\s*)?(?:\d+\s*,\s*)?/g; +/** A handler argument: a named function (group 1), or an inline function. */ +const HANDLER_ARG = /^(?:(?:async\s+)?([A-Za-z_$][\w$.]*)\s*(?:[,)]|$)|(?:async\s*)?(?:\(|function\b|[A-Za-z_$][\w$]*\s*=>))/; + +interface QueueProducer { + fn: Node; + file: string; + line: number; + column: number; + callee: string; + queue: string | null; + job: string; +} + +interface QueueConsumer { + node: Node; + file: string; + line: number; + queue: string | null; + /** Null: every job on the queue (`@Process()` with no name, a WorkerHost's `process`, `new Worker`). */ + job: string | null; +} + +/** The queue a receiver is bound to, by its binding in this file or the file it is imported from. */ +function queueFor(ctx: ResolutionContext, facts: FileFacts, receiver: string, cache: Map): string | null { + const chain = receiver.replace(/\s+/g, '').replace(/^this\./, '').split('.'); + const head = chain[0]!; + const own = facts.queues.get(head); + if (own) return own; + const imported = importedFacts(ctx, facts, head, cache); + if (imported) { + const bound = imported.facts.queues.get(imported.exportedName); + if (bound) return bound; + } + return null; +} + +/** The function a handler argument names or encloses; null when it is neither. */ +function handlerNode(ctx: ResolutionContext, facts: FileFacts, text: string, line: number, cache: Map): Node | null { + const m = HANDLER_ARG.exec(text.trimStart()); + if (!m) return null; + if (m[1]) { + const name = m[1].split('.').pop()!; + const candidates = ctx.getNodesByName(name).filter((n) => n.kind === 'function' || n.kind === 'method'); + const local = candidates.filter((n) => n.filePath === facts.file); + if (local.length === 1) return local[0]!; + if (local.length > 1) return null; + const imported = importedFacts(ctx, facts, m[1].split('.')[0]!, cache); + if (imported) { + const viaImport = candidates.filter((n) => n.filePath === imported.facts.file); + if (viaImport.length === 1) return viaImport[0]!; + } + return candidates.length === 1 ? candidates[0]! : null; + } + return enclosingFn(facts.nodes, line) ?? enclosingValue(facts.nodes, line); +} + +/** The nearest class declared at or after `index`, as its node. */ +function classAfter(facts: FileFacts, index: number): Node | null { + const m = /\bclass\s+([A-Za-z_$][\w$]*)/g; + m.lastIndex = index; + const hit = m.exec(facts.safe); + if (!hit) return null; + const line = facts.lineOf(hit.index); + return facts.nodes.find((n) => n.kind === 'class' && n.name === hit[1] && n.startLine >= line - 2) ?? null; +} + +/** The method node a decorator at `end` sits on, inside `cls` when given. */ +function decoratedMethod(facts: FileFacts, end: number, cls: Node | null): Node | null { + const named = methodNameAfter(facts.safe, end); + if (!named) return null; + const line = facts.lineOf(named.index); + return ( + facts.nodes.find( + (n) => + (n.kind === 'method' || n.kind === 'function') && + n.name === named.name && + n.startLine >= line - 1 && + n.startLine <= line + 1 && + (!cls || (n.startLine >= cls.startLine && n.endLine <= cls.endLine)) + ) ?? null + ); +} + +function collectQueue(ctx: ResolutionContext, facts: FileFacts, producers: QueueProducer[], consumers: QueueConsumer[], cache: Map): void { + const { safe, nodes, lineOf } = facts; + let m: RegExpExecArray | null; + QUEUE_ADD.lastIndex = 0; + while ((m = QUEUE_ADD.exec(safe)) !== null) { + const receiver = m[1]!; + const queue = queueFor(ctx, facts, receiver, cache); + const last = receiver.replace(/\s+/g, '').split('.').pop()!; + if (queue === null && !QUEUE_SHAPED.test(last)) continue; + const line = lineOf(m.index); + const fn = enclosingFn(nodes, line); + if (!fn) continue; + producers.push({ fn, file: facts.file, line, column: facts.columnOf(m.index), callee: `${receiver.replace(/\s+/g, '')}.add`, queue, job: m[3]! }); + } + + // Nest: `@Processor('email')` on a class; `@Process('welcome')` on its methods, + // or a WorkerHost's `process(job)`. + for (const proc of decorators(safe, 'Processor')) { + const queue = firstLiteral(proc.args); + const cls = classAfter(facts, proc.end); + if (!cls) continue; + let any = false; + for (const job of decorators(safe, 'Process')) { + const line = lineOf(job.index); + if (line < cls.startLine || line > cls.endLine) continue; + const method = decoratedMethod(facts, job.end, cls); + if (!method) continue; + any = true; + consumers.push({ node: method, file: facts.file, line, queue, job: firstLiteral(job.args) }); + } + if (!any) { + const process = nodes.find((n) => n.kind === 'method' && n.name === 'process' && n.startLine >= cls.startLine && n.endLine <= cls.endLine); + if (process) consumers.push({ node: process, file: facts.file, line: process.startLine, queue, job: null }); + } + } + + // BullMQ: `new Worker('email', handler)`. + NEW_WORKER.lastIndex = 0; + while ((m = NEW_WORKER.exec(safe)) !== null) { + const line = lineOf(m.index); + const node = handlerNode(ctx, facts, safe.slice(m.index + m[0].length, m.index + m[0].length + 200), line, cache); + if (!node) continue; + consumers.push({ node, file: facts.file, line, queue: m[2]!, job: null }); + } + + // Bull: `queue.process('welcome', handler)` / `queue.process(handler)`. + QUEUE_PROCESS.lastIndex = 0; + while ((m = QUEUE_PROCESS.exec(safe)) !== null) { + const receiver = m[1]!; + const queue = queueFor(ctx, facts, receiver, cache); + const last = receiver.replace(/\s+/g, '').split('.').pop()!; + if (queue === null && !QUEUE_SHAPED.test(last)) continue; + const line = lineOf(m.index); + const node = handlerNode(ctx, facts, safe.slice(m.index + m[0].length, m.index + m[0].length + 200), line, cache); + if (!node) continue; + consumers.push({ node, file: facts.file, line, queue, job: m[3] ?? null }); + } +} + +function pairQueue(producers: readonly QueueProducer[], consumers: readonly QueueConsumer[], edges: Edge[], seen: Set): void { + for (const p of producers) { + let candidates = consumers.filter((c) => (p.queue === null || c.queue === null || c.queue === p.queue) && (c.job === null || c.job === p.job)); + // The most specific pairing wins: the job by name on the named queue, + // then the job by name, then the queue's default consumer. + const exact = candidates.filter((c) => c.job === p.job && c.queue === p.queue && p.queue !== null); + if (exact.length > 0) candidates = exact; + else { + const byJob = candidates.filter((c) => c.job === p.job); + if (byJob.length > 0) candidates = byJob; + else if (p.queue === null) continue; // an unnamed queue and no consumer naming the job: a guess + else candidates = candidates.filter((c) => c.queue === p.queue); + } + if (candidates.length === 0 || candidates.length > EVENT_FANOUT_CAP) continue; + for (const c of candidates) { + if (c.node.id === p.fn.id) continue; + const key = `${p.fn.id}>${c.node.id}`; + if (seen.has(key)) continue; + seen.add(key); + edges.push({ + source: p.fn.id, + target: c.node.id, + kind: 'calls', + line: p.line, + column: p.column, + provenance: 'heuristic', + metadata: { + synthesizedBy: 'queue-job', + channel: 'queue', + callee: p.callee, + event: p.job, + ...(p.queue ?? c.queue ? { queue: p.queue ?? c.queue } : {}), + registeredAt: `${c.file}:${c.line}`, + }, + }); + } + } +} + +// ============================================================================= +// 3. Events: a bus, and sockets both ways +// ============================================================================= + +const EMIT = /((?:[\w$]+(?:\([^()]*\))?\s*\.\s*)*[\w$]+)\s*\.\s*(emit|emitAsync)\s*\(\s*(['"`])([^'"`\n]+)\3/g; +const SOCKET_ON = /((?:[\w$]+(?:\([^()]*\))?\s*\.\s*)*[\w$]+)\s*\.\s*(?:on|once)\s*\(\s*(['"`])([^'"`\n]+)\2\s*,\s*/g; +const SOCKET_WORDS = /^(?:socket|io|ws|wss|client|server|namespace|nsp|conn|connection|gateway|broadcast|to|in|of|except|volatile|local|sockets|socketServer|wsServer|room|channel|pusher|ably|ioClient|socketClient|sock)$/; +const BUS_WORDS = /^(?:eventEmitter|emitter|events|eventBus|bus|dispatcher|pubsub|publisher|eventPublisher|ee|hub|mediator|broker|messageBus|appEvents|domainEvents|eventsService|eventService)$/; +/** The transport's own events — every socket emits and handles them; pairing them says nothing. */ +const GENERIC_EVENT = + /^(?:error|connect|connect_error|connect_failed|connection|disconnect|disconnecting|reconnect|reconnect_attempt|reconnecting|reconnect_error|reconnect_failed|close|open|end|data|ready|drain|finish|pipe|unpipe|listening|timeout|ping|pong|upgrade|newListener|removeListener)$/; + +interface Dispatch { + fn: Node; + file: string; + line: number; + column: number; + callee: string; + event: string; + shape: 'bus' | 'socket'; + side: 'server' | 'client'; +} + +interface Handler { + node: Node; + file: string; + line: number; + /** An event name, or an `@OnEvent` glob. */ + pattern: string; + kind: 'bus' | 'socket'; + side: 'server' | 'client'; +} + +function shapeOf(receiver: string): 'bus' | 'socket' | null { + const segs = receiver.replace(/\([^()]*\)/g, '').replace(/\s+/g, '').split('.').filter((s) => s !== 'this'); + if (segs.some((s) => SOCKET_WORDS.test(s))) return 'socket'; + if (segs.some((s) => BUS_WORDS.test(s))) return 'bus'; + return null; +} + +function collectEvents(ctx: ResolutionContext, facts: FileFacts, dispatches: Dispatch[], handlers: Handler[], cache: Map): void { + const { safe, nodes, lineOf } = facts; + const side: 'server' | 'client' = facts.socketServer ? 'server' : 'client'; + let m: RegExpExecArray | null; + EMIT.lastIndex = 0; + while ((m = EMIT.exec(safe)) !== null) { + const shape = shapeOf(m[1]!); + if (!shape || GENERIC_EVENT.test(m[4]!)) continue; + const line = lineOf(m.index); + const fn = enclosingFn(nodes, line); + if (!fn) continue; + dispatches.push({ fn, file: facts.file, line, column: facts.columnOf(m.index), callee: `${m[1]!.replace(/\s+/g, '')}.${m[2]!}`, event: m[4]!, shape, side }); + } + for (const d of decorators(safe, 'OnEvent')) { + const method = decoratedMethod(facts, d.end, null); + if (!method) continue; + const patterns = d.args.trimStart().startsWith('[') ? allLiterals(d.args) : [firstLiteral(d.args)].filter((x): x is string => x !== null); + for (const pattern of patterns) handlers.push({ node: method, file: facts.file, line: lineOf(d.index), pattern, kind: 'bus', side }); + } + for (const d of decorators(safe, 'SubscribeMessage')) { + const method = decoratedMethod(facts, d.end, null); + const event = firstLiteral(d.args); + if (!method || event === null) continue; + handlers.push({ node: method, file: facts.file, line: lineOf(d.index), pattern: event, kind: 'socket', side: 'server' }); + } + SOCKET_ON.lastIndex = 0; + while ((m = SOCKET_ON.exec(safe)) !== null) { + if (shapeOf(m[1]!) !== 'socket' || GENERIC_EVENT.test(m[3]!)) continue; + const line = lineOf(m.index); + const node = handlerNode(ctx, facts, safe.slice(m.index + m[0].length, m.index + m[0].length + 200), line, cache); + if (!node) continue; + handlers.push({ node, file: facts.file, line, pattern: m[3]!, kind: 'socket', side }); + } +} + +/** `user.*` matches one segment, `**` any; anything else is exact. */ +function eventMatches(pattern: string, event: string): boolean { + if (pattern === event) return true; + if (!pattern.includes('*')) return false; + const re = new RegExp('^' + pattern.split('**').map((part) => part.split('*').map(escapeRe).join('[^.]+')).join('.*') + '$'); + return re.test(event); +} + +function escapeRe(s: string): string { + return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); +} + +function pairEvents(dispatches: readonly Dispatch[], handlers: readonly Handler[], edges: Edge[], seen: Set): void { + // Fan-out is judged per event name on each side, as the emitter pass does. + const dispatchesByEvent = new Map(); + for (const d of dispatches) dispatchesByEvent.set(`${d.shape}:${d.event}`, [...(dispatchesByEvent.get(`${d.shape}:${d.event}`) ?? []), d]); + for (const [, group] of dispatchesByEvent) { + if (group.length > EVENT_FANOUT_CAP) continue; + for (const d of group) { + let matched: Handler[]; + let tier: string | null = null; + if (d.shape === 'bus') matched = handlers.filter((h) => h.kind === 'bus' && eventMatches(h.pattern, d.event)); + else if (d.side === 'client') { + matched = handlers.filter((h) => h.kind === 'socket' && h.side === 'server' && h.pattern === d.event); + tier = TIER_CLIENT_TO_SERVER; + } else { + matched = handlers.filter((h) => h.kind === 'socket' && h.side === 'client' && h.pattern === d.event); + tier = TIER_SERVER_TO_CLIENT; + } + if (matched.length === 0 || matched.length > EVENT_FANOUT_CAP) continue; + for (const h of matched) { + if (h.node.id === d.fn.id) continue; + const key = `${d.fn.id}>${h.node.id}`; + if (seen.has(key)) continue; + seen.add(key); + edges.push({ + source: d.fn.id, + target: h.node.id, + kind: 'calls', + line: d.line, + column: d.column, + provenance: 'heuristic', + metadata: { + synthesizedBy: 'event-bus', + channel: d.shape === 'bus' ? 'event' : 'socket', + callee: d.callee, + event: d.event, + ...(tier ? { tier } : {}), + registeredAt: `${h.file}:${h.line}`, + }, + }); + } + } + } +} + +// ============================================================================= +// The pass +// ============================================================================= + +const HTTP_GATE = /\b(?:fetch|\$fetch|ofetch|axios|ky|got|useFetch|useSWR)\s*\(|\.\s*(?:get|post|put|patch|delete|head|options|request|\$get|\$post)\s*\(/; +const QUEUE_GATE = /\.\s*add\s*\(|@Processor\s*\(|\bnew\s+Worker\s*[<(]|\.\s*process\s*\(/; +const EVENT_GATE = /\.\s*(?:emit|emitAsync|on|once)\s*\(|@OnEvent\s*\(|@SubscribeMessage\s*\(/; + +export async function crossTierEdges(ctx: ResolutionContext, onYield: MaybeYield): Promise { + const routes = httpRoutes(ctx); + const httpSites: HttpSite[] = []; + const producers: QueueProducer[] = []; + const consumers: QueueConsumer[] = []; + const dispatches: Dispatch[] = []; + const handlers: Handler[] = []; + const cache = new Map(); + + let scanned = 0; + for (const file of ctx.getAllFiles()) { + if (!JS_FILE.test(file) || isTestPath(file) || isGeneratedFile(file)) continue; + if ((++scanned & 63) === 0) await onYield(); + const content = ctx.readFile(file); + if (!content) continue; + const wantsHttp = routes.length > 0 && HTTP_GATE.test(content); + const wantsQueue = QUEUE_GATE.test(content); + const wantsEvents = EVENT_GATE.test(content); + if (!wantsHttp && !wantsQueue && !wantsEvents) continue; + let facts = cache.get(file); + if (facts === undefined) { + facts = readFacts(ctx, file); + cache.set(file, facts); + } + if (!facts) continue; + if (wantsHttp) collectHttpSites(ctx, facts, httpSites, cache); + if (wantsQueue) collectQueue(ctx, facts, producers, consumers, cache); + if (wantsEvents) collectEvents(ctx, facts, dispatches, handlers, cache); + } + + const edges: Edge[] = []; + const seen = new Set(); + for (const site of httpSites) { + const route = matchHttp(site, routes); + if (!route || route.node.id === site.fn.id) continue; + const key = `${site.fn.id}>${route.node.id}`; + if (seen.has(key)) continue; + seen.add(key); + edges.push({ + source: site.fn.id, + target: route.node.id, + kind: 'calls', + line: site.line, + column: site.column, + provenance: 'heuristic', + metadata: { + synthesizedBy: 'http-client', + channel: 'http', + callee: site.callee, + tier: TIER_CLIENT_TO_SERVER, + method: site.method, + href: site.display, + registeredAt: `${route.node.filePath}:${route.node.startLine}`, + }, + }); + } + await onYield(); + pairQueue(producers, consumers, edges, seen); + pairEvents(dispatches, handlers, edges, seen); + return edges; +} diff --git a/src/search/query-utils.ts b/src/search/query-utils.ts index de0882c..03817b8 100644 --- a/src/search/query-utils.ts +++ b/src/search/query-utils.ts @@ -332,9 +332,10 @@ export function isTestPath(filePath: string): boolean { lower.includes('/tests/') || lower.includes('/test/') || lower.includes('/__tests__/') || lower.includes('/spec/') || lower.includes('/specs/') || lower.includes('/testlib/') || - lower.includes('/testing/') || + lower.includes('/testing/') || lower.includes('/e2e/') || lower.startsWith('test/') || lower.startsWith('tests/') || lower.startsWith('spec/') || lower.startsWith('specs/') || + lower.startsWith('e2e/') || // CamelCase test source-set dirs (Kotlin Multiplatform / Gradle / Xcode): // jvmTest/, commonTest/, androidTest/, iosTest/, integrationTest/. Capital-led // so "latest/" / "manifest/" are not matched. diff --git a/src/ui-server/api/route-roots.ts b/src/ui-server/api/route-roots.ts index 6f44316..78412b8 100644 --- a/src/ui-server/api/route-roots.ts +++ b/src/ui-server/api/route-roots.ts @@ -35,7 +35,14 @@ export interface RouteRoot { inline: boolean; } -const HANDLER_KINDS: ReadonlySet = new Set(['function', 'method', 'class', 'component']); +/** + * What a resolver's `references` edge may name as the handler. A constant or + * a variable counts: `const authUser = asyncHandler(async (req, res) => …)` is + * how an Express handler is written with a wrapper, and the registration site + * named it — the arrow inside has no node of its own, so the binding is the + * handler, and the walk lends it the file-scope calls within its lines. + */ +const HANDLER_KINDS: ReadonlySet = new Set(['function', 'method', 'class', 'component', 'constant', 'variable']); const JS_FAMILY: ReadonlySet = new Set(['javascript', 'typescript', 'tsx', 'jsx']); /** A React component, by the convention that names one: a PascalCase function in a JS-family file. */ @@ -59,7 +66,7 @@ export function routeRoots(cg: CodeGraph, routes: readonly Node[]): Map (n.kind === 'function' || n.kind === 'method' ? 0 : n.kind === 'component' ? 1 : 2); + const rank = (n: Node): number => (n.kind === 'function' || n.kind === 'method' ? 0 : n.kind === 'component' ? 1 : n.kind === 'class' ? 2 : 3); for (const route of routes) { const list = byRoute.get(route.id); if (!list || list.length === 0) continue; diff --git a/src/ui-server/api/steps.ts b/src/ui-server/api/steps.ts index 740f1db..88c7b65 100644 --- a/src/ui-server/api/steps.ts +++ b/src/ui-server/api/steps.ts @@ -103,8 +103,9 @@ export interface WireStep { depth: number; /** * Why the walk did not go on from this step, when it did not: a cap it hit - * (`depth`, `fan-out`, `folded`, `steps`), or `screen` — another screen is - * a chapter of its own, drawn but not entered unless `through` asks. + * (`depth`, `fan-out`, `folded`, `steps`), or `screen` — another screen, or + * an endpoint reached across a tier, is a chapter of its own, drawn but not + * entered unless `through` asks. */ cut: 'depth' | 'fan-out' | 'folded' | 'steps' | 'screen' | 'component' | null; /** The event name a native event step arrived on (`onZipComplete`) — the first, when several land here. */ @@ -227,8 +228,19 @@ const WALK_KINDS: Edge['kind'][] = ['calls', 'instantiates', 'navigates', 'refer const JS_FAMILY: ReadonlySet = new Set(['javascript', 'typescript', 'tsx', 'jsx']); const NATIVE_FAMILY: ReadonlySet = new Set(['swift', 'objc', 'java', 'kotlin']); -/** JS → native is a bridge call; native → JS is an event. Anything else is one family. */ -export function crossing(from: Language, to: Language): 'bridge' | 'event' | null { +/** + * JS → native is a bridge call; native → JS is an event. Anything else is one + * family — unless the edge itself says which way it crosses: a synthesized + * channel (`resolution/tier-synthesizer.ts`) marks a client's request onto its + * own route `client→server`, a socket message back `server→client`, and a + * queue job or a bus event as a `channel` whose landing is an arrival; a + * server action called from a client file is marked `client→server` at + * request time, by its directive. + */ +export function crossing(from: Language, to: Language, meta: Record = {}): 'bridge' | 'event' | null { + if (meta.tier === 'client→server') return 'bridge'; + if (meta.tier === 'server→client') return 'event'; + if (meta.channel === 'queue' || meta.channel === 'event' || meta.channel === 'socket') return 'event'; if (JS_FAMILY.has(from) && NATIVE_FAMILY.has(to)) return 'bridge'; if (NATIVE_FAMILY.has(from) && JS_FAMILY.has(to)) return 'event'; return null; @@ -470,6 +482,7 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS const fanIn = new Map(); const chromeParents = new Map(); const fileScopeRefs = new Map(); + const fileScopeUnresolved = new Map(); const stepFor = (node: Node, kind: WireStepKind, depth: number, extra: Partial = {}): StepRecord | null => { const existing = steps.get(node.id); @@ -495,7 +508,9 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS const routeRoot = isRoute ? (roots.get(node.id) ?? null) : null; const record: StepRecord = { id: node.id, - kind: isRoute ? 'screen' : kind, + // A route is a screen or an endpoint — except one reached across a + // tier (`fetch('/api/users')` onto its own route), which is the crossing. + kind: isRoute && kind !== 'bridge' ? 'screen' : kind, anchor: false, node: toNodeRef(node), label: node.name, @@ -708,7 +723,9 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS // Another screen is a chapter of its own: the Screens view draws the way // between screens, and a picture that walked on through Home would be the // whole app. Drawn as a boundary, entered on request. - if (step.kind === 'screen' && !step.anchor && !through) { + // An endpoint reached across a tier is the same kind of boundary: the + // request's own picture starts at its handler, entered on request. + if ((step.kind === 'screen' || (step.kind === 'bridge' && step.node?.kind === 'route')) && !step.anchor && !through) { step.cut = 'screen'; continue; } @@ -743,9 +760,14 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS // from the FILE scope, at the wrapper's line. Lend the wrapper those // references, so the screen that renders `` walks on into // what the component does. + // The same for a value a registration is written inside — `const + // worker = new Worker('q', async (job) => { … })`: the arrow's calls + // belong to the file scope and the constant spans them; a queue job + // lands on the constant, and the walk goes on into what the handler does. for (const fold of frontier) { - if (fold.node.kind !== 'component' || (bySource.get(fold.node.id)?.length ?? 0) > 0) continue; - for (const e of fileScopeFnRefsWithin(cg, fold.node, fileScopeRefs)) { + const value = fold.node.kind === 'constant' || fold.node.kind === 'variable'; + if ((fold.node.kind !== 'component' && !value) || (bySource.get(fold.node.id)?.length ?? 0) > 0) continue; + for (const e of fileScopeEdgesWithin(cg, fold.node, fileScopeRefs, value)) { const list = bySource.get(fold.node.id) ?? []; list.push({ ...e, source: fold.node.id }); bySource.set(fold.node.id, list); @@ -759,17 +781,38 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS if (unknownFanIn.length > 0) for (const [id, n] of cg.getFanIn(unknownFanIn)) fanIn.set(id, n); for (const fold of frontier) { - // Effects made by this node, folded or not. + // A call a synthesized channel already follows — the `fetch` that + // reaches its own route, the `queue.add` its consumer picks up — is + // the crossing, not also a call outside the index. + const channelLines = new Set(); + /** Per line, the last segment of each call a channel follows there (`add` of `emailQueue.add`). */ + const channelCalls = new Map>(); + for (const e of bySource.get(fold.node.id) ?? []) { + const m = e.metadata as Record | undefined; + if (typeof m?.channel !== 'string' || typeof e.line !== 'number') continue; + channelLines.add(e.line); + if (typeof m.callee === 'string') { + const set = channelCalls.get(e.line) ?? new Set(); + set.add(m.callee.split(/[.:]/).pop() ?? m.callee); + channelCalls.set(e.line, set); + } + } + // Effects made by this node, folded or not. A value a handler is + // written inside (`const authUser = asyncHandler(async (req, res) => + // …)`) made none itself — the arrow's calls belong to the file scope — + // so it is lent the file's, within its lines, as its call edges are. if (effectScans < MAX_EFFECT_SCANS) { effectScans++; let refs: UnresolvedReference[] = []; try { refs = cg.getUnresolvedReferencesFrom(fold.node.id); + if (refs.length === 0 && (fold.node.kind === 'constant' || fold.node.kind === 'variable')) refs = fileScopeRefsWithin(cg, fold.node, fileScopeUnresolved); } catch { refs = []; } for (const ref of [...refs].sort((a, b) => a.line - b.line || a.column - b.column)) { if (ref.referenceKind !== 'calls' && ref.referenceKind !== 'instantiates') continue; + if (channelLines.has(ref.line)) continue; await effectLink(step, fold, { referenceName: ref.referenceName, referenceKind: ref.referenceKind, line: ref.line, column: ref.column }, null); } } @@ -824,6 +867,14 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS // same case with the constant as the target. let target = targets.get(e.target)!; let retargeted = false; + // `api.get('/users')` resolves to the `api` constant — and + // `this.audioQueue.add('transcode')` to some `add` by name — AND, + // on the same line, a channel follows the call: the channel is the story. + if (typeof meta.channel !== 'string' && e.kind === 'calls' && channelLines.has(e.line ?? -1)) { + const written = typeof meta.refName === 'string' ? meta.refName : target.name; + const last = written.split(/[.:]/).pop() ?? written; + if (target.kind === 'constant' || target.kind === 'variable' || channelCalls.get(e.line!)?.has(last)) continue; + } if (e.kind === 'calls' && typeof meta.synthesizedBy !== 'string' && e.provenance !== 'heuristic') { const refName = typeof meta.refName === 'string' ? meta.refName : target.name; const bare = !refName.includes('.'); @@ -873,11 +924,28 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS const isCall = e.kind === 'calls' || e.kind === 'instantiates' || (e.kind === 'references' && meta.fnRef === true); const trigger = isCall ? await triggerAt(fold.node, { line: e.line, column: e.column }) : null; + // A server action, by its directive: a function in a `'use server'` + // file (or opening with the directive) called from a file that is + // not — the call crosses to the server, whatever the import says. + if ( + e.provenance !== 'heuristic' && + (e.kind === 'calls' || (e.kind === 'references' && meta.fnRef === true)) && + (target.kind === 'function' || target.kind === 'method') && + JS_FAMILY.has(target.language) && + JS_FAMILY.has(fold.node.language) + ) { + const callee = await calls.directive(target); + if ((callee.file === 'server' || callee.own) && (await calls.directive(fold.node)).file !== 'server') { + meta.tier = 'client→server'; + meta.channel = 'server-action'; + } + } + // What kind of step, if any, this edge arrives at. let kind: WireStepKind | null = null; let linkKind: WireStepLinkKind = 'calls'; const extra: Partial = {}; - if (target.kind === 'route') { + if (target.kind === 'route' && meta.tier !== 'client→server') { kind = 'screen'; linkKind = 'navigates'; } else { @@ -886,8 +954,9 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS // a synthesized channel's. A plain name-matched call across the // families (`arr.flat()` landing on a Swift `flat`) is noise, and // is neither drawn nor walked. - const cross = crossing(fold.node.language, target.language); - const evidenced = e.provenance === 'heuristic' || meta.bridge === 'react-native' || meta.resolvedBy === 'framework'; + const cross = crossing(fold.node.language, target.language, meta); + const evidenced = + e.provenance === 'heuristic' || meta.bridge === 'react-native' || meta.resolvedBy === 'framework' || meta.channel === 'server-action'; if (cross !== null && !evidenced) continue; if (cross === 'event') { kind = 'event'; @@ -937,8 +1006,15 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS const at = { line: a.e.line, column: a.e.column }; const when = await whenAt(fold.node, at); // A call-shaped hop says what it passes; a navigation already says - // its href, a handler binding and an event channel pass nothing. - const site = a.linkKind === 'bridge' || a.linkKind === 'store' || a.linkKind === 'calls' ? await withArgs(a.site, fold.node, at) : a.site; + // its href, a handler binding and a native event channel pass + // nothing. A hop over a synthesized channel is a call in the source + // — `fetch('/api/users', {…})`, `emailQueue.add('welcome', {…})` — + // and its site reads as written. + let site = a.site; + if (typeof a.meta.channel === 'string' && a.meta.channel !== 'server-action') { + const written = await callAt(fold.node, at); + site = written && written.callee ? { ...a.site, text: written.callee, args: written.args } : await withArgs(a.site, fold.node, at); + } else if (a.linkKind === 'bridge' || a.linkKind === 'store' || a.linkKind === 'calls') site = await withArgs(a.site, fold.node, at); link(step, to, a.linkKind, fold.chain, [...fold.whens, when], site, a.e, a.trigger); if (to.root !== null && !explored.has(to.id)) { explored.add(to.id); @@ -1116,20 +1192,40 @@ function basename(p: string): string { } /** - * Function-as-value references made at a file's top level within a node's - * lines — what `const Memoized = memo(CaptureComponent)` leaves behind: the - * reference belongs to the file scope, the wrapper node spans the line. + * Function-as-value references — and, for a value, calls — made at a file's + * top level within a node's lines: what `const Memoized = memo(CaptureComponent)` + * leaves behind (the reference belongs to the file scope, the wrapper node + * spans the line), and what `const worker = new Worker('q', async (job) => + * { … })` leaves behind (the handler's calls belong to the file scope, the + * constant spans them). */ -function fileScopeFnRefsWithin(cg: CodeGraph, node: Node, memo: Map): Edge[] { +function fileScopeEdgesWithin(cg: CodeGraph, node: Node, memo: Map, calls: boolean): Edge[] { let refs = memo.get(node.filePath); if (refs === undefined) { const file = cg.getNodesInFile(node.filePath).find((n) => n.kind === 'file'); refs = file - ? cg.getOutgoingEdgesFrom([file.id], ['references']).filter((e) => (e.metadata as Record | undefined)?.fnRef === true) + ? cg + .getOutgoingEdgesFrom([file.id], ['references', 'calls']) + .filter((e) => e.kind === 'calls' || (e.metadata as Record | undefined)?.fnRef === true) : []; memo.set(node.filePath, refs); } - return refs.filter((e) => typeof e.line === 'number' && e.line >= node.startLine && e.line <= node.endLine); + return refs.filter((e) => (calls || e.kind === 'references') && typeof e.line === 'number' && e.line >= node.startLine && e.line <= node.endLine); +} + +/** The file scope's unresolved calls within a value's lines — what a wrapped handler's arrow body leaves on the file node. */ +function fileScopeRefsWithin(cg: CodeGraph, node: Node, memo: Map): UnresolvedReference[] { + let refs = memo.get(node.filePath); + if (refs === undefined) { + const file = cg.getNodesInFile(node.filePath).find((n) => n.kind === 'file'); + try { + refs = file ? cg.getUnresolvedReferencesFrom(file.id) : []; + } catch { + refs = []; + } + memo.set(node.filePath, refs); + } + return refs.filter((r) => r.line >= node.startLine && r.line <= node.endLine); } /** `push /capture`, `renders