@kirrosh/zond 0.26.0 → 0.27.0

package/src/core/lint/rules/heuristics.ts

@@ -1,97 +0,0 @@
-import type { OpenAPIV3 } from "openapi-types";
-import type { Issue, RuleId, Severity, HeuristicConfig } from "../types.ts";
-import { DEFAULT_SEVERITY } from "../types.ts";
-import type { ParamContext, SchemaContext, RequestBodyContext } from "../walker.ts";
-import { normalisedTypes } from "../walker.ts";
-
-interface RuleSink {
-  push(rule: RuleId, severity: Severity, message: string, opts: Partial<Pick<Issue, "path" | "method" | "fix_hint">> & { jsonpointer: string }): void;
-}
-
-/**
- * B2 — path/query param named like an id (`*_id`, `id`) without `format: uuid`
- * or `pattern`. Heuristic: only on params whose name matches the id-suffix list.
- */
-export function runParamHeuristics(ctx: ParamContext, sink: RuleSink, h: HeuristicConfig): void {
-  const p = ctx.param;
-  if (p.in !== "path" && p.in !== "query") return;
-  const schema = (p.schema ?? {}) as OpenAPIV3.SchemaObject;
-  const types = normalisedTypes(schema);
-  // B2 only applies to string-shaped ids (uuid). Integer ids are constrained
-  // by minimum/maximum (B3 territory), not by format: uuid.
-  if (types.length > 0 && !types.includes("string")) return;
-  const looksLikeId = p.name === "id" || h.id_suffixes.some(s => p.name.endsWith(s));
-  if (!looksLikeId) return;
-  const fmt = (schema as { format?: string }).format;
-  const hasPattern = !!(schema as { pattern?: string }).pattern;
-  if (fmt !== "uuid" && !hasPattern) {
-    sink.push("B2", DEFAULT_SEVERITY.B2, `id-like param "${p.name}" missing format: uuid or pattern (heuristic)`, {
-      jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
-      fix_hint: "if the id is a UUID, add format: uuid; otherwise add a pattern",
-    });
-  }
-}
-
-/**
- * B5/B6 — schema property name suggests a known semantic type, but `format`
- * is missing.
- *   - `*_at`, `*_date`, `*_time`, `created`, `updated`, `timestamp` → `date-time`
- *   - `email`, `url`, `website`, `homepage` → `email` / `uri`
- */
-export function runSchemaHeuristics(ctx: SchemaContext, sink: RuleSink, h: HeuristicConfig): void {
-  if (ctx.origin !== "property" || !ctx.propertyName) return;
-  const s = ctx.schema;
-  const types = normalisedTypes(s);
-  if (!types.includes("string")) return;
-  const fmt = (s as { format?: string }).format;
-  const name = ctx.propertyName;
-
-  // B5 — timestamp fields
-  const looksLikeTimestamp =
-    h.timestamp_suffixes.some(suf => name.endsWith(suf)) ||
-    ["created", "updated", "timestamp"].includes(name);
-  if (looksLikeTimestamp && fmt !== "date-time" && fmt !== "date") {
-    sink.push("B5", DEFAULT_SEVERITY.B5, `field "${name}" looks like a timestamp but has no format: date-time (heuristic)`, {
-      jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
-      fix_hint: "add format: date-time so --validate-schema enforces RFC3339",
-    });
-  }
-
-  // B6 — email / url
-  if (name === "email" && fmt !== "email") {
-    sink.push("B6", DEFAULT_SEVERITY.B6, `field "${name}" missing format: email (heuristic)`, {
-      jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
-      fix_hint: "add format: email",
-    });
-  }
-  if (h.url_names.includes(name) && fmt !== "uri" && fmt !== "url") {
-    sink.push("B6", DEFAULT_SEVERITY.B6, `field "${name}" missing format: uri (heuristic)`, {
-      jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
-      fix_hint: "add format: uri",
-    });
-  }
-}
-
-/**
- * B9 — request-body schema declares semantically-required-looking properties
- * (`name`, `email`, `title`) but `required: []` is empty / absent. Heuristic.
- */
-export function runRequestBodyHeuristics(ctx: RequestBodyContext, sink: RuleSink, h: HeuristicConfig): void {
-  if (!ctx.requestBody.content) return;
-  for (const [ct, mt] of Object.entries(ctx.requestBody.content)) {
-    if (!ct.includes("json")) continue;
-    const schema = mt.schema as OpenAPIV3.SchemaObject | undefined;
-    if (!schema || !schema.properties) continue;
-    const required = (schema.required ?? []) as string[];
-    const propNames = Object.keys(schema.properties);
-    const semanticPresent = h.semantic_required.filter(n => propNames.includes(n));
-    const semanticMissing = semanticPresent.filter(n => !required.includes(n));
-    if (semanticPresent.length > 0 && semanticMissing.length === semanticPresent.length) {
-      sink.push("B9", DEFAULT_SEVERITY.B9, `request body has properties [${semanticPresent.join(", ")}] but none are required (heuristic)`, {
-        jsonpointer: `${ctx.jsonpointer}/content/${ct.replace(/~/g, "~0").replace(/\//g, "~1")}/schema/required`,
-        path: ctx.path, method: ctx.method,
-        fix_hint: `consider adding to required: [${semanticMissing.map(n => `"${n}"`).join(", ")}]`,
-      });
-    }
-  }
-}

