@untangle-code/cli 0.0.0-stage → 0.1.0

package/dist/commands/extensions.js

@@ -0,0 +1,223 @@
+import { enumFlag } from "../cli/args.js";
+import { EXIT, UsageError } from "../cli/exit.js";
+import { runAdd } from "./extensions/add.js";
+import { runConfigure } from "./extensions/configure.js";
+import { runDisable, runEnable } from "./extensions/enable.js";
+import { createExtensionEnvironment } from "./extensions/environment.js";
+import { runList } from "./extensions/list.js";
+import { runLogs } from "./extensions/logs.js";
+import { runRemove } from "./extensions/remove.js";
+import { runRun } from "./extensions/run.js";
+import { runStatus } from "./extensions/status.js";
+const FLAGS = {
+    from: {
+        kind: "string",
+        placeholder: "URL|PATH",
+        describe: "add: manifest source. configure: private JSON file containing secret values.",
+    },
+    digest: {
+        kind: "string",
+        placeholder: "sha256:HEX",
+        describe: "add: expected manifest sha256. Required for a URL.",
+    },
+    "allow-project-local": {
+        kind: "boolean",
+        describe: "add: explicitly allow a path inside the project directory.",
+    },
+    force: {
+        kind: "boolean",
+        describe: "add: replace an installed extension with the same ID.",
+    },
+    "acknowledge-license": {
+        kind: "boolean",
+        describe: "add/enable: acknowledge the tool-license gate, not the ruleset gate.",
+    },
+    "acknowledge-ruleset": {
+        kind: "list",
+        placeholder: "ID",
+        describe: "add/enable: acknowledge exactly one ruleset. Repeatable.",
+    },
+    "revoke-license": {
+        kind: "boolean",
+        describe: "disable/remove: revoke the stored license acknowledgment.",
+    },
+    category: {
+        kind: "string",
+        placeholder: "C,...",
+        describe: "list: show only extensions in these categories.",
+    },
+    "enabled-only": {
+        kind: "boolean",
+        describe: "list: show only enabled extensions.",
+    },
+    yes: {
+        kind: "boolean",
+        describe: "run/setup: allow container provisioning and missing-credential setup (X1).",
+    },
+    tail: {
+        kind: "number",
+        placeholder: "N",
+        describe: "logs: number of trailing lines.",
+        defaultLabel: "200",
+    },
+    "remove-container": {
+        kind: "boolean",
+        describe: "disable: stop and remove only the owned container, verified by its labels.",
+    },
+    "remove-volumes": {
+        kind: "boolean",
+        describe: "disable: also remove named volumes. Destructive.",
+    },
+    workspace: {
+        kind: "string",
+        placeholder: "PATH",
+        describe: "run: root of the analyzed workspace.",
+        defaultLabel: "current directory",
+    },
+    target: {
+        kind: "string",
+        placeholder: "PATH",
+        describe: "run: analysis target inside the workspace.",
+        defaultLabel: "the workspace",
+    },
+    ruleset: {
+        kind: "string",
+        placeholder: "NAME",
+        describe: "run: effective ruleset; otherwise the manifest's defaultRuleset applies.",
+    },
+    url: {
+        kind: "string",
+        placeholder: "URL",
+        describe: "run: endpoint for invocation kind `http`.",
+    },
+    timeout: {
+        kind: "number",
+        placeholder: "MS",
+        describe: "run: execution time budget in milliseconds.",
+        defaultLabel: "900000",
+    },
+    "max-output-bytes": {
+        kind: "number",
+        placeholder: "N",
+        describe: "run: maximum collected tool-output bytes.",
+    },
+    format: {
+        kind: "string",
+        placeholder: "text|json",
+        describe: "Output format.",
+        defaultLabel: "text",
+    },
+};
+/**
+ * Which flags each subcommand accepts.
+ *
+ * The parser validates flags against the union above; this table catches the
+ * rest. Without it, `untangle extensions list --from=x` would be silently
+ * accepted and silently ignored — precisely the kind of quiet skip E4
+ * forbids, one layer above the pipeline.
+ */
+const ALLOWED_FLAGS = {
+    add: [
+        "from",
+        "digest",
+        "allow-project-local",
+        "force",
+        "acknowledge-license",
+        "acknowledge-ruleset",
+        "format",
+    ],
+    list: ["category", "enabled-only", "format"],
+    status: ["format"],
+    configure: ["from", "format"],
+    setup: ["workspace", "url", "timeout", "max-output-bytes", "yes", "format"],
+    logs: ["tail", "format"],
+    enable: ["acknowledge-license", "acknowledge-ruleset", "format"],
+    disable: ["revoke-license", "remove-container", "remove-volumes", "format"],
+    remove: ["revoke-license", "format"],
+    run: ["workspace", "target", "ruleset", "url", "timeout", "max-output-bytes", "yes", "format"],
+};
+const SUBCOMMANDS = Object.keys(ALLOWED_FLAGS);
+export const extensionsCommand = {
+    spec: {
+        name: "extensions",
+        implementedBy: "commands/extensions.js",
+        summary: "Manage and run analyzer extensions",
+        usage: "untangle extensions <add|list|status|configure|setup|enable|disable|remove|run|logs> [options]",
+        details: [
+            "Untangle supplies the extension runtime, manifest schema and format parsers, without bundled tool definitions. A manifest is an external artifact you explicitly load (extensions.md §17, X9). The runtime understands formats (sarif, junit-xml, generic-findings, generic-metrics), not individual tools.",
+            "Trust boundary: manifests in the project directory are never loaded automatically. Discovery searches only the user profile (~/.untangle/extensions/<id>/manifest.toml and the OS data directory). A manifest specifies how to launch a program; trusting a cloned project's manifest automatically would allow unrequested execution. `add --from` therefore rejects project-local paths unless --allow-project-local is explicit.",
+            "Likewise, `add --from <https-URL>` requires --digest: changing content behind a stable URL could silently change findings. X6 forbids mutable container tags for the same reason.",
+            "Installing a manifest starts nothing. `enable` records activation without launching processes or containers (X1). Restrictively licensed tools require explicit personal acknowledgment (X5).",
+            "`status` previews the effective pinned image digest, running digest and comparison, license and ruleset gates, endpoint and last run. It neither starts containers nor pulls images (X1); an open gate also prevents version probes (X5).",
+            "setup --yes provisions the service, configures missing credentials through the manifest's declared setup process and verifies them with an analysis run. configure creates private secret configuration or imports values with --from. Environment variables take precedence; status creates no tokens.",
+            "External tool findings are `ExternalFindingV1`: evidence, never Untangle metrics. They never contribute to complexity values or Risk Score (X3), and never change the exit code.",
+        ],
+        flags: FLAGS,
+        examples: [
+            "untangle extensions add --from=./my-analyzer/manifest.toml",
+            "untangle extensions add --from=https://example.invalid/manifest.toml --digest=sha256:<64 hex>",
+            "untangle extensions list --format=json",
+            "untangle extensions status my-analyzer",
+            "untangle extensions configure my-analyzer",
+            "untangle extensions setup my-analyzer --yes",
+            "untangle extensions enable my-analyzer --acknowledge-license",
+            "untangle extensions run my-analyzer --target=src --format=json",
+            "untangle extensions remove my-analyzer --revoke-license",
+        ],
+        exitCodes: [
+            [EXIT.ok, "The command completed. Findings do not change this code (X3)."],
+            [EXIT.operational, "Invalid manifest, missing extension or failed run."],
+            [EXIT.usage, "Usage error: unknown subcommand, missing or unsupported option."],
+            [
+                EXIT.environment,
+                "License/ruleset gate is open, or a required secret is missing. Nothing was started.",
+            ],
+        ],
+    },
+    async run(ctx, args) {
+        const subcommand = args.positionals[0];
+        if (subcommand === undefined) {
+            throw new UsageError("`untangle extensions` needs a subcommand.", `Choose one of: ${SUBCOMMANDS.join(", ")} — see untangle extensions --help.`);
+        }
+        const allowed = ALLOWED_FLAGS[subcommand];
+        if (allowed === undefined) {
+            throw new UsageError(`Unknown subcommand "extensions ${subcommand}".`, `Choose one of: ${SUBCOMMANDS.join(", ")}.`);
+        }
+        rejectForeignFlags(subcommand, args, allowed);
+        const format = enumFlag(args, "format", ["text", "json"], "text");
+        const environment = await createExtensionEnvironment({ cwd: ctx.cwd, env: ctx.env });
+        switch (subcommand) {
+            case "add":
+                return await runAdd(environment, args, ctx.io, format);
+            case "list":
+                return await runList(environment, args, ctx.io, format);
+            case "status":
+                return await runStatus(environment, args, ctx.io, format);
+            case "logs":
+                return await runLogs(environment, args, ctx.io, format);
+            case "enable":
+                return await runEnable(environment, args, ctx.io, format);
+            case "disable":
+                return await runDisable(environment, args, ctx.io, format);
+            case "remove":
+                return await runRemove(environment, args, ctx.io, format);
+            case "configure":
+                return await runConfigure(environment, args, ctx.io, format);
+            case "setup":
+            case "run":
+                return await runRun(environment, args, ctx.io, format, { signal: ctx.signal });
+            default:
+                throw new UsageError(`Unknown subcommand "extensions ${subcommand}".`, `Choose one of: ${SUBCOMMANDS.join(", ")}.`);
+        }
+    },
+};
+function rejectForeignFlags(subcommand, args, allowed) {
+    const foreign = Object.keys(args.flags)
+        .filter((name) => !allowed.includes(name))
+        .sort();
+    if (foreign.length === 0) {
+        return;
+    }
+    throw new UsageError(`"extensions ${subcommand}" does not accept ${foreign.map((name) => `--${name}`).join(", ")}.`, `Accepted here: ${allowed.map((name) => `--${name}`).join(", ")}.`);
+}
+//# sourceMappingURL=extensions.js.map

