@nekostack/cli 1.0.0

package/dist/commands/schema/migrate/verify.js

@@ -0,0 +1,268 @@
+/**
+ * `neko schema migrate verify` command implementation (v0.8 Step 22).
+ *
+ * Mirrors `runMigratePlan`'s pure / writer-injected discipline
+ * (Master plan Decision #1).
+ *
+ * Flow:
+ *
+ *   1. `walkWorkspace({ root })` — load every `*.schema.{ts,js}`.
+ *      Any per-file load failure → IO_ERROR.
+ *   2. `buildRegistry(walk.entries)` — index the schemas.
+ *      `duplicate_schema_id` → LOGICAL_FAILURE; `integrity_error` →
+ *      INTEGRITY_ERROR.
+ *   3. `readMigrations({ root })` — load every `*.migration.ts`.
+ *      Any per-file load failure → IO_ERROR.
+ *   4. `buildMigrationRegistry(migWalk.entries)` — index migrations
+ *      and parse each one's provenance. `duplicate_migration` →
+ *      LOGICAL_FAILURE; `integrity_error` → INTEGRITY_ERROR.
+ *   5. **CLI-side verdict derivation** — walk the migration registry
+ *      with the same classification rule as
+ *      `verifyMigrationProvenance` so the CLI can surface verdicts +
+ *      summary on BOTH the success and failure JSON branches. (The
+ *      schema-side handler discards verdicts on failure; the v0.8
+ *      verify-CLI contract requires them on both branches.)
+ *   6. `verifyMigrationsHandler({ schemaRegistry, migrationRegistry })`
+ *      — gets the official success/failure determination and any
+ *      `migration_drift` / `migration_missing_endpoint` issues.
+ *   7. Format and write:
+ *      - `--json` (success) → `{ verdicts, summary }`
+ *      - `--json` (failure) → `{ verdicts, summary, issues }`
+ *      - pretty → summary header + per-verdict rows
+ *   8. Exit-code mapping:
+ *      - any drift / missing_endpoint → LOGICAL_FAILURE
+ *      - only bound / cosmetic_drift (or empty registry) → SUCCESS
+ *
+ * **Pure.** No `process.exit`, no `console.*`, no direct
+ * `process.stdout` / `process.stderr` writes. Writers are injected.
+ *
+ * **`migration.transform` is NEVER invoked here.** Verification is
+ * provenance-only (the v0.8 INVARIANTS contract). Static-scan
+ * asserted by [`../../../../tests/commands/schema-migrate-verify.test.ts`](../../../../tests/commands/schema-migrate-verify.test.ts).
+ *
+ * **JSON output never serializes `MigrationEntry.migration` or its
+ * `transform` closure.** Verdicts are already shaped as
+ * `{ status, schemaId, fromVersion, toVersion, sourcePath }` per the
+ * `MigrationVerdict` type — no migration reference — so the projection
+ * is the identity. Issue records likewise carry only structured
+ * metadata.
+ */
+import { buildMigrationRegistry, buildRegistry, findSchema, verifyMigrationsHandler, } from "@nekostack/schema/cli";
+import { EXIT_CODES } from "../../../exit-codes.js";
+import { formatJson } from "../../../formatters/json.js";
+import { formatIssuesPretty, formatLoadFailuresPretty, } from "../../../formatters/pretty.js";
+import { readMigrations } from "../../../loaders/read-migrations.js";
+import { walkWorkspace } from "../../../loaders/walk-workspace.js";
+/**
+ * CLI-side mirror of `verifyMigrationProvenance`'s classification +
+ * iteration discipline. Produces verdicts on **every** invocation —
+ * the schema-side handler drops them on the failure branch, but the
+ * CLI must surface them on both branches per the Step 22 JSON
+ * contract.
+ *
+ * Source of truth for the classification rule is
+ * [`packages/schema/src/migrations/verify-provenance.ts`](../../../../../schema/src/migrations/verify-provenance.ts).
+ * Decision #9 (the four-way verdict matrix) is locked in
+ * `packages/schema/docs/MIGRATIONS.md`; any future change there must
+ * land here too.
+ *
+ * Iteration is `(schemaId, fromVersion, toVersion)` lex-ascending so
+ * the CLI verdicts list matches the handler's on success.
+ */
+function deriveVerdicts(schemaRegistry, migrationRegistry) {
+    const verdicts = [];
+    const counts = { bound: 0, cosmetic_drift: 0, drift: 0, missing_endpoint: 0 };
+    for (const entry of iterateRegistry(migrationRegistry)) {
+        const verdict = classifyEntry(entry, schemaRegistry);
+        verdicts.push(verdict);
+        counts[verdict.status] += 1;
+    }
+    return { verdicts, summary: counts };
+}
+function* iterateRegistry(registry) {
+    const schemaIds = [...registry.keys()].sort();
+    for (const schemaId of schemaIds) {
+        const byFrom = registry.get(schemaId);
+        if (byFrom === undefined)
+            continue;
+        const fromVersions = [...byFrom.keys()].sort();
+        for (const fromVersion of fromVersions) {
+            const byTo = byFrom.get(fromVersion);
+            if (byTo === undefined)
+                continue;
+            const toVersions = [...byTo.keys()].sort();
+            for (const toVersion of toVersions) {
+                const entry = byTo.get(toVersion);
+                if (entry !== undefined)
+                    yield entry;
+            }
+        }
+    }
+}
+function classifyEntry(entry, schemaRegistry) {
+    const base = {
+        sourcePath: entry.sourcePath,
+        schemaId: entry.schemaId,
+        fromVersion: entry.fromVersion,
+        toVersion: entry.toVersion,
+    };
+    const fromSchema = findSchema(schemaRegistry, entry.schemaId, entry.fromVersion);
+    const toSchema = findSchema(schemaRegistry, entry.schemaId, entry.toVersion);
+    if (fromSchema === undefined || toSchema === undefined) {
+        return { status: "missing_endpoint", ...base };
+    }
+    const fromIrMatch = entry.fromIrHash === fromSchema.irHash;
+    const toIrMatch = entry.toIrHash === toSchema.irHash;
+    if (!fromIrMatch || !toIrMatch) {
+        return { status: "drift", ...base };
+    }
+    const fromSourceMatch = entry.fromSourceHash === fromSchema.sourceHash;
+    const toSourceMatch = entry.toSourceHash === toSchema.sourceHash;
+    if (!fromSourceMatch || !toSourceMatch) {
+        return { status: "cosmetic_drift", ...base };
+    }
+    return { status: "bound", ...base };
+}
+// =============================================================================
+// Pretty formatter
+// =============================================================================
+function formatVerifyPretty(d) {
+    const { verdicts, summary } = d;
+    const total = verdicts.length;
+    if (total === 0) {
+        return "No migrations to verify.\n";
+    }
+    const lines = [];
+    lines.push(`Verified ${total} migration${total === 1 ? "" : "s"}:` +
+        `  bound=${summary.bound}` +
+        `  cosmetic_drift=${summary.cosmetic_drift}` +
+        `  drift=${summary.drift}` +
+        `  missing_endpoint=${summary.missing_endpoint}`);
+    const idWidth = maxWidth(verdicts.map((v) => v.schemaId));
+    const versionsWidth = maxWidth(verdicts.map((v) => `${v.fromVersion} → ${v.toVersion}`));
+    for (const v of verdicts) {
+        const versions = `${v.fromVersion} → ${v.toVersion}`;
+        const tag = v.status === "bound"
+            ? "[bound]"
+            : v.status === "cosmetic_drift"
+                ? "[warn ] cosmetic_drift"
+                : v.status === "drift"
+                    ? "[FAIL ] drift"
+                    : "[FAIL ] missing_endpoint";
+        lines.push(`  ${v.schemaId.padEnd(idWidth)}   ${versions.padEnd(versionsWidth)}   ${tag}   ${v.sourcePath}`);
+    }
+    return lines.join("\n") + "\n";
+}
+function maxWidth(values) {
+    let max = 0;
+    for (const v of values)
+        if (v.length > max)
+            max = v.length;
+    return max;
+}
+// =============================================================================
+// Failure helpers
+// =============================================================================
+function toSerializableLoadFailure(f) {
+    return { path: f.path, reason: f.reason, message: f.message };
+}
+/**
+ * `buildRegistry` / `buildMigrationRegistry` failure → exit code.
+ * Same mapping as `runMigratePlan` / `runMigrateList`.
+ */
+function pickRegistryFailureExitCode(issues) {
+    for (const i of issues) {
+        if (i.code === "integrity_error")
+            return EXIT_CODES.INTEGRITY_ERROR;
+    }
+    return EXIT_CODES.LOGICAL_FAILURE;
+}
+// =============================================================================
+// Public entry
+// =============================================================================
+export async function runMigrateVerify(opts) {
+    // 1. Schema walk + load failures → IO_ERROR.
+    const walk = await walkWorkspace({ root: opts.root });
+    if (walk.failures.length > 0) {
+        if (opts.json) {
+            opts.stdout(formatJson({ failures: walk.failures.map(toSerializableLoadFailure) }));
+        }
+        else {
+            opts.stderr(formatLoadFailuresPretty(walk.failures));
+        }
+        return EXIT_CODES.IO_ERROR;
+    }
+    // 2. Build the schema registry.
+    const reg = buildRegistry(walk.entries);
+    if (!reg.success) {
+        if (opts.json) {
+            opts.stdout(formatJson({ issues: reg.issues }));
+        }
+        else {
+            opts.stderr(formatIssuesPretty(reg.issues));
+        }
+        return pickRegistryFailureExitCode(reg.issues);
+    }
+    // 3. Migration walk + load failures → IO_ERROR.
+    const migWalk = await readMigrations({ root: opts.root });
+    if (migWalk.failures.length > 0) {
+        if (opts.json) {
+            opts.stdout(formatJson({
+                failures: migWalk.failures.map(toSerializableLoadFailure),
+            }));
+        }
+        else {
+            opts.stderr(formatLoadFailuresPretty(migWalk.failures, {
+                noun: { singular: "migration file", plural: "migration files" },
+            }));
+        }
+        return EXIT_CODES.IO_ERROR;
+    }
+    // 4. Build the migration registry.
+    const migReg = buildMigrationRegistry(migWalk.entries);
+    if (!migReg.success) {
+        if (opts.json) {
+            opts.stdout(formatJson({ issues: migReg.issues }));
+        }
+        else {
+            opts.stderr(formatIssuesPretty(migReg.issues));
+        }
+        return pickRegistryFailureExitCode(migReg.issues);
+    }
+    // 5. Derive verdicts on the CLI side (mirrors the handler's
+    //    classification so verdicts + summary are available on the
+    //    failure branch).
+    const derived = deriveVerdicts(reg.data, migReg.data);
+    // 6. Call the handler for success/failure determination + issues.
+    const result = verifyMigrationsHandler({
+        schemaRegistry: reg.data,
+        migrationRegistry: migReg.data,
+    });
+    // 7. Emit and pick exit code.
+    if (result.success) {
+        if (opts.json) {
+            opts.stdout(formatJson({
+                verdicts: derived.verdicts,
+                summary: derived.summary,
+            }));
+        }
+        else {
+            opts.stdout(formatVerifyPretty(derived));
+        }
+        return EXIT_CODES.SUCCESS;
+    }
+    // Failure branch: verdicts + summary + issues all in the JSON.
+    if (opts.json) {
+        opts.stdout(formatJson({
+            verdicts: derived.verdicts,
+            summary: derived.summary,
+            issues: result.issues,
+        }));
+    }
+    else {
+        opts.stdout(formatVerifyPretty(derived));
+        opts.stderr(formatIssuesPretty(result.issues));
+    }
+    return EXIT_CODES.LOGICAL_FAILURE;
+}
+//# sourceMappingURL=verify.js.map