package/src/core/lint/rules/strictness.ts

@@ -1,109 +0,0 @@
-import type { OpenAPIV3 } from "openapi-types";
-import type { Issue, RuleId, Severity, HeuristicConfig } from "../types.ts";
-import { DEFAULT_SEVERITY } from "../types.ts";
-import type { ParamContext, ResponseContext, RequestBodyContext, SchemaContext } from "../walker.ts";
-import { normalisedTypes } from "../walker.ts";
-
-interface RuleSink {
-  push(rule: RuleId, severity: Severity, message: string, opts: Partial<Pick<Issue, "path" | "method" | "fix_hint">> & { jsonpointer: string }): void;
-}
-
-/**
- * Group B — formal strictness gaps on parameters.
- * B1 (path-param without format/pattern) → high.
- * B3 (integer-param without min/max — pagination names get medium, others low).
- * B4 (cursor-name string-param without minLength: 1) → low.
- */
-export function runParamStrictnessRules(ctx: ParamContext, sink: RuleSink, h: HeuristicConfig): void {
-  const p = ctx.param;
-  const schema = (p.schema ?? {}) as OpenAPIV3.SchemaObject;
-  const types = normalisedTypes(schema);
-
-  if (p.in === "path" && types.includes("string")) {
-    // Only flag string path-params: integer/number params have type-level
-    // constraints (minimum/maximum, multipleOf), so missing format/pattern
-    // is benign there.
-    const hasFormat = !!(schema as { format?: string }).format;
-    const hasPattern = !!(schema as { pattern?: string }).pattern;
-    if (!hasFormat && !hasPattern) {
-      sink.push("B1", DEFAULT_SEVERITY.B1, `path-param "${p.name}" missing format/pattern`, {
-        jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
-        fix_hint: "add format: uuid (or pattern: ^...$) so SDKs reject malformed values client-side",
-      });
-    }
-  }
-
-  if (types.includes("integer") || types.includes("number")) {
-    const hasMin = typeof (schema as { minimum?: unknown }).minimum === "number";
-    const hasMax = typeof (schema as { maximum?: unknown }).maximum === "number";
-    if (!hasMin || !hasMax) {
-      const isPagination = h.pagination_names.some(n => n.toLowerCase() === p.name.toLowerCase());
-      const sev: Severity = isPagination ? "medium" : "low";
-      const which = !hasMin && !hasMax ? "minimum/maximum" : !hasMin ? "minimum" : "maximum";
-      sink.push("B3", sev, `${p.in}-param "${p.name}" (${types.join("|")}) missing ${which}`, {
-        jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
-        fix_hint: `add ${which} so out-of-range values are rejected before reaching the server`,
-      });
-    }
-  }
-
-  if (types.includes("string") && h.cursor_names.some(n => n.toLowerCase() === p.name.toLowerCase())) {
-    const minLen = (schema as { minLength?: unknown }).minLength;
-    if (typeof minLen !== "number" || minLen < 1) {
-      sink.push("B4", DEFAULT_SEVERITY.B4, `cursor-param "${p.name}" missing minLength: 1`, {
-        jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
-        fix_hint: "add minLength: 1 so empty cursor strings are rejected client-side",
-      });
-    }
-  }
-}
-
-/**
- * B7 — 2xx response without a JSON schema. `--validate-schema` silently skips
- * such endpoints, masking real type drift.
- */
-export function runResponseStrictnessRules(ctx: ResponseContext, sink: RuleSink): void {
-  const status = parseInt(ctx.status, 10);
-  if (!Number.isFinite(status) || status < 200 || status >= 300) return;
-  // 204 No Content / 205 Reset Content / 304 Not Modified by definition carry no body.
-  if (status === 204 || status === 205) return;
-  const r = ctx.response;
-  const hasJsonSchema = r.content && Object.entries(r.content).some(([ct, mt]) => {
-    return ct.includes("json") && (mt.schema !== undefined);
-  });
-  if (!hasJsonSchema) {
-    sink.push("B7", DEFAULT_SEVERITY.B7, `${ctx.status} response missing JSON schema`, {
-      jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
-      fix_hint: "declare content.application/json.schema so --validate-schema can verify the response",
-    });
-  }
-}
-
-/**
- * B8 — request-body root schema without explicit `additionalProperties`.
- * Informational; tied to mass-assignment risk (T58).
- */
-export function runRequestBodyStrictnessRules(ctx: RequestBodyContext, sink: RuleSink): void {
-  if (!ctx.requestBody.content) return;
-  for (const [ct, mt] of Object.entries(ctx.requestBody.content)) {
-    if (!ct.includes("json")) continue;
-    const schema = mt.schema as OpenAPIV3.SchemaObject | undefined;
-    if (!schema) continue;
-    const ap = (schema as { additionalProperties?: unknown }).additionalProperties;
-    if (ap === undefined) {
-      sink.push("B8", DEFAULT_SEVERITY.B8, `request body schema does not set additionalProperties`, {
-        jsonpointer: `${ctx.jsonpointer}/content/${ct.replace(/~/g, "~0").replace(/\//g, "~1")}/schema`,
-        path: ctx.path, method: ctx.method,
-        fix_hint: "set additionalProperties: false to make mass-assignment vectors explicit",
-      });
-    }
-  }
-}
-
-/**
- * Schema-level B-rules that aren't on parameters: currently empty placeholder
- * for future expansion (e.g. response-body B5 picked up via heuristics).
- */
-export function runSchemaStrictnessRules(_ctx: SchemaContext, _sink: RuleSink): void {
-  // intentionally empty — heuristic schema-level checks live in heuristics.ts
-}