package/dist/commands/extensions.js.map

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

package/dist/commands/flow/index.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "../../cli/command.js";
+export declare const flowCommand: Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/flow/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/flow/index.ts"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,sBAAsB,CAAC;AA+EpE,eAAO,MAAM,WAAW,EAAE,OA+OzB,CAAC"}

package/dist/commands/flow/index.js

@@ -0,0 +1,295 @@
+/**
+ * `untangle flow` — der Symbolgraph als Oberflaeche: wer ruft wen, auf
+ * welchem Weg, und wie sicher ist das.
+ *
+ * Er baut nichts. Er liest den Shard `symbol-graph`, den `untangle index`
+ * abgelegt hat, und beantwortet vier Fragen:
+ *
+ *   1. WEG: Welche Aufrufpfade fuehren von einem Symbol zu einem anderen —
+ *      der kuerzeste, und alle bis Tiefe N.
+ *   2. ANFANG: Welche Symbole sind Einstiegspunkte (WP-88: verwaiste Symbole,
+ *      konventionelle Namen, Testdateien, Routenverzeichnisse)?
+ *   3. SICHERHEIT: Jede Kante auf jedem Weg traegt ihre Aufloesungsart
+ *      (exact/heuristic/ambiguous/unresolved) und ihre Confidence mit Basis
+ *      und Signalen. Eine MEHRDEUTIGE Kante zeigt ALLE Kandidaten — es wird
+ *      keiner ausgewaehlt.
+ *   4. WIRKUNG: Welche Symbole sind von einer Aenderung an X betroffen, und
+ *      wie sicher ist diese Aussage (`--impact`)?
+ *
+ * DETERMINISMUS: Dieser Befehl gibt den Traversierungen bewusst KEINE
+ * Zeitquelle mit. Das Zeitbudget waere die einzige Groesse, die zwei Laeufe
+ * ueber denselben Index verschieden ausgehen liesse; Tiefe, Knoten- und
+ * Kantenbudget begrenzen die Arbeit ohnehin. Zwei Aufrufe liefern damit
+ * dieselbe Ausgabe.
+ */
+import path from "node:path";
+import { DEFAULT_TRAVERSAL_LIMITS } from "@untangle-code/file-graph";
+import { analyzeImpact, createSymbolGraphIndex, detectEntryPoints, findAllCallPaths, findShortestCallPath, } from "@untangle-code/symbol-graph";
+import { boolFlag, enumFlag, integerFlag, numberFlag, stringFlag, } from "../../cli/args.js";
+import { EXIT, EnvironmentError, OperationalError, UsageError } from "../../cli/exit.js";
+import { loadGraphs } from "../../cli/graphs.js";
+import { line, note } from "../../cli/io.js";
+import { renderIssues } from "../graph/render.js";
+import { DEFAULT_FLOW_DEPTH, DEFAULT_FLOW_RESULT_LIMIT, MAX_FLOW_DEPTH, MAX_FLOW_EDGES, MAX_FLOW_NODES, MAX_FLOW_RESULT_LIMIT, } from "./limits.js";
+import { limitItems } from "./output.js";
+import { renderAllPaths, renderEntryPoints, renderImpact, renderShortest, renderSymbolGraphHeader, renderSymbolOverview, } from "./render.js";
+import { describeSymbol, selectSymbolNode } from "./select.js";
+const FLAGS = {
+    root: {
+        kind: "string",
+        placeholder: "PATH",
+        describe: "Project directory; configuration is discovered from here.",
+        defaultLabel: "current directory",
+    },
+    depth: {
+        kind: "number",
+        placeholder: "N",
+        describe: "Maximum path length or impact-analysis depth.",
+        defaultLabel: String(DEFAULT_FLOW_DEPTH),
+    },
+    limit: {
+        kind: "number",
+        alias: "n",
+        placeholder: "N",
+        describe: "Maximum number of displayed paths, entry points or affected symbols.",
+        defaultLabel: String(DEFAULT_FLOW_RESULT_LIMIT),
+    },
+    "entry-points": {
+        kind: "boolean",
+        describe: "List entry points instead of searching paths (heuristic, with evidence).",
+    },
+    impact: {
+        kind: "boolean",
+        describe: "Impact analysis: which symbols depend on the selected symbol.",
+    },
+    "min-confidence": {
+        kind: "number",
+        placeholder: "X",
+        describe: "Minimum path confidence for --impact; excluded paths remain reported.",
+        defaultLabel: "0",
+    },
+    "max-nodes": {
+        kind: "number",
+        placeholder: "N",
+        describe: "Traversal node budget.",
+        defaultLabel: String(DEFAULT_TRAVERSAL_LIMITS.maxNodes),
+    },
+    "max-edges": {
+        kind: "number",
+        placeholder: "N",
+        describe: "Traversal edge budget.",
+        defaultLabel: String(DEFAULT_TRAVERSAL_LIMITS.maxEdges),
+    },
+    format: {
+        kind: "string",
+        placeholder: "text|json",
+        describe: "Output format. json contains the same information in machine-readable form.",
+        defaultLabel: "text",
+    },
+};
+export const flowCommand = {
+    spec: {
+        name: "flow",
+        implementedBy: "commands/flow/index.js",
+        summary: "Show call paths between symbols",
+        usage: "untangle flow <from> [<to>] | untangle flow --entry-points | untangle flow <symbol> --impact",
+        details: [
+            "Three forms: `flow <from> <to>` finds call paths, including the shortest and all paths up to depth N. `flow <symbol>` shows its callers and callees. `flow <symbol> --impact` identifies dependent symbols and the confidence of each relationship.",
+            "`--entry-points` lists detected entry points: orphan symbols, conventional start names, test symbols and symbols in route directories. Detection is heuristic; each entry includes its evidence and individual weights.",
+            "Every edge includes its resolution and confidence: exact (proven), heuristic (plausible), ambiguous (multiple candidates), unresolved (no target, with a reason). Ambiguous edges show all weighted candidates without selecting one.",
+            "A name matching multiple symbols is never guessed: candidates are shown with file and line, and the command exits with code 2. Use `path/file.ts:name` or a qualified name to select one.",
+            "Reads the stored graph. A missing graph produces exit code 4 and points to `untangle index`; it never claims there are no calls.",
+        ],
+        flags: FLAGS,
+        examples: [
+            "untangle flow --entry-points",
+            "untangle flow main calculateDiscount",
+            "untangle flow services/api/src/orders.ts:calculateDiscount --impact",
+            "untangle flow calculateDiscount --format=json",
+        ],
+        exitCodes: [
+            [EXIT.ok, "The symbol graph was read and displayed."],
+            [EXIT.operational, "Operational error, or the selected symbol is absent from the graph."],
+            [EXIT.usage, "Usage error, or an ambiguous symbol name."],
+            [EXIT.environment, "No symbol graph is available; run `untangle index`."],
+        ],
+    },
+    async run(ctx, args) {
+        const format = enumFlag(args, "format", ["text", "json"], "text");
+        const depth = integerFlag(args, "depth", DEFAULT_FLOW_DEPTH);
+        if (depth < 1 || depth > MAX_FLOW_DEPTH) {
+            throw new UsageError(`Option "--depth" requires 1 to ${String(MAX_FLOW_DEPTH)}; received "${String(depth)}".`, "Example: --depth=6");
+        }
+        const limit = integerFlag(args, "limit", DEFAULT_FLOW_RESULT_LIMIT);
+        if (limit < 1 || limit > MAX_FLOW_RESULT_LIMIT) {
+            throw new UsageError(`Option "--limit" requires 1 to ${String(MAX_FLOW_RESULT_LIMIT)}; received "${String(limit)}".`, "Example: --limit=20");
+        }
+        const maxNodes = integerFlag(args, "max-nodes", DEFAULT_TRAVERSAL_LIMITS.maxNodes);
+        if (maxNodes < 1 || maxNodes > MAX_FLOW_NODES) {
+            throw new UsageError(`Option "--max-nodes" requires 1 to ${String(MAX_FLOW_NODES)}; received "${String(maxNodes)}".`, `Example: --max-nodes=${String(DEFAULT_TRAVERSAL_LIMITS.maxNodes)}`);
+        }
+        const maxEdges = integerFlag(args, "max-edges", DEFAULT_TRAVERSAL_LIMITS.maxEdges);
+        if (maxEdges < 1 || maxEdges > MAX_FLOW_EDGES) {
+            throw new UsageError(`Option "--max-edges" requires 1 to ${String(MAX_FLOW_EDGES)}; received "${String(maxEdges)}".`, `Example: --max-edges=${String(DEFAULT_TRAVERSAL_LIMITS.maxEdges)}`);
+        }
+        const wantEntryPoints = boolFlag(args, "entry-points");
+        const wantImpact = boolFlag(args, "impact");
+        const minConfidence = numberFlag(args, "min-confidence") ?? 0;
+        if (minConfidence < 0 || minConfidence > 1) {
+            throw new UsageError(`Option "--min-confidence" requires a value in [0, 1]; received "${String(minConfidence)}".`, "Example: --min-confidence=0.5");
+        }
+        const rootFlag = stringFlag(args, "root");
+        const positionals = args.positionals;
+        if (!wantEntryPoints && positionals.length === 0) {
+            throw new UsageError("A symbol is required.", "Use `untangle flow <from> <to>`, `untangle flow <symbol> [--impact]`, or `untangle flow --entry-points`.");
+        }
+        if (wantEntryPoints && positionals.length > 0) {
+            throw new UsageError("`--entry-points` lists the entire graph and does not accept a symbol.", "Omit the argument, or query a symbol without --entry-points.");
+        }
+        if (positionals.length > 2) {
+            throw new UsageError(`Expected at most two symbols; received ${String(positionals.length)}.`, "Use `untangle flow <from> <to>`.");
+        }
+        if (wantImpact && positionals.length === 2) {
+            throw new UsageError("`--impact` examines the impact of one symbol, not a path between two symbols.", "Omit the second symbol, or query the path without --impact.");
+        }
+        const loaded = await loadGraphs({
+            cwd: ctx.cwd,
+            env: ctx.env,
+            signal: ctx.signal,
+            ...(rootFlag === undefined ? {} : { root: path.resolve(ctx.cwd, rootFlag) }),
+        });
+        for (const issue of renderIssues(loaded.issues))
+            note(ctx.io, issue);
+        const symbolGraph = requireSymbolGraph(loaded);
+        const index = createSymbolGraphIndex(symbolGraph.graph);
+        const limits = {
+            maxDepth: depth,
+            maxNodes,
+            maxEdges,
+            maxWallTimeMs: DEFAULT_TRAVERSAL_LIMITS.maxWallTimeMs,
+        };
+        const header = renderSymbolGraphHeader(index, loaded.generationId, symbolGraph.ledgerInShard);
+        /* --------------------------- Einstiegspunkte ---------------------- */
+        if (wantEntryPoints) {
+            const set = detectEntryPoints(index);
+            if (format === "json") {
+                line(ctx.io, JSON.stringify({ generationId: loaded.generationId, entryPoints: set }, null, 2));
+                return EXIT.ok;
+            }
+            for (const text of [...header, "", ...renderEntryPoints(set, limit)])
+                line(ctx.io, text);
+            return EXIT.ok;
+        }
+        const from = resolveSymbol(index, positionals[0]);
+        /* ------------------------------ Wirkung --------------------------- */
+        if (wantImpact) {
+            const result = analyzeImpact(index, {
+                rootSymbolIds: [from.id],
+                limits,
+                minConfidence,
+            });
+            if (format === "json") {
+                const affected = limitItems(result.affected, limit);
+                line(ctx.io, JSON.stringify({
+                    generationId: loaded.generationId,
+                    root: from,
+                    impact: { ...result, affected: affected.items },
+                    truncated: affected.truncated,
+                    omittedCount: affected.omittedCount,
+                }, null, 2));
+                return EXIT.ok;
+            }
+            for (const text of [
+                ...header,
+                "",
+                `IMPACT OF A CHANGE TO  ${describeSymbol(from)}`,
+                "",
+                ...renderImpact(index, result, limit),
+            ]) {
+                line(ctx.io, text);
+            }
+            return EXIT.ok;
+        }
+        /* --------------------------- Einzelnes Symbol --------------------- */
+        if (positionals.length === 1) {
+            if (format === "json") {
+                const outgoing = limitItems(index.outgoingEdges(from.id), limit);
+                const callers = limitItems(index.callers(from.id), limit);
+                const omittedCount = outgoing.omittedCount + callers.omittedCount;
+                line(ctx.io, JSON.stringify({
+                    generationId: loaded.generationId,
+                    symbol: from,
+                    outgoing: outgoing.items,
+                    callers: callers.items,
+                    truncated: omittedCount > 0,
+                    omittedCount,
+                }, null, 2));
+                return EXIT.ok;
+            }
+            for (const text of [...header, "", ...renderSymbolOverview(index, from)])
+                line(ctx.io, text);
+            return EXIT.ok;
+        }
+        /* ------------------------------- Pfade ---------------------------- */
+        const to = resolveSymbol(index, positionals[1]);
+        const shortest = findShortestCallPath(index, {
+            fromSymbolId: from.id,
+            toSymbolId: to.id,
+            limits,
+        });
+        const all = findAllCallPaths(index, {
+            fromSymbolId: from.id,
+            toSymbolId: to.id,
+            maxDepth: depth,
+            maxPaths: limit,
+            maxNodes,
+            maxEdges,
+        });
+        if (format === "json") {
+            line(ctx.io, JSON.stringify({ generationId: loaded.generationId, from, to, shortest, all }, null, 2));
+            return EXIT.ok;
+        }
+        for (const text of [
+            ...header,
+            "",
+            `VON   ${describeSymbol(from)}`,
+            `TO    ${describeSymbol(to)}`,
+            "",
+            // `false`: siehe Kopfkommentar — dieser Befehl gibt der Suche keine
+            // Zeitquelle, das Zeitbudget ist also nicht durchgesetzt und sagt das.
+            ...renderShortest(index, shortest, false),
+            "",
+            ...renderAllPaths(index, all),
+        ]) {
+            line(ctx.io, text);
+        }
+        return EXIT.ok;
+    },
+};
+/* ------------------------------------------------------------------ */
+function requireSymbolGraph(loaded) {
+    if (loaded.symbolGraph !== null)
+        return loaded.symbolGraph;
+    throw new EnvironmentError(`No symbol graph is available: ${loaded.symbolGraphMissingReason ?? "no reason given"} ` +
+        "Nothing was searched; this does not mean there are no calls.", "Run `untangle index` to store the symbol-graph shard.");
+}
+/**
+ * Das Symbol zur Nutzereingabe — oder ein Abbruch, der die Kandidaten nennt.
+ * Geraten wird nie (architecture.md §17.2 gilt auch fuer die Oberflaeche).
+ */
+function resolveSymbol(index, query) {
+    const selection = selectSymbolNode(index.nodes(), query);
+    if (selection.status === "found")
+        return selection.node;
+    if (selection.status === "ambiguous") {
+        const list = selection.candidates.map((node) => `\n    ${describeSymbol(node)}`).join("");
+        throw new UsageError(`"${query}" matches ${String(selection.candidates.length)} symbols (${selection.matchedBy}) — ` +
+            `no candidate is selected:${list}`, "Select one using `path/file.ts:name` or the qualified name.");
+    }
+    const near = selection.near.length === 0
+        ? ""
+        : ` Similar names: ${selection.near.map((node) => node.qualifiedName).join(", ")}.`;
+    throw new OperationalError(`Symbol "${query}" is absent from the symbol graph. Nothing was evaluated; ` +
+        `this does not mean there are no calls.${near}`, "Check the name or run `untangle index` again. `untangle flow --entry-points` lists known symbols.");
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/flow/index.js.map

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

package/dist/commands/flow/limits.d.ts

@@ -0,0 +1,12 @@
+/** Public CLI/MCP resource ceilings for symbol-graph reads. */
+export declare const DEFAULT_FLOW_DEPTH = 6;
+export declare const MAX_FLOW_DEPTH = 64;
+export declare const DEFAULT_FLOW_RESULT_LIMIT = 20;
+export declare const MAX_FLOW_RESULT_LIMIT = 1000;
+export declare const MAX_FLOW_NODES: number;
+export declare const MAX_FLOW_EDGES: number;
+/** MCP graph queries deliberately expose the bounded neighborhood form only. */
+export declare const MAX_GRAPH_QUERY_DEPTH: number;
+export declare const MAX_GRAPH_QUERY_NODES: number;
+export declare const MAX_GRAPH_QUERY_EDGES: number;
+//# sourceMappingURL=limits.d.ts.map

package/dist/commands/flow/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../../src/commands/flow/limits.ts"],"names":[],"mappings":"AAEA,+DAA+D;AAC/D,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAC5C,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAC3C,eAAO,MAAM,cAAc,QAAoC,CAAC;AAChE,eAAO,MAAM,cAAc,QAAoC,CAAC;AAEhE,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,QAAoC,CAAC;AACvE,eAAO,MAAM,qBAAqB,QAAoC,CAAC;AACvE,eAAO,MAAM,qBAAqB,QAAoC,CAAC"}

package/dist/commands/flow/limits.js

@@ -0,0 +1,13 @@
+import { DEFAULT_TRAVERSAL_LIMITS } from "@untangle-code/file-graph";
+/** Public CLI/MCP resource ceilings for symbol-graph reads. */
+export const DEFAULT_FLOW_DEPTH = 6;
+export const MAX_FLOW_DEPTH = 64;
+export const DEFAULT_FLOW_RESULT_LIMIT = 20;
+export const MAX_FLOW_RESULT_LIMIT = 1_000;
+export const MAX_FLOW_NODES = DEFAULT_TRAVERSAL_LIMITS.maxNodes;
+export const MAX_FLOW_EDGES = DEFAULT_TRAVERSAL_LIMITS.maxEdges;
+/** MCP graph queries deliberately expose the bounded neighborhood form only. */
+export const MAX_GRAPH_QUERY_DEPTH = DEFAULT_TRAVERSAL_LIMITS.maxDepth;
+export const MAX_GRAPH_QUERY_NODES = DEFAULT_TRAVERSAL_LIMITS.maxNodes;
+export const MAX_GRAPH_QUERY_EDGES = DEFAULT_TRAVERSAL_LIMITS.maxEdges;
+//# sourceMappingURL=limits.js.map

package/dist/commands/flow/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../../src/commands/flow/limits.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAErE,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AACpC,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC;AACjC,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAC5C,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAC3C,MAAM,CAAC,MAAM,cAAc,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AAChE,MAAM,CAAC,MAAM,cAAc,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AAEhE,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AACvE,MAAM,CAAC,MAAM,qBAAqB,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AACvE,MAAM,CAAC,MAAM,qBAAqB,GAAG,wBAAwB,CAAC,QAAQ,CAAC"}

package/dist/commands/flow/output.d.ts

@@ -0,0 +1,8 @@
+export interface LimitedItems<T> {
+    items: T[];
+    truncated: boolean;
+    omittedCount: number;
+}
+/** Bounded presentation helper shared by text-independent JSON surfaces. */
+export declare function limitItems<T>(items: readonly T[], limit: number): LimitedItems<T>;
+//# sourceMappingURL=output.d.ts.map

package/dist/commands/flow/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../../src/commands/flow/output.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAQjF"}

package/dist/commands/flow/output.js

@@ -0,0 +1,11 @@
+/** Bounded presentation helper shared by text-independent JSON surfaces. */
+export function limitItems(items, limit) {
+    const boundedLimit = Math.max(0, Math.floor(limit));
+    const omittedCount = Math.max(0, items.length - boundedLimit);
+    return {
+        items: items.slice(0, boundedLimit),
+        truncated: omittedCount > 0,
+        omittedCount,
+    };
+}
+//# sourceMappingURL=output.js.map

package/dist/commands/flow/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../../src/commands/flow/output.ts"],"names":[],"mappings":"AAMA,4EAA4E;AAC5E,MAAM,UAAU,UAAU,CAAI,KAAmB,EAAE,KAAa;IAC9D,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IACpD,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,YAAY,CAAC,CAAC;IAC9D,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC;QACnC,SAAS,EAAE,YAAY,GAAG,CAAC;QAC3B,YAAY;KACb,CAAC;AACJ,CAAC"}