@opensip-cli/graph 0.1.6 → 0.1.8

package/dist/cli/graph/graph-aux-command-specs.js

@@ -1,21 +1,27 @@
-// @fitness-ignore-file no-direct-stdout-in-tool-engine -- auxiliary subcommand status line: `graph-baseline-export` writes the JSON baseline to a file and prints a one-line "Exported graph baseline to <path>" confirmation (the --json path uses cli.emitJson). This is not the signal-envelope run output (ADR-0011), which routes through the composition root.
+// @fitness-ignore-file no-direct-stdout-in-tool-engine -- auxiliary subcommand status line: `graph export --format baseline` writes the JSON baseline to a file and prints a one-line "Exported graph baseline to <path>" confirmation (the --json path uses cli.emitJson). This is not the signal-envelope run output (ADR-0011), which routes through the composition root.
 // @fitness-ignore-file detached-promises -- async command handlers invoke synchronous helpers (runCatalogJsonMode/runSarifExportMode/handleGraphError all return void); the heuristic flags them inside the async handlers. Matches the sibling graph CLI files (graph.ts, graph-modes.ts, orchestrate.ts).
 // @fitness-ignore-file only-documented-toolcli-seams -- same rationale as the no-direct-stdout waiver above: the one-line "Exported graph baseline to <path>" status confirmation after a file write; the --json path uses cli.emitJson. Not run output through a ToolCliContext seam.
 /**
- * graph-aux-command-specs — the declarative graph auxiliary commands (release
- * launch Phase 5 Task 5.2).
+ * graph-aux-command-specs — the declarative graph auxiliary commands.
  *
- * Replaces graph's hand-rolled `registerGraph*Command()` bodies. The host mounts
- * each spec via `mountCommandSpec`; the tool no longer touches Commander. Each
- * helper's raw `.option()`/`.argument()` calls translate 1:1 to
+ * The host mounts each spec via `mountCommandSpec`; the tool no longer touches
+ * Commander. Each helper's raw `.option()`/`.argument()` calls translate 1:1 to
  * `OptionSpec`/`ArgSpec`; positional arguments arrive on the parsed-opts object
  * under the `_args` key (the host's uniform positional convention — see
  * `mountCommandSpec`).
  *
+ * The canonical surface is the nested `<tool> <verb>` grammar — `graph recipes`
+ * / `graph lookup` / `graph index` / `graph list` / `graph export` all mount as
+ * children of the `graph` primary (`parent: 'graph'`). The legacy flat-root
+ * aliases (`graph-recipes` / `graph-lookup` / `graph-symbol-index` /
+ * `graph-baseline-export` / `catalog-export` / `sarif-export`) were removed once
+ * their deprecation window closed.
+ *
  * Output modes:
- *  - `graph-recipes` → `command-result`: the handler returns the list result;
- *    the host dispatches it through the shared seam (`--json` → JSON, else
- *    render). Byte-identical to the former `if (json) emitJson else render` body.
+ *  - `graph recipes` / `graph list` → `command-result`: the handler returns the
+ *    list result; the host dispatches it through the shared seam (`--json` →
+ *    JSON, else render). Byte-identical to the former `if (json) emitJson else
+ *    render` body.
  *  - every other aux command → `raw-stream`: each owns its full IO (writes a
  *    file and/or prints a line, sets its own exit code, owns its `--json`
  *    branch) — the documented non-Ink exception. The host renders nothing.
@@ -23,6 +29,7 @@
 import { commonFlags, EXIT_CODES } from '@opensip-cli/contracts';
 import { ConfigurationError, defineCommand, logger } from '@opensip-cli/core';
 import { executeEquivalenceCheck } from '../equivalence-check-command.js';
+import { listGraphRules } from '../graph-list.js';
 import { runCatalogJsonMode } from '../graph-modes.js';
 import { listGraphRecipes } from '../graph-recipes.js';
 import { handleGraphError } from '../graph.js';
@@ -32,38 +39,202 @@ import { runSarifExportMode } from '../sarif-export.js';
 import { executeShardWorker } from '../shard-worker.js';
 import { executeSymbolIndex } from '../symbol-index.js';
 // Shared --cwd flag string for the auxiliary subcommands that declare it as a
-// tool option (symbol-index keeps a custom description; the export commands keep
-// the canonical one). Sourced from the ADR-0021 common-flag registry so the
-// string matches the run command's --cwd and cannot drift.
+// tool option (the index command keeps a custom description). Sourced from the
+// ADR-0021 common-flag registry so the string matches the run command's --cwd
+// and cannot drift.
 const OPT_CWD = commonFlags.cwd.flags;
-const OPT_DESC_CWD = commonFlags.cwd.description;
-// Shared output mode for the file-/stdout-writing aux commands (every aux
-// command except graph-recipes owns its full IO). Extracted to a const so the
-// literal is declared once (sonarjs/no-duplicate-string) and stays a typed
-// CommandOutputMode member.
+// Shared output mode for the file-/stdout-writing aux commands. Extracted to a
+// const so the literal is declared once (sonarjs/no-duplicate-string) and stays
+// a typed CommandOutputMode member.
 const RAW_STREAM = 'raw-stream';
+// Shared `rawStreamReason` for the file-writing aux commands (the index command
+// + the canonical `graph export`). Declared once so the literal is not
+// duplicated (sonarjs/no-duplicate-string).
+const REASON_FILE_EXPORT = 'file-export';
 /** Read the single trailing positional (`<name>` / `<specPath>`) off the parsed opts. */
 function firstArg(opts) {
     const args = (opts._args ?? []);
     return args[0] ?? '';
 }