package/src/core/lint/types.ts

@@ -1,96 +0,0 @@
-import type { RecommendedAction } from "../diagnostics/failure-hints.ts";
-
-// Severity unified in src/core/severity (ARV-250). Lint historically used a
-// 3-tier ladder (high/medium/low) without 'critical' or 'info'. ARV-255
-// will downgrade most lint findings to info/low; this re-export aligns the
-// type but does not yet change DEFAULT_SEVERITY values per rule.
-import type { Severity } from "../severity/index.ts";
-export type { Severity };
-
-export type { RecommendedAction };
-
-export type RuleId =
-  | "A1" | "A2" | "A3" | "A4" | "A5" | "A6"
-  | "B1" | "B2" | "B3" | "B4" | "B5" | "B6" | "B7" | "B8" | "B9";
-
-export const ALL_RULES: RuleId[] = [
-  "A1", "A2", "A3", "A4", "A5", "A6",
-  "B1", "B2", "B3", "B4", "B5", "B6", "B7", "B8", "B9",
-];
-
-/**
- * ARV-255 (m-21 pivot): all lint findings cap at LOW/INFO. Static spec
- * analysis is hygiene — no runtime evidence, no exploit pathway, no
- * security or contract drift. The old "HIGH on missing additionalProperties"
- * inflation made the audit report unreadable; now lint lives in the
- * hygiene category and surfaces via `zond lint` separately.
- *
- * Tier assignment:
- * - `low`: real spec violations (format mismatch in example, missing
- *   path-param format, response without schema). Worth fixing, but not
- *   security.
- * - `info`: style and documentation gaps (additionalProperties, naming,
- *   missing examples, optional descriptions). Could be intentional.
- */
-export const DEFAULT_SEVERITY: Record<RuleId, Severity> = {
-  A1: "low",    A2: "low",    A3: "info",   A4: "info",   A5: "info",   A6: "info",
-  B1: "low",    B2: "info",   B3: "info",   B4: "info",   B5: "info",
-  B6: "info",   B7: "low",    B8: "info",   B9: "info",
-};
-
-export interface Issue {
-  rule: RuleId;
-  severity: Severity;
-  path?: string;
-  method?: string;
-  jsonpointer: string;
-  message: string;
-  fix_hint?: string;
-  affects?: string[];
-  /** TASK-294: agent-routable action — always `fix_spec` for lint issues
-   *  (the spec is the source of truth and the only thing to edit). */
-  recommended_action: RecommendedAction;
-}
-
-export type RuleSetting = "off" | Severity;
-
-export interface HeuristicConfig {
-  id_suffixes: string[];
-  timestamp_suffixes: string[];
-  url_names: string[];
-  cursor_names: string[];
-  pagination_names: string[];
-  semantic_required: string[];
-}
-
-export interface LintConfig {
-  rules: Partial<Record<RuleId, RuleSetting>>;
-  heuristics: HeuristicConfig;
-  ignore_paths: string[];
-  include_paths?: string[];
-  max_issues?: number;
-}
-
-export interface LintStats {
-  total: number;
-  critical: number;
-  high: number;
-  medium: number;
-  low: number;
-  info: number;
-  endpoints: number;
-}
-
-export interface LintResult {
-  issues: Issue[];
-  stats: LintStats;
-}
-
-export const DEFAULT_HEURISTICS: HeuristicConfig = {
-  id_suffixes: ["_id", "Id", "ID"],
-  timestamp_suffixes: ["_at", "_date", "_time"],
-  url_names: ["url", "website", "homepage", "callback_url", "webhook_url"],
-  cursor_names: ["after", "before", "cursor", "token", "page_token", "next_token"],
-  pagination_names: ["limit", "offset", "page", "size", "count", "per_page", "page_size"],
-  semantic_required: ["name", "email", "title"],
-};

