@akanjs/devkit 3.0.2 → 3.1.0-rc.0

package/pipeline/PipelineDefinition.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { WorkspaceExecutor } from "../executors";
+import { PipelineDefinition } from "./PipelineDefinition";
+
+const context = {
+  branch: "main",
+  env: "main",
+  apps: ["web", "api"],
+  trigger: "push",
+  buildNum: 1,
+  commit: null,
+} as const;
+
+const withWorkspace = async (files: Record<string, string>, run: (workspace: WorkspaceExecutor) => Promise<void>) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "akan-plan-definition-"));
+  try {
+    for (const [relative, content] of Object.entries(files)) {
+      fs.mkdirSync(path.dirname(path.join(root, relative)), { recursive: true });
+      fs.writeFileSync(path.join(root, relative), content);
+    }
+    await run(WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "repo" }));
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+};
+
+const webConfig = `import type { AppConfig } from "akanjs";
+
+const config: AppConfig = {
+  externalLibs: ["shiki"],
+  pipeline: { stages: [{ use: "build" }, { name: "Test", sh: "bun test" }, { use: "docker" }, { use: "deploy" }] },
+};
+
+export default config;
+`;
+
+describe("PipelineDefinition", () => {
+  test("reads the root config and each app's, type-only imports with no node_modules at all", async () => {
+    await withWorkspace(
+      {
+        "akan.config.ts":
+          'import type { WorkspaceConfig } from "akanjs";\n\nexport default { pipeline: { before: [{ name: "Lint", sh: "bun lint" }] } } satisfies WorkspaceConfig;\n',
+        "apps/web/akan.config.ts": webConfig,
+        "apps/api/akan.config.ts": "export default (app) => ({ externalLibs: [app.name] });\n",
+      },
+      async (workspace) => {
+        const definition = await PipelineDefinition.load(workspace, context.apps);
+        const result = definition.compile({ ...context, apps: [...context.apps] });
+        if (!result.ok) throw new Error(JSON.stringify(result.diagnostics));
+        expect(result.plan.phases.map((phase) => phase.id)).toEqual([
+          "lint",
+          "build",
+          "after-build",
+          "docker",
+          "deploy",
+        ]);
+        expect(result.plan.sources.workspace?.declared).toBe(true);
+        expect(result.plan.sources.apps.web).toEqual({
+          file: "apps/web/akan.config.ts",
+          sha256: createHash("sha256").update(webConfig).digest("hex"),
+          declared: true,
+        });
+        expect(result.plan.sources.apps.api?.declared).toBe(false);
+        expect(definition.workspaceApps).toEqual(["api", "web"]);
+      },
+    );
+  });
+
+  test("a config that cannot load is an error naming the file, never a silent default", async () => {
+    await withWorkspace(
+      {
+        "apps/web/akan.config.ts": 'throw new Error("boom");\n',
+        "apps/api/akan.config.ts": "export default {};\n",
+      },
+      async (workspace) => {
+        const result = (await PipelineDefinition.load(workspace, context.apps)).compile({
+          ...context,
+          apps: [...context.apps],
+        });
+        expect(result.ok).toBe(false);
+        expect(result.diagnostics[0]).toMatchObject({ code: "pipeline.load.failed", file: "apps/web/akan.config.ts" });
+      },
+    );
+  });
+});

package/pipeline/PipelineDefinition.ts

