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

package/pipeline/PipelineCompiler.ts

@@ -25,19 +25,21 @@ import {
   pipelineActions,
   pipelineMilestones,
   pipelineOtaPlatforms,
+  pipelinePlanLimits,
   pipelinePlanVersion,
+  toError,
 } from "akanjs/common";
-import {
-  type PipelineActionStageRule,
-  type PipelineAppRule,
-  PipelineInputReader,
-  type PipelinePostRule,
-  type PipelineShellStageRule,
-  type PipelineStepRule,
-  type PipelineWhenRule,
-  type PipelineWorkspaceRule,
-  type PipelineWorkspaceStageRule,
-} from "./PipelineInputReader";
+import { PipelineInputReader } from "./PipelineInputReader";
+import type {
+  PipelineActionStageRule,
+  PipelineAppRule,
+  PipelinePostRule,
+  PipelineShellStageRule,
+  PipelineStepRule,
+  PipelineWhenRule,
+  PipelineWorkspaceRule,
+  PipelineWorkspaceStageRule,
+} from "./PipelineRules";
 
 export interface PipelineSourceFile<T> {
   /** Relative to the workspace root, with `/`. */
@@ -59,7 +61,6 @@ export interface PipelineCompileInput {
   akanVersion: string;
   /** Function forms run against a sample context (`validate`), which is said once per file. */
   sampled?: boolean;
-  /** What loading the files already found. */
   diagnostics?: readonly PipelineDiagnostic[];
 }
 
@@ -87,7 +88,6 @@ interface StageOptions {
   timeoutSeconds?: number | null;
 }
 
-/** Composes the workspace's and each app's rules into one plan for one run. */
 export class PipelineCompiler {
   static readonly #slotAfter = {
     build: "after-build",
@@ -112,6 +112,8 @@ export class PipelineCompiler {
   static readonly #reservedPhaseId =
     /^(?:build|docker|deploy|ota|(?:before-build|after-build|after-docker|after-deploy|after-ota)(?:-\d+)?)$/;
   static readonly #actionStepNames = { build: "akan build", docker: "image", deploy: "deploy", ota: "ota" } as const;
+  //? PipelinePlanSchema reads at most 1024 characters of a skip reason.
+  static readonly #reasonChars = 1024;
 
   static compile(input: PipelineCompileInput): PipelinePlanResult {
     return new PipelineCompiler(input).#compile();
@@ -130,13 +132,9 @@ export class PipelineCompiler {
     const { context, workspaceApps } = this.#input;
     this.#checkContext();
     const pipelineContext: PipelineContext = {
-      branch: context.branch,
-      env: context.env,
+      ...context,
       apps: [...context.apps],
       workspaceApps: [...workspaceApps],
-      trigger: context.trigger,
-      buildNum: context.buildNum,
-      commit: context.commit,
     };
     const workspace = this.#readWorkspace(pipelineContext);
     const lanes = new Map<string, AppLane>();
@@ -164,11 +162,23 @@ export class PipelineCompiler {
     try {
       PipelinePlanSchema.parse(plan);
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = toError(error).message;
       this.#error(message.includes("at most") ? "pipeline.limit.exceeded" : "pipeline.internal", message, null, null);
       return this.#failed();
     }
-    return { ok: true, plan, diagnostics: this.#diagnostics };
+    const result: PipelinePlanResult = { ok: true, plan, diagnostics: this.#diagnostics };
+    //? Sized as `akan pipeline plan --out` writes it, since that text is what an executor's parseText bounds.
+    const bytes = new TextEncoder().encode(`${JSON.stringify(result, null, 2)}\n`).length;
+    if (bytes > pipelinePlanLimits.planBytes) {
+      this.#error(
+        "pipeline.limit.exceeded",
+        `the plan is ${bytes} bytes as written, and an executor reads at most ${pipelinePlanLimits.planBytes}`,
+        null,
+        null,
+      );
+      return this.#failed();
+    }
+    return result;
   }
 
   #checkContext() {
@@ -184,11 +194,11 @@ export class PipelineCompiler {
 
   #readWorkspace(context: PipelineContext): PipelineWorkspaceRule | null {
     const source = this.#input.workspace;
-    if (!source?.pipeline) return null;
-    const value = this.#evaluate(source.pipeline, context, source.file);
-    if (value === undefined) return null;
+    if (source?.pipeline == null) return null;
+    const evaluated = this.#evaluate(source.pipeline, context, source.file);
+    if (!evaluated) return null;
     const reader = new PipelineInputReader(source.file);
-    const rule = reader.workspace(value);
+    const rule = reader.workspace(evaluated.value);
     this.#diagnostics.push(...reader.diagnostics);
     return rule;
   }
@@ -197,34 +207,55 @@ export class PipelineCompiler {
     const source = this.#input.apps.get(app);
     if (!source) return null;
     const appContext: AppPipelineContext = { ...context, app };
-    const value = source.pipeline ? this.#evaluate(source.pipeline, appContext, source.file) : defaultAppPipeline;
-    if (value === undefined) return null;
+    const evaluated =
+      source.pipeline == null
+        ? { value: defaultAppPipeline }
+        : this.#evaluate(source.pipeline, appContext, source.file);
+    if (!evaluated) return null;
     const reader = new PipelineInputReader(source.file);
-    const rule = reader.app(value);
+    const rule = reader.app(evaluated.value);
     this.#diagnostics.push(...reader.diagnostics);
     return rule ? this.#lane(app, rule, source.file) : null;
   }
 
-  #evaluate<C>(config: unknown, context: C, file: string): unknown {
-    if (typeof config !== "function") return config;
-    if (this.#input.sampled)
-      this.#warning(
-        "pipeline.function.sampled",
-        "a function form was checked against one sample context; other branches, triggers or apps may differ",
-        file,
-        "pipeline",
-      );
-    try {
-      return (config as (context: C) => unknown)(context);
-    } catch (error) {
+  #evaluate<C>(config: unknown, context: C, file: string): { value: unknown } | null {
+    let value = config;
+    if (typeof config === "function") {
+      if (this.#input.sampled)
+        this.#warning(
+          "pipeline.function.sampled",
+          "a function form was checked against one sample context; other branches, triggers or apps may differ",
+          file,
+          "pipeline",
+        );
+      try {
+        value = (config as (context: C) => unknown)(context);
+      } catch (error) {
+        this.#error("pipeline.load.failed", `the pipeline function threw: ${toError(error).message}`, file, "pipeline");
+        return null;
+      }
+      if (value === undefined) {
+        this.#error(
+          "pipeline.schema.invalid",
+          "the pipeline function returned nothing for this run: return a pipeline on every path",
+          file,
+          "pipeline",
+        );
+        return null;
+      }
+    }
+    if (typeof (value as PromiseLike<unknown> | null)?.then === "function") {
+      //? Handled so a rejection cannot end the CLI before it writes the envelope.
+      void Promise.resolve(value).catch(() => undefined);
       this.#error(
-        "pipeline.load.failed",
-        `the pipeline function threw: ${error instanceof Error ? error.message : String(error)}`,
+        "pipeline.schema.invalid",
+        "is a Promise, which the planner cannot wait for: return the pipeline itself, not from an async function",
         file,
         "pipeline",
       );
-      return undefined;
+      return null;
     }
+    return { value };
   }
 
   #lane(app: string, rule: PipelineAppRule, file: string): AppLane {
@@ -552,7 +583,9 @@ export class PipelineCompiler {
         maxParallel: stage.maxParallel,
         failFast: false,
         timeoutSeconds: stage.timeoutSeconds,
-        stages: apps.map((app) => this.#shellStage(copy, { id: `${stage.id}:${app}`, name: app, app, milestone, env })),
+        stages: apps.map((app) =>
+          this.#shellStage(copy, { id: `${stage.id}.apps.${app}`, name: app, app, milestone, env }),
+        ),
       },
     ];
   }
@@ -603,10 +636,11 @@ export class PipelineCompiler {
 
   #skipOf(when: PipelineWhenRule): PipelineSkip | null {
     const { branch, trigger } = this.#input.context;
+    const skip = (reason: string) => ({ reason: PipelineInputReader.clip(reason, PipelineCompiler.#reasonChars) });
     if (when.branch && !PipelinePattern.matches(when.branch, branch))
-      return { reason: `branch "${branch}" does not match ${when.branch.map((glob) => `"${glob}"`).join(", ")}` };
+      return skip(`branch "${branch}" does not match ${when.branch.map((glob) => `"${glob}"`).join(", ")}`);
     if (when.trigger && !when.trigger.includes(trigger))
-      return { reason: `trigger "${trigger}" is not ${when.trigger.map((name) => `"${name}"`).join(" or ")}` };
+      return skip(`trigger "${trigger}" is not ${when.trigger.map((name) => `"${name}"`).join(" or ")}`);
     return null;
   }
 
@@ -615,7 +649,7 @@ export class PipelineCompiler {
     const sourceOf = (source: PipelineSourceFile<unknown>): PipelinePlanSource => ({
       file: source.file,
       sha256: source.sha256,
-      declared: source.pipeline !== null,
+      declared: source.pipeline != null,
     });
     return {
       workspace: workspace ? sourceOf(workspace) : null,

package/pipeline/PipelineDefinition.test.ts

@@ -70,6 +70,15 @@ describe("PipelineDefinition", () => {
     );
   });
 
+  test("the workspace's apps are in code-point order, whatever the machine's locale", async () => {
+    await withWorkspace(
+      { "apps/api/akan.config.ts": "export default {};\n", "apps/Web/akan.config.ts": "export default {};\n" },
+      async (workspace) => {
+        expect((await PipelineDefinition.load(workspace, [])).workspaceApps).toEqual(["Web", "api"]);
+      },
+    );
+  });
+
   test("a config that cannot load is an error naming the file, never a silent default", async () => {
     await withWorkspace(
       {

package/pipeline/PipelineDefinition.ts

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import type { AppPipelineConfig, WorkspacePipelineConfig } from "akanjs";
 import type { PipelineDiagnostic, PipelinePlanContext, PipelinePlanResult } from "akanjs/common";
+import { toError } from "akanjs/common";
 import { AkanAppConfig, AkanWorkspaceConfig } from "../akanConfig";
 import { AppExecutor, type WorkspaceExecutor } from "../executors";
 import { FileSys } from "../fileSys";
@@ -44,7 +45,7 @@ export class PipelineDefinition {
   }
 
   async #load(apps: readonly string[]) {
-    this.workspaceApps = (await this.#workspace.getApps()).sort((a, b) => a.localeCompare(b));
+    this.workspaceApps = (await this.#workspace.getApps()).sort();
     this.workspaceSource = await this.#loadWorkspace();
     for (const app of new Set(apps)) {
       if (!this.workspaceApps.includes(app)) continue;
@@ -68,7 +69,7 @@ export class PipelineDefinition {
       const targets = await resolveMobileTargets(AppExecutor.from(this.#workspace, app), "all");
       return { targets: targets.map(({ name, config }) => ({ name, updates: !!config.updates })) };
     } catch (error) {
-      return { error: error instanceof Error ? error.message : String(error) };
+      return { error: toError(error).message };
     }
   }
 
@@ -105,7 +106,7 @@ export class PipelineDefinition {
     this.diagnostics.push({
       severity: "error",
       code: "pipeline.load.failed",
-      message: `could not load: ${error instanceof Error ? error.message : String(error)}`,
+      message: `could not load: ${toError(error).message}`,
       file,
       path: null,
     });

package/pipeline/PipelineDryRun.test.ts

@@ -76,6 +76,33 @@ describe("PipelineDryRun", () => {
     );
   });
 
+  test("a phase of one stage still names its app", () => {
+    const result = PipelineCompiler.compile({
+      context: { ...context, apps: ["web"] },
+      workspaceApps: ["web"],
+      workspace: {
+        file: "akan.config.ts",
+        sha256: sha,
+        pipeline: { after: [{ name: "E2E", matrix: "apps", sh: "bun run e2e" }] },
+      },
+      apps: new Map([["web", { file: "apps/web/akan.config.ts", sha256: sha, pipeline: null }]]),
+      akanVersion: "3.0.3",
+    });
+    expect(PipelineDryRun.render(result)).toBe(
+      [
+        "plan v1 · branch develop · env develop · trigger push · apps web",
+        "from akan.config.ts, apps/web/akan.config.ts (default)",
+        "",
+        "prepare  (executor)          checkout · env · install · plan",
+        "build    build       Build   web  action build",
+        "package  docker      Docker  web  action docker",
+        "deploy   deploy      Deploy  → web (one at a time)",
+        "finish   e2e         E2E     web  bun run e2e",
+        "finish   (executor)          cleanup",
+      ].join("\n"),
+    );
+  });
+
   test("a failed plan prints its diagnostics", () => {
     const rendered = PipelineDryRun.render({
       ok: false,

package/pipeline/PipelineDryRun.ts

@@ -6,7 +6,7 @@ import type {
   PipelinePlanStage,
 } from "akanjs/common";
 
-/** A plan as a person reads it: one line per phase in run order, the executor's own work included. Runs nothing. */
+/** A plan as a person reads it: one line per phase in run order, the executor's own work included. */
 export class PipelineDryRun {
   static render(result: PipelinePlanResult) {
     const lines = result.ok ? PipelineDryRun.#plan(result.plan) : ["no plan: the definition has errors"];
@@ -61,7 +61,7 @@ export class PipelineDryRun {
       const command = stage?.steps
         .map((step) => (step.kind === "sh" ? step.name : `action ${step.action}`))
         .join(" · ");
-      return [labels[0], command].filter((part) => part && part !== stage?.name).join("  ");
+      return [labels[0], command].filter((part) => part && part !== phase.name).join("  ");
     }
     return `‖ ${labels.join(" · ")}`;
   }