@vyuhlabs/dxkit 2.18.1 → 2.19.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.19.0] - 2026-06-30
+
+### Added — application-flow extraction (`flow extract`)
+
+`vyuh-dxkit flow extract` statically maps a frontend's HTTP calls to a backend's
+routes and writes the result as CSVs. It is the first slice of the Flow feature
+(UI to API traceability).
+
+- **AST-based, not regex.** A new in-process, graphify-independent tree-sitter
+  layer (`src/ast/`, web-tree-sitter/wasm) parses source; a per-language
+  `httpFlow` descriptor declares which constructs are HTTP clients and routes,
+  so no framework literal is hardcoded in the analyzer.
+- **Both sides plus the join.** It extracts outbound client calls
+  (fetch/axios/wrappers) and inbound routes (LoopBack/NestJS decorators, Express
+  app/router), canonicalizes URLs and route paths to a common shape, and binds
+  each call to the route it targets with a confidence score.
+- **OpenAPI when present.** An existing OpenAPI spec is consumed as the
+  authoritative served side (`--specs`), unioned with static extraction (spec
+  for authority, static for recall, since generated specs are often incomplete).
+- **Usage:** `flow extract [--frontend <dir>] [--backend <dir>] [--specs a.json,b.json] [--out <dir>]`;
+  writes `api_calls.csv`, `routes.csv`, `api_route_mapping.csv`. TypeScript and
+  JavaScript in this release; more languages follow.
+
 ## [2.18.1] - 2026-06-23
 
 ### Fixed — next-step hints now use a resolvable invocation

package/dist/analyzers/flow/csv.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CSV renderers over a `FlowModel` — the parity output surface (mirrors the
+ * reference tool's `api_data` / `controller_data` / `api_controller_mapping`
+ * CSVs). Pure: a model in, CSV text out. CSV is one renderer among several
+ * (the graph + the gate consume the same model), so nothing analytical lives
+ * here — only serialization.
+ */
+import type { FlowModel } from './model';
+/** Outbound HTTP calls (the consumed side). */
+export declare function callsCsv(model: FlowModel): string;
+/** Served routes (the served side), from source extraction and/or a spec. */
+export declare function routesCsv(model: FlowModel): string;
+/** The join: each client call mapped to the route it targets (or not). */
+export declare function mappingCsv(model: FlowModel): string;
+/** The full parity CSV set, keyed by output filename. */
+export declare function flowCsvFiles(model: FlowModel): Record<string, string>;
+//# sourceMappingURL=csv.d.ts.map

package/dist/analyzers/flow/csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../../../src/analyzers/flow/csv.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAczC,+CAA+C;AAC/C,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAKjD;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAKlD;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CA2BnD;AAED,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMrE"}

package/dist/analyzers/flow/csv.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * CSV renderers over a `FlowModel` — the parity output surface (mirrors the
+ * reference tool's `api_data` / `controller_data` / `api_controller_mapping`
+ * CSVs). Pure: a model in, CSV text out. CSV is one renderer among several
+ * (the graph + the gate consume the same model), so nothing analytical lives
+ * here — only serialization.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callsCsv = callsCsv;
+exports.routesCsv = routesCsv;
+exports.mappingCsv = mappingCsv;
+exports.flowCsvFiles = flowCsvFiles;
+/** Quote every field (CSV-safe: doubles embedded quotes), join a row. */
+function row(fields) {
+    return fields.map((f) => `"${String(f ?? '').replace(/"/g, '""')}"`).join(',');
+}
+function toCsv(header, rows) {
+    return [row(header), ...rows.map(row)].join('\n') + '\n';
+}
+/** Outbound HTTP calls (the consumed side). */
+function callsCsv(model) {
+    return toCsv(['method', 'path', 'raw_url', 'receiver', 'file', 'line'], model.calls.map((c) => [c.method, c.path, c.rawUrl, c.receiver, c.file, c.line]));
+}
+/** Served routes (the served side), from source extraction and/or a spec. */
+function routesCsv(model) {
+    return toCsv(['method', 'path', 'via', 'handler', 'file', 'line'], // arch-shape-ok: CSV column name, not a role label
+    model.routes.map((r) => [r.method, r.path, r.via, r.handler, r.file, r.line]));
+}
+/** The join: each client call mapped to the route it targets (or not). */
+function mappingCsv(model) {
+    return toCsv([
+        'call_method',
+        'call_path',
+        'call_file',
+        'call_line',
+        'reason',
+        'confidence',
+        'route_path',
+        'route_handler',
+        'route_via',
+        'route_file',
+    ], model.bindings.map((b) => [
+        b.call.method,
+        b.call.path,
+        b.call.file,
+        b.call.line,
+        b.reason,
+        b.confidence,
+        b.route?.path ?? '',
+        b.route?.handler ?? '',
+        b.route?.via ?? '',
+        b.route?.file ?? '',
+    ]));
+}
+/** The full parity CSV set, keyed by output filename. */
+function flowCsvFiles(model) {
+    return {
+        'api_calls.csv': callsCsv(model),
+        'routes.csv': routesCsv(model),
+        'api_route_mapping.csv': mappingCsv(model),
+    };
+}
+//# sourceMappingURL=csv.js.map