package/dist/commands/schema/migrate/verify.js.map

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

package/dist/exit-codes.d.ts

@@ -0,0 +1,47 @@
+/**
+ * CLI exit-code contract (v0.7 Step 26).
+ *
+ * The locked five-value enum from CLI plan Decision #6. Imported by
+ * `dispatch()` in `cli.ts` and by each schema-verb command module
+ * (Steps 29–32) so every code path uses the same vocabulary instead
+ * of inlining magic numbers.
+ *
+ * Semantics:
+ *
+ *   0  SUCCESS           — command completed without issue.
+ *   1  LOGICAL_FAILURE   — load-bearing CI signal. Verdict-level
+ *                          problems found by the verb itself: stale
+ *                          generated artifacts (`check`), a breaking
+ *                          diff (`diff`), a missing schema referenced
+ *                          on the argv (`diff` / `check`), etc.
+ *                          CI should fail on this.
+ *   2  USAGE_ERROR       — argv shape is wrong: unknown command,
+ *                          missing argument, unknown option, bad
+ *                          flag value.
+ *   3  IO_ERROR          — workspace not readable, schema source
+ *                          file failed to load (any of the four
+ *                          `schema_load_failed` reasons), committed
+ *                          artifact unreadable.
+ *   4  INTEGRITY_ERROR   — the "impossible" two-hash row from
+ *                          Master plan Decision #6: the artifact's
+ *                          recorded `sourceHash` matches the schema
+ *                          source but the `irHash` differs. Suggests
+ *                          hand-edited artifact or tampered
+ *                          provenance. The CLI does NOT auto-
+ *                          regenerate when this fires.
+ *
+ * Anything ≥ 2 is a problem with the invocation or the workspace,
+ * not with the schemas under inspection. Tooling layered on top of
+ * `neko schema *` (e.g., CI helpers, future `@nekostack/migrate`)
+ * should treat 1 as "the schemas need attention" and ≥ 2 as
+ * "something else is wrong before we can even check the schemas."
+ */
+export declare const EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly LOGICAL_FAILURE: 1;
+    readonly USAGE_ERROR: 2;
+    readonly IO_ERROR: 3;
+    readonly INTEGRITY_ERROR: 4;
+};
+export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+//# sourceMappingURL=exit-codes.d.ts.map

