omp-conductor 0.13.0 → 0.15.0

package/src/config-schema.ts

@@ -0,0 +1,352 @@
+/**
+ * The zod schema for the on-disk conductor config, and the JSON Schema it
+ * renders.
+ *
+ * `ConductorConfig`'s vocabulary was validated field by field by hand-written
+ * guards in `config.ts`. This file is the upgrade those guards always pointed
+ * at (see the note on `Raw` in `config.ts`): the shape, the value types and
+ * every closed enum are now a declarative schema built from the same exported
+ * `as const` arrays `types.ts` publishes, so the on-disk vocabulary, the load
+ * gate and the shipped `config.schema.json` cannot fork.
+ *
+ * This schema is the per-field authority: types, enums, numeric bounds,
+ * required/optional, and defaults all live here. What it deliberately does
+ * **not** express — because the loader must, and zod cannot cleanly — is left
+ * to the residue normalisers in `config.ts`: cross-field coherence
+ * (scope-vs-explicit reporting, digest/availability times, `start !== end`),
+ * the version-keyed cap migration, the clone-URL credential rejection, and
+ * `~`/default path expansion. Editing a schema node here changes both what
+ * `loadConfig` accepts and the shipped schema; `bun test`'s freshness lock
+ * fails if the checked-in JSON is not regenerated.
+ */
+
+import { z } from "zod";
+import {
+  AUTHORITY_HOLDERS,
+  BASE_FRESHNESS,
+  BEHIND_BASE_ACTIONS,
+  CONFIG_VERSION,
+  DEFAULT_AUTHORITY,
+  DEFAULT_CAPS,
+  DEFAULT_PROJECT_POLICY,
+  DRAFT_POLICIES,
+  INTERRUPT_CATEGORIES,
+  LEGACY_RELEASE_POLICIES,
+  ORCHESTRATOR_MODES,
+  READABLE_CONFIG_VERSIONS,
+  RELEASE_REQUIREMENTS,
+  RELEASE_SHAPES,
+  REPORT_SCOPES,
+  WEEKDAYS,
+  DIGEST_CADENCES,
+} from "./types.ts";
+
+/**
+ * The quoted-literal spelling the loader uses in error text (`"a" or "b"`),
+ * so a message built from these vocabularies cannot fork from the values it
+ * names. Kept here (not in `config.ts`) because `config.ts` imports this file
+ * at the parse boundary.
+ */
+export function quoteList(values: readonly string[]): string {
+  return values.map((v) => `"${v}"`).join(" or ");
+}
+
+const REPORT_SCOPE_LIST = quoteList(REPORT_SCOPES);
+const INTERRUPT_CATEGORY_LIST = quoteList(INTERRUPT_CATEGORIES);
+const WEEKDAY_LIST = quoteList(WEEKDAYS);
+const DIGEST_CADENCE_LIST = quoteList(DIGEST_CADENCES);
+const AUTHORITY_HOLDER_LIST = quoteList(AUTHORITY_HOLDERS);
+const BASE_FRESHNESS_LIST = quoteList(BASE_FRESHNESS);
+const DRAFT_POLICY_LIST = quoteList(DRAFT_POLICIES);
+const BEHIND_BASE_ACTION_LIST = quoteList(BEHIND_BASE_ACTIONS);
+const RELEASE_REQUIREMENT_LIST = quoteList(RELEASE_REQUIREMENTS);
+const RELEASE_SHAPE_LIST = quoteList(RELEASE_SHAPES);
+const ORCHESTRATOR_MODE_LIST = quoteList(ORCHESTRATOR_MODES);
+const LEGACY_RELEASE_POLICY_LIST = quoteList(LEGACY_RELEASE_POLICIES);
+
+// ---------------------------------------------------------------------------
+// Closed vocabularies — every one built from the exported `as const` array in
+// types.ts so a new member is a schema change too, never a silent fork.
+// ---------------------------------------------------------------------------
+
+const reportScopeEnum = z.enum([...REPORT_SCOPES]);
+const interruptCategoryEnum = z.enum([...INTERRUPT_CATEGORIES]);
+const weekdayEnum = z.enum([...WEEKDAYS]);
+const digestCadenceEnum = z.enum([...DIGEST_CADENCES]);
+const authorityHolderEnum = z.enum([...AUTHORITY_HOLDERS]);
+const baseFreshnessEnum = z.enum([...BASE_FRESHNESS]);
+const draftPolicyEnum = z.enum([...DRAFT_POLICIES]);
+const behindBaseActionEnum = z.enum([...BEHIND_BASE_ACTIONS]);
+const releaseRequirementEnum = z.enum([...RELEASE_REQUIREMENTS]);
+const releaseShapeEnum = z.enum([...RELEASE_SHAPES]);
+const orchestratorModeEnum = z.enum([...ORCHESTRATOR_MODES]);
+const releasePolicyLegacyEnum = z.enum([...LEGACY_RELEASE_POLICIES]);
+
+/** The 24-hour `HH:MM` shape `digest.at` / `availability.start/end` take. */
+const HHMM = /^([01]\d|2[0-3]):[0-5]\d$/;
+
+// ---------------------------------------------------------------------------
+// Caps
+// ---------------------------------------------------------------------------
+
+const planUsageCap = z
+  .object({
+    windowId: z
+      .string()
+      .min(1, "must be a non-empty allowance id such as \"anthropic:7d\"")
+      .describe("The allowance window this threshold guards"),
+    maxUsedFraction: z
+      .number()
+      .min(0)
+      .max(1)
+      
+      .describe("Consumed share, 0–1, at which new claims stop"),
+  })
+  .strict()
+  .describe("An allowance-window spend guard, or null for unmetered");
+
+const capsSchema = z
+  .object({
+    maxConcurrentWorkers: z.number().min(0).describe(`Parallel omp sessions (default ${DEFAULT_CAPS.maxConcurrentWorkers})`),
+    maxConcurrentWorkersPerRepo: z.number().min(0).describe(`Max live workers per repository (default ${DEFAULT_CAPS.maxConcurrentWorkersPerRepo})`),
+    dailySpendUsd: z
+      .number()
+      .min(0)
+      .nullable()
+      .describe(`Rolling-day spend ceiling; null means no spend gate (default ${DEFAULT_CAPS.dailySpendUsd})`),
+    planUsage: z.union([planUsageCap, z.null()]).describe(`Plan-allowance guard, or null for unmetered`),
+    workerMaxTurns: z.number().min(0).describe(`Turn ceiling for one worker (default ${DEFAULT_CAPS.workerMaxTurns})`),
+    workerMaxTurnsCeiling: z.number().min(0).describe(`Maximum turn budget assignable to one issue's next attempt`),
+    workerWallClockMs: z.number().min(0).describe(`Wall-clock ceiling for one worker (default ${DEFAULT_CAPS.workerWallClockMs})`),
+    maxAttemptsPerIssue: z.number().min(0).describe(`Failed attempts allowed before escalation (default ${DEFAULT_CAPS.maxAttemptsPerIssue})`),
+    maxContinuationsPerIssue: z.number().min(0).describe(`Operational continuations allowed before crash/resume escalation (default ${DEFAULT_CAPS.maxContinuationsPerIssue})`),
+  })
+  // A cap object carries any subset (project overrides are partial) and may
+  // carry retired keys (v1) that the load boundary drops or rejects by version,
+  // so unknown keys are kept and reconciled in `config.ts`, never rejected here.
+  .partial()
+  .loose()
+  .describe("Per-fleet or per-project hard limits");
+
+// ---------------------------------------------------------------------------
+// Reporting policy
+// ---------------------------------------------------------------------------
+
+const availabilitySchema = z
+  .object({
+    timezone: z.string().min(1).describe("IANA timezone of the window"),
+    days: z.array(weekdayEnum).min(1).describe("Days the window is open"),
+    start: z.string().regex(HHMM, "must be a 24h HH:MM time").describe("Window open time, operator-local"),
+    end: z.string().regex(HHMM, "must be a 24h HH:MM time").describe("Window close time, operator-local"),
+    bypass: z.array(interruptCategoryEnum).describe("Categories that may interrupt outside the window").optional(),
+  })
+  .strict()
+  .superRefine((a, ctx) => {
+    // Presence is required on disk (unlike a defaultable field); report the
+    // missing key in the loader's own voice rather than zod's.
+    if (a.bypass === undefined) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["bypass"],
+        message: `must be an array of ${INTERRUPT_CATEGORY_LIST} (empty means none)`,
+      });
+    }
+  });
+
+const digestSchema = z
+  .object({
+    cadence: digestCadenceEnum.describe("When the daily/report rollup is due"),
+    at: z.string().regex(HHMM, "must be a 24h HH:MM time").optional().describe("Daily rollup time"),
+    timezone: z.string().describe("IANA timezone of the daily rollup").optional(),
+  })
+  .strict()
+  .describe("The reporting digest/rollup schedule");
+
+const reportingSchema = z
+  .object({
+    scope: reportScopeEnum.optional().describe("Legacy reporting preset; mutually exclusive with the explicit form"),
+    scopePreset: reportScopeEnum.optional().describe("Back-annotation of the legacy preset this policy came from"),
+    interruptOn: z.array(interruptCategoryEnum).optional().describe("Which categories interrupt the operator's phone"),
+    digest: digestSchema.optional(),
+    availability: availabilitySchema.optional(),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------
+// Merge / release preconditions
+// ---------------------------------------------------------------------------
+
+const nameListSchema = z.array(z.string().min(1));
+
+const mergePreconditionsSchema = z
+  .object({
+    requiredChecks: nameListSchema.default(DEFAULT_PROJECT_POLICY.merge.requiredChecks),
+    baseFreshness: baseFreshnessEnum.default(DEFAULT_PROJECT_POLICY.merge.baseFreshness),
+    drafts: draftPolicyEnum.default(DEFAULT_PROJECT_POLICY.merge.drafts),
+    whenBehindBase: behindBaseActionEnum.default(DEFAULT_PROJECT_POLICY.merge.whenBehindBase),
+  })
+  .strict();
+
+const releasePreconditionsSchema = z
+  .object({
+    requires: z.array(releaseRequirementEnum).default(DEFAULT_PROJECT_POLICY.release.requires),
+    requiredChecks: nameListSchema.default(DEFAULT_PROJECT_POLICY.release.requiredChecks),
+    artefacts: nameListSchema.default(DEFAULT_PROJECT_POLICY.release.artefacts),
+    environments: nameListSchema.default(DEFAULT_PROJECT_POLICY.release.environments),
+  })
+  .strict();
+
+const projectPolicySchema = z
+  .object({
+    merge: mergePreconditionsSchema.optional(),
+    release: releasePreconditionsSchema.optional(),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------
+// Authority / escalation / release policy
+// ---------------------------------------------------------------------------
+
+const authoritySchema = z
+  .object({
+    merge: authorityHolderEnum.default(DEFAULT_AUTHORITY.merge),
+    release: authorityHolderEnum.default(DEFAULT_AUTHORITY.release),
+  })
+  .strict();
+
+const escalationSchema = z
+  .object({
+    telegramChatId: z.unknown().optional(),
+    telegramTopicId: z.unknown().optional(),
+    fallbackToIssueComment: z.unknown().default(true),
+    orchestrator: orchestratorModeEnum.default("embedded"),
+  })
+  .strict();
+
+const releasePolicySchema = z.union([
+  releasePolicyLegacyEnum,
+  z.record(z.string(), authorityHolderEnum),
+]);
+
+// ---------------------------------------------------------------------------
+// Repo targets
+// ---------------------------------------------------------------------------
+
+const gateSchema = z
+  .object({
+    cmd: z.string().optional(),
+    cwd: z.unknown().default("."),
+  })
+  .superRefine((g, ctx) => {
+    if (typeof g.cmd !== "string" || g.cmd.trim() === "") {
+      ctx.addIssue({ code: "custom", message: `must be { cmd, cwd } with a non-empty cmd` });
+    }
+  });
+
+const gatesSchema = z.array(gateSchema);
+
+const repoTargetSchema = z
+  .object({
+    name: z.unknown().optional(),
+    cloneUrl: z.string().min(1, "must be a non-empty string"),
+    defaultBranch: z.unknown().default("main").optional(),
+    gates: gatesSchema.optional(),
+    graphProject: z.string().optional(),
+    migrations: z
+      .object({ dir: z.string().min(1, "must be a non-empty string") })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+const stateLabelsSchema = z
+  .object({
+    // The loader defaults each of these (pickString), so a malformed value is
+    // tolerated rather than rejected — the schema admits any shape and lets the
+    // normaliser decide what is usable.
+    inProgress: z.unknown(),
+    blocked: z.unknown(),
+    failed: z.unknown(),
+  })
+  .partial();
+
+// ---------------------------------------------------------------------------
+// Project / root
+// ---------------------------------------------------------------------------
+
+const routingSchema = z.object({
+  labelPrefix: z.unknown().optional(),
+  repos: z
+    .record(z.string(), repoTargetSchema)
+    .refine((r) => Object.keys(r).length > 0, `routing.repos needs at least one repo entry, or no issue can be routed`),
+});
+
+const projectSchema = z
+  .object({
+    name: z.string().min(1, "must be a non-empty string"),
+    tracker: z
+      .object({
+        kind: z.literal("github").optional(),
+        repo: z.string().regex(/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/, `must look like "owner/repo"`),
+      })
+      .strict(),
+    queueLabel: z.string().min(1, "must be a non-empty string — it is the human sign-off gate"),
+    groomBelow: z.unknown().optional(),
+    stateLabels: stateLabelsSchema.optional(),
+    routing: routingSchema.optional(),
+    caps: capsSchema.optional(),
+    workerModel: z.unknown().optional(),
+    escalation: escalationSchema.optional(),
+    authority: authoritySchema.optional(),
+    releasePolicy: releasePolicySchema.optional(),
+    policy: projectPolicySchema.optional(),
+    reporting: reportingSchema.optional(),
+    // Roots silently fall back to the default when unusable, so the schema
+    // admits any shape and the normaliser picks the usable path.
+    workspaceRoot: z.unknown().optional(),
+    mirrorRoot: z.unknown().optional(),
+  })
+  .loose()
+  .describe("One product this conductor services");
+
+const configSchema = z
+  .object({
+    $schema: z.string().optional().describe("Path to the shipped config.schema.json"),
+    version: z.number().describe(`The config format version (${READABLE_CONFIG_VERSIONS.join(" or ")})`),
+    defaults: capsSchema.optional(),
+    projects: z.array(projectSchema).min(1, `"projects" must be a non-empty array — the dispatcher has nothing to service otherwise`),
+  })
+  .loose()
+  .describe("On-disk configuration for omp-conductor");
+
+// ---------------------------------------------------------------------------
+// Emitted schema
+// ---------------------------------------------------------------------------
+
+/** The zod schema `loadConfig` parses the on-disk config with. */
+export const ConfigSchema = configSchema;
+
+/**
+ * The draft 2020-12 JSON Schema rendering of {@link ConfigSchema}, shipped to
+ * `schema/config.schema.json` (see the `bun run schema` script) so editors can
+ * validate a hand-written config against the same vocabulary the loader enforces.
+ */
+export function configJsonSchema(): object {
+  return z.toJSONSchema(ConfigSchema) as object;
+}
+
+// Re-exports the renderer consumes without duplicating the lists.
+export {
+  REPORT_SCOPE_LIST,
+  INTERRUPT_CATEGORY_LIST,
+  WEEKDAY_LIST,
+  DIGEST_CADENCE_LIST,
+  AUTHORITY_HOLDER_LIST,
+  BASE_FRESHNESS_LIST,
+  DRAFT_POLICY_LIST,
+  BEHIND_BASE_ACTION_LIST,
+  RELEASE_REQUIREMENT_LIST,
+  RELEASE_SHAPE_LIST,
+  ORCHESTRATOR_MODE_LIST,
+  LEGACY_RELEASE_POLICY_LIST,
+};