@vyuhlabs/dxkit 2.18.1 → 2.19.0

package/dist/analyzers/flow/model.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.joinFlow = joinFlow;
+exports.buildFlowModel = buildFlowModel;
+exports.extractFlowModel = extractFlowModel;
+exports.summarize = summarize;
+const extract_1 = require("./extract");
+/** A path made up entirely of `{var}` segments carries no static signal. */
+function isPlaceholderOnly(path) {
+    return /^(\/\{var\})+$/.test(path);
+}
+/**
+ * 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).
+ */
+function joinFlow(calls, routes) {
+    const routeIndex = new Map();
+    for (const r of routes)
+        routeIndex.set(`${r.method} ${r.path}`, r);
+    return calls.map((call) => {
+        if (call.path == null)
+            return { call, route: null, confidence: 0, reason: 'external' };
+        const route = routeIndex.get(`${call.method} ${call.path}`) ?? null;
+        if (!route)
+            return { call, route: null, confidence: 0, reason: 'no-route' };
+        if (isPlaceholderOnly(call.path)) {
+            return { call, route, confidence: 0.3, reason: 'placeholder-only' };
+        }
+        return { call, route, confidence: 1, reason: 'exact' };
+    });
+}
+/** Flatten per-file surfaces into one model + its bindings. */
+function buildFlowModel(fileFlows) {
+    const calls = fileFlows.flatMap((f) => f.calls);
+    const routes = fileFlows.flatMap((f) => f.routes);
+    return { calls, routes, bindings: joinFlow(calls, routes) };
+}
+/**
+ * Extract + assemble a flow model from a set of files. `null` extractions
+ * (unparseable / engine unavailable) are skipped, never fatal.
+ */
+async function extractFlowModel(filePaths, config) {
+    const flows = [];
+    for (const path of filePaths) {
+        const flow = await (0, extract_1.extractFileFlow)(path, config);
+        if (flow)
+            flows.push(flow);
+    }
+    return buildFlowModel(flows);
+}
+function summarize(model) {
+    const resolved = model.bindings.filter((b) => b.route !== null).length;
+    const highConfidence = model.bindings.filter((b) => b.confidence >= 1).length;
+    return {
+        calls: model.calls.length,
+        routes: model.routes.length,
+        resolved,
+        highConfidence,
+        unresolved: model.calls.length - resolved,
+    };
+}
+//# sourceMappingURL=model.js.map

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

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

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