package/dist/exit-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,eAAO,MAAM,UAAU;;;;;;CAMb,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC"}

package/dist/exit-codes.js

@@ -0,0 +1,46 @@
+/**
+ * CLI exit-code contract (v0.7 Step 26).
+ *
+ * The locked five-value enum from CLI plan Decision #6. Imported by
+ * `dispatch()` in `cli.ts` and by each schema-verb command module
+ * (Steps 29–32) so every code path uses the same vocabulary instead
+ * of inlining magic numbers.
+ *
+ * Semantics:
+ *
+ *   0  SUCCESS           — command completed without issue.
+ *   1  LOGICAL_FAILURE   — load-bearing CI signal. Verdict-level
+ *                          problems found by the verb itself: stale
+ *                          generated artifacts (`check`), a breaking
+ *                          diff (`diff`), a missing schema referenced
+ *                          on the argv (`diff` / `check`), etc.
+ *                          CI should fail on this.
+ *   2  USAGE_ERROR       — argv shape is wrong: unknown command,
+ *                          missing argument, unknown option, bad
+ *                          flag value.
+ *   3  IO_ERROR          — workspace not readable, schema source
+ *                          file failed to load (any of the four
+ *                          `schema_load_failed` reasons), committed
+ *                          artifact unreadable.
+ *   4  INTEGRITY_ERROR   — the "impossible" two-hash row from
+ *                          Master plan Decision #6: the artifact's
+ *                          recorded `sourceHash` matches the schema
+ *                          source but the `irHash` differs. Suggests
+ *                          hand-edited artifact or tampered
+ *                          provenance. The CLI does NOT auto-
+ *                          regenerate when this fires.
+ *
+ * Anything ≥ 2 is a problem with the invocation or the workspace,
+ * not with the schemas under inspection. Tooling layered on top of
+ * `neko schema *` (e.g., CI helpers, future `@nekostack/migrate`)
+ * should treat 1 as "the schemas need attention" and ≥ 2 as
+ * "something else is wrong before we can even check the schemas."
+ */
+export const EXIT_CODES = {
+    SUCCESS: 0,
+    LOGICAL_FAILURE: 1,
+    USAGE_ERROR: 2,
+    IO_ERROR: 3,
+    INTEGRITY_ERROR: 4,
+};
+//# sourceMappingURL=exit-codes.js.map