package/dist/analyzers/flow/csv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.js","sourceRoot":"","sources":["../../../src/analyzers/flow/csv.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAiBH,4BAKC;AAGD,8BAKC;AAGD,gCA2BC;AAGD,oCAMC;AAjED,yEAAyE;AACzE,SAAS,GAAG,CAAC,MAA6C;IACxD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACjF,CAAC;AAED,SAAS,KAAK,CACZ,MAAyB,EACzB,IAA0D;IAE1D,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAC3D,CAAC;AAED,+CAA+C;AAC/C,SAAgB,QAAQ,CAAC,KAAgB;IACvC,OAAO,KAAK,CACV,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EACzD,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CACjF,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,SAAgB,SAAS,CAAC,KAAgB;IACxC,OAAO,KAAK,CACV,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,mDAAmD;IACzG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAC9E,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,SAAgB,UAAU,CAAC,KAAgB;IACzC,OAAO,KAAK,CACV;QACE,aAAa;QACb,WAAW;QACX,WAAW;QACX,WAAW;QACX,QAAQ;QACR,YAAY;QACZ,YAAY;QACZ,eAAe;QACf,WAAW;QACX,YAAY;KACb,EACD,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACxB,CAAC,CAAC,IAAI,CAAC,MAAM;QACb,CAAC,CAAC,IAAI,CAAC,IAAI;QACX,CAAC,CAAC,IAAI,CAAC,IAAI;QACX,CAAC,CAAC,IAAI,CAAC,IAAI;QACX,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,KAAK,EAAE,IAAI,IAAI,EAAE;QACnB,CAAC,CAAC,KAAK,EAAE,OAAO,IAAI,EAAE;QACtB,CAAC,CAAC,KAAK,EAAE,GAAG,IAAI,EAAE;QAClB,CAAC,CAAC,KAAK,EAAE,IAAI,IAAI,EAAE;KACpB,CAAC,CACH,CAAC;AACJ,CAAC;AAED,yDAAyD;AACzD,SAAgB,YAAY,CAAC,KAAgB;IAC3C,OAAO;QACL,eAAe,EAAE,QAAQ,CAAC,KAAK,CAAC;QAChC,YAAY,EAAE,SAAS,CAAC,KAAK,CAAC;QAC9B,uBAAuB,EAAE,UAAU,CAAC,KAAK,CAAC;KAC3C,CAAC;AACJ,CAAC"}

