@vyuhlabs/dxkit 2.18.1 → 2.20.0

package/dist/ast/parse.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.astEngineAvailable = astEngineAvailable;
+exports.parseSource = parseSource;
+exports.grammarForExtension = grammarForExtension;
+exports.parseFile = parseFile;
+exports.walk = walk;
+exports.resetAstCachesForTest = resetAstCachesForTest;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const languages_1 = require("../languages");
+let enginePromise = null;
+const languageCache = new Map();
+const parserCache = new Map();
+let warnedUnavailable = false;
+/**
+ * Resolve a dependency's installed directory via its package.json (works
+ * around packages whose `main`/`exports` block direct resolution — e.g.
+ * `tree-sitter-wasms`' broken `main`, and `web-tree-sitter`' exports-gated
+ * package.json: resolve the runtime entry for that one).
+ */
+function runtimeWasmPath() {
+    return (0, path_1.join)((0, path_1.dirname)(require.resolve('web-tree-sitter')), 'tree-sitter.wasm');
+}
+function grammarWasmPath(grammar) {
+    const wasmsDir = (0, path_1.dirname)(require.resolve('tree-sitter-wasms/package.json'));
+    return (0, path_1.join)(wasmsDir, 'out', `tree-sitter-${grammar}.wasm`);
+}
+/** Lazily load + init the wasm engine. Returns null (once-warned) on failure. */
+async function getEngine() {
+    if (enginePromise)
+        return enginePromise;
+    enginePromise = (async () => {
+        try {
+            // Dynamic import keeps the engine out of the startup path; web-tree-sitter
+            // is require-compatible so this resolves cleanly under CommonJS output.
+            const mod = await Promise.resolve().then(() => __importStar(require('web-tree-sitter')));
+            const runtime = runtimeWasmPath();
+            await mod.Parser.init({ locateFile: () => runtime });
+            return { ParserCtor: mod.Parser, LanguageCtor: mod.Language };
+        }
+        catch (err) {
+            if (!warnedUnavailable) {
+                warnedUnavailable = true;
+                const reason = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[dxkit] AST engine unavailable, skipping AST features: ${reason}\n`);
+            }
+            return null;
+        }
+    })();
+    return enginePromise;
+}
+async function getLanguage(engine, grammar) {
+    if (languageCache.has(grammar))
+        return languageCache.get(grammar) ?? null;
+    let lang = null;
+    try {
+        lang = await engine.LanguageCtor.load(grammarWasmPath(grammar));
+    }
+    catch {
+        lang = null; // grammar artifact missing/unreadable → that language degrades
+    }
+    languageCache.set(grammar, lang);
+    return lang;
+}
+async function getParser(engine, grammar) {
+    const cached = parserCache.get(grammar);
+    if (cached)
+        return cached;
+    const lang = await getLanguage(engine, grammar);
+    if (!lang)
+        return null;
+    const parser = new engine.ParserCtor();
+    parser.setLanguage(lang);
+    parserCache.set(grammar, parser);
+    return parser;
+}
+// ── Public API ──────────────────────────────────────────────────────────────
+/** Whether the AST engine can be loaded in this environment (for doctor checks). */
+async function astEngineAvailable() {
+    return (await getEngine()) !== null;
+}
+/**
+ * Parse source text with a named grammar. Returns the tree, or `null` if the
+ * engine or grammar is unavailable (never throws).
+ */
+async function parseSource(source, grammar) {
+    const engine = await getEngine();
+    if (!engine)
+        return null;
+    const parser = await getParser(engine, grammar);
+    if (!parser)
+        return null;
+    try {
+        return parser.parse(source);
+    }
+    catch {
+        return 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.
+ */
+function grammarForExtension(ext) {
+    const lower = ext.toLowerCase();
+    for (const pack of languages_1.LANGUAGES) {
+        const grammar = pack.treeSitterGrammars?.[lower];
+        if (grammar)
+            return { grammar, languageId: pack.id };
+    }
+    return 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.
+ */
+async function parseFile(filePath) {
+    const resolved = grammarForExtension((0, path_1.extname)(filePath));
+    if (!resolved)
+        return null;
+    let source;
+    try {
+        source = (0, fs_1.readFileSync)(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const tree = await parseSource(source, resolved.grammar);
+    if (!tree)
+        return null;
+    return { tree, source, grammar: resolved.grammar, languageId: resolved.languageId };
+}
+/**
+ * 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.
+ */
+function walk(node, visit) {
+    const proceed = visit(node);
+    if (proceed === false)
+        return;
+    for (const child of node.children) {
+        if (child)
+            walk(child, visit);
+    }
+}
+/** Test seam: drop cached engine/grammars/parsers so a test can re-init. */
+function resetAstCachesForTest() {
+    enginePromise = null;
+    languageCache.clear();
+    parserCache.clear();
+    warnedUnavailable = false;
+}
+//# sourceMappingURL=parse.js.map

package/dist/ast/parse.js.map

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

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuSA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA64DvD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuSA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA67DvD"}

package/dist/cli.js

@@ -318,6 +318,9 @@ async function run(argv) {
             xlsx: { type: 'boolean', default: false },
             filter: { type: 'string' },
             all: { type: 'boolean', default: false },
+            frontend: { type: 'string' },
+            backend: { type: 'string' },
+            specs: { type: 'string' },
             'reports-dir': { type: 'string' },
             'json-dir': { type: 'string' },
             'project-name': { type: 'string' },
@@ -820,6 +823,49 @@ async function run(argv) {
             });
             break;
         }
+        case 'flow': {
+            const subCommand = positionals[1];
+            const frontend = values.frontend;
+            const backend = values.backend;
+            const specs = values.specs;
+            // `flow` / `flow map` → the traceability map (writes the graph overlay).
+            if (subCommand === undefined || subCommand === 'map') {
+                const { runFlowMap } = await Promise.resolve().then(() => __importStar(require('./flow-cli')));
+                await runFlowMap({ cwd, frontend, backend, specs, json: !!values.json });
+                break;
+            }
+            // `flow trace "<METHOD> <path>"` → one endpoint's full trace.
+            if (subCommand === 'trace') {
+                const target = positionals.slice(2).join(' ').trim();
+                if (!target) {
+                    logger.fail('Usage: vyuh-dxkit flow trace "<METHOD> <path>"');
+                    process.exit(1);
+                }
+                const { runFlowTrace } = await Promise.resolve().then(() => __importStar(require('./flow-cli')));
+                await runFlowTrace({ cwd, frontend, backend, specs, json: !!values.json, target });
+                break;
+            }
+            // `flow extract` → the parity CSVs.
+            if (subCommand === 'extract') {
+                const { runFlowExtract } = await Promise.resolve().then(() => __importStar(require('./flow-cli')));
+                await runFlowExtract({
+                    cwd,
+                    frontend,
+                    backend,
+                    specs,
+                    out: values.out,
+                    json: !!values.json,
+                });
+                break;
+            }
+            logger.fail(`Unknown flow subcommand: ${subCommand}`);
+            logger.info('Usage:');
+            logger.info('  vyuh-dxkit flow [map] [--frontend <dir>] [--backend <dir>] [--specs <a,b>]');
+            logger.info('  vyuh-dxkit flow trace "<METHOD> <path>"');
+            logger.info('  vyuh-dxkit flow extract [--out <dir>]');
+            process.exit(1);
+            break;
+        }
         case 'vulnerabilities':
         case 'vuln': {
             const targetPath = resolveRepoPath(positionals[1]);