package/dist/exit-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,OAAO,EAAE,CAAC;IACV,eAAe,EAAE,CAAC;IAClB,WAAW,EAAE,CAAC;IACd,QAAQ,EAAE,CAAC;IACX,eAAe,EAAE,CAAC;CACV,CAAC"}

package/dist/formatters/json.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `formatJson(payload)` — single-line JSON output formatter (v0.7 Step 27).
+ *
+ * The `--json` flag on every `neko schema *` verb routes through this
+ * function. CLI plan §"Output formats" locks the contract:
+ *
+ *   - One line per invocation (no pretty-printing) — pipeable.
+ *   - Exactly one trailing newline so callers can `writeOut(formatJson(x))`
+ *     without remembering to add `\n`.
+ *   - `JSON.stringify` errors propagate. Unserializable inputs (cycles,
+ *     `BigInt`, etc.) are programmer errors, not user errors; the
+ *     dispatch layer treats an unhandled throw as an unexpected
+ *     condition rather than masking it behind a fake success line.
+ *
+ * Pure utility — no `console.*`, no `process.*`, no `fs.*`. Static-
+ * scan asserted by [`../../tests/formatters/json.test.ts`](../../tests/formatters/json.test.ts).
+ *
+ * Per-command JSON schemas (the shape each verb emits) are locked by
+ * the schema-side `*Result` types those verbs wrap; this formatter
+ * is shape-agnostic. When a `*Result` shape changes, the
+ * corresponding command's snapshot test catches it without anything
+ * here needing to change.
+ */
+export declare function formatJson(payload: unknown): string;
+//# sourceMappingURL=json.d.ts.map