package/dist/analyzers/flow/extract.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Flow extraction — the AST pass that turns source into the two sides of an
+ * HTTP integration: outbound client calls (CONSUMED) and inbound route
+ * declarations (SERVED).
+ *
+ * It is the cross-cutting consumer of three seams and hardcodes none of them:
+ *   - the canonical AST layer (`src/ast/`) for parsing — graphify-independent,
+ *     and registered as its own concern, never folded into graphify's pass;
+ *   - each pack's `httpFlow` descriptor (Rule 6) for WHICH constructs are HTTP
+ *     — no `fetch`/`axios`/`@get` literal lives here;
+ *   - the shared normalizer for canonical paths + verbs.
+ *
+ * Every source file is scanned for BOTH surfaces: a backend that serves routes
+ * AND calls other services contributes to both lists (the consumer/provider
+ * model — a participant is whatever its served/consumed sets make it). Role
+ * assignment happens above this module, never inside it.
+ *
+ * Precision guard (validated): a member call with no declared receiver allowlist
+ * (`axios.get`, `requests.get`, `agent.X.del`) only counts as a client call when
+ * its first argument is a path-like literal — that filter keeps non-HTTP `.get`/
+ * `.delete` (lodash, Maps) out while still catching app-specific wrappers.
+ */
+import type { HttpFlowSupport } from '../../languages/types';
+import { type Node } from '../../ast/parse';
+import { type HttpMethod, type NormalizeConfig } from './normalize';
+/** An outbound HTTP call found in source (the consumed side). */
+export interface ClientCall {
+    readonly method: HttpMethod;
+    readonly rawUrl: string;
+    /** Normalized path, or `null` when the URL is dynamic/external (unresolved). */
+    readonly path: string | null;
+    readonly receiver: string;
+    readonly file: string;
+    readonly line: number;
+}
+/** An inbound route a service serves (the served side). `via` records how it
+ *  was discovered: a source decorator, an Express-style route call, or an
+ *  ingested OpenAPI/spec document (preferred when available). */
+export interface RouteEndpoint {
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly via: 'decorator' | 'router-call' | 'spec';
+    readonly handler: string | null;
+    readonly file: string;
+    readonly line: number;
+}
+/** Both HTTP surfaces extracted from one file. */
+export interface FileFlow {
+    readonly calls: ClientCall[];
+    readonly routes: RouteEndpoint[];
+}
+/**
+ * Extract both HTTP surfaces from one already-parsed tree using a pack's
+ * httpFlow descriptor. Pure over its inputs.
+ */
+export declare function extractFromTree(root: Node, hf: HttpFlowSupport, file: string, config?: NormalizeConfig): FileFlow;
+/**
+ * Extract both HTTP surfaces from one file on disk. Returns empty surfaces when
+ * the language has no httpFlow descriptor, and `null` when the file can't be
+ * parsed (engine/grammar unavailable or unreadable) — callers treat `null` as
+ * "skip this file", never an error.
+ */
+export declare function extractFileFlow(filePath: string, config?: NormalizeConfig): Promise<FileFlow | null>;
+//# sourceMappingURL=extract.d.ts.map

package/dist/analyzers/flow/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../../src/analyzers/flow/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAc,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAmB,KAAK,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAkC,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAEpG,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;iEAEiE;AACjE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,aAAa,GAAG,MAAM,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC;CAClC;AAiGD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,eAAe,EACnB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,eAAe,GACvB,QAAQ,CA0GV;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAM1B"}