-/** `graph-lookup` — look up function occurrences by simple name. */
-export const graphLookupCommandSpec = defineCommand({
-    name: 'graph-lookup',
-    description: 'Look up function occurrences by simple name from the persisted catalog',
-    commonFlags: ['json'],
-    args: [{ name: 'name', description: 'Function simple name to look up (e.g. "saveBaseline")' }],
-    scope: 'project',
-    output: RAW_STREAM,
-    rawStreamReason: 'lookup',
-    handler: async (rawOpts, cli) => {
-        const opts = rawOpts;
-        await executeLookup({ name: firstArg(opts), json: opts.json }, cli);
-    },
-});
+// =============================================================================
+// EXPORT OPTION SPECS (the canonical `graph export --format <fmt>` command)
+//
+// The canonical `graph export` command declares `--format <fmt>` (required) plus
+// the UNION of the per-format flags as OPTIONAL and validates the required
+// subset per format at runtime. Each OptionSpec is declared once here.
+// =============================================================================
+/** `--out` for the baseline export — JSON fingerprints. */
+const OPT_BASELINE_OUT = {
+    flag: '--out',
+    value: '<path>',
+    description: 'Output file path for the JSON baseline',
+};
+/** `--catalog-output` (catalog export). */
+const OPT_CATALOG_OUTPUT = {
+    flag: '--catalog-output',
+    value: '<path>',
+    description: 'Output file path for the CatalogExport JSON',
+};
+/** `--output-sarif` (sarif export). */
+const OPT_OUTPUT_SARIF = {
+    flag: '--output-sarif',
+    value: '<path>',
+    description: 'Output file path for the SARIF v2.1.0 document',
+};
+/** `--tenant-id` (catalog/sarif export). */
+const OPT_TENANT_ID_CATALOG = {
+    flag: '--tenant-id',
+    value: '<id>',
+    description: 'Tenant scope stamped on every row + provenance',
+};
+/** `--repo-id` (catalog/sarif export). */
+const OPT_REPO_ID_CATALOG = {
+    flag: '--repo-id',
+    value: '<id>',
+    description: 'Repository scope stamped on every row',
+};
+/** `--git-sha` (catalog export). */
+const OPT_GIT_SHA = {
+    flag: '--git-sha',
+    value: '<sha>',
+    description: 'Commit SHA the catalog was extracted at',
+};
+/** `--run-id` (catalog/sarif export). */
+const OPT_RUN_ID_CATALOG = {
+    flag: '--run-id',
+    value: '<uuid>',
+    description: 'Run id for provenance (auto-generated if absent)',
+};
+/** `--mode` (catalog export). */
+const OPT_MODE = {
+    flag: '--mode',
+    value: '<mode>',
+    description: "'initial' (full rebuild) or 'incremental' (reuse cache when present)",
+    default: 'initial',
+};
+/** `--changed-file` (catalog export) — repeatable accumulator. */
+const OPT_CHANGED_FILE = {
+    flag: '--changed-file',
+    value: '<relPath>',
+    description: 'Changed file (repeatable). Advisory today — the engine derives the true changed set from fingerprint diffs; recorded for observability.',
+    arrayDefault: [],
+    parse: (val, prev) => [...prev, val],
+};
+/** `--language` (catalog/sarif export). */
+const OPT_LANGUAGE = {
+    flag: '--language',
+    value: '<name>',
+    description: 'Force a specific language adapter (suppresses auto-detection)',
+};
+/** `--resolution` (catalog/sarif export) — host-validated choices enum. */
+const OPT_RESOLUTION = {
+    flag: '--resolution',
+    value: '<mode>',
+    description: 'Edge resolution tier: exact (semantic) or fast (syntactic, no type checker)',
+    default: 'exact',
+    choices: ['exact', 'fast'],
+};
+/** Run graph analysis and write OpenSIP-convention SARIF to `--output-sarif`. */
+async function runGraphSarifExport(opts, cli) {
+    try {
+        const resolution = opts.resolution === 'fast' ? 'fast' : 'exact';
+        const result = await runGraph({
+            cwd: opts.cwd,
+            noCache: true,
+            resolution,
+            language: opts.language,
+            datastore: cli.scope.datastore(),
+        });
+        await runSarifExportMode({
+            outputSarif: opts.outputSarif,
+            tenantId: opts.tenantId,
+            repoId: opts.repoId,
+            runId: opts.runId,
+        }, result.signals, cli);
+    }
+    catch (error) {
+        handleGraphError('sarif-export', error, cli);
+    }
+}
+/** Run graph analysis and write the CatalogExport JSON to `--catalog-output`. */
+async function runGraphCatalogExport(opts, cli) {
+    const startedAt = new Date().toISOString();
+    try {
+        // `--resolution`'s value is `exact`/`fast` by construction (declared
+        // `choices`); the mount layer rejected any other value before we got here.
+        const resolution = opts.resolution === 'fast' ? 'fast' : 'exact';
+        const incremental = opts.mode === 'incremental';
+        const changedFiles = opts.changedFile ?? [];
+        if (incremental && changedFiles.length > 0) {
+            // Advisory only: the incremental path self-derives the changed set from
+            // on-disk fingerprint diffs, so a caller-supplied set does not (yet)
+            // narrow the walk. Logged for observability.
+            logger.info({
+                evt: 'graph.cli.catalog_export.changed_files_advisory',
+                module: 'graph:cli',
+                runId: opts.runId,
+                changedFileCount: changedFiles.length,
+            });
+        }
+        const result = await runGraph({
+            cwd: opts.cwd,
+            noCache: !incremental,
+            resolution,
+            language: opts.language,
+            datastore: cli.scope.datastore(),
+        });
+        runCatalogJsonMode({
+            cwd: opts.cwd,
+            catalogOutput: opts.catalogOutput,
+            tenantId: opts.tenantId,
+            repoId: opts.repoId,
+            gitSha: opts.gitSha,
+            runId: opts.runId,
+        }, result, cli, startedAt);
+    }
+    catch (error) {
+        handleGraphError('catalog-export', error, cli);
+    }
+}
+/**
+ * Export the graph gate fingerprint baseline (JSON) to `--out` via the host
+ * baseline seam (ADR-0036). Maps the ConfigurationError "no baseline" path to
+ * exit 2 for both the `--json` and plain-text boundaries.
+ */
+async function runGraphBaselineExport(opts, cli) {
+    try {
+        await cli.exportBaselineFingerprints('graph', opts.out);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const exitCode = error instanceof ConfigurationError
+            ? EXIT_CODES.CONFIGURATION_ERROR
+            : EXIT_CODES.RUNTIME_ERROR;
+        logger.warn({
+            evt: 'cli.graph.baseline_export.failed',
+            module: 'graph:cli',
+            message,
+            exitCode,
+        });
+        if (opts.json === true) {
+            cli.emitError({ message, exitCode });
+            return;
+        }
+        cli.setExitCode(exitCode);
+        process.stderr.write(`Error: ${message}\n`);
+        return;
+    }
+    const result = { type: 'graph-baseline-export', outPath: opts.out };
+    if (opts.json === true) {
+        cli.emitJson(result);
+        return;
+    }
+    process.stdout.write(`Exported graph baseline to ${opts.out}\n`);
+}
 /** `graph-shard-worker` — [internal] build one shard from a spec file. */
 export const graphShardWorkerCommandSpec = defineCommand({
     name: 'graph-shard-worker',
+    visibility: 'internal',
     description: '[internal] Build one shard from a spec file and emit a ShardBuildResult JSON (spawned by the sharded build)',
     commonFlags: [],
     args: [{ name: 'specPath', description: 'Path to a JSON ShardWorkerSpec file' }],
@@ -84,6 +255,7 @@ export const graphShardWorkerCommandSpec = defineCommand({
  */
 export const graphEquivalenceCheckCommandSpec = defineCommand({
     name: 'graph-equivalence-check',
+    visibility: 'internal',
     description: '[internal] Verify the sharded build is byte-equivalent to the exact build on a real repo (gates production edge divergence against a committed budget)',
     commonFlags: [],
     options: [
@@ -111,280 +283,202 @@ export const graphEquivalenceCheckCommandSpec = defineCommand({
         await executeEquivalenceCheck({ cwd: opts.cwd, budget: opts.budget, updateBudget: opts.updateBudget }, cli);
     },
 });
-/** `graph-symbol-index` — emit a symbolindex.json artifact. */
-export const graphSymbolIndexCommandSpec = defineCommand({
-    name: 'graph-symbol-index',
-    description: 'Emit a symbolindex.json artifact (name→file:line and file→names) from the persisted catalog',
-    commonFlags: [],
-    options: [
-        // --cwd keeps its command-specific description (the out path resolves
-        // against it), so it is declared as a tool option rather than the common
-        // flag. The literal default is `process.cwd()`, evaluated once at module
-        // load (CLI startup) — equivalent to the former register-time evaluation.
-        {
-            flag: OPT_CWD,
-            description: 'Target directory (out path resolves against this)',
-            default: process.cwd(),
-        },
-        {
-            flag: '--out',
-            value: '<path>',
-            description: 'Output file path',
-            default: 'symbolindex.json',
-        },
-    ],
-    scope: 'project',
-    output: RAW_STREAM,
-    rawStreamReason: 'file-export',
-    handler: (rawOpts, cli) => {
-        const opts = rawOpts;
-        executeSymbolIndex({ cwd: opts.cwd, out: opts.out }, cli);
-    },
-});
-/** `graph-baseline-export` — export the graph gate baseline (JSON). */
-export const graphBaselineExportCommandSpec = defineCommand({
-    name: 'graph-baseline-export',
-    description: 'Export the graph gate baseline (JSON) from the datastore to a file',
+/**
+ * The canonical graph export formats (taxonomy spec Q2: one `export` subcommand
+ * dispatching on `--format`, not nested argv). Declared as a `choices` enum so
+ * the host validates the value at mount and `graph export --format <bad>` is
+ * rejected before the handler runs.
+ */
+export const GRAPH_EXPORT_FORMATS = ['sarif', 'catalog', 'baseline'];
+/**
+ * Validate that the per-format required flags are present on the canonical
+ * `graph export` opts. Returns `true` when the required subset is satisfied;
+ * otherwise reports the missing flags (to the `--json` channel or stderr, like
+ * the shared export error paths) + sets exit 2 (CONFIGURATION_ERROR) and returns
+ * `false`. Keeps the per-format required-flag validation in one place without
+ * making all format-specific subsets simultaneously mandatory on one spec.
+ */
+function requireExportFlags(format, present, required, cli) {
+    const missing = required.filter((flag) => {
+        // Flag names map to camelCase opt keys (`--output-sarif` → `outputSarif`).
+        const key = flag.replace(/^--/, '').replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+        const value = present[key];
+        return value === undefined || value === '';
+    });
+    if (missing.length === 0)
+        return true;
+    const message = `graph export --format ${format} requires ${missing.join(', ')}.`;
+    const exitCode = EXIT_CODES.CONFIGURATION_ERROR;
+    logger.warn({ evt: 'cli.graph.export.missing_flags', module: 'graph:cli', format, missing });
+    if (present.json === true) {
+        cli.emitError({ message, exitCode });
+        return false;
+    }
+    cli.setExitCode(exitCode);
+    process.stderr.write(`Error: ${message}\n`);
+    return false;
+}
+/**
+ * `graph export --format sarif|catalog|baseline` — the canonical graph export
+ * command (taxonomy spec Q2). Mounts as a SUBCOMMAND of the `graph` primary
+ * (`parent: 'graph'`, via the nested-mount capability), so it shares the root
+ * with `fit export` without colliding (both declare `name: 'export'`).
+ *
+ * The legacy flat-root commands (`sarif-export`/`catalog-export`/
+ * `graph-baseline-export`) were removed. The canonical spec declares `--format`
+ * (required) + the UNION of the per-format flags as OPTIONAL and validates the
+ * required subset per format at runtime (`requireExportFlags` →
+ * ConfigurationError → exit 2).
+ */
+export const graphExportCommandSpec = defineCommand({
+    name: 'export',
+    parent: 'graph',
+    description: 'Export graph analysis artifacts: --format sarif (SARIF v2.1.0 findings), catalog (CatalogExport JSON), or baseline (gate fingerprint JSON)',
     commonFlags: ['cwd', 'json'],
     options: [
         {
-            flag: '--out',
-            value: '<path>',
-            description: 'Output file path for the JSON baseline',
+            flag: '--format',
+            value: '<fmt>',
+            description: 'Export artifact: sarif | catalog | baseline',
             required: true,
+            choices: [...GRAPH_EXPORT_FORMATS],
         },
+        // Union of the per-format flags, all OPTIONAL here (the required subset is
+        // validated per-format at runtime). --cwd is a common flag (declared above),
+        // so it is NOT repeated here.
+        OPT_OUTPUT_SARIF,
+        OPT_CATALOG_OUTPUT,
+        OPT_TENANT_ID_CATALOG,
+        OPT_REPO_ID_CATALOG,
+        OPT_GIT_SHA,
+        OPT_RUN_ID_CATALOG,
+        OPT_MODE,
+        OPT_CHANGED_FILE,
+        OPT_LANGUAGE,
+        OPT_RESOLUTION,
+        OPT_BASELINE_OUT,
     ],
     scope: 'project',
     output: RAW_STREAM,
-    rawStreamReason: 'file-export',
+    rawStreamReason: REASON_FILE_EXPORT,
     handler: async (rawOpts, cli) => {
         const opts = rawOpts;
-        // ADR-0036: the host owns the byte-identical fingerprint-JSON export. The seam
-        // throws ConfigurationError (→ exit 2) when no baseline exists; map it here for
-        // both the --json (structured) and plain-text boundaries, as today.
-        try {
-            await cli.exportBaselineFingerprints('graph', opts.out);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const exitCode = error instanceof ConfigurationError
-                ? EXIT_CODES.CONFIGURATION_ERROR
-                : EXIT_CODES.RUNTIME_ERROR;
-            logger.warn({
-                evt: 'cli.graph.baseline_export.failed',
-                module: 'graph:cli',
-                message,
-                exitCode,
-            });
-            if (opts.json === true) {
-                cli.emitError({ message, exitCode });
+        switch (opts.format) {
+            case 'sarif': {
+                if (!requireExportFlags('sarif', opts, ['--output-sarif', '--tenant-id', '--repo-id'], cli))
+                    return;
+                await runGraphSarifExport(opts, cli);
+                return;
+            }
+            case 'catalog': {
+                if (!requireExportFlags('catalog', opts, ['--catalog-output', '--tenant-id', '--repo-id', '--git-sha'], cli))
+                    return;
+                await runGraphCatalogExport(opts, cli);
+                return;
+            }
+            case 'baseline': {
+                if (!requireExportFlags('baseline', opts, ['--out'], cli))
+                    return;
+                await runGraphBaselineExport(opts, cli);
                 return;
             }
-            cli.setExitCode(exitCode);
-            process.stderr.write(`Error: ${message}\n`);
-            return;
-        }
-        const result = { type: 'graph-baseline-export', outPath: opts.out };
-        if (opts.json === true) {
-            cli.emitJson(result);
-            return;
         }
-        process.stdout.write(`Exported graph baseline to ${opts.out}\n`);
     },
 });
+// =============================================================================
+// GROUPED <tool> <verb> CHILDREN (the canonical Tier-2 grammar)
+//
+// `graph recipes` / `graph lookup` / `graph index` / `graph list` mount as
+// SUBCOMMANDS of the `graph` primary via the nested-mount capability
+// (`parent: 'graph'`). They own their handler bodies directly (calling the
+// shared engine functions) — the legacy flat `graph-recipes` / `graph-lookup` /
+// `graph-symbol-index` aliases were removed.
+// =============================================================================
 /**
- * `catalog-export` — dedicated subcommand carrying the catalog-JSON renderer +
- * machine flags (`--catalog-output`/`--tenant-id`/`--repo-id`/`--git-sha`). This
- * is the CLI contract the opensip `EngineSubprocessPort.runCatalogExport` spawns
- * (DEC-498). The flags live here, NOT on `graph` — the v1 `graph
- * --catalog-output` shape was retired by the split, so docs/consumers must
- * target `catalog-export`.
+ * `graph recipes` — list available graph recipes (mirrors `fit recipes`). Reuses
+ * the shared ListRecipesResult contract + viewListRecipes renderer.
+ * `command-result`: the host dispatches the returned result through the shared
+ * seam (`--json` → JSON, else render).
  */
-export const graphCatalogExportCommandSpec = defineCommand({
-    name: 'catalog-export',
-    description: 'Run graph analysis and write the CatalogExport JSON document (symbols + edges + provenance) to a file',
-    commonFlags: [],
-    options: [
-        {
-            flag: '--catalog-output',
-            value: '<path>',
-            description: 'Output file path for the CatalogExport JSON',
-            required: true,
-        },
-        {
-            flag: '--tenant-id',
-            value: '<id>',
-            description: 'Tenant scope stamped on every row + provenance',
-            required: true,
-        },
-        {
-            flag: '--repo-id',
-            value: '<id>',
-            description: 'Repository scope stamped on every row',
-            required: true,
-        },
-        {
-            flag: '--git-sha',
-            value: '<sha>',
-            description: 'Commit SHA the catalog was extracted at',
-            required: true,
-        },
-        {
-            flag: '--run-id',
-            value: '<uuid>',
-            description: 'Run id for provenance (auto-generated if absent)',
-        },
-        {
-            flag: '--mode',
-            value: '<mode>',
-            description: "'initial' (full rebuild) or 'incremental' (reuse cache when present)",
-            default: 'initial',
-        },
-        {
-            flag: '--changed-file',
-            value: '<relPath>',
-            description: 'Changed file (repeatable). Advisory today — the engine derives the true changed set from fingerprint diffs; recorded for observability.',
-            arrayDefault: [],
-            parse: (val, prev) => [...prev, val],
-        },
-        { flag: OPT_CWD, description: OPT_DESC_CWD, default: process.cwd() },
-        {
-            flag: '--language',
-            value: '<name>',
-            description: 'Force a specific language adapter (suppresses auto-detection)',
-        },
-        {
-            flag: '--resolution',
-            value: '<mode>',
-            description: 'Edge resolution tier: exact (semantic) or fast (syntactic, no type checker)',
-            default: 'exact',
-            choices: ['exact', 'fast'],
-        },
-    ],
+export const graphRecipesGroupedCommandSpec = defineCommand({
+    name: 'recipes',
+    parent: 'graph',
+    description: 'List available graph recipes',
+    commonFlags: ['json'],
+    scope: 'project',
+    output: 'command-result',
+    handler: async () => listGraphRecipes(),
+});
+/** `graph lookup <name>` — look up function occurrences by simple name. */
+export const graphLookupGroupedCommandSpec = defineCommand({
+    name: 'lookup',
+    parent: 'graph',
+    description: 'Look up function occurrences by simple name from the persisted catalog',
+    commonFlags: ['json'],
+    args: [{ name: 'name', description: 'Function simple name to look up (e.g. "saveBaseline")' }],
     scope: 'project',
     output: RAW_STREAM,
-    rawStreamReason: 'file-export',
+    rawStreamReason: 'lookup',
     handler: async (rawOpts, cli) => {
         const opts = rawOpts;
-        const startedAt = new Date().toISOString();
-        try {
-            // `--resolution`'s value is `exact`/`fast` by construction (declared
-            // `choices`); the mount layer rejected any other value before we got here.
-            const resolution = opts.resolution === 'fast' ? 'fast' : 'exact';
-            const incremental = opts.mode === 'incremental';
-            const changedFiles = opts.changedFile ?? [];
-            if (incremental && changedFiles.length > 0) {
-                // Advisory only: the incremental path self-derives the changed set from
-                // on-disk fingerprint diffs, so a caller-supplied set does not (yet)
-                // narrow the walk. Logged for observability.
-                logger.info({
-                    evt: 'graph.cli.catalog_export.changed_files_advisory',
-                    module: 'graph:cli',
-                    runId: opts.runId,
-                    changedFileCount: changedFiles.length,
-                });
-            }
-            const result = await runGraph({
-                cwd: opts.cwd,
-                noCache: !incremental,
-                resolution,
-                language: opts.language,
-                datastore: cli.scope.datastore(),
-            });
-            runCatalogJsonMode({
-                cwd: opts.cwd,
-                catalogOutput: opts.catalogOutput,
-                tenantId: opts.tenantId,
-                repoId: opts.repoId,
-                gitSha: opts.gitSha,
-                runId: opts.runId,
-            }, result, cli, startedAt);
-        }
-        catch (error) {
-            handleGraphError('catalog-export', error, cli);
-        }
+        await executeLookup({ name: firstArg(opts), json: opts.json }, cli);
     },
 });
 /**
- * `sarif-export` — runs the pipeline and writes OpenSIP-convention SARIF to a
- * file, matching the opensip `EngineSubprocessPort.runSarifExport` contract
- * (DEC-498). Always a full run (findings, not incremental).
+ * `graph index` — emit a `symbolindex.json` artifact (name→file:line and
+ * file→names) from the persisted catalog. It BOTH builds and queries the symbol
+ * index.
+ *
+ * Q7 (open): `graph index` currently both builds and queries; the build/query
+ * verb split (`graph index build` | `graph index query`) is deferred. Do NOT add
+ * a `--build` flag here without resolving Q7.
  */
-export const graphSarifExportCommandSpec = defineCommand({
-    name: 'sarif-export',
-    description: 'Run graph analysis and write OpenSIP-convention SARIF v2.1.0 findings to a file',
+export const graphIndexGroupedCommandSpec = defineCommand({
+    name: 'index',
+    parent: 'graph',
+    description: 'Emit a symbolindex.json artifact (name→file:line and file→names) from the persisted catalog',
     commonFlags: [],
     options: [
+        // --cwd keeps its command-specific description (the out path resolves
+        // against it), so it is declared as a tool option rather than the common
+        // flag. The literal default is `process.cwd()`, evaluated once at module
+        // load (CLI startup) — equivalent to the former register-time evaluation.
         {
-            flag: '--output-sarif',
-            value: '<path>',
-            description: 'Output file path for the SARIF v2.1.0 document',
-            required: true,
-        },
-        { flag: '--tenant-id', value: '<id>', description: 'Tenant scope for the run', required: true },
-        {
-            flag: '--repo-id',
-            value: '<id>',
-            description: 'Repository scope for the run',
-            required: true,
-        },
-        {
-            flag: '--run-id',
-            value: '<uuid>',
-            description: 'Run id for trace correlation (auto-generated if absent)',
-        },
-        { flag: OPT_CWD, description: OPT_DESC_CWD, default: process.cwd() },
-        {
-            flag: '--language',
-            value: '<name>',
-            description: 'Force a specific language adapter (suppresses auto-detection)',
+            flag: OPT_CWD,
+            description: 'Target directory (out path resolves against this)',
+            default: process.cwd(),
         },
         {
-            flag: '--resolution',
-            value: '<mode>',
-            description: 'Edge resolution tier: exact (semantic) or fast (syntactic, no type checker)',
-            default: 'exact',
-            choices: ['exact', 'fast'],
+            flag: '--out',
+            value: '<path>',
+            description: 'Output file path',
+            default: 'symbolindex.json',
         },
     ],
     scope: 'project',
     output: RAW_STREAM,
-    rawStreamReason: 'file-export',
-    handler: async (rawOpts, cli) => {
+    rawStreamReason: REASON_FILE_EXPORT,
+    handler: (rawOpts, cli) => {
         const opts = rawOpts;
-        try {
-            const resolution = opts.resolution === 'fast' ? 'fast' : 'exact';
-            const result = await runGraph({
-                cwd: opts.cwd,
-                noCache: true,
-                resolution,
-                language: opts.language,
-                datastore: cli.scope.datastore(),
-            });
-            await runSarifExportMode({
-                outputSarif: opts.outputSarif,
-                tenantId: opts.tenantId,
-                repoId: opts.repoId,
-                runId: opts.runId,
-            }, result.signals, cli);
-        }
-        catch (error) {
-            handleGraphError('sarif-export', error, cli);
-        }
+        executeSymbolIndex({ cwd: opts.cwd, out: opts.out }, cli);
     },
 });
 /**
- * `graph-recipes` — list available graph recipes (mirrors fit-recipes). Reuses
- * the shared ListRecipesResult contract + viewListRecipes renderer.
- * `command-result`: the host dispatches the returned result through the shared
- * seam (`--json` → JSON, else render).
+ * `graph list` — list available graph rules (the natural analog of `fit list`,
+ * which lists checks): graph *rules* are the listable surface.
+ *
+ * `command-result`: the handler returns a `ListChecksResult`; the host
+ * dispatches it through the shared seam (`--json` → JSON, else the shared
+ * `viewListChecks` renderer with the graph-supplied title) — the same path
+ * `graph recipes` / `fit list` use.
  */
-export const graphRecipesCommandSpec = defineCommand({
-    name: 'graph-recipes',
-    description: 'List available graph recipes',
-    commonFlags: ['json'],
+export const graphListCommandSpec = defineCommand({
+    name: 'list',
+    parent: 'graph',
+    description: 'List available graph rules',
+    commonFlags: ['cwd', 'json'],
     scope: 'project',
     output: 'command-result',
-    handler: async () => listGraphRecipes(),
+    handler: async () => listGraphRules(),
 });
 //# sourceMappingURL=graph-aux-command-specs.js.map