@@ -0,0 +1,76 @@
+/**
+ * URL / route-path normalization — the canonical, pure transform that lets a
+ * frontend client call and a backend route declaration JOIN even though they
+ * are written differently. It is the precision-critical core of the flow
+ * feature: this algorithm was validated at 96% precision (vs ~84% for a regex
+ * approach) on a real axios → LoopBack stack — the win comes from being
+ * structural rather than regex-mangled.
+ *
+ * The contract: turn a raw URL/route literal into a canonical path string in
+ * which path parameters are erased to `{var}` and host/prefix noise is gone,
+ * so `axios.get(`${Config.apiBase()}/articles/${slug}`)` (client) and
+ * `@get('/articles/{id}')` (server) both reduce to `/articles/{var}` and
+ * match. Method normalization (`del` → `DELETE`) lives here too.
+ *
+ * Two inputs are deliberately NOT baked in as language facts (CLAUDE.md
+ * Rule 6 boundary):
+ *   - **Host helpers** (`${Config.apiBase()}`, `${apiUrl}`) are per-APP, not
+ *     per-language — they arrive via `NormalizeConfig.stripUrlPrefixes`
+ *     (sourced from `.dxkit/policy.json:flow.stripUrlPrefixes`).
+ *   - **Param-form canonicalization** (`:id`, `{id}`, `${x}` → `{var}`) is
+ *     uniform across frameworks, so it lives here rather than in a per-pack
+ *     descriptor.
+ *
+ * Pure: no I/O, deterministic over its inputs. Identity-bearing (a binding's
+ * Rule 9 fingerprint is computed from the normalized path), so changes here
+ * are a normalization-scheme change — treat with the same care as a
+ * fingerprint-scheme bump.
+ */
+/** Canonical HTTP verbs the flow feature recognizes. */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/** Per-app normalization inputs (not language facts — see module header). */
+export interface NormalizeConfig {
+    /**
+     * Host-helper / base-URL prefixes to strip before matching, so a client
+     * call's absolute-ish URL reduces to the bare route path. Each entry is a
+     * literal substring removed wherever it appears at the head of the URL —
+     * e.g. `['${Config.apiBase()}', '${apiUrl}']`. Sourced from
+     * `.dxkit/policy.json:flow.stripUrlPrefixes`; `flow init` auto-suggests the
+     * dominant host-helper found across client calls.
+     */
+    stripUrlPrefixes?: readonly string[];
+}
+/**
+ * Canonicalize a raw URL / route literal to a comparable path, or `null` for
+ * an external absolute URL or empty / non-path input. A path that is entirely
+ * dynamic (`${x}`) normalizes faithfully to `/{var}` rather than being
+ * dropped here — the join (not this function) treats an all-placeholder path
+ * as unresolved (validated: precision held at 96% with this split).
+ *
+ * `raw` is the literal text as it appears in source, including any
+ * surrounding quotes/backticks (the extractor passes the node text verbatim).
+ *
+ * Steps (order matters):
+ *  1. strip surrounding quotes / backticks;
+ *  2. strip configured host-helper prefixes;
+ *  3. reject external absolute URLs (`http(s)://…`, `${host}://…`) → `null`
+ *     (a call to a host we don't serve is not an internal route binding);
+ *  4. collapse template expressions `${…}` → `{var}`;
+ *  5. drop the query string (`?…`) — query params don't distinguish a route;
+ *  6. canonicalize path params `:id` and `{id}` → `{var}`;
+ *  7. ensure a single leading slash (LoopBack allows `@post('zen/x')`);
+ *  8. drop a trailing slash;
+ *  9. require a real path head (`/letter` or `/{var}`), else `null`.
+ */
+export declare function normalizePath(raw: string | null | undefined, config?: NormalizeConfig): string | null;
+/**
+ * Canonicalize a matched method token (a decorator name like `get`, or a
+ * client/router member like `post`) to an uppercase {@link HttpMethod}.
+ * `aliases` carries pack-declared exceptions (LoopBack's `del` → `DELETE`);
+ * everything else upper-cases. Returns `null` for a token that doesn't map to
+ * a known verb.
+ */
+export declare function normalizeMethod(token: string, aliases?: Readonly<Record<string, string>>): HttpMethod | null;
+/** A normalized binding key `"<METHOD> <path>"` — the join key + identity input. */
+export declare function bindingKey(method: HttpMethod, path: string): string;
+//# sourceMappingURL=normalize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/analyzers/flow/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1F,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,MAAM,CAAC,EAAE,eAAe,GACvB,MAAM,GAAG,IAAI,CAiDf;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACzC,UAAU,GAAG,IAAI,CAInB;AAgBD,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnE"}