package/dist/analyzers/flow/extract.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * Flow extraction — the AST pass that turns source into the two sides of an
+ * HTTP integration: outbound client calls (CONSUMED) and inbound route
+ * declarations (SERVED).
+ *
+ * It is the cross-cutting consumer of three seams and hardcodes none of them:
+ *   - the canonical AST layer (`src/ast/`) for parsing — graphify-independent,
+ *     and registered as its own concern, never folded into graphify's pass;
+ *   - each pack's `httpFlow` descriptor (Rule 6) for WHICH constructs are HTTP
+ *     — no `fetch`/`axios`/`@get` literal lives here;
+ *   - the shared normalizer for canonical paths + verbs.
+ *
+ * Every source file is scanned for BOTH surfaces: a backend that serves routes
+ * AND calls other services contributes to both lists (the consumer/provider
+ * model — a participant is whatever its served/consumed sets make it). Role
+ * assignment happens above this module, never inside it.
+ *
+ * Precision guard (validated): a member call with no declared receiver allowlist
+ * (`axios.get`, `requests.get`, `agent.X.del`) only counts as a client call when
+ * its first argument is a path-like literal — that filter keeps non-HTTP `.get`/
+ * `.delete` (lodash, Maps) out while still catching app-specific wrappers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractFromTree = extractFromTree;
+exports.extractFileFlow = extractFileFlow;
+const languages_1 = require("../../languages");
+const parse_1 = require("../../ast/parse");
+const normalize_1 = require("./normalize");
+const HTTP_VERB_METHODS = new Set([
+    'get',
+    'post',
+    'put',
+    'patch',
+    'delete',
+    'del',
+    'head',
+    'options',
+]);
+function line(node) {
+    return node.startPosition.row + 1;
+}
+/** Text of a string/template-string node, else null (a dynamic argument). */
+function literalText(node) {
+    if (!node)
+        return null;
+    return node.type === 'string' || node.type === 'template_string' ? node.text : null;
+}
+/**
+ * Does a raw literal look like a URL/path at the source level — i.e. could this
+ * `.get(...)`/`.post(...)` plausibly be an HTTP call rather than a Map/cache/
+ * lodash accessor? Used only for member calls with NO declared receiver
+ * allowlist, where it is the precision guard: a leading `/`, a leading template
+ * (`${host}/…`), an explicit scheme, or any embedded `/` qualifies; a bare token
+ * like `'config-key'` does not. (Route decorators are exempt — a framework route
+ * string is known to be a path even without a leading slash.)
+ */
+function looksLikeUrlLiteral(raw) {
+    if (raw == null)
+        return false;
+    let s = raw.trim();
+    if (s.length >= 2 && /^['"`]/.test(s) && s.endsWith(s[0]))
+        s = s.slice(1, -1);
+    return s.startsWith('/') || s.startsWith('${') || s.includes('://') || s.includes('/');
+}
+function firstNamedArg(callOrArgs) {
+    const args = callOrArgs?.childForFieldName('arguments') ?? null;
+    if (!args)
+        return null;
+    for (const c of args.namedChildren)
+        if (c)
+            return c;
+    return null;
+}
+/** Does a member-call receiver match one of the declared bases (e.g. `app`, or
+ *  `this.app`)? */
+function receiverMatchesBase(receiver, bases) {
+    return bases.some((b) => receiver === b || receiver.endsWith(`.${b}`));
+}
+/** Pull `method: 'X'` out of a fetch options object (2nd arg), default GET. */
+function fetchMethod(call, hf) {
+    const args = call.childForFieldName('arguments');
+    const opts = args?.namedChildren?.[1] ?? null;
+    if (opts && opts.type === 'object') {
+        let verb = null;
+        (0, parse_1.walk)(opts, (n) => {
+            if (verb)
+                return false;
+            if (n.type === 'pair') {
+                const key = n.childForFieldName('key');
+                const val = n.childForFieldName('value');
+                const keyName = key ? key.text.replace(/['"`]/g, '') : '';
+                if (keyName === 'method') {
+                    const raw = literalText(val);
+                    if (raw)
+                        verb = (0, normalize_1.normalizeMethod)(raw.replace(/['"`]/g, ''), hf.methodAliases);
+                }
+            }
+        });
+        if (verb)
+            return verb;
+    }
+    return 'GET';
+}
+/**
+ * The handler name a route decorator is attached to (best-effort). Decorators
+ * are siblings preceding the member in the class body, so the handler is the
+ * decorator's next named sibling (skipping any stacked decorators); a nested
+ * grammar shape is handled by an ancestor fallback.
+ */
+function decoratedHandlerName(decorator) {
+    let sib = decorator.nextNamedSibling;
+    while (sib && sib.type === 'decorator')
+        sib = sib.nextNamedSibling;
+    const sibName = sib?.childForFieldName('name');
+    if (sibName)
+        return sibName.text;
+    let cur = decorator.parent;
+    for (let i = 0; cur && i < 3; i++) {
+        if (cur.type === 'method_definition' || cur.type === 'function_declaration') {
+            const name = cur.childForFieldName('name');
+            if (name)
+                return name.text;
+        }
+        cur = cur.parent;
+    }
+    return null;
+}
+/**
+ * Extract both HTTP surfaces from one already-parsed tree using a pack's
+ * httpFlow descriptor. Pure over its inputs.
+ */
+function extractFromTree(root, hf, file, config) {
+    const calls = [];
+    const routes = [];
+    const clientCallees = new Set(hf.clientCallees ?? []);
+    const methodCallMethods = new Set(hf.clientMethodCallees?.methods ?? []);
+    const methodCallBases = hf.clientMethodCallees?.bases;
+    const routeDecorators = new Set(hf.routeDecorators ?? []);
+    const routerMethods = new Set(hf.routeRouterCallees?.methods ?? []);
+    const routerBases = hf.routeRouterCallees?.bases ?? [];
+    (0, parse_1.walk)(root, (node) => {
+        // ── decorator routes: @get('/x') ──
+        if (node.type === 'decorator' && routeDecorators.size) {
+            const call = node.namedChildren.find((c) => c?.type === 'call_expression') ?? null;
+            const callee = call?.childForFieldName('function');
+            const name = callee && callee.type === 'identifier' ? callee.text : '';
+            if (call && routeDecorators.has(name)) {
+                const path = (0, normalize_1.normalizePath)(literalText(firstNamedArg(call)), config);
+                const method = (0, normalize_1.normalizeMethod)(name, hf.methodAliases);
+                if (path && method) {
+                    routes.push({
+                        method,
+                        path,
+                        via: 'decorator',
+                        handler: decoratedHandlerName(node),
+                        file,
+                        line: line(node),
+                    });
+                }
+            }
+            return; // a decorator's call is bookkeeping, not a client call
+        }
+        if (node.type !== 'call_expression')
+            return;
+        const callee = node.childForFieldName('function');
+        if (!callee)
+            return;
+        // ── bare client call: fetch(url, opts) ──
+        if (callee.type === 'identifier' && clientCallees.has(callee.text)) {
+            const raw = literalText(firstNamedArg(node));
+            if (raw != null) {
+                calls.push({
+                    method: fetchMethod(node, hf),
+                    rawUrl: raw,
+                    path: (0, normalize_1.normalizePath)(raw, config),
+                    receiver: callee.text,
+                    file,
+                    line: line(node),
+                });
+            }
+            return;
+        }
+        // ── member call: <recv>.<verb>(url|path, ...) ──
+        if (callee.type === 'member_expression') {
+            const prop = callee.childForFieldName('property');
+            const obj = callee.childForFieldName('object');
+            const verb = prop ? prop.text : '';
+            const receiver = obj ? obj.text : '';
+            if (!HTTP_VERB_METHODS.has(verb))
+                return;
+            // router/app route declaration
+            if (routerMethods.has(verb) && receiverMatchesBase(receiver, routerBases)) {
+                const path = (0, normalize_1.normalizePath)(literalText(firstNamedArg(node)), config);
+                const method = (0, normalize_1.normalizeMethod)(verb, hf.methodAliases);
+                if (path && method) {
+                    routes.push({
+                        method,
+                        path,
+                        via: 'router-call',
+                        handler: receiver,
+                        file,
+                        line: line(node),
+                    });
+                }
+                return;
+            }
+            // client call (bases optional). With no allowlist, require a path-like
+            // literal first arg — the precision guard against non-HTTP .get/.delete.
+            if (methodCallMethods.has(verb)) {
+                const baseOk = !methodCallBases ||
+                    receiverMatchesBase(receiver, methodCallBases) ||
+                    methodCallBases.includes(receiver);
+                if (!baseOk)
+                    return;
+                const raw = literalText(firstNamedArg(node));
+                // Unallowlisted receiver → require a URL-looking literal (precision guard).
+                if (!methodCallBases && !looksLikeUrlLiteral(raw))
+                    return;
+                const method = (0, normalize_1.normalizeMethod)(verb, hf.methodAliases);
+                if (raw != null && method) {
+                    calls.push({
+                        method,
+                        rawUrl: raw,
+                        path: (0, normalize_1.normalizePath)(raw, config),
+                        receiver,
+                        file,
+                        line: line(node),
+                    });
+                }
+            }
+        }
+    });
+    return { calls, routes };
+}
+/**
+ * Extract both HTTP surfaces from one file on disk. Returns empty surfaces when
+ * the language has no httpFlow descriptor, and `null` when the file can't be
+ * parsed (engine/grammar unavailable or unreadable) — callers treat `null` as
+ * "skip this file", never an error.
+ */
+async function extractFileFlow(filePath, config) {
+    const parsed = await (0, parse_1.parseFile)(filePath);
+    if (!parsed)
+        return null;
+    const hf = httpFlowFor(parsed.languageId);
+    if (!hf)
+        return { calls: [], routes: [] };
+    return extractFromTree(parsed.tree.rootNode, hf, filePath, config);
+}
+function httpFlowFor(languageId) {
+    return (0, languages_1.getLanguage)(languageId)?.httpFlow;
+}
+//# sourceMappingURL=extract.js.map

package/dist/analyzers/flow/extract.js.map

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

package/dist/analyzers/flow/gather.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Flow gather — walk a set of roots, extract both HTTP surfaces from every
+ * source file, and assemble a `FlowModel`. The served side is the UNION of what
+ * source extraction finds and what any configured OpenAPI spec declares (a spec
+ * is authoritative but often incomplete, so static extraction adds recall).
+ *
+ * File discovery goes through the canonical `walkSourceFiles` (Rule 4
+ * exclusions + test-file skipping built in); the scanned extensions are exactly
+ * those of packs that declare BOTH an httpFlow descriptor and a tree-sitter
+ * grammar, so a non-flow language's files are never parsed and adding a flow
+ * pack auto-extends the scan (Rule 6).
+ */
+import { type FlowModel } from './model';
+export interface GatherFlowOptions {
+    /** Directories to scan for source (frontend, backend, services…). */
+    readonly roots: readonly string[];
+    /** OpenAPI spec files whose served routes union with the extracted ones. */
+    readonly specs?: readonly string[];
+    /** Host-helper prefixes to strip during URL normalization (per-app config). */
+    readonly stripUrlPrefixes?: readonly string[];
+}
+/** Walk + extract + assemble. Files that don't parse are skipped, never fatal. */
+export declare function gatherFlowModel(opts: GatherFlowOptions): Promise<FlowModel>;
+//# sourceMappingURL=gather.d.ts.map

package/dist/analyzers/flow/gather.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gather.d.ts","sourceRoot":"","sources":["../../../src/analyzers/flow/gather.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAIzD,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/C;AAaD,kFAAkF;AAClF,wBAAsB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAgBjF"}

package/dist/analyzers/flow/gather.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Flow gather — walk a set of roots, extract both HTTP surfaces from every
+ * source file, and assemble a `FlowModel`. The served side is the UNION of what
+ * source extraction finds and what any configured OpenAPI spec declares (a spec
+ * is authoritative but often incomplete, so static extraction adds recall).
+ *
+ * File discovery goes through the canonical `walkSourceFiles` (Rule 4
+ * exclusions + test-file skipping built in); the scanned extensions are exactly
+ * those of packs that declare BOTH an httpFlow descriptor and a tree-sitter
+ * grammar, so a non-flow language's files are never parsed and adding a flow
+ * pack auto-extends the scan (Rule 6).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatherFlowModel = gatherFlowModel;
+const path_1 = require("path");
+const languages_1 = require("../../languages");
+const walk_source_files_1 = require("../tools/walk-source-files");
+const extract_1 = require("./extract");
+const model_1 = require("./model");
+const spec_source_1 = require("./spec-source");
+/** Extensions of packs that can contribute flow (httpFlow + a grammar). */
+function flowExtensions() {
+    const exts = new Set();
+    for (const pack of languages_1.LANGUAGES) {
+        if (pack.httpFlow && pack.treeSitterGrammars) {
+            for (const ext of Object.keys(pack.treeSitterGrammars))
+                exts.add(ext);
+        }
+    }
+    return [...exts];
+}
+/** Walk + extract + assemble. Files that don't parse are skipped, never fatal. */
+async function gatherFlowModel(opts) {
+    const config = { stripUrlPrefixes: opts.stripUrlPrefixes };
+    const extensions = flowExtensions();
+    const fileFlows = [];
+    for (const root of opts.roots) {
+        for (const rel of (0, walk_source_files_1.walkSourceFiles)(root, { extensions })) {
+            const flow = await (0, extract_1.extractFileFlow)((0, path_1.join)(root, rel), config);
+            if (flow)
+                fileFlows.push(flow);
+        }
+    }
+    // Served side = extracted routes UNION spec routes (dedup is implicit: the
+    // join indexes routes by (method, path), so a duplicate collapses).
+    const specRoutes = (opts.specs ?? []).flatMap((spec) => (0, spec_source_1.loadOpenApiRoutes)(spec));
+    return (0, model_1.buildFlowModel)([...fileFlows, { calls: [], routes: specRoutes }]);
+}
+//# sourceMappingURL=gather.js.map

package/dist/analyzers/flow/gather.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gather.js","sourceRoot":"","sources":["../../../src/analyzers/flow/gather.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AA+BH,0CAgBC;AA7CD,+BAA4B;AAC5B,+CAA4C;AAC5C,kEAA6D;AAC7D,uCAA2D;AAC3D,mCAAyD;AACzD,+CAAkD;AAYlD,2EAA2E;AAC3E,SAAS,cAAc;IACrB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,qBAAS,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC7C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;AACnB,CAAC;AAED,kFAAkF;AAC3E,KAAK,UAAU,eAAe,CAAC,IAAuB;IAC3D,MAAM,MAAM,GAAoB,EAAE,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE,CAAC;IAC5E,MAAM,UAAU,GAAG,cAAc,EAAE,CAAC;IACpC,MAAM,SAAS,GAAe,EAAE,CAAC;IAEjC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC9B,KAAK,MAAM,GAAG,IAAI,IAAA,mCAAe,EAAC,IAAI,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,GAAG,MAAM,IAAA,yBAAe,EAAC,IAAA,WAAI,EAAC,IAAI,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;YAC5D,IAAI,IAAI;gBAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,oEAAoE;IACpE,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAA,+BAAiB,EAAC,IAAI,CAAC,CAAC,CAAC;IACjF,OAAO,IAAA,sBAAc,EAAC,CAAC,GAAG,SAAS,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;AAC3E,CAAC"}

package/dist/analyzers/flow/model.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Flow model + the join — assemble extracted client calls and route
+ * declarations into a `FlowModel`, then bind each call to the route it targets
+ * on the normalized `(method, path)` key.
+ *
+ * The join is where consumed meets served. A binding carries a confidence in
+ * [0, 1] + a reason, mirroring the git-aware matcher's contract: an exact key
+ * match on a path with real static signal is full confidence; a path that is
+ * all placeholder (`/{var}`) carries no signal and is low confidence even when
+ * it happens to match a catch-all; a dynamic or unrouted call is unresolved.
+ * Confidence is what a gate thresholds on — only high-confidence bindings can
+ * block, which is what keeps the false-positive budget intact.
+ *
+ * Pure over its inputs (the file-extraction step that produces `FileFlow`s does
+ * the I/O); this module just structures + joins.
+ */
+import { type ClientCall, type FileFlow, type RouteEndpoint } from './extract';
+import type { NormalizeConfig } from './normalize';
+/**
+ * Why a call did or didn't bind to a route:
+ *   - `exact`            — matched a route on a path with real static signal;
+ *   - `placeholder-only` — matched, but the path is all `{var}` (no signal);
+ *   - `no-route`         — path resolved to an internal route shape, but no
+ *                          served route matches it;
+ *   - `external`         — the URL is an external/absolute address we don't
+ *                          serve (path is null), so it is not an internal binding.
+ */
+export type BindingReason = 'exact' | 'placeholder-only' | 'no-route' | 'external';
+/** One client call resolved (or not) against the served routes. */
+export interface FlowBinding {
+    readonly call: ClientCall;
+    readonly route: RouteEndpoint | null;
+    readonly confidence: number;
+    readonly reason: BindingReason;
+}
+/** The assembled flow: both surfaces plus the bindings between them. */
+export interface FlowModel {
+    readonly calls: readonly ClientCall[];
+    readonly routes: readonly RouteEndpoint[];
+    readonly bindings: readonly FlowBinding[];
+}
+/**
+ * Bind each client call to the route it targets, on the normalized
+ * `(method, path)` key. Routes are indexed once; each call resolves in O(1).
+ */
+export declare function joinFlow(calls: readonly ClientCall[], routes: readonly RouteEndpoint[]): FlowBinding[];
+/** Flatten per-file surfaces into one model + its bindings. */
+export declare function buildFlowModel(fileFlows: readonly FileFlow[]): FlowModel;
+/**
+ * Extract + assemble a flow model from a set of files. `null` extractions
+ * (unparseable / engine unavailable) are skipped, never fatal.
+ */
+export declare function extractFlowModel(filePaths: readonly string[], config?: NormalizeConfig): Promise<FlowModel>;
+/** Summary counts for a model (drives the `flow` preview + acceptance checks). */
+export interface FlowSummary {
+    readonly calls: number;
+    readonly routes: number;
+    readonly resolved: number;
+    readonly highConfidence: number;
+    readonly unresolved: number;
+}
+export declare function summarize(model: FlowModel): FlowSummary;
+//# sourceMappingURL=model.d.ts.map

package/dist/analyzers/flow/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/analyzers/flow/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAmB,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAChG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,kBAAkB,GAAG,UAAU,GAAG,UAAU,CAAC;AAEnF,mEAAmE;AACnE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED,wEAAwE;AACxE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAC3C;AAOD;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,MAAM,EAAE,SAAS,aAAa,EAAE,GAC/B,WAAW,EAAE,CAaf;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,CAIxE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,SAAS,CAAC,CAOpB;AAED,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,WAAW,CAUvD"}