package/src/core/lint/walker.ts

@@ -1,248 +0,0 @@
-import type { OpenAPIV3 } from "openapi-types";
-
-const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"] as const;
-
-export type SchemaContextKind =
-  | "param-schema"
-  | "request-body"
-  | "response-body"
-  | "property";
-
-export interface ParamContext {
-  kind: "parameter";
-  jsonpointer: string;
-  path: string;
-  method: string;
-  param: OpenAPIV3.ParameterObject;
-}
-
-export interface ResponseContext {
-  kind: "response";
-  jsonpointer: string;
-  path: string;
-  method: string;
-  status: string;
-  response: OpenAPIV3.ResponseObject;
-}
-
-export interface RequestBodyContext {
-  kind: "requestBody";
-  jsonpointer: string;
-  path: string;
-  method: string;
-  requestBody: OpenAPIV3.RequestBodyObject;
-}
-
-export interface SchemaContext {
-  kind: "schema";
-  jsonpointer: string;
-  path?: string;
-  method?: string;
-  origin: SchemaContextKind;
-  /** Property name if this schema is a value of `properties.<name>`. */
-  propertyName?: string;
-  schema: OpenAPIV3.SchemaObject;
-}
-
-export type WalkContext = ParamContext | ResponseContext | RequestBodyContext | SchemaContext;
-
-export type Visitor = (ctx: WalkContext) => void;
-
-/**
- * RFC6901 segment encoder: `~` → `~0`, `/` → `~1`.
- */
-function escapePointerSegment(s: string | number): string {
-  return String(s).replace(/~/g, "~0").replace(/\//g, "~1");
-}
-
-/**
- * Walk an OpenAPI 3.x document, invoking `visit` for parameters, request bodies,
- * responses, and every nested schema (recursively through properties / items /
- * combinators). Each call carries a stable RFC6901 jsonpointer so issues can
- * point precisely to the source.
- *
- * Cycles (already-visited schema objects by reference) are short-circuited so
- * `@readme/openapi-parser`-resolved $ref-cycles don't loop.
- */
-export function walk(doc: OpenAPIV3.Document, visit: Visitor): void {
-  if (!doc.paths) return;
-  for (const [path, pathItem] of Object.entries(doc.paths)) {
-    if (!pathItem) continue;
-    const pathPtr = `/paths/${escapePointerSegment(path)}`;
-
-    // Path-level parameters
-    if (pathItem.parameters) {
-      pathItem.parameters.forEach((p, idx) => {
-        const param = p as OpenAPIV3.ParameterObject;
-        const ptr = `${pathPtr}/parameters/${idx}`;
-        visit({ kind: "parameter", jsonpointer: ptr, path, method: "*", param });
-        if (param.schema) {
-          walkSchema(
-            param.schema as OpenAPIV3.SchemaObject,
-            `${ptr}/schema`,
-            { origin: "param-schema", path, method: "*" },
-            visit,
-            new Set(),
-          );
-        }
-      });
-    }
-
-    for (const m of HTTP_METHODS) {
-      const op = (pathItem as Record<string, unknown>)[m] as OpenAPIV3.OperationObject | undefined;
-      if (!op) continue;
-      const opPtr = `${pathPtr}/${m}`;
-      const method = m.toUpperCase();
-
-      // Operation-level parameters
-      if (op.parameters) {
-        op.parameters.forEach((p, idx) => {
-          const param = p as OpenAPIV3.ParameterObject;
-          const ptr = `${opPtr}/parameters/${idx}`;
-          visit({ kind: "parameter", jsonpointer: ptr, path, method, param });
-          if (param.schema) {
-            walkSchema(
-              param.schema as OpenAPIV3.SchemaObject,
-              `${ptr}/schema`,
-              { origin: "param-schema", path, method },
-              visit,
-              new Set(),
-            );
-          }
-        });
-      }
-
-      // Request body
-      if (op.requestBody) {
-        const rb = op.requestBody as OpenAPIV3.RequestBodyObject;
-        const rbPtr = `${opPtr}/requestBody`;
-        visit({ kind: "requestBody", jsonpointer: rbPtr, path, method, requestBody: rb });
-        if (rb.content) {
-          for (const [ct, mt] of Object.entries(rb.content)) {
-            if (mt.schema) {
-              walkSchema(
-                mt.schema as OpenAPIV3.SchemaObject,
-                `${rbPtr}/content/${escapePointerSegment(ct)}/schema`,
-                { origin: "request-body", path, method },
-                visit,
-                new Set(),
-              );
-            }
-          }
-        }
-      }
-
-      // Responses
-      if (op.responses) {
-        for (const [status, respObj] of Object.entries(op.responses)) {
-          const resp = respObj as OpenAPIV3.ResponseObject;
-          const respPtr = `${opPtr}/responses/${escapePointerSegment(status)}`;
-          visit({ kind: "response", jsonpointer: respPtr, path, method, status, response: resp });
-          if (resp.content) {
-            for (const [ct, mt] of Object.entries(resp.content)) {
-              if (mt.schema) {
-                walkSchema(
-                  mt.schema as OpenAPIV3.SchemaObject,
-                  `${respPtr}/content/${escapePointerSegment(ct)}/schema`,
-                  { origin: "response-body", path, method },
-                  visit,
-                  new Set(),
-                );
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-
-interface WalkSchemaCtx {
-  origin: SchemaContextKind;
-  path?: string;
-  method?: string;
-  propertyName?: string;
-}
-
-function walkSchema(
-  schema: OpenAPIV3.SchemaObject,
-  pointer: string,
-  ctx: WalkSchemaCtx,
-  visit: Visitor,
-  visited: Set<unknown>,
-): void {
-  if (!schema || typeof schema !== "object") return;
-  if (visited.has(schema)) return;
-  visited.add(schema);
-
-  visit({
-    kind: "schema",
-    jsonpointer: pointer,
-    path: ctx.path,
-    method: ctx.method,
-    origin: ctx.origin,
-    propertyName: ctx.propertyName,
-    schema,
-  });
-
-  if (schema.properties) {
-    for (const [name, sub] of Object.entries(schema.properties)) {
-      walkSchema(
-        sub as OpenAPIV3.SchemaObject,
-        `${pointer}/properties/${escapePointerSegment(name)}`,
-        { origin: "property", path: ctx.path, method: ctx.method, propertyName: name },
-        visit,
-        visited,
-      );
-    }
-  }
-
-  const arraySchema = schema as OpenAPIV3.ArraySchemaObject;
-  if (arraySchema.items) {
-    walkSchema(
-      arraySchema.items as OpenAPIV3.SchemaObject,
-      `${pointer}/items`,
-      { ...ctx, propertyName: undefined },
-      visit,
-      visited,
-    );
-  }
-
-  for (const combinator of ["allOf", "anyOf", "oneOf"] as const) {
-    const arr = (schema as Record<string, unknown>)[combinator] as OpenAPIV3.SchemaObject[] | undefined;
-    if (Array.isArray(arr)) {
-      arr.forEach((sub, idx) => {
-        walkSchema(
-          sub,
-          `${pointer}/${combinator}/${idx}`,
-          { ...ctx, propertyName: undefined },
-          visit,
-          visited,
-        );
-      });
-    }
-  }
-
-  if (typeof schema.additionalProperties === "object" && schema.additionalProperties !== null) {
-    walkSchema(
-      schema.additionalProperties as OpenAPIV3.SchemaObject,
-      `${pointer}/additionalProperties`,
-      { ...ctx, propertyName: undefined },
-      visit,
-      visited,
-    );
-  }
-}
-
-/**
- * Normalise OpenAPI 3.0 `nullable: true` so callers can reason about a single
- * type list. Returns the (possibly array) type without mutating the schema.
- */
-export function normalisedTypes(schema: OpenAPIV3.SchemaObject): string[] {
-  const t = (schema as { type?: string | string[] }).type;
-  const list: string[] = Array.isArray(t) ? [...t] : t ? [t] : [];
-  if ((schema as { nullable?: boolean }).nullable === true && !list.includes("null")) {
-    list.push("null");
-  }
-  return list;
-}

package/src/core/meta/meta-store.ts

@@ -1,11 +0,0 @@
-import { createHash } from "crypto";
-
-/**
- * SHA-256 of the canonical (decycled) JSON form of an OpenAPI document.
- * Used as the freshness hash recorded in `.api-catalog.yaml`,
- * `.api-resources.yaml`, and `.api-fixtures.yaml` so `zond doctor` can
- * detect drift between the local snapshot and its derived artifacts.
- */
-export function hashSpec(specContent: string): string {
-  return createHash("sha256").update(specContent).digest("hex");
-}

package/src/core/output/README.md

@@ -1,73 +0,0 @@
-# core/output — typed `--report` / `--output` / `--json` policy
-
-`OutputSpec<Payload>` is the single source-of-truth for how a command
-produces output. Closes the seven divergent-output bugs collected in
-`strategy/lessons.md` §E (ARV-50, ARV-82, ARV-97, …) by replacing N
-ad-hoc parsers with one resolver.
-
-## Policy matrix
-
-`resolveOutput(spec, opts)` reads `--report`, `--output`, and `--json`
-from the CLI layer and resolves them to a `ResolvedOutput` decision
-according to this matrix:
-
-| Input                                | Format         | Channel             | Notes |
-| ------------------------------------ | -------------- | ------------------- | ----- |
-| _(nothing)_                          | `defaultFormat`| from format policy  | bare invocation |
-| `--report <fmt>`                     | `<fmt>` (or alias) | from format policy | unknown → error |
-| `--json`                             | first format with `envelopeWrap: true` | from format policy | falls back to `defaultFormat` when no envelope-wrap format exists |
-| `--output <path>`                    | unchanged      | `file` (path = resolved absolute) | `--output` always wins over `defaultChannel` |
-| `--report sarif` (defaults to file)  | `sarif`        | `file` (`defaultFilename` if no `--output`) | ARV-5 default `zond-checks.sarif` |
-| `--report ndjson` (defaults to stdout) | `ndjson`     | `stdout` | event stream — see ARV-10 |
-| `--report ndjson --output <path>`    | `ndjson`       | `file`     | ARV-97 — explicit `--output` redirects the stream |
-| `--json` + `--report <fmt>`          | —              | —          | mutually exclusive (throws `OutputSpecError`) |
-
-Aliases (`spec.aliases`) let a single CLI flag value resolve to
-another format — used by `checks run` so `--report ndjson` continues to
-mean "the `--ndjson` streaming flag", matching skill-prompt
-expectations (ARV-63).
-
-## Building a spec
-
-```ts
-import type { OutputSpec } from "@/core/output";
-
-interface ChecksPayload { findings: Finding[]; summary: Summary }
-
-export const CHECKS_RUN_OUTPUT: OutputSpec<ChecksPayload> = {
-  command: "checks run",
-  defaultFormat: "json",
-  formats: {
-    json:   { defaultChannel: "stdout", envelopeWrap: true,  description: "JSON envelope" },
-    sarif:  { defaultChannel: "file",   defaultFilename: "zond-checks.sarif" },
-    ndjson: { defaultChannel: "stdout", description: "event stream — one JSON per line" },
-  },
-  aliases: {
-    // `--report ndjson` is a friendly alias retained from skill prompts.
-    ndjson: "ndjson",
-  },
-};
-```
-
-The CLI handler calls `resolveOutput()` and renders/writes the payload
-itself — each command's shape (streaming vs single-shot, envelope vs
-raw) differs enough that a shared render/write runner added indirection
-without removing per-command logic. `checks run` and `probe *` open an
-fd from `resolved.path`/`resolved.channel` and feed output into it
-incrementally; `run` renders a single payload and writes it once. See
-any of `src/cli/commands/{run,checks,probe}.ts` for the pattern.
-
-## Why the format set is open
-
-Each command owns its own format vocabulary. `run` ships
-`json`/`junit`; `checks run` ships `json`/`sarif`/`ndjson`; `probe *`
-ships `json` only. Declaring formats per-spec instead of in a global
-union avoids a leaky enum and keeps `--help` accurate per command.
-
-## Errors
-
-`resolveOutput` throws `OutputSpecError` for policy violations
-(`--json + --report`, unknown format, file-default without filename).
-The CLI handler catches it and produces either `jsonError` or a human
-`printError`, matching the rest of the codebase's input-error
-behaviour (exit code 2).

package/src/core/output/index.ts

@@ -1,13 +0,0 @@
-/**
- * ARV-116 (m-19): public surface of the output-spec module.
- */
-export type {
-  OutputChannel,
-  OutputFormat,
-  OutputOptions,
-  OutputSpec,
-  FormatPolicy,
-  ResolvedOutput,
-} from "./types.ts";
-export { OutputSpecError } from "./types.ts";
-export { resolveOutput } from "./run.ts";