package/dist/formatters/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/formatters/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAEnD"}

package/dist/formatters/json.js

@@ -0,0 +1,27 @@
+/**
+ * `formatJson(payload)` — single-line JSON output formatter (v0.7 Step 27).
+ *
+ * The `--json` flag on every `neko schema *` verb routes through this
+ * function. CLI plan §"Output formats" locks the contract:
+ *
+ *   - One line per invocation (no pretty-printing) — pipeable.
+ *   - Exactly one trailing newline so callers can `writeOut(formatJson(x))`
+ *     without remembering to add `\n`.
+ *   - `JSON.stringify` errors propagate. Unserializable inputs (cycles,
+ *     `BigInt`, etc.) are programmer errors, not user errors; the
+ *     dispatch layer treats an unhandled throw as an unexpected
+ *     condition rather than masking it behind a fake success line.
+ *
+ * Pure utility — no `console.*`, no `process.*`, no `fs.*`. Static-
+ * scan asserted by [`../../tests/formatters/json.test.ts`](../../tests/formatters/json.test.ts).
+ *
+ * Per-command JSON schemas (the shape each verb emits) are locked by
+ * the schema-side `*Result` types those verbs wrap; this formatter
+ * is shape-agnostic. When a `*Result` shape changes, the
+ * corresponding command's snapshot test catches it without anything
+ * here needing to change.
+ */
+export function formatJson(payload) {
+    return JSON.stringify(payload) + "\n";
+}
+//# sourceMappingURL=json.js.map

