@akanjs/devkit 3.1.0-rc.1 → 3.1.0-rc.2

package/pipeline/PipelineInputReader.ts

@@ -1,122 +1,62 @@
 import {
-  type PipelineActionName,
   type PipelineDiagnostic,
-  type PipelineMilestone,
   PipelineNames,
-  type PipelineOtaPlatform,
   PipelinePattern,
   type PipelinePlanRetry,
-  type PipelineTrigger,
+  type PipelineValueProblem,
+  PipelineValueReader,
   pipelineActionNames,
   pipelineMilestones,
   pipelineOtaPlatforms,
   pipelinePlanLimits,
   pipelineTriggers,
 } from "akanjs/common";
+import type {
+  PipelineActionStageRule,
+  PipelineAppRule,
+  PipelineAppStageRule,
+  PipelineMatrixStageRule,
+  PipelineParallelStageRule,
+  PipelinePostRule,
+  PipelineShellStageRule,
+  PipelineStepRule,
+  PipelineWhenRule,
+  PipelineWorkspaceRule,
+  PipelineWorkspaceStageRule,
+} from "./PipelineRules";
 
-export interface PipelineWhenRule {
-  branch: string[] | null;
-  trigger: PipelineTrigger[] | null;
-  changed: string[] | null;
-  /** A workspace `matrix: "apps"` stage's narrowing; never set elsewhere. */
-  app: string[] | null;
-}
-
-export interface PipelineStepRule {
-  localId: string;
-  name: string;
-  timeoutSeconds: number | null;
-  retry: PipelinePlanRetry | null;
-  allowFailure: boolean;
-  run: string;
-  cwd: string;
-  /** The stage's env under the step's own. */
-  env: Record<string, string>;
-  secrets: string[];
-  skipExitCodes: number[];
-}
-
-interface PipelineStageRuleBase {
-  id: string;
-  name: string;
-  description: string | null;
-  milestone: PipelineMilestone | null;
-  when: PipelineWhenRule;
-  timeoutSeconds: number | null;
-  allowFailure: boolean;
-  path: string;
-}
-
-export interface PipelineShellStageRule extends PipelineStageRuleBase {
-  kind: "sh";
-  steps: PipelineStepRule[];
-}
-
-export interface PipelineActionStageRule extends PipelineStageRuleBase {
-  kind: "action";
-  action: PipelineActionName;
-  named: boolean;
-  retry: PipelinePlanRetry | null;
-  /** `ota` only; `null` takes the default. */
-  targets: string[] | null;
-  platforms: PipelineOtaPlatform[] | null;
-}
-
-export interface PipelineParallelStageRule extends PipelineStageRuleBase {
-  kind: "parallel";
-  maxParallel: number | null;
-  failFast: boolean;
-  branches: PipelineShellStageRule[];
-}
-
-export interface PipelineMatrixStageRule extends PipelineStageRuleBase {
-  kind: "matrix";
-  maxParallel: number | null;
-  steps: PipelineStepRule[];
-}
-
-export type PipelineWorkspaceStageRule = PipelineShellStageRule | PipelineParallelStageRule | PipelineMatrixStageRule;
-export type PipelineAppStageRule = PipelineShellStageRule | PipelineActionStageRule;
-
-export interface PipelinePostRule {
-  success: PipelineStepRule[];
-  failure: PipelineStepRule[];
-  canceled: PipelineStepRule[];
-  always: PipelineStepRule[];
-}
-
-export interface PipelineWorkspaceRule {
-  env: Record<string, string>;
-  timeoutSeconds: number | null;
-  before: PipelineWorkspaceStageRule[];
-  after: PipelineWorkspaceStageRule[];
-  post: PipelinePostRule;
-}
-
-export interface PipelineAppRule {
-  env: Record<string, string>;
-  after: string[];
-  stages: PipelineAppStageRule[];
-}
-
-type Scope = "workspace" | "app";
 type JsonObject = Record<string, unknown>;
 
 /** Turns one file's `pipeline` value into rules, reporting what is wrong with it rather than throwing. */
 export class PipelineInputReader {
   static readonly #futureKeys = ["cache", "artifacts", "input", "image", "services", "notify"];
+  static readonly #stageKeys = ["id", "name", "description", "milestone", "when", "timeout", "allowFailure"];
+  static readonly #shellKeys = [...PipelineInputReader.#stageKeys, "sh", "steps", "env", "secrets", "retry"];
+  static readonly #postResults: readonly string[] = ["success", "failure", "canceled", "always"];
   static readonly #durationPattern = /^(\d+)(s|m|h)$/;
+  static readonly #trailingHighSurrogate = /[\uD800-\uDBFF]$/;
   static readonly #stepNameChars = 80;
+  static readonly #shownChars = 80;
+
+  static clip(text: string, max: number) {
+    if (text.length <= max) return text;
+    const cut = text.slice(0, max - 1);
+    return `${PipelineInputReader.#trailingHighSurrogate.test(cut) ? cut.slice(0, -1) : cut}…`;
+  }
 
   readonly diagnostics: PipelineDiagnostic[] = [];
   readonly #file: string;
+  readonly #read = new PipelineValueReader<null>("config", (path, ...problems) => {
+    for (const problem of problems) this.#problem(path, problem);
+    return null;
+  });
 
   constructor(file: string) {
     this.#file = file;
   }
 
   workspace(value: unknown): PipelineWorkspaceRule | null {
-    const input = this.#object(value, "pipeline", ["schemaVersion", "env", "timeout", "before", "after", "post"]);
+    const input = this.#read.object(value, "pipeline", ["schemaVersion", "env", "timeout", "before", "after", "post"]);
     if (!input) return null;
     this.#schemaVersion(input.schemaVersion, "pipeline.schemaVersion");
     const ids = new Set<string>();
@@ -136,7 +76,7 @@ export class PipelineInputReader {
   }
 
   app(value: unknown): PipelineAppRule | null {
-    const input = this.#object(value, "pipeline", ["schemaVersion", "stages", "env", "after"]);
+    const input = this.#read.object(value, "pipeline", ["schemaVersion", "stages", "env", "after"]);
     if (!input) return null;
     this.#schemaVersion(input.schemaVersion, "pipeline.schemaVersion");
     if (input.stages === undefined) this.#report("pipeline.schema.invalid", "lists no `stages`", "pipeline");
@@ -154,9 +94,9 @@ export class PipelineInputReader {
   }
 
   #workspaceStage(value: unknown, path: string): PipelineWorkspaceStageRule | null {
-    const raw = this.#object(value, path);
+    const raw = this.#read.object(value, path);
     if (!raw) return null;
-    if ("use" in raw) {
+    if (this.#declares(raw, "use")) {
       this.#report(
         "pipeline.schema.invalid",
         "built-in actions are declared per app, in apps/<app>/akan.config.ts",
@@ -164,49 +104,50 @@ export class PipelineInputReader {
       );
       return null;
     }
-    if ("parallel" in raw) return this.#parallelStage(raw, path);
-    if ("matrix" in raw) return this.#matrixStage(raw, path);
-    return this.#shellStage(raw, path, "workspace");
+    if (this.#declares(raw, "parallel")) return this.#parallelStage(raw, path);
+    if (this.#declares(raw, "matrix")) return this.#matrixStage(raw, path);
+    return this.#shellStage(raw, path);
   }
 
   #appStage(value: unknown, path: string): PipelineAppStageRule | null {
-    const raw = this.#object(value, path);
+    const raw = this.#read.object(value, path);
     if (!raw) return null;
-    if ("parallel" in raw || "matrix" in raw) {
+    const workspaceKey = this.#declares(raw, "parallel") ? "parallel" : this.#declares(raw, "matrix") ? "matrix" : null;
+    if (workspaceKey) {
       this.#report(
         "pipeline.schema.invalid",
-        `an app's own stage takes no \`${"parallel" in raw ? "parallel" : "matrix"}\`: it is already that app's, and parallel or per-app copies belong to the workspace root akan.config.ts`,
+        `an app's own stage takes no \`${workspaceKey}\`: it is already that app's, and parallel or per-app copies belong to the workspace root akan.config.ts`,
         path,
       );
       return null;
     }
-    if ("use" in raw) return this.#actionStage(raw, path);
-    return this.#shellStage(raw, path, "app");
+    if (this.#declares(raw, "use")) return this.#actionStage(raw, path);
+    return this.#shellStage(raw, path);
+  }
+
+  //? `key: undefined` is the key left out, but on a stage without `sh` or `steps` it still tells which kind was meant.
+  #declares(raw: JsonObject, key: "use" | "parallel" | "matrix") {
+    return raw[key] !== undefined || (key in raw && raw.sh === undefined && raw.steps === undefined);
   }
 
   #actionStage(raw: JsonObject, path: string): PipelineActionStageRule | null {
     if (
-      !this.#keys(raw, path, [
+      !this.#read.keys(raw, path, [
         "use",
-        "id",
-        "name",
-        "description",
-        "milestone",
-        "when",
-        "timeout",
-        "allowFailure",
+        ...PipelineInputReader.#stageKeys,
         "retry",
         ...(raw.use === "ota" ? ["targets", "platforms"] : []),
       ])
     )
       return null;
-    const action = this.#oneOf(raw.use, `${path}.use`, pipelineActionNames);
+    const action = this.#read.oneOf(raw.use, `${path}.use`, pipelineActionNames);
     if (!action) return null;
-    const name = raw.name === undefined ? null : this.#text(raw.name, `${path}.name`, pipelinePlanLimits.nameChars);
+    const name =
+      raw.name === undefined ? null : this.#read.string(raw.name, `${path}.name`, pipelinePlanLimits.nameChars);
     const id = raw.id === undefined ? action : this.#id(raw.id, `${path}.id`);
     if (!id) return null;
     const attempts =
-      raw.retry === undefined ? null : this.#int(raw.retry, `${path}.retry`, 1, pipelinePlanLimits.retryAttempts);
+      raw.retry === undefined ? null : this.#read.int(raw.retry, `${path}.retry`, 1, pipelinePlanLimits.retryAttempts);
     return {
       kind: "action",
       action,
@@ -215,7 +156,7 @@ export class PipelineInputReader {
       named: name !== null,
       description: this.#description(raw.description, `${path}.description`),
       milestone: this.#milestone(raw.milestone, `${path}.milestone`),
-      when: this.#when(raw.when, `${path}.when`, false),
+      when: this.#when(raw.when, `${path}.when`),
       timeoutSeconds: this.#duration(raw.timeout, `${path}.timeout`),
       allowFailure: this.#boolean(raw.allowFailure, `${path}.allowFailure`),
       retry: attempts === null ? null : { attempts, delaySeconds: 0 },
@@ -228,7 +169,7 @@ export class PipelineInputReader {
           ? null
           : this.#nonEmptySet(
               this.#list(raw.platforms, `${path}.platforms`).flatMap((platform, idx) => {
-                const parsed = this.#oneOf(platform, `${path}.platforms[${idx}]`, pipelineOtaPlatforms);
+                const parsed = this.#read.oneOf(platform, `${path}.platforms[${idx}]`, pipelineOtaPlatforms);
                 return parsed ? [parsed] : [];
               }),
               `${path}.platforms`,
@@ -245,55 +186,25 @@ export class PipelineInputReader {
     return [...new Set(items)];
   }
 
-  #shellStage(raw: JsonObject, path: string, scope: Scope): PipelineShellStageRule | null {
-    const keys = [
-      "id",
-      "name",
-      "description",
-      "milestone",
-      "when",
-      "timeout",
-      "allowFailure",
-      "sh",
-      "steps",
-      "env",
-      "secrets",
-      "retry",
-    ];
-    if (!this.#keys(raw, path, keys)) return null;
-    const head = this.#stageHead(raw, path, scope === "workspace" ? "workspace" : "app");
+  #shellStage(raw: JsonObject, path: string): PipelineShellStageRule | null {
+    if (!this.#read.keys(raw, path, PipelineInputReader.#shellKeys)) return null;
+    const head = this.#stageHead(raw, path);
     if (!head) return null;
     const steps = this.#stageSteps(raw, path);
     return steps ? { kind: "sh", ...head, steps } : null;
   }
 
   #matrixStage(raw: JsonObject, path: string): PipelineMatrixStageRule | null {
-    const keys = [
-      "id",
-      "name",
-      "description",
-      "milestone",
-      "when",
-      "timeout",
-      "allowFailure",
-      "sh",
-      "steps",
-      "env",
-      "secrets",
-      "retry",
-      "matrix",
-      "maxParallel",
-    ];
-    if (!this.#keys(raw, path, keys)) return null;
+    if (!this.#read.keys(raw, path, [...PipelineInputReader.#shellKeys, "matrix", "maxParallel"])) return null;
     if (raw.matrix !== "apps") {
       this.#report(
         "pipeline.schema.invalid",
-        `${JSON.stringify(raw.matrix)} is not a matrix axis: only "apps"`,
+        `${PipelineInputReader.#show(raw.matrix)} is not a matrix axis: only "apps"`,
         `${path}.matrix`,
       );
       return null;
     }
-    const head = this.#stageHead(raw, path, "matrix");
+    const head = this.#stageHead(raw, path, { allowApp: true });
     if (!head) return null;
     const steps = this.#stageSteps(raw, path);
     if (!steps) return null;
@@ -301,35 +212,22 @@ export class PipelineInputReader {
   }
 
   #parallelStage(raw: JsonObject, path: string): PipelineParallelStageRule | null {
-    const keys = [
-      "id",
-      "name",
-      "description",
-      "milestone",
-      "when",
-      "timeout",
-      "allowFailure",
-      "parallel",
-      "maxParallel",
-      "failFast",
-      "env",
-      "secrets",
-    ];
-    if (!this.#keys(raw, path, keys)) return null;
-    const head = this.#stageHead(raw, path, "workspace");
+    const keys = [...PipelineInputReader.#stageKeys, "parallel", "maxParallel", "failFast", "env", "secrets"];
+    if (!this.#read.keys(raw, path, keys)) return null;
+    const head = this.#stageHead(raw, path);
     if (!head) return null;
     const env = this.#env(raw.env, `${path}.env`);
     const secrets = this.#secrets(raw.secrets, `${path}.secrets`);
     const ids = new Set<string>();
     const branches = this.#list(raw.parallel, `${path}.parallel`).flatMap((branch, idx) => {
       const branchPath = `${path}.parallel[${idx}]`;
-      const branchRaw = this.#object(branch, branchPath);
+      const branchRaw = this.#read.object(branch, branchPath);
       if (!branchRaw) return [];
-      if ("use" in branchRaw || "parallel" in branchRaw || "matrix" in branchRaw) {
+      if ((["use", "parallel", "matrix"] as const).some((key) => this.#declares(branchRaw, key))) {
         this.#report("pipeline.schema.invalid", "a parallel branch is a shell stage", branchPath);
         return [];
       }
-      const rule = this.#shellStage(branchRaw, branchPath, "workspace");
+      const rule = this.#shellStage(branchRaw, branchPath);
       if (!rule) return [];
       if (rule.when.changed && head.when.changed) {
         this.#report(
@@ -339,6 +237,12 @@ export class PipelineInputReader {
         );
         return [];
       }
+      if (head.id === "post" && PipelineInputReader.#postResults.includes(rule.id))
+        this.#report(
+          "pipeline.id.reserved",
+          `"post.${rule.id}" is reserved for the steps of post.${rule.id}; give this branch or its parallel stage another \`id\``,
+          `${branchPath}.${branchRaw.id === undefined ? "name" : "id"}`,
+        );
       this.#claimId(ids, rule.id, rule.path);
       const steps = rule.steps.map((step) => ({
         ...step,
@@ -347,7 +251,7 @@ export class PipelineInputReader {
       }));
       return [{ ...rule, steps }];
     });
-    if (!branches.length && Array.isArray(raw.parallel))
+    if (!branches.length && (raw.parallel === undefined || Array.isArray(raw.parallel)))
       this.#report("pipeline.schema.invalid", "a parallel stage holds at least one branch", `${path}.parallel`);
     return {
       kind: "parallel",
@@ -358,8 +262,8 @@ export class PipelineInputReader {
     };
   }
 
-  #stageHead(raw: JsonObject, path: string, whenScope: "workspace" | "app" | "matrix") {
-    const name = this.#text(raw.name, `${path}.name`, pipelinePlanLimits.nameChars);
+  #stageHead(raw: JsonObject, path: string, { allowApp = false }: { allowApp?: boolean } = {}) {
+    const name = this.#read.string(raw.name, `${path}.name`, pipelinePlanLimits.nameChars);
     if (name === null) return null;
     const id = raw.id === undefined ? this.#slugId(name, `${path}.name`) : this.#id(raw.id, `${path}.id`);
     if (!id) return null;
@@ -368,7 +272,7 @@ export class PipelineInputReader {
       name,
       description: this.#description(raw.description, `${path}.description`),
       milestone: this.#milestone(raw.milestone, `${path}.milestone`),
-      when: this.#when(raw.when, `${path}.when`, whenScope === "matrix"),
+      when: this.#when(raw.when, `${path}.when`, { allowApp }),
       timeoutSeconds: this.#duration(raw.timeout, `${path}.timeout`),
       allowFailure: this.#boolean(raw.allowFailure, `${path}.allowFailure`),
       path,
@@ -407,11 +311,11 @@ export class PipelineInputReader {
   }
 
   #step(value: unknown, path: string, idx: number): PipelineStepRule | null {
-    const raw = typeof value === "string" ? { sh: value } : this.#object(value, path);
+    const raw = typeof value === "string" ? { sh: value } : this.#read.object(value, path);
     if (!raw) return null;
     const keys = ["sh", "id", "name", "cwd", "env", "secrets", "timeout", "retry", "allowFailure", "skipExitCodes"];
-    if (!this.#keys(raw, path, keys)) return null;
-    const run = this.#text(raw.sh, typeof value === "string" ? path : `${path}.sh`, Number.POSITIVE_INFINITY);
+    if (!this.#read.keys(raw, path, keys)) return null;
+    const run = this.#read.string(raw.sh, typeof value === "string" ? path : `${path}.sh`, Number.POSITIVE_INFINITY);
     if (run === null) return null;
     if (new TextEncoder().encode(run).length > pipelinePlanLimits.shBytes) {
       this.#report("pipeline.limit.exceeded", `a script is at most ${pipelinePlanLimits.shBytes} bytes`, path);
@@ -420,7 +324,7 @@ export class PipelineInputReader {
     const name =
       raw.name === undefined
         ? PipelineInputReader.#nameOf(run)
-        : this.#text(raw.name, `${path}.name`, pipelinePlanLimits.nameChars);
+        : this.#read.string(raw.name, `${path}.name`, pipelinePlanLimits.nameChars);
     if (name === null) return null;
     const localId =
       raw.id !== undefined
@@ -446,10 +350,10 @@ export class PipelineInputReader {
   #post(value: unknown, path: string): PipelinePostRule {
     const empty: PipelinePostRule = { success: [], failure: [], canceled: [], always: [] };
     if (value === undefined) return empty;
-    const raw = this.#object(value, path);
+    const raw = this.#read.object(value, path);
     if (!raw) return empty;
     for (const key of Object.keys(raw))
-      if (!["success", "failure", "canceled", "always"].includes(key))
+      if (!PipelineInputReader.#postResults.includes(key))
         this.#report(
           "pipeline.schema.unknownKey",
           key === "unstable"
@@ -473,10 +377,10 @@ export class PipelineInputReader {
     };
   }
 
-  #when(value: unknown, path: string, allowApp: boolean): PipelineWhenRule {
+  #when(value: unknown, path: string, { allowApp = false }: { allowApp?: boolean } = {}): PipelineWhenRule {
     const none: PipelineWhenRule = { branch: null, trigger: null, changed: null, app: null };
     if (value === undefined) return none;
-    const raw = this.#object(value, path);
+    const raw = this.#read.object(value, path);
     if (!raw) return none;
     for (const key of Object.keys(raw)) {
       if (["branch", "trigger", "changed"].includes(key) || (allowApp && key === "app")) continue;
@@ -493,10 +397,12 @@ export class PipelineInputReader {
         ? null
         : (typeof raw.trigger === "string" ? [raw.trigger] : this.#list(raw.trigger, `${path}.trigger`)).flatMap(
             (trigger, idx) => {
-              const parsed = this.#oneOf(trigger, `${path}.trigger[${idx}]`, pipelineTriggers);
+              const parsed = this.#read.oneOf(trigger, `${path}.trigger[${idx}]`, pipelineTriggers);
               return parsed ? [parsed] : [];
             },
           );
+    if (Array.isArray(raw.trigger) && !raw.trigger.length)
+      this.#report("pipeline.schema.invalid", "a trigger list may not be empty", `${path}.trigger`);
     return {
       branch: this.#patterns(raw.branch, `${path}.branch`),
       trigger: triggers,
@@ -520,14 +426,14 @@ export class PipelineInputReader {
     if (value !== undefined && value !== 1)
       this.#report(
         "pipeline.schema.unsupported",
-        `${JSON.stringify(value)} is not a schemaVersion this CLI reads (1)`,
+        `${PipelineInputReader.#show(value)} is not a schemaVersion this CLI reads (1)`,
         path,
       );
   }
 
   #env(value: unknown, path: string): Record<string, string> {
     if (value === undefined) return {};
-    const raw = this.#object(value, path);
+    const raw = this.#read.object(value, path);
     if (!raw) return {};
     const env: Record<string, string> = {};
     for (const [name, entry] of Object.entries(raw)) {
@@ -535,6 +441,12 @@ export class PipelineInputReader {
       if (problem) this.#report("pipeline.env.name", problem, `${path}.${name}`);
       else if (typeof entry !== "string")
         this.#report("pipeline.schema.invalid", "must be a string", `${path}.${name}`);
+      else if (entry.length > pipelinePlanLimits.shBytes)
+        this.#report(
+          "pipeline.limit.exceeded",
+          `an env value is at most ${pipelinePlanLimits.shBytes} characters`,
+          `${path}.${name}`,
+        );
       else env[name] = entry;
     }
     return env;
@@ -542,9 +454,9 @@ export class PipelineInputReader {
 
   #secrets(value: unknown, path: string): string[] {
     const names = value === undefined ? [] : this.#strings(value, path);
-    const valid = names.filter((name) => {
+    const valid = names.filter((name, idx) => {
       const problem = PipelineNames.secretNameError(name);
-      if (problem) this.#report("pipeline.secret.name", problem, path);
+      if (problem) this.#report("pipeline.secret.name", problem, `${path}[${idx}]`);
       return !problem;
     });
     return [...new Set(valid)];
@@ -552,7 +464,7 @@ export class PipelineInputReader {
 
   #cwd(value: unknown, path: string) {
     if (value === undefined) return ".";
-    const cwd = this.#text(value, path, 1024);
+    const cwd = this.#read.string(value, path, 1024);
     if (cwd === null) return ".";
     if (cwd.startsWith("/") || cwd.startsWith("~") || cwd.includes("\\") || cwd.split("/").includes("..")) {
       this.#report("pipeline.cwd.outside", `"${cwd}" is not a path inside the workspace`, path);
@@ -564,7 +476,7 @@ export class PipelineInputReader {
   #exitCodes(value: unknown, path: string): number[] {
     if (value === undefined) return [];
     const codes = this.#list(value, path).flatMap((code, idx) => {
-      const parsed = this.#int(code, `${path}[${idx}]`, 1, 255);
+      const parsed = this.#read.int(code, `${path}[${idx}]`, 1, 255);
       return parsed === null ? [] : [parsed];
     });
     return [...new Set(codes)];
@@ -573,12 +485,12 @@ export class PipelineInputReader {
   #retry(value: unknown, path: string): PipelinePlanRetry | null {
     if (value === undefined) return null;
     if (typeof value === "number") {
-      const attempts = this.#int(value, path, 1, pipelinePlanLimits.retryAttempts);
+      const attempts = this.#read.int(value, path, 1, pipelinePlanLimits.retryAttempts);
       return attempts === null ? null : { attempts, delaySeconds: 0 };
     }
-    const raw = this.#object(value, path);
-    if (!raw || !this.#keys(raw, path, ["attempts", "delay"])) return null;
-    const attempts = this.#int(raw.attempts, `${path}.attempts`, 1, pipelinePlanLimits.retryAttempts);
+    const raw = this.#read.object(value, path);
+    if (!raw || !this.#read.keys(raw, path, ["attempts", "delay"])) return null;
+    const attempts = this.#read.int(raw.attempts, `${path}.attempts`, 1, pipelinePlanLimits.retryAttempts);
     const delaySeconds = this.#duration(raw.delay, `${path}.delay`, {
       min: 0,
       max: pipelinePlanLimits.retryDelaySeconds,
@@ -598,7 +510,7 @@ export class PipelineInputReader {
     if (!Number.isInteger(seconds) || seconds < min || seconds > max) {
       this.#report(
         "pipeline.duration.invalid",
-        `${JSON.stringify(value)} is not a duration between ${min} and ${max} seconds: whole seconds, or "30s", "20m", "1h"`,
+        `${PipelineInputReader.#show(value)} is not a duration between ${min} and ${max} seconds: whole seconds, or "30s", "20m", "1h"`,
         path,
       );
       return null;
@@ -607,19 +519,19 @@ export class PipelineInputReader {
   }
 
   #maxParallel(value: unknown, path: string) {
-    return value === undefined ? null : this.#int(value, path, 1, pipelinePlanLimits.stages);
+    return value === undefined ? null : this.#read.int(value, path, 1, pipelinePlanLimits.stages);
   }
 
   #milestone(value: unknown, path: string) {
-    return value === undefined ? null : this.#oneOf(value, path, pipelineMilestones);
+    return value === undefined ? null : this.#read.oneOf(value, path, pipelineMilestones);
   }
 
   #description(value: unknown, path: string) {
-    return value === undefined ? null : this.#text(value, path, pipelinePlanLimits.descriptionChars);
+    return value === undefined ? null : this.#read.string(value, path, pipelinePlanLimits.descriptionChars);
   }
 
   #id(value: unknown, path: string) {
-    const id = this.#text(value, path, 64);
+    const id = this.#read.string(value, path, 64);
     if (id === null) return null;
     const problem = PipelineNames.idError(id);
     if (problem) {
@@ -657,80 +569,72 @@ export class PipelineInputReader {
       .split("\n")
       .map((text) => text.trim())
       .find(Boolean);
-    const name = line ?? run.trim();
-    return name.length > PipelineInputReader.#stepNameChars
-      ? `${name.slice(0, PipelineInputReader.#stepNameChars - 1)}…`
-      : name;
+    return PipelineInputReader.clip(line ?? run.trim(), PipelineInputReader.#stepNameChars);
   }
 
-  #keys(raw: JsonObject, path: string, keys: readonly string[]) {
-    let ok = true;
-    for (const key of Object.keys(raw)) {
-      if (keys.includes(key)) continue;
-      ok = false;
-      if (PipelineInputReader.#futureKeys.includes(key))
-        this.#report("pipeline.schema.unsupported", `\`${key}\` is not supported in schemaVersion 1`, `${path}.${key}`);
-      else
-        this.#report("pipeline.schema.unknownKey", `"${key}" is not a key here: ${keys.join(", ")}`, `${path}.${key}`);
+  static #show(value: unknown) {
+    let text: string;
+    try {
+      text = JSON.stringify(value) ?? String(value);
+    } catch {
+      text = typeof value === "bigint" ? `${value}n` : Object.prototype.toString.call(value);
     }
-    return ok;
-  }
-
-  #object(value: unknown, path: string, keys?: readonly string[]): JsonObject | null {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-      this.#report("pipeline.schema.invalid", "must be an object", path);
-      return null;
-    }
-    const raw = value as JsonObject;
-    if (keys && !this.#keys(raw, path, keys)) return null;
-    return raw;
+    return PipelineInputReader.clip(text, PipelineInputReader.#shownChars);
   }
 
   #list(value: unknown, path: string): unknown[] {
-    if (value === undefined) return [];
-    if (!Array.isArray(value)) {
-      this.#report("pipeline.schema.invalid", "must be a list", path);
-      return [];
-    }
-    return value;
+    return value === undefined ? [] : (this.#read.list(value, path) ?? []);
   }
 
   #strings(value: unknown, path: string): string[] {
     return this.#list(value, path).flatMap((item, idx) => {
-      const text = this.#text(item, `${path}[${idx}]`, 1024);
+      const text = this.#read.string(item, `${path}[${idx}]`);
       return text === null ? [] : [text];
     });
   }
 
-  #text(value: unknown, path: string, max: number) {
-    if (typeof value !== "string" || !value.trim()) {
-      this.#report("pipeline.schema.invalid", "must be a non-empty string", path);
-      return null;
-    }
-    if (value.length > max) {
-      this.#report("pipeline.schema.invalid", `is longer than ${max} characters`, path);
-      return null;
-    }
-    return value;
-  }
-
   #boolean(value: unknown, path: string) {
-    if (value === undefined) return false;
-    if (typeof value === "boolean") return value;
-    this.#report("pipeline.schema.invalid", "must be true or false", path);
-    return false;
+    return value === undefined ? false : (this.#read.boolean(value, path) ?? false);
   }
 
-  #int(value: unknown, path: string, min: number, max: number) {
-    if (typeof value === "number" && Number.isInteger(value) && value >= min && value <= max) return value;
-    this.#report("pipeline.schema.invalid", `must be a whole number between ${min} and ${max}`, path);
-    return null;
+  #problem(path: string, problem: PipelineValueProblem) {
+    if (problem.kind !== "unknownKey")
+      this.#report("pipeline.schema.invalid", PipelineInputReader.#reason(problem), path);
+    else if (PipelineInputReader.#futureKeys.includes(problem.key))
+      this.#report(
+        "pipeline.schema.unsupported",
+        `\`${problem.key}\` is not supported in schemaVersion 1`,
+        `${path}.${problem.key}`,
+      );
+    else
+      this.#report(
+        "pipeline.schema.unknownKey",
+        `"${problem.key}" is not a key here: ${problem.keys.join(", ")}`,
+        `${path}.${problem.key}`,
+      );
   }
 
-  #oneOf<T extends string>(value: unknown, path: string, options: readonly T[]): T | null {
-    if (typeof value === "string" && (options as readonly string[]).includes(value)) return value as T;
-    this.#report("pipeline.schema.invalid", `${JSON.stringify(value)} is not one of ${options.join(", ")}`, path);
-    return null;
+  static #reason(problem: Exclude<PipelineValueProblem, { kind: "unknownKey" }>): string {
+    switch (problem.kind) {
+      case "object":
+        return "must be an object";
+      case "missingKey":
+        return `"${problem.key}" is missing`;
+      case "list":
+        return "must be a list";
+      case "string":
+      case "empty":
+        return "must be a non-empty string";
+      case "length":
+        return `is longer than ${problem.max} characters`;
+      case "boolean":
+        return "must be true or false";
+      case "int":
+      case "range":
+        return `must be a whole number between ${problem.min} and ${problem.max}`;
+      case "oneOf":
+        return `${PipelineInputReader.#show(problem.value)} is not one of ${problem.options.join(", ")}`;
+    }
   }
 
   #report(code: string, message: string, path: string) {