Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

10.6 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

import { createRequire } from "node:module";
import type * as Zod from "zod";

/**
 * Versioned id of the context bundle contract. Bump only on a breaking shape
 * change, never per run.
 */
export const BUNDLE_SCHEMA = "ix-context-bundle/1";

/** Versioned id of the saved-investigation envelope written by `--save`. */
export const INVESTIGATION_SCHEMA = "ix-investigation/1";

/**
 * zod costs ~40 ms of module loading, on every command, and only four paths
 * of `ix context` ever validate (`--out`, `--save`, `--resume`/`--diff`,
 * `--list`). So the schemas are built on first use, from a synchronous require
 * (zod ships CommonJS too) because two of those paths are synchronous.
 */
const requireZod = createRequire(import.meta.url);

function buildSchemas(z: typeof Zod.z) {
  /**
   * Versioned contract for the deterministic context bundle produced by
   * `ix context` (schema `ix-context-bundle/1`).
   *
   * This is the single source of truth for the bundle's shape. The CLI
   * validates every bundle with it on the way to disk (investigation save and
   * `--out`) and on the way back off it (`loadInvestigation`), so a malformed
   * or unexpected payload can never be
   * written as if it were a valid bundle, nor honoured when read back.
   *
   * The shapes below mirror the `ContextBundle` and `EvidenceItem` interfaces in
   * `commands/context.ts`. Fields the renderers and `--diff` dereference by name
   * — `evidence[].title`, the `budgets`, the four `truncation` counters and
   * the `metadata` values `--diff` re-sends to the backend — are pinned to their
   * real types rather than left as open records: validation that accepts `{}`
   * where the code goes on to read `.title` or `.maxEntities` only moves the
   * failure downstream, from a named refusal to a TypeError or a NaN.
   *
   * The three backend report arrays (decisions/conflicts/intents) keep their own
   * internal shapes and stay deliberately loose here; the bundle's versioned
   * `schema` field remains the authoritative marker.
   */
  const contextBundleSchema = z.object({
    schema: z.literal(BUNDLE_SCHEMA),
    // Optional on the way in: the MCP structured copy leaves it out so identical
    // calls are byte-identical. Still declared, because zod strips an undeclared
    // key and `--save` / `--out` files must keep it.
    generatedAt: z.string().optional(),
    target: z.object({
      id: z.string(),
      name: z.string(),
      kind: z.string(),
      resolutionMode: z.string(),
      path: z.string().optional(),
    }),
    // Both optional, and only on a bundle built with `--from-issue`: every
    // bundle saved before them, and every bundle built from a named target,
    // still validates. Declared rather than left out, because zod strips an
    // undeclared key on the way to disk and on the way back.
    issue: z
      .object({
        startingPoints: z.array(
          z.object({
            token: z.string(),
            id: z.string().optional(),
            name: z.string(),
            kind: z.string(),
            path: z.string(),
            lineStart: z.number().int().positive().optional(),
            lineEnd: z.number().int().positive().optional(),
            via: z.enum(["path in issue", "identifier in issue", "bm25 fallback"]),
          }),
        ),
        unresolved: z.array(z.string()),
        fallback: z.boolean(),
      })
      .optional(),
    rankedFiles: z
      .array(z.object({ path: z.string(), score: z.number(), reason: z.string() }))
      .optional(),
    entities: z.array(
      z.object({
        id: z.string(),
        name: z.string(),
        kind: z.string(),
        path: z.string().optional(),
        lineStart: z.number().int().positive().optional(),
        lineEnd: z.number().int().positive().optional(),
        stale: z.boolean(),
      }),
    ),
    relationships: z.array(z.object({ src: z.string(), dst: z.string(), predicate: z.string() })),
    claims: z.array(
      z
        .object({ id: z.string(), entityId: z.string(), statement: z.string(), status: z.string() })
        .catchall(z.unknown()),
    ),
    // DecisionReport/ConflictReport/IntentReport are the backend's own contracts
    // with their own shapes; they are forwarded, never dereferenced field-by-field
    // here, so they stay loose rather than duplicating those types in a second
    // place that could drift from them.
    decisions: z.array(z.record(z.string(), z.unknown())),
    conflicts: z.array(z.record(z.string(), z.unknown())),
    intents: z.array(z.record(z.string(), z.unknown())),
    provenance: z
      .object({
        sourceUri: z.string().optional(),
        sourceHash: z.string().optional(),
        extractor: z.string().optional(),
        sourceType: z.string().optional(),
        observedAt: z.string().optional(),
        introducedRev: z.number().optional(),
        historyLength: z.number(),
        stale: z.boolean(),
      })
      .catchall(z.unknown()),
    freshness: z.object({ stale: z.boolean(), classification: z.string() }),
    // Only when the graph the bundle was drawn from is degraded or empty (see
    // graph-health.ts). Optional and additive, like `issue`; declared so zod
    // does not strip it on the way to disk.
    graph: z
      .object({
        status: z.string(),
        reason: z.string().optional(),
        message: z.string().optional(),
        fix: z.string().optional(),
      })
      .catchall(z.unknown())
      .optional(),
    evidence: z.array(
      z.object({
        id: z.string(),
        kind: z.string(),
        source: z.string(),
        title: z.string(),
        score: z.number(),
        reason: z.string(),
        refs: z.array(z.string()),
        // Optional and additive: bundles saved before it existed still parse.
        // Listed rather than left to `catchall`, because an unlisted key is
        // stripped on the way to disk and on the way back.
        location: z
          .object({
            path: z.string(),
            lineStart: z.number().int().positive().optional(),
            lineEnd: z.number().int().positive().optional(),
          })
          .optional(),
        // The "used by" row's sample size and total. Optional and additive,
        // listed for the same reason as `location`.
        count: z
          .object({
            shown: z.number().int().nonnegative(),
            total: z.number().int().nonnegative(),
          })
          .optional(),
      }),
    ),
    budgets: z.object({
      maxEntities: z.number().int().positive(),
      maxRelationships: z.number().int().positive(),
      maxEvidence: z.number().int().positive(),
      // Optional, and only this one. A bundle built before `--max-tokens`
      // existed carries the other four and nothing else, and zod strips keys it
      // does not declare — so leaving it out here would not have been "tolerant
      // of old files", it would have silently dropped the field from every new
      // one on its way to disk. Required would refuse to load those old files
      // instead, which is a worse answer than reporting `tokens=not-given`.
      maxTokens: z.number().int().positive().optional(),
      maxChars: z.number().int().positive(),
      // Optional and declared: the output the budget was sized for. Undeclared
      // it would be stripped on save; required it would refuse older files.
      format: z.enum(["llm", "json", "text"]).optional(),
    }),
    truncation: z.object({
      // Optional for the same reason `budgets.maxTokens` is: a bundle saved
      // before this field existed carries the counters and nothing else, and an
      // undeclared key would be stripped from every new one on its way to disk.
      cut: z.array(z.object({ what: z.string(), count: z.number().int().positive() })).optional(),
      entitiesTruncated: z.number().int().nonnegative(),
      relationshipsTruncated: z.number().int().nonnegative(),
      evidenceTruncated: z.number().int().nonnegative(),
      charactersTruncated: z.number().int().nonnegative(),
      // Optional on the way in, always written on the way out: a bundle saved
      // before the conflict cap existed has no such counter, and refusing to
      // read it back would break `--diff` against every investigation on disk.
      conflictsTruncated: z.number().int().nonnegative().optional(),
    }),
    // `asOfRev` and `depth` are the two saved values `ix context --diff` re-sends
    // to the backend, so they are typed rather than accepted as anything.
    // Unknown keys pass through: metadata is the bundle's extension point, and
    // stripping them would silently drop data on the read-back path.
    metadata: z
      .object({
        asOfRev: z.number().optional(),
        depth: z.string().optional(),
        rankingRule: z.string(),
      })
      .catchall(z.unknown()),
  });

  /**
   * Contract for the on-disk saved-investigation envelope (`~/.ix/investigations`).
   *
   * `id` and `savedAt` are rendered to the terminal and copied into the emitted
   * `ix-investigation-diff/1` JSON, so they are validated here alongside the
   * bundle rather than trusted from a bare cast.
   */
  const savedInvestigationSchema = z.object({
    schema: z.literal(INVESTIGATION_SCHEMA),
    // `sanitizeId` percent-escapes anything outside this set on the way in, so a
    // stored id can only contain these characters. Pinning the same set on the
    // way out keeps control characters and ANSI escapes out of an id that
    // `renderNote`/`renderSection` write straight to the terminal.
    id: z.string().regex(/^[A-Za-z0-9._~-]+$/),
    savedAt: z.string(),
    bundle: contextBundleSchema,
  });

  return { contextBundleSchema, savedInvestigationSchema };
}

let built: ReturnType<typeof buildSchemas> | undefined;
function schemas(): ReturnType<typeof buildSchemas> {
  return (built ??= buildSchemas((requireZod("zod") as typeof Zod).z));
}

type BundleSchema = ReturnType<typeof buildSchemas>["contextBundleSchema"];
type InvestigationSchema = ReturnType<typeof buildSchemas>["savedInvestigationSchema"];

/** The bundle contract (see `buildSchemas`); zod is loaded on the first parse. */
export const contextBundleSchema = {
  parse: (value: unknown): Zod.infer<BundleSchema> => schemas().contextBundleSchema.parse(value),
  safeParse: (value: unknown): ReturnType<BundleSchema["safeParse"]> => schemas().contextBundleSchema.safeParse(value),
};

/** The saved-investigation contract (see `buildSchemas`); zod is loaded on the first parse. */
export const savedInvestigationSchema = {
  parse: (value: unknown): Zod.infer<InvestigationSchema> => schemas().savedInvestigationSchema.parse(value),
  safeParse: (value: unknown): ReturnType<InvestigationSchema["safeParse"]> =>
    schemas().savedInvestigationSchema.safeParse(value),
};