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

package/pipeline/PipelineRules.ts

@@ -0,0 +1,92 @@
+import type {
+  PipelineActionName,
+  PipelineMilestone,
+  PipelineOtaPlatform,
+  PipelinePlanRetry,
+  PipelineTrigger,
+} from "akanjs/common";
+
+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[];
+}

package/pipeline/index.ts

@@ -2,3 +2,4 @@ export * from "./PipelineCompiler";
 export * from "./PipelineDefinition";
 export * from "./PipelineDryRun";
 export * from "./PipelineInputReader";
+export * from "./PipelineRules";

package/qualityScanner.test.ts

@@ -243,7 +243,7 @@ describe("AkanQualityScanner layout rules", () => {
 
     const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.lib-facet-file");
 
-    expect(warnings.map((warning) => warning.file).sort()).toEqual([
+    expect(warnings.map((warning) => warning.file ?? "").sort((a, b) => a.localeCompare(b))).toEqual([
       "libs/demo/lib/helper.ts",
       "libs/demo/lib/user.signal.test.ts",
     ]);
@@ -302,7 +302,7 @@ describe("bang comments in browser-reachable files", () => {
       "apps/demo/ui/Last.tsx": "export const Last = () => null;\n//! left behind\n",
     });
 
-    expect(warnings.map((warning) => `${warning.file}:${warning.line}`).sort()).toEqual([
+    expect(warnings.map((warning) => `${warning.file}:${warning.line}`).sort((a, b) => a.localeCompare(b))).toEqual([
       "apps/demo/ui/First.tsx:1",
       "apps/demo/ui/Last.tsx:2",
     ]);
@@ -350,6 +350,8 @@ describe("bang comments in browser-reachable files", () => {
     ];
     const warnings = await bangWarningsIn(Object.fromEntries(files.map((file) => [file, body])));
 
-    expect(warnings.map((warning) => warning.file).sort()).toEqual([...files].sort());
+    expect(warnings.map((warning) => warning.file ?? "").sort((a, b) => a.localeCompare(b))).toEqual(
+      [...files].sort((a, b) => a.localeCompare(b)),
+    );
   });
 });

package/slicePlanner.ts

@@ -51,6 +51,10 @@ export class SlicePlanner {
     return found ? peers : null;
   }
 
+  static rootEntriesOf(rootFiles: string[]) {
+    return [...new Set(rootFiles.map((file) => file.split("/")[0] ?? file))].sort();
+  }
+
   /** DefinitelyTyped's name for a package: `lodash` -> `@types/lodash`, `@scope/x` -> `@types/scope__x`. */
   static typesPackageOf(dependency: string) {
     return dependency.startsWith("@") ? `@types/${dependency.slice(1).replace("/", "__")}` : `@types/${dependency}`;
@@ -191,8 +195,6 @@ export class SlicePlanner {
   }
 }
 
-const rootEntriesOf = (rootFiles: string[]) => [...new Set(rootFiles.map((file) => file.split("/")[0] ?? file))].sort();
-
 export function formatSlicePlan(plan: SlicePlan) {
   const libCounts = Object.entries(plan.libFiles).map(([lib, files]) => `  - libs/${lib}: ${files.length} files`);
   const sections = [
@@ -200,7 +202,7 @@ export function formatSlicePlan(plan: SlicePlan) {
     `app: ${plan.app} (apps/${plan.app}: ${plan.appFiles.length} files)`,
     `libs: ${plan.libs.length ? plan.libs.join(", ") : "(none)"}`,
     ...libCounts,
-    `workspace shell: ${plan.rootFiles.length} files across ${rootEntriesOf(plan.rootFiles).join(", ")}`,
+    `workspace shell: ${plan.rootFiles.length} files across ${SlicePlanner.rootEntriesOf(plan.rootFiles).join(", ")}`,
     "",
     `Root dependencies this slice does not use (${plan.unusedDependencies.length}) — pruned:`,
     "",

package/subspace.test.ts

@@ -3,14 +3,10 @@ import { mkdir, readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { Executor, WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
-import {
-  formatSubspaceDiff,
-  formatSubspacePlan,
-  formatSubspacePushResults,
-  formatSubspaceStatuses,
-  Subspace,
-} from "./subspace";
+import { Subspace } from "./subspace";
+import { SubspaceClone } from "./subspaceClone";
 import { SubspaceConfig } from "./subspaceConfig";
+import { SubspaceReport } from "./subspaceReport";
 import { isolateEnv, tempDirs, writeText as write } from "./testHelpers";
 
 //? Each case drives several real git clones and pushes; on a 4-core Windows VM that alone lands at 2-5s.
@@ -189,7 +185,7 @@ describe("Subspace push", () => {
     await subspace.push("develop", { verify: false });
     const subspaceRoot = await cloneSubspace(workRoot, bareRoot, "check");
 
-    const anchor = (await FileSys.readJson(path.join(subspaceRoot, Subspace.anchorFile))) as {
+    const anchor = (await FileSys.readJson(path.join(subspaceRoot, SubspaceClone.anchorFile))) as {
       branch: string;
       apps: string[];
     };
@@ -257,7 +253,7 @@ describe("Subspace push", () => {
     await git(customer, ["commit", "--quiet", "-m", "our own global stages"]);
     await write(path.join(customer, "Jenkinsfile"), "pipeline { agent none }\n");
     await git(customer, ["add", "-A"]);
-    await git(customer, ["commit", "--quiet", "-m", `${Subspace.syncSubjectPrefix}workspace@0000000`]);
+    await git(customer, ["commit", "--quiet", "-m", `${SubspaceClone.syncSubjectPrefix}workspace@0000000`]);
     await git(customer, ["push", "--quiet", "origin", "develop"]);
 
     expect((await subspace.push("develop", { verify: false })).outcome).toBe("pushed");
@@ -268,8 +264,8 @@ describe("Subspace push", () => {
     expect(await FileSys.fileExists(path.join(subspaceRoot, "Jenkinsfile"))).toBe(false);
   });
 
-  test("refuses a lock that resolves from a registry only this machine reaches", async () => {
-    const { wsRoot, subspace } = await makeMirror("lock-served", "lock-private", "lock-kit");
+  test("refuses a lock that resolves from a registry only this machine reaches, before it clones", async () => {
+    const { wsRoot, subspace, clonePath } = await makeMirror("lock-served", "lock-private", "lock-kit");
     await write(
       path.join(wsRoot, "bun.lock"),
       '{ "packages": { "lodash": ["lodash@4.0.0", "http://127.0.0.1:4873/lodash/-/lodash-4.0.0.tgz"] } }\n',
@@ -279,6 +275,40 @@ describe("Subspace push", () => {
     const result = (await subspace.push("develop", { verify: false })) as { outcome: string; reason?: string };
     expect(result.outcome).toBe("refused");
     expect(result.reason).toContain("http://127.0.0.1:4873");
+    expect(await FileSys.dirExists(clonePath)).toBe(false);
+  });
+
+  test("refuses a push and a pull while akan.subspace.ts is left at the workspace root", async () => {
+    const { wsRoot, workRoot, bareRoot, subspace } = await makeMirror("left-served", "left-private", "left-kit");
+    await write(
+      path.join(wsRoot, Subspace.retiredConfigFile),
+      'export default { subspaces: [{ name: "globex", repo: "git@example.com:globex/app.git", apps: ["left-private"] }] };\n',
+    );
+    await git(wsRoot, ["add", "-A"]);
+    await git(wsRoot, ["commit", "--quiet", "-m", "moved the declaration, kept the file"]);
+
+    const result = await subspace.push("develop", { verify: false });
+    expect(result.outcome).toBe("refused");
+    expect(result.reason).toContain("move it under `subspace` in akan.config.ts and delete it");
+    await expect(subspace.pull("develop")).rejects.toThrow("delete it");
+    const subspaceRoot = await cloneSubspace(workRoot, bareRoot, "left-check");
+    expect(await FileSys.fileExists(path.join(subspaceRoot, Subspace.retiredConfigFile))).toBe(false);
+  });
+
+  test("removes an akan.subspace.ts an earlier push left in the subspace", async () => {
+    const { workRoot, bareRoot, subspace } = await makeMirror("leaked-served", "leaked-private", "leaked-kit");
+    const customer = await cloneSubspace(workRoot, bareRoot, "leaked-customer");
+    await write(
+      path.join(customer, Subspace.retiredConfigFile),
+      'export default { subspaces: [{ name: "globex" }] };\n',
+    );
+    await git(customer, ["add", "-A"]);
+    await git(customer, ["commit", "--quiet", "-m", `${SubspaceClone.syncSubjectPrefix}workspace@0000000`]);
+    await git(customer, ["push", "--quiet", "origin", "develop"]);
+
+    expect((await subspace.push("develop", { verify: false })).outcome).toBe("pushed");
+    const subspaceRoot = await cloneSubspace(workRoot, bareRoot, "leaked-check");
+    expect(await FileSys.fileExists(path.join(subspaceRoot, Subspace.retiredConfigFile))).toBe(false);
   });
 
   test("refuses a branch the subspace does not have, and one the config does not allow", async () => {
@@ -319,7 +349,7 @@ describe("Subspace push", () => {
   });
 
   test("reports a refusal's whole reason, indented, instead of one truncated line", () => {
-    const report = formatSubspacePushResults([
+    const report = SubspaceReport.pushResults([
       { name: "acme", outcome: "refused", reason: "verification failed\nexit code: 1", changedFiles: 12 },
       { name: "beta", outcome: "pushed", commit: "abc1234", changedFiles: 3 },
     ]);
@@ -341,7 +371,7 @@ describe("Subspace status", () => {
     expect(status.driftedLibs).toEqual([]);
     expect(status.anchor.commit).toMatch(/^[0-9a-f]{40}$/);
     expect(status.anchor.incoming).toEqual([]);
-    expect(formatSubspaceStatuses([status])).toContain("up to date, no customer commits");
+    expect(SubspaceReport.statuses([status])).toContain("up to date, no customer commits");
   });
 
   test("names the drifted library and counts the customer commits", async () => {
@@ -358,7 +388,7 @@ describe("Subspace status", () => {
 
     expect(status.driftedLibs).toEqual(["sdrift-kit"]);
     expect(status.anchor.incoming.map((commit) => commit.subject)).toEqual(["lib hack"]);
-    expect(formatSubspaceStatuses([status])).toContain("DRIFTED LIBS: sdrift-kit");
+    expect(SubspaceReport.statuses([status])).toContain("DRIFTED LIBS: sdrift-kit");
   });
 
   test("reports a subspace with no such branch instead of creating one", async () => {
@@ -366,7 +396,7 @@ describe("Subspace status", () => {
     const status = await subspace.status("main");
 
     expect(status.hasBranch).toBe(false);
-    expect(formatSubspaceStatuses([status])).toContain("no such branch");
+    expect(SubspaceReport.statuses([status])).toContain("no such branch");
   });
 });
 
@@ -389,7 +419,7 @@ describe("Subspace diff", () => {
     //? Direction: the workspace would restore `helper = 1` and delete the file the subspace added.
     expect(result.libs.patch).toContain("-export const helper = 99;");
     expect(result.libs.patch).toContain("+export const helper = 1;");
-    expect(formatSubspaceDiff(result)).toContain("LIBRARY changes (1)");
+    expect(SubspaceReport.diff(result)).toContain("LIBRARY changes (1)");
   });
 
   test("is empty right after a push", async () => {
@@ -399,7 +429,7 @@ describe("Subspace diff", () => {
     const result = await subspace.diff("develop");
     expect(result.app.files).toEqual([]);
     expect(result.libs.files).toEqual([]);
-    expect(formatSubspaceDiff(result)).toContain("identical to the workspace");
+    expect(SubspaceReport.diff(result)).toContain("identical to the workspace");
   });
 });
 
@@ -509,6 +539,16 @@ describe("SubspaceConfig", () => {
     expect(() => config.assertPushable("feature/x")).toThrow(/not pushable/);
     expect(() => config.assertPushable("develop")).not.toThrow();
   });
+
+  test("names the setting that allows a branch when it refuses one", () => {
+    const config = new SubspaceConfig({
+      pushableBranches: ["main"],
+      subspaces: [{ name: "a", repo: "a.git", apps: ["one"] }],
+    });
+    expect(() => config.assertPushable("develop")).toThrow(
+      'Branch "develop" is not pushable. `subspace.pushableBranches` in the workspace root akan.config.ts allows: main',
+    );
+  });
 });
 
 describe("Subspace.plan", () => {
@@ -532,7 +572,7 @@ describe("Subspace.plan", () => {
     expect(plan.files).toBeGreaterThan(0);
     expect((await git(wsRoot, ["remote"])).trim()).toBe("");
     expect(await FileSys.dirExists(clonePath)).toBe(false);
-    expect(formatSubspacePlan(plan)).toContain("Nothing here would make a push refuse.");
+    expect(SubspaceReport.plan(plan)).toContain("Nothing here would make a push refuse.");
   });
 
   test("names what a push would refuse: a branch it may not push and a loopback-registry lock", async () => {
@@ -545,7 +585,38 @@ describe("Subspace.plan", () => {
     await git(wsRoot, ["commit", "--quiet", "-m", "lock"]);
     const plan = await subspace.plan("main");
     expect(plan.branchRefusal).toContain('Branch "main" is not pushable');
+    expect(plan.branchRefusal).toContain("`subspace.pushableBranches`");
     expect(plan.lockProblem).toContain("http://127.0.0.1:4873");
-    expect(formatSubspacePlan(plan)).toContain("A push would be refused:");
+    expect(SubspaceReport.plan(plan)).toContain("A push would be refused:");
+  });
+
+  test("names a dirty tree as a blocker, as push refuses one, and judges HEAD's lock, the one a push ships", async () => {
+    const { wsRoot, subspace } = await makeMirror("served", "private", "kit");
+    await write(path.join(wsRoot, "bun.lock"), '{ "packages": {} }\n');
+    await git(wsRoot, ["add", "-f", "bun.lock"]);
+    await git(wsRoot, ["commit", "--quiet", "-m", "a public lock"]);
+    await write(
+      path.join(wsRoot, "bun.lock"),
+      '{ "packages": { "x": ["x@1.0.0", "http://127.0.0.1:4873/x/-/x-1.0.0.tgz"] } }\n',
+    );
+
+    const plan = await subspace.plan("develop");
+
+    expect(plan.workspaceRefusal).toBe("workspace working tree is dirty");
+    expect(plan.lockProblem).toBeNull();
+    expect(Subspace.planBlockers(plan)).toEqual(["workspace working tree is dirty"]);
+    expect(SubspaceReport.plan(plan)).toContain("  - workspace working tree is dirty");
+  });
+
+  test("names a leftover akan.subspace.ts as a blocker and never as an entry a push ships", async () => {
+    const { wsRoot, subspace } = await makeMirror("served", "private", "kit");
+    await write(path.join(wsRoot, Subspace.retiredConfigFile), "export default {};\n");
+    await git(wsRoot, ["add", "-A"]);
+    await git(wsRoot, ["commit", "--quiet", "-m", "kept the old declaration"]);
+
+    const plan = await subspace.plan("develop");
+
+    expect(plan.workspaceRefusal).toContain("delete it");
+    expect(plan.rootEntries).not.toContain(Subspace.retiredConfigFile);
   });
 });