package/dist/analyzers/flow/normalize.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * URL / route-path normalization — the canonical, pure transform that lets a
+ * frontend client call and a backend route declaration JOIN even though they
+ * are written differently. It is the precision-critical core of the flow
+ * feature: this algorithm was validated at 96% precision (vs ~84% for a regex
+ * approach) on a real axios → LoopBack stack — the win comes from being
+ * structural rather than regex-mangled.
+ *
+ * The contract: turn a raw URL/route literal into a canonical path string in
+ * which path parameters are erased to `{var}` and host/prefix noise is gone,
+ * so `axios.get(`${Config.apiBase()}/articles/${slug}`)` (client) and
+ * `@get('/articles/{id}')` (server) both reduce to `/articles/{var}` and
+ * match. Method normalization (`del` → `DELETE`) lives here too.
+ *
+ * Two inputs are deliberately NOT baked in as language facts (CLAUDE.md
+ * Rule 6 boundary):
+ *   - **Host helpers** (`${Config.apiBase()}`, `${apiUrl}`) are per-APP, not
+ *     per-language — they arrive via `NormalizeConfig.stripUrlPrefixes`
+ *     (sourced from `.dxkit/policy.json:flow.stripUrlPrefixes`).
+ *   - **Param-form canonicalization** (`:id`, `{id}`, `${x}` → `{var}`) is
+ *     uniform across frameworks, so it lives here rather than in a per-pack
+ *     descriptor.
+ *
+ * Pure: no I/O, deterministic over its inputs. Identity-bearing (a binding's
+ * Rule 9 fingerprint is computed from the normalized path), so changes here
+ * are a normalization-scheme change — treat with the same care as a
+ * fingerprint-scheme bump.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePath = normalizePath;
+exports.normalizeMethod = normalizeMethod;
+exports.bindingKey = bindingKey;
+const PLACEHOLDER = '{var}';
+/**
+ * Canonicalize a raw URL / route literal to a comparable path, or `null` for
+ * an external absolute URL or empty / non-path input. A path that is entirely
+ * dynamic (`${x}`) normalizes faithfully to `/{var}` rather than being
+ * dropped here — the join (not this function) treats an all-placeholder path
+ * as unresolved (validated: precision held at 96% with this split).
+ *
+ * `raw` is the literal text as it appears in source, including any
+ * surrounding quotes/backticks (the extractor passes the node text verbatim).
+ *
+ * Steps (order matters):
+ *  1. strip surrounding quotes / backticks;
+ *  2. strip configured host-helper prefixes;
+ *  3. reject external absolute URLs (`http(s)://…`, `${host}://…`) → `null`
+ *     (a call to a host we don't serve is not an internal route binding);
+ *  4. collapse template expressions `${…}` → `{var}`;
+ *  5. drop the query string (`?…`) — query params don't distinguish a route;
+ *  6. canonicalize path params `:id` and `{id}` → `{var}`;
+ *  7. ensure a single leading slash (LoopBack allows `@post('zen/x')`);
+ *  8. drop a trailing slash;
+ *  9. require a real path head (`/letter` or `/{var}`), else `null`.
+ */
+function normalizePath(raw, config) {
+    if (raw == null)
+        return null;
+    let s = raw.trim();
+    if (s.length === 0)
+        return null;
+    // 1. surrounding quotes / backticks
+    if (s.length >= 2 && (s[0] === "'" || s[0] === '"' || s[0] === '`') && s[s.length - 1] === s[0]) {
+        s = s.slice(1, -1);
+    }
+    // 2. host-helper prefixes (longest first, so a more specific prefix wins)
+    for (const prefix of [...(config?.stripUrlPrefixes ?? [])].sort((a, b) => b.length - a.length)) {
+        if (prefix && s.startsWith(prefix)) {
+            s = s.slice(prefix.length);
+            break;
+        }
+        // also strip when embedded at the head inside a template, e.g. a leading
+        // `${Config.apiBase()}` not at index 0 due to whitespace — rare; handled by
+        // a single replace of the first occurrence.
+        if (prefix && s.includes(prefix)) {
+            s = s.replace(prefix, '');
+            break;
+        }
+    }
+    // 3. external absolute URL (not one of our host helpers) → not internal
+    if (/^https?:\/\//i.test(s) || /^\$\{[^}]*\}:\/\//.test(s))
+        return null;
+    // 4. template expressions → placeholder
+    s = s.replace(/\$\{[^}]*\}/g, PLACEHOLDER);
+    // 5. drop query string
+    const q = s.indexOf('?');
+    if (q !== -1)
+        s = s.slice(0, q);
+    // 6. canonicalize path params
+    s = s.replace(/:[A-Za-z0-9_]+/g, PLACEHOLDER); // Express/Rails :id
+    s = s.replace(/\{[^}]*\}/g, PLACEHOLDER); // OpenAPI/LoopBack {id} (and already-{var})
+    // 7. single leading slash
+    if (!s.startsWith('/'))
+        s = '/' + s;
+    s = s.replace(/\/{2,}/g, '/'); // collapse accidental doubles after prefix strip
+    // 8. trailing slash
+    if (s.length > 1 && s.endsWith('/'))
+        s = s.slice(0, -1);
+    // 9. require a real path head
+    if (!/^\/([A-Za-z]|\{var\})/.test(s))
+        return null;
+    return s;
+}
+/**
+ * Canonicalize a matched method token (a decorator name like `get`, or a
+ * client/router member like `post`) to an uppercase {@link HttpMethod}.
+ * `aliases` carries pack-declared exceptions (LoopBack's `del` → `DELETE`);
+ * everything else upper-cases. Returns `null` for a token that doesn't map to
+ * a known verb.
+ */
+function normalizeMethod(token, aliases) {
+    const lower = token.toLowerCase();
+    const mapped = (aliases?.[lower] ?? lower).toUpperCase();
+    return isHttpMethod(mapped) ? mapped : null;
+}
+const HTTP_METHODS = new Set([
+    'GET',
+    'POST',
+    'PUT',
+    'PATCH',
+    'DELETE',
+    'HEAD',
+    'OPTIONS',
+]);
+function isHttpMethod(s) {
+    return HTTP_METHODS.has(s);
+}
+/** A normalized binding key `"<METHOD> <path>"` — the join key + identity input. */
+function bindingKey(method, path) {
+    return `${method} ${path}`;
+}
+//# sourceMappingURL=normalize.js.map

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

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