@@ -0,0 +1,117 @@
+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 { AkanAppConfig, AkanWorkspaceConfig } from "../akanConfig";
+import { AppExecutor, type WorkspaceExecutor } from "../executors";
+import { FileSys } from "../fileSys";
+import { resolveMobileTargets } from "../mobile/mobileTarget";
+import { PipelineCompiler, type PipelineNativeTargets, type PipelineSourceFile } from "./PipelineCompiler";
+
+/**
+ * The workspace root config and each app's, for one run. Loading evaluates the workspace's own TypeScript, so a plan is
+ * made where that code may run (the build pod) and what leaves is data only.
+ */
+export class PipelineDefinition {
+  static async load(workspace: WorkspaceExecutor, apps: readonly string[]) {
+    const definition = new PipelineDefinition(workspace);
+    await definition.#load(apps);
+    return definition;
+  }
+
+  readonly diagnostics: PipelineDiagnostic[] = [];
+  readonly appSources = new Map<string, PipelineSourceFile<AppPipelineConfig>>();
+  readonly nativeTargets = new Map<string, PipelineNativeTargets>();
+  workspaceApps: string[] = [];
+  workspaceSource: PipelineSourceFile<WorkspacePipelineConfig> | null = null;
+  readonly #workspace: WorkspaceExecutor;
+
+  constructor(workspace: WorkspaceExecutor) {
+    this.#workspace = workspace;
+  }
+
+  compile(context: PipelinePlanContext, { sampled = false }: { sampled?: boolean } = {}): PipelinePlanResult {
+    return PipelineCompiler.compile({
+      context,
+      workspaceApps: this.workspaceApps,
+      workspace: this.workspaceSource,
+      apps: this.appSources,
+      nativeTargets: this.nativeTargets,
+      akanVersion: AkanAppConfig.akanVersion,
+      sampled,
+      diagnostics: this.diagnostics,
+    });
+  }
+
+  async #load(apps: readonly string[]) {
+    this.workspaceApps = (await this.#workspace.getApps()).sort((a, b) => a.localeCompare(b));
+    this.workspaceSource = await this.#loadWorkspace();
+    for (const app of new Set(apps)) {
+      if (!this.workspaceApps.includes(app)) continue;
+      const source = await this.#loadApp(app);
+      this.appSources.set(app, source);
+      if (PipelineDefinition.#mayTakeOta(source.pipeline))
+        this.nativeTargets.set(app, await this.#loadNativeTargets(app));
+    }
+  }
+
+  //? A function form is only known once the compiler runs it, so it pays for the config load either way.
+  static #mayTakeOta(pipeline: AppPipelineConfig | null) {
+    if (typeof pipeline === "function") return true;
+    const stages: unknown = pipeline?.stages;
+    return Array.isArray(stages) && stages.some((stage) => (stage as { use?: unknown } | null)?.use === "ota");
+  }
+
+  //? The whole app config, libs included: a target's `updates` may come from `native.updates` or its own section.
+  async #loadNativeTargets(app: string): Promise<PipelineNativeTargets> {
+    try {
+      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) };
+    }
+  }
+
+  async #loadWorkspace(): Promise<PipelineSourceFile<WorkspacePipelineConfig> | null> {
+    const file = AkanWorkspaceConfig.fileName;
+    const absolute = path.join(this.#workspace.workspaceRoot, file);
+    if (!(await FileSys.fileExists(absolute))) return null;
+    const sha256 = await PipelineDefinition.#sha256(absolute);
+    try {
+      return { file, sha256, pipeline: (await this.#workspace.getConfig()).pipeline };
+    } catch (error) {
+      this.#failed(file, error);
+      return { file, sha256, pipeline: null };
+    }
+  }
+
+  async #loadApp(app: string): Promise<PipelineSourceFile<AppPipelineConfig>> {
+    const executor = AppExecutor.from(this.#workspace, app);
+    const file = `apps/${app}/akan.config.ts`;
+    const sha256 = await PipelineDefinition.#sha256(path.join(executor.cwdPath, "akan.config.ts"));
+    try {
+      const module = await AkanAppConfig.importConfigModule(executor.cwdPath);
+      const config = typeof module === "function" ? (module as (app: AppExecutor) => unknown)(executor) : module;
+      const pipeline =
+        typeof config === "object" && config !== null ? (config as { pipeline?: AppPipelineConfig }).pipeline : null;
+      return { file, sha256, pipeline: pipeline ?? null };
+    } catch (error) {
+      this.#failed(file, error);
+      return { file, sha256, pipeline: null };
+    }
+  }
+
+  #failed(file: string, error: unknown) {
+    this.diagnostics.push({
+      severity: "error",
+      code: "pipeline.load.failed",
+      message: `could not load: ${error instanceof Error ? error.message : String(error)}`,
+      file,
+      path: null,
+    });
+  }
+
+  static async #sha256(file: string) {
+    return new Bun.CryptoHasher("sha256").update(await readFile(file)).digest("hex");
+  }
+}