package/dist/formatters/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/formatters/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;AACxC,CAAC"}

package/dist/formatters/pretty.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Terminal-readable formatters for the four `neko schema *` verbs
+ * plus the two cross-cutting result kinds (load failures and Issues).
+ * v0.7 Step 28.
+ *
+ * Each function returns a `string` ending in exactly one trailing
+ * newline — same shape as `formatJson` (Step 27), so command modules
+ * can write either through the same `stdout`/`stderr` writer without
+ * remembering to add `\n`.
+ *
+ * Pure utility. No `console.*`, no `process.*`, no `fs.*`. Static-
+ * scan asserted by [`../../tests/formatters/pretty.test.ts`](../../tests/formatters/pretty.test.ts).
+ *
+ * Color is NOT applied here. CLI plan §"Explicit non-scope" defers
+ * richer color to a later phase; v0.7 ships plain ANSI-free output
+ * that respects `NO_COLOR` by default (i.e., never emits codes).
+ *
+ * Output stability — pretty output is **not** a contract across
+ * versions (the locked promise is `--json`, see [`./json.ts`](./json.ts)).
+ * These functions still aim for a deterministic shape so snapshot
+ * tests can compare against known strings; downstream consumers
+ * should consume `--json` rather than parsing pretty output.
+ *
+ * Pure: takes data in, returns a string. Inputs are never mutated;
+ * sorted/iterated lazily and the caller's arrays are preserved.
+ */
+import type { DiffChange, DiffSeverity, FreshnessVerdict, GeneratedArtifact, MigrationEntry, RegistryEntry } from "@nekostack/schema/cli";
+import type { Issue } from "@nekostack/schema";
+import type { LoadFailure } from "../loaders/tsx-loader.js";
+/**
+ * Render a registry-listing as a fixed-width table. Format matches
+ * the example in the CLI companion plan:
+ *
+ *     3 schemas in workspace:
+ *       com.nekostack.tenant.Tenant      1.0.0          path/to/tenant.schema.ts
+ *       com.nekostack.audit.AuditEvent   1.0.0          path/to/audit-event.schema.ts
+ *
+ * Empty input produces a single human-readable line. Versions are
+ * displayed as `(unversioned)` when the entry's `schemaVersion` is
+ * `undefined`. Entries are NOT re-sorted here — `listHandler`
+ * already returns them in deterministic schemaId-ascending order.
+ */
+export declare function formatListPretty(entries: readonly RegistryEntry[]): string;
+/**
+ * Render a migration-listing as a fixed-width table. Same shape as
+ * `formatListPretty` but with `(schemaId, fromVersion → toVersion,
+ * sourcePath)` columns. Entries are NOT re-sorted —
+ * `listMigrationsHandler` already returns them in
+ * `(schemaId, fromVersion, toVersion)` ascending order.
+ *
+ * The `migration` field on `MigrationEntry` (the loaded `AnyMigration`)
+ * is deliberately NOT rendered: it carries a closure `transform` that
+ * the v0.8 boundary forbids touching here, and the pretty output is
+ * for human review of the registry shape only.
+ */
+export declare function formatMigrationListPretty(entries: readonly MigrationEntry[]): string;
+/**
+ * Render a `DiffResult.data` payload (the unwrapped success branch).
+ * Header carries the count + `worstSeverity`; rows list each change
+ * as `[severity] kind at path — message`.
+ *
+ * Empty change list prints `No changes.` with the worst-severity
+ * sentinel `null`. Non-empty lists print the count and severity in
+ * a uniform header so machine post-processing (e.g., a CI script
+ * grepping the pretty output, even though `--json` is the contract)
+ * has a stable single-line summary at the top.
+ */
+export declare function formatDiffPretty(payload: {
+    readonly changes: readonly DiffChange[];
+    readonly worstSeverity: DiffSeverity | null;
+}): string;
+/**
+ * Render a list of freshness verdicts (`CheckResult.data.verdicts`).
+ * Header is a per-status tally:
+ *
+ *     4 artifacts: 2 clean, 1 cosmetic_drift, 1 stale
+ *
+ * Body lists each verdict as `[status] artifactPath` in input order
+ * (the schema-side handler emits in the order the CLI handed it the
+ * artifacts, which is already deterministic — see Step 24).
+ *
+ * Empty input prints a single human-readable line; the CLI dispatch
+ * layer is responsible for deciding what an empty `check` exits as.
+ */
+export declare function formatCheckPretty(verdicts: readonly FreshnessVerdict[]): string;
+/**
+ * Render the list of `GeneratedArtifact`s `generateHandler` returned.
+ * The CLI dispatch layer is what actually writes each artifact's
+ * `content` to its `suggestedPath`; this formatter only summarizes
+ * the plan for the user's terminal.
+ *
+ *     Generated 12 artifacts (3 schemas × 4 kinds):
+ *       com.x.Tenant     typescript    schemas/generated/tenant.types.ts
+ *       com.x.Tenant     zod           schemas/generated/tenant.zod.ts
+ *       …
+ *
+ * Empty input prints a single human-readable line. Artifacts are
+ * NOT re-sorted — `generateHandler` already emits them in
+ * deterministic schemaId-then-kind order.
+ */
+export declare function formatGeneratePretty(artifacts: readonly GeneratedArtifact[]): string;
+/**
+ * Render `LoadFailure[]` from a CLI loader (`walk-workspace.ts` for
+ * schema files, `read-migrations.ts` for migration files). Each row
+ * carries the file path, the locked reason, and the underlying
+ * message. Used by the CLI dispatch layer when one or more files
+ * failed to load — distinct concern from `Issue[]` (the schema-side
+ * normalized error vocabulary).
+ *
+ * The header noun defaults to `"schema file" / "schema files"` so
+ * the existing `neko schema list / diff / check / generate` commands
+ * keep their byte-identical output. Migration commands pass
+ * `{ noun: { singular: "migration file", plural: "migration files" } }`
+ * so their stderr is unambiguous.
+ */
+export interface LoadFailuresPrettyOpts {
+    readonly noun?: {
+        readonly singular: string;
+        readonly plural: string;
+    };
+}
+export declare function formatLoadFailuresPretty(failures: readonly LoadFailure[], opts?: LoadFailuresPrettyOpts): string;
+/**
+ * Render a list of `Issue`s — used when a schema-side handler returns
+ * `Result.failure` and the CLI needs a human-readable digest.
+ * Severity prefixes the message; `error` is the only severity v0.7
+ * emits, but the formatter handles the full vocabulary for
+ * forward compatibility.
+ */
+export declare function formatIssuesPretty(issues: readonly Issue[]): string;
+//# sourceMappingURL=pretty.d.ts.map

package/dist/formatters/pretty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pretty.d.ts","sourceRoot":"","sources":["../../src/formatters/pretty.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAM5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,aAAa,EAAE,GAChC,MAAM,CAiBR;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,SAAS,cAAc,EAAE,GACjC,MAAM,CAiBR;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE;IACP,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;CAC7C,GACA,MAAM,CAMR;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,MAAM,CA0BR;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,iBAAiB,EAAE,GACtC,MAAM,CAcR;AAMD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE;QACd,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,WAAW,EAAE,EAChC,IAAI,GAAE,sBAA2B,GAChC,MAAM,CASR;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,MAAM,CAUnE"}