package/dist/analyzers/flow/spec-source.d.ts

@@ -0,0 +1,44 @@
+/**
+ * OpenAPI / spec served-side source — consume an existing API spec as the
+ * authoritative served contract, rather than statically extracting routes.
+ *
+ * Build-vs-buy (CLAUDE.md Rule 5 at the served layer): where a backend ships or
+ * can emit an OpenAPI document — LoopBack's `exportOpenApiSpec`, NestJS/FastAPI
+ * generators, hand-maintained specs — that document is higher-fidelity than
+ * decorator scraping: it is the framework's own answer, and it cannot pick up a
+ * commented-out or dead route. So a spec, when present, is the PREFERRED served
+ * source; static route extraction (`extract.ts`) is the fallback for backends
+ * with no spec. The CONSUMED side (client calls) has no spec equivalent and is
+ * always AST-extracted — a spec replaces half the problem, never the engine.
+ *
+ * Output is the same `RouteEndpoint` shape the static extractor produces, so the
+ * join (`model.ts`) is indifferent to where a route came from. Identity-bearing
+ * via the normalized path (Rule 9), so paths route through the shared normalizer
+ * exactly as source-extracted ones do.
+ *
+ * JSON OpenAPI (2.0/3.x) today; YAML is a fast-follow (a parser dependency
+ * decision). Pure over its inputs; the file read is the only I/O.
+ */
+import type { RouteEndpoint } from './extract';
+/** A path item holds HTTP-method operations alongside non-method siblings
+ *  (`parameters`, `summary`, `$ref`), so its values are loosely typed and the
+ *  method entries are narrowed at read time. */
+type OpenApiPathItem = Record<string, unknown>;
+interface OpenApiDoc {
+    paths?: Record<string, OpenApiPathItem | undefined>;
+}
+/**
+ * Routes from a parsed OpenAPI document. Each `(path, method)` pair becomes a
+ * served `RouteEndpoint` with `via: 'spec'`; the handler is the operationId when
+ * present. Paths are canonicalized through the shared normalizer so they join
+ * against client calls identically to source-extracted routes.
+ */
+export declare function routesFromOpenApi(doc: OpenApiDoc, sourceFile: string): RouteEndpoint[];
+/**
+ * Read + parse a JSON OpenAPI document into served routes. Returns `[]` (never
+ * throws) when the file is unreadable or not valid JSON OpenAPI — a missing or
+ * broken spec degrades to the static fallback, it does not fail the run.
+ */
+export declare function loadOpenApiRoutes(filePath: string): RouteEndpoint[];
+export {};
+//# sourceMappingURL=spec-source.d.ts.map

package/dist/analyzers/flow/spec-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-source.d.ts","sourceRoot":"","sources":["../../../src/analyzers/flow/spec-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAK/C;;gDAEgD;AAChD,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC/C,UAAU,UAAU;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC,CAAC;CACrD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,aAAa,EAAE,CAkBtF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE,CASnE"}