package/pipeline/PipelineDryRun.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from "bun:test";
+import type { PipelinePlanContext } from "akanjs/common";
+import { PipelineCompiler } from "./PipelineCompiler";
+import { PipelineDryRun } from "./PipelineDryRun";
+
+const sha = "0".repeat(64);
+const context: PipelinePlanContext = {
+  branch: "develop",
+  env: "develop",
+  apps: ["web", "api"],
+  trigger: "push",
+  buildNum: 3,
+  commit: null,
+};
+
+describe("PipelineDryRun", () => {
+  test("shows each phase in run order, with skips, allowed failures and the executor's own work", () => {
+    const result = PipelineCompiler.compile({
+      context,
+      workspaceApps: ["api", "web"],
+      workspace: {
+        file: "akan.config.ts",
+        sha256: sha,
+        pipeline: {
+          before: [
+            {
+              name: "Checks",
+              parallel: [
+                { name: "Lint", sh: "bun lint" },
+                { name: "Test", sh: "bun test" },
+              ],
+            },
+          ],
+          post: { failure: [{ name: "Notify", sh: "./notify.sh", secrets: ["DISCORD_WEBHOOK"] }] },
+        },
+      },
+      apps: new Map([
+        [
+          "web",
+          {
+            file: "apps/web/akan.config.ts",
+            sha256: sha,
+            pipeline: {
+              after: ["api"],
+              stages: [
+                { use: "build" },
+                { name: "Test", sh: "bun run akan test web" },
+                { use: "docker" },
+                { use: "deploy", when: { branch: "main" } },
+                { name: "Smoke", sh: "curl -fsS https://web.example.com/api/ping", allowFailure: true },
+              ],
+            },
+          },
+        ],
+        ["api", { file: "apps/api/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, api · order api → web",
+        "from akan.config.ts, apps/web/akan.config.ts, apps/api/akan.config.ts (default)",
+        "",
+        "prepare  (executor)                  checkout · env · install · plan",
+        "prepare  checks        Checks        ‖ Lint · Test",
+        "build    build         Build         ‖ api · web",
+        "verify   after-build   After build   web:Test  bun run akan test web",
+        "package  docker        Docker        ‖ api · web",
+        'deploy   deploy        Deploy        → api, web (skipped: branch "develop" does not match "main") (one at a time)',
+        "deploy   after-deploy  After deploy  web:Smoke (may fail)  curl -fsS https://web.example.com/api/ping",
+        "finish   post.failure                Notify",
+        "finish   (executor)                  cleanup",
+        "",
+        "secrets required: DISCORD_WEBHOOK",
+      ].join("\n"),
+    );
+  });
+
+  test("a failed plan prints its diagnostics", () => {
+    const rendered = PipelineDryRun.render({
+      ok: false,
+      plan: null,
+      diagnostics: [
+        { severity: "error", code: "pipeline.action.order", message: "x", file: "apps/web/akan.config.ts", path: "p" },
+      ],
+    });
+    expect(rendered).toBe(
+      ["no plan: the definition has errors", "", "error pipeline.action.order (apps/web/akan.config.ts · p): x"].join(
+        "\n",
+      ),
+    );
+  });
+});

package/pipeline/PipelineDryRun.ts

@@ -0,0 +1,89 @@
+import type {
+  PipelineDiagnostic,
+  PipelinePlan,
+  PipelinePlanPhase,
+  PipelinePlanResult,
+  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. */
+export class PipelineDryRun {
+  static render(result: PipelinePlanResult) {
+    const lines = result.ok ? PipelineDryRun.#plan(result.plan) : ["no plan: the definition has errors"];
+    const diagnostics = PipelineDryRun.diagnostics(result.diagnostics);
+    return [...lines, ...(diagnostics.length ? ["", ...diagnostics] : [])].join("\n");
+  }
+
+  static #plan(plan: PipelinePlan) {
+    const { context } = plan;
+    const order = plan.appOrder.join() === context.apps.join() ? "" : ` · order ${plan.appOrder.join(" → ")}`;
+    const rows: [string, string, string, string][] = [
+      ["prepare", "(executor)", "", "checkout · env · install · plan"],
+      ...plan.phases.map((phase): [string, string, string, string] => [
+        phase.milestone,
+        phase.id,
+        phase.name,
+        PipelineDryRun.#stages(phase),
+      ]),
+      ...(["success", "failure", "canceled", "always"] as const).flatMap(
+        (result): [string, string, string, string][] => {
+          const steps = plan.post[result];
+          if (!steps.length) return [];
+          return [["finish", `post.${result}`, "", steps.map((step) => step.name).join(" · ")]];
+        },
+      ),
+      ["finish", "(executor)", "", "cleanup"],
+    ];
+    const widths = [0, 1, 2].map((column) => Math.max(...rows.map((row) => row[column]?.length ?? 0)));
+    const sources = [
+      ...(plan.sources.workspace ? [plan.sources.workspace] : []),
+      ...Object.values(plan.sources.apps),
+    ].map((source) => `${source.file}${source.declared ? "" : " (default)"}`);
+    return [
+      `plan v${plan.schemaVersion} · branch ${context.branch} · env ${context.env} · trigger ${context.trigger} · apps ${context.apps.join(", ") || "(none)"}${order}`,
+      `from ${sources.join(", ") || "(no files)"}`,
+      "",
+      ...rows.map((row) =>
+        row
+          .map((cell, column) => (column < 3 ? cell.padEnd(widths[column] ?? 0) : cell))
+          .join("  ")
+          .trimEnd(),
+      ),
+      ...(plan.requiredSecrets.length ? ["", `secrets required: ${plan.requiredSecrets.join(", ")}`] : []),
+    ];
+  }
+
+  static #stages(phase: PipelinePlanPhase) {
+    const labels = phase.stages.map((stage) => PipelineDryRun.#stage(phase, stage));
+    if (phase.order === "sequential") return `→ ${labels.join(", ")} (one at a time)`;
+    if (phase.stages.length === 1) {
+      const [stage] = phase.stages;
+      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.join(" · ")}`;
+  }
+
+  static #stage(phase: PipelinePlanPhase, stage: PipelinePlanStage) {
+    const label = stage.app && !phase.action && stage.name !== stage.app ? `${stage.app}:${stage.name}` : stage.name;
+    const ota = stage.steps.find((step) => step.kind === "action" && step.action === "ota");
+    const notes = [
+      ota?.kind === "action" && ota.action === "ota"
+        ? `${ota.with.targets.join(", ")} × ${ota.with.platforms.join(", ")}`
+        : null,
+      stage.skip ? `skipped: ${stage.skip.reason}` : null,
+      stage.allowFailure ? "may fail" : null,
+      stage.runtimeWhen ? `if changed: ${stage.runtimeWhen.changed.join(", ")}` : null,
+    ].filter(Boolean);
+    return notes.length ? `${label} (${notes.join("; ")})` : label;
+  }
+
+  static diagnostics(diagnostics: readonly PipelineDiagnostic[]) {
+    return diagnostics.map((diagnostic) => {
+      const where = [diagnostic.file, diagnostic.path].filter(Boolean).join(" · ");
+      return `${diagnostic.severity} ${diagnostic.code}${where ? ` (${where})` : ""}: ${diagnostic.message}`;
+    });
+  }
+}