package/dist/analyzers/flow/spec-source.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * OpenAPI / spec served-side source — consume an existing API spec as the
+ * authoritative served contract, rather than statically extracting routes.
+ *
+ * Build-vs-buy (CLAUDE.md Rule 5 at the served layer): where a backend ships or
+ * can emit an OpenAPI document — LoopBack's `exportOpenApiSpec`, NestJS/FastAPI
+ * generators, hand-maintained specs — that document is higher-fidelity than
+ * decorator scraping: it is the framework's own answer, and it cannot pick up a
+ * commented-out or dead route. So a spec, when present, is the PREFERRED served
+ * source; static route extraction (`extract.ts`) is the fallback for backends
+ * with no spec. The CONSUMED side (client calls) has no spec equivalent and is
+ * always AST-extracted — a spec replaces half the problem, never the engine.
+ *
+ * Output is the same `RouteEndpoint` shape the static extractor produces, so the
+ * join (`model.ts`) is indifferent to where a route came from. Identity-bearing
+ * via the normalized path (Rule 9), so paths route through the shared normalizer
+ * exactly as source-extracted ones do.
+ *
+ * JSON OpenAPI (2.0/3.x) today; YAML is a fast-follow (a parser dependency
+ * decision). Pure over its inputs; the file read is the only I/O.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routesFromOpenApi = routesFromOpenApi;
+exports.loadOpenApiRoutes = loadOpenApiRoutes;
+const fs_1 = require("fs");
+const normalize_1 = require("./normalize");
+const SPEC_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options']);
+/**
+ * Routes from a parsed OpenAPI document. Each `(path, method)` pair becomes a
+ * served `RouteEndpoint` with `via: 'spec'`; the handler is the operationId when
+ * present. Paths are canonicalized through the shared normalizer so they join
+ * against client calls identically to source-extracted routes.
+ */
+function routesFromOpenApi(doc, sourceFile) {
+    const out = [];
+    const paths = doc.paths ?? {};
+    for (const [rawPath, ops] of Object.entries(paths)) {
+        if (!ops || typeof ops !== 'object')
+            continue;
+        const path = (0, normalize_1.normalizePath)(rawPath);
+        if (!path)
+            continue;
+        for (const [rawMethod, op] of Object.entries(ops)) {
+            const lower = rawMethod.toLowerCase();
+            if (!SPEC_METHODS.has(lower))
+                continue; // skip parameters/summary/$ref siblings
+            const method = (0, normalize_1.normalizeMethod)(lower);
+            if (!method)
+                continue;
+            const operationId = op?.operationId;
+            const handler = typeof operationId === 'string' ? operationId : null;
+            out.push({ method, path, via: 'spec', handler, file: sourceFile, line: 0 });
+        }
+    }
+    return out;
+}
+/**
+ * Read + parse a JSON OpenAPI document into served routes. Returns `[]` (never
+ * throws) when the file is unreadable or not valid JSON OpenAPI — a missing or
+ * broken spec degrades to the static fallback, it does not fail the run.
+ */
+function loadOpenApiRoutes(filePath) {
+    let doc;
+    try {
+        doc = JSON.parse((0, fs_1.readFileSync)(filePath, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    if (!doc || typeof doc !== 'object' || !doc.paths)
+        return [];
+    return routesFromOpenApi(doc, filePath);
+}
+//# sourceMappingURL=spec-source.js.map

package/dist/analyzers/flow/spec-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-source.js","sourceRoot":"","sources":["../../../src/analyzers/flow/spec-source.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AAsBH,8CAkBC;AAOD,8CASC;AAtDD,2BAAkC;AAElC,2CAA8E;AAE9E,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAU3F;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,GAAe,EAAE,UAAkB;IACnE,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,SAAS;QAC9C,MAAM,IAAI,GAAG,IAAA,yBAAa,EAAC,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,KAAK,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAClD,MAAM,KAAK,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;YACtC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,SAAS,CAAC,wCAAwC;YAChF,MAAM,MAAM,GAAsB,IAAA,2BAAe,EAAC,KAAK,CAAC,CAAC;YACzD,IAAI,CAAC,MAAM;gBAAE,SAAS;YACtB,MAAM,WAAW,GAAI,EAAuC,EAAE,WAAW,CAAC;YAC1E,MAAM,OAAO,GAAG,OAAO,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;YACrE,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,SAAgB,iBAAiB,CAAC,QAAgB;IAChD,IAAI,GAAe,CAAC;IACpB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAA,iBAAY,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAe,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAC7D,OAAO,iBAAiB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAC1C,CAAC"}

package/dist/ast/parse.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Canonical AST access — dxkit's in-process, graphify-independent parser.
+ *
+ * This is the ONE module that touches a tree-sitter engine. Every AST-based
+ * feature (flow extraction today; a future graph builder that could replace
+ * graphify; any later AST analysis) parses through here, so the engine stays
+ * swappable in a single file — the same adapter discipline graphify sits
+ * behind, but for raw parsing.
+ *
+ * Why its own layer (vs graphify): graphify is a high-level *graph builder*
+ * (functions/calls/communities) that does not expose raw call/decorator/
+ * string-literal nodes, and it runs as an optional Python subprocess. This
+ * layer is the low-level *parser*: source → concrete syntax tree, in-process
+ * (web-tree-sitter wasm), no Python, no graphify. It is also the foundation a
+ * future in-house graph builder would consume to migrate the code graph off
+ * graphify.
+ *
+ * Design:
+ *   - **Lazy + graceful.** The wasm engine loads on first use (keeps startup
+ *     fast) and every entry point returns `null` rather than throwing when the
+ *     engine or a grammar is unavailable — AST features degrade, they don't
+ *     crash (mirrors graphify's "unavailable" contract).
+ *   - **Pack-driven grammars (Rule 6).** A file's grammar is resolved from the
+ *     owning pack's `treeSitterGrammars[ext]`; this module never hardcodes a
+ *     per-language mapping. Logical grammar names map to wasm artifacts here,
+ *     so the artifact source (currently `tree-sitter-wasms`, pinned) is
+ *     swappable / vendorable without touching packs.
+ *   - **Cached.** Parser.init runs once; each grammar's `Language` and a bound
+ *     `Parser` are cached for the process.
+ */
+import type { Node, Tree } from 'web-tree-sitter';
+import type { LanguageId } from '../languages/types';
+export type { Node, Tree } from 'web-tree-sitter';
+/** A successfully parsed file. */
+export interface ParsedFile {
+    readonly tree: Tree;
+    readonly source: string;
+    readonly grammar: string;
+    readonly languageId: LanguageId;
+}
+/** Whether the AST engine can be loaded in this environment (for doctor checks). */
+export declare function astEngineAvailable(): Promise<boolean>;
+/**
+ * Parse source text with a named grammar. Returns the tree, or `null` if the
+ * engine or grammar is unavailable (never throws).
+ */
+export declare function parseSource(source: string, grammar: string): Promise<Tree | null>;
+/**
+ * The grammar + owning language for a file extension (with leading dot),
+ * resolved from the active pack registry — or `null` if no pack parses it.
+ */
+export declare function grammarForExtension(ext: string): {
+    grammar: string;
+    languageId: LanguageId;
+} | null;
+/**
+ * Read + parse a file, resolving its grammar from the extension via the pack
+ * registry. Returns `null` if the extension maps to no grammar, the file is
+ * unreadable, or the engine is unavailable.
+ */
+export declare function parseFile(filePath: string): Promise<ParsedFile | null>;
+/**
+ * Depth-first walk of a node and its descendants. The visitor runs on each
+ * node; return `false` to skip a node's children. Consumers use this rather
+ * than walking `node.children` directly so a future engine swap stays
+ * contained in this module.
+ */
+export declare function walk(node: Node, visit: (node: Node) => void | boolean): void;
+/** Test seam: drop cached engine/grammars/parsers so a test can re-init. */
+export declare function resetAstCachesForTest(): void;
+//# sourceMappingURL=parse.d.ts.map

package/dist/ast/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/ast/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,KAAK,EAAY,IAAI,EAAU,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIrD,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAElD,kCAAkC;AAClC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AA4ED,oFAAoF;AACpF,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,OAAO,CAAC,CAE3D;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAUvF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,GACV;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,GAAG,IAAI,CAOpD;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAY5E;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,GAAG,OAAO,GAAG,IAAI,CAM5E;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,IAAI,IAAI,CAK5C"}