@synap-core/workspace-templates 0.11.0 → 0.23.0

package/src/lifecycle-presets.test.ts

@@ -0,0 +1,468 @@
+/**
+ * Lifecycle presets (`lifecycle.adopts`, plan aac47c4a W5): the ten bases
+ * compile, at template time, into the flat declaration the pod stores.
+ *
+ * (1) BYTE-IDENTICAL CONVERSION. Five lifecycles were rewritten from a flat
+ *     `options` list + a hand-kept `enumValues` copy into `adopts:` overlays.
+ *     `__fixtures__/lifecycle-presets.flat-before.json` holds each one's flat
+ *     lifecycle and select property exactly as main declared them before
+ *     (generated from `git show 1d590b166:…`, not typed by hand). The test
+ *     compiles today's YAML and requires the same JSON, byte for byte (key
+ *     order included: it is what `src/templates.ts` and dist/ carry).
+ * (2) The compiler's overlay operations and the problems it reports.
+ * (3) The three doors that read authored YAML compile it: the validator, both
+ *     define converters, and the generator (through readYamlTemplates).
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { load } from "js-yaml";
+import { describe, expect, it } from "vitest";
+import { readYamlTemplates } from "./generate.mjs";
+import {
+  BASE_LIFECYCLES,
+  resolveLifecyclePresets,
+} from "./lifecycle-presets.js";
+import { toPackageDefinition, toWorkspaceDefinition } from "./define.js";
+import { LIFECYCLE_CATEGORIES, validateTemplate } from "./validate.js";
+import type {
+  TemplateLifecycle,
+  TemplateProfile,
+  TemplateProperty,
+  WorkspaceYaml,
+} from "./types.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const before = JSON.parse(
+  readFileSync(
+    join(HERE, "__fixtures__/lifecycle-presets.flat-before.json"),
+    "utf8"
+  )
+) as {
+  profiles: Array<{
+    template: string;
+    profile: string;
+    lifecycle: TemplateLifecycle;
+    property: TemplateProperty;
+  }>;
+};
+const compiled = new Map(
+  readYamlTemplates().map((t) => [t.slug, t.data as WorkspaceYaml])
+);
+const authored = (slug: string) =>
+  load(readFileSync(join(HERE, `${slug}.yaml`), "utf8")) as WorkspaceYaml;
+const profileOf = (tpl: WorkspaceYaml, slug: string) =>
+  tpl.profiles.find((p) => p.slug === slug)!;
+
+describe("lifecycle presets — the converted lifecycles compile byte-identical", () => {
+  it("non-vacuity: five conversions, each authored with adopts and no enumValues", () => {
+    expect(before.profiles).toHaveLength(5);
+    for (const b of before.profiles) {
+      const raw = profileOf(authored(b.template), b.profile);
+      expect(raw.lifecycle, `${b.template}/${b.profile}`).toHaveProperty(
+        "adopts"
+      );
+      expect(raw.lifecycle, `${b.template}/${b.profile}`).not.toHaveProperty(
+        "options"
+      );
+      expect(
+        raw.properties.find((p) => p.slug === b.lifecycle.property)
+      ).not.toHaveProperty("enumValues");
+    }
+  });
+
+  // The ONE intended change since the conversion: the muted tone the presets
+  // give a lost step that is a decision (UX review 2026-10-29). Everything
+  // else is main's flat declaration, byte for byte.
+  const TONE_SINCE: Record<string, Record<string, string>> = {
+    "brand-color": { deprecated: "textMuted" },
+    "brand-asset": { deprecated: "textMuted" },
+    "brand-reference": { archived: "textMuted" },
+  };
+  const withTone = (b: (typeof before.profiles)[number]) => ({
+    ...b.lifecycle,
+    options: b.lifecycle.options.map((o) => {
+      const tone = TONE_SINCE[b.profile]?.[o.key];
+      if (!tone) return o;
+      const { key, category, ...rest } = o;
+      return { key, category, tone, ...rest };
+    }),
+  });
+
+  for (const b of before.profiles) {
+    it(`${b.template}/${b.profile}: lifecycle and select equal main's flat declaration`, () => {
+      const profile = profileOf(compiled.get(b.template)!, b.profile);
+      expect(JSON.stringify(profile.lifecycle)).toBe(
+        JSON.stringify(withTone(b))
+      );
+      expect(
+        JSON.stringify(
+          profile.properties.find((p) => p.slug === b.property.slug)
+        )
+      ).toBe(JSON.stringify(b.property));
+    });
+  }
+});
+
+describe("lifecycle presets — the ten bases", () => {
+  it("a lost step that is a decision is muted; a failure keeps the lost default (no tone)", () => {
+    const muted = Object.entries(BASE_LIFECYCLES).flatMap(([name, steps]) =>
+      steps
+        .filter((s) => "tone" in s && s.tone === "textMuted")
+        .map((s) => `${name}.${s.key}`)
+    );
+    expect(muted.sort()).toEqual([
+      "asset.deprecated",
+      "decision.superseded",
+      "decision.withdrawn",
+      "publication.archived",
+      "run.cancelled",
+      "work-item.cancelled",
+    ]);
+    for (const [name, key] of [
+      ["run", "failed"],
+      ["pipeline", "lost"],
+      ["relationship", "churned"],
+    ] as const)
+      expect(
+        BASE_LIFECYCLES[name].find((s) => s.key === key),
+        `${name}.${key}`
+      ).not.toHaveProperty("tone");
+    for (const steps of Object.values(BASE_LIFECYCLES))
+      for (const s of steps) if ("tone" in s) expect(s.category).toBe("lost");
+  });
+
+  it("are ten, each with unique keys, known categories and a done step", () => {
+    expect(Object.keys(BASE_LIFECYCLES)).toHaveLength(10);
+    for (const [name, steps] of Object.entries(BASE_LIFECYCLES)) {
+      const keys = steps.map((s) => s.key);
+      expect(new Set(keys).size, name).toBe(keys.length);
+      for (const s of steps)
+        expect(LIFECYCLE_CATEGORIES, `${name}.${s.key}`).toContain(s.category);
+      expect(
+        steps.some((s) => s.category === "done"),
+        name
+      ).toBe(true);
+      // Picker order follows the categories: open → active → paused → done → lost.
+      const ranks = steps.map((s) => LIFECYCLE_CATEGORIES.indexOf(s.category));
+      expect(ranks, name).toEqual([...ranks].sort((a, b) => a - b));
+    }
+  });
+
+  it("each base alone validates as a lifecycle", () => {
+    for (const name of Object.keys(BASE_LIFECYCLES)) {
+      const { errors } = validateTemplate(
+        templateWith({ property: "status", adopts: name })
+      );
+      expect(errors, name).toEqual([]);
+    }
+  });
+});
+
+/** A minimal valid template whose one profile carries `lifecycle` on a select without enumValues. */
+function templateWith(
+  lifecycle: unknown,
+  property: Partial<TemplateProperty> = {}
+): WorkspaceYaml {
+  return {
+    meta: {
+      slug: "preset-probe",
+      name: "Probe",
+      description: "d",
+      icon: "box",
+      color: "blue",
+    },
+    workspace: { name: "Probe", description: "d" },
+    profiles: [
+      {
+        slug: "probe",
+        displayName: "Probe",
+        lifecycle,
+        properties: [
+          {
+            slug: "title",
+            label: "Title",
+            valueType: "string",
+            inputType: "text",
+          },
+          {
+            slug: "status",
+            label: "Status",
+            valueType: "string",
+            inputType: "select",
+            constraints: { defaultValue: "x" },
+            ...property,
+          },
+        ],
+      } as unknown as TemplateProfile,
+    ],
+  } as unknown as WorkspaceYaml;
+}
+const resolvedProbe = (
+  lifecycle: unknown,
+  property?: Partial<TemplateProperty>
+) => {
+  const r = resolveLifecyclePresets(templateWith(lifecycle, property));
+  return { ...r, profile: r.template.profiles[0] };
+};
+
+describe("lifecycle presets — overlay operations", () => {
+  it("adopts a base as is and generates enumValues right after inputType", () => {
+    const { profile, problems } = resolvedProbe({
+      property: "status",
+      adopts: "relationship",
+    });
+    expect(problems).toEqual([]);
+    expect(profile.lifecycle).toEqual({
+      property: "status",
+      options: [...BASE_LIFECYCLES.relationship],
+    });
+    expect(Object.keys(profile.properties[1])).toEqual([
+      "slug",
+      "label",
+      "valueType",
+      "inputType",
+      "enumValues",
+      "constraints",
+    ]);
+    expect(profile.properties[1].enumValues).toEqual([
+      "prospect",
+      "active",
+      "paused",
+      "former",
+      "churned",
+    ]);
+  });
+
+  it("renames, drops, adds at a position, and overrides humanOnly and stuckAfterDays", () => {
+    const { profile, problems } = resolvedProbe({
+      property: "status",
+      adopts: "agreement",
+      rename: { fulfilled: "ended" },
+      drop: ["in-progress", "expired"],
+      add: [
+        { key: "signed", category: "active", after: "sent" },
+        { key: "renewing", category: "paused" },
+        { key: "first", category: "open", before: "draft" },
+      ],
+      humanOnly: { void: false, signed: true },
+      stuckAfterDays: { sent: 14 },
+    });
+    expect(problems).toEqual([]);
+    expect(profile.lifecycle!.options).toEqual([
+      { key: "first", category: "open" },
+      { key: "draft", category: "open" },
+      { key: "sent", category: "active", stuckAfterDays: 14 },
+      { key: "signed", category: "active", humanOnly: true },
+      { key: "on-hold", category: "paused" },
+      { key: "renewing", category: "paused" },
+      { key: "ended", category: "done" },
+      { key: "declined", category: "lost", humanOnly: true },
+      { key: "void", category: "lost" },
+    ]);
+  });
+
+  it("leaves a flat lifecycle that carries its enumValues as the same object (idempotent)", () => {
+    const tpl = compiled.get("crm")!;
+    expect(resolveLifecyclePresets(tpl).template).toBe(tpl);
+    const once = resolveLifecyclePresets(
+      templateWith({ property: "status", adopts: "asset" })
+    ).template;
+    expect(resolveLifecyclePresets(once).template).toBe(once);
+  });
+
+  it("generates enumValues for a FLAT lifecycle too", () => {
+    const flat = {
+      property: "status",
+      options: [
+        { key: "draft", category: "open" },
+        { key: "done", category: "done" },
+      ],
+    };
+    const { profile, problems } = resolvedProbe(flat);
+    expect(problems).toEqual([]);
+    expect(profile.lifecycle).toBe(profile.lifecycle); // kept as authored
+    expect(profile.properties[1].enumValues).toEqual(["draft", "done"]);
+    expect(validateTemplate(templateWith(flat)).errors).toEqual([]);
+  });
+
+  it("generates nothing for a malformed option list; the validator names it", () => {
+    const malformed = {
+      property: "status",
+      options: [{ key: "draft", category: "open" }, { category: "done" }],
+    };
+    const { profile } = resolvedProbe(malformed);
+    expect(profile.properties[1]).not.toHaveProperty("enumValues");
+    expect(
+      validateTemplate(templateWith(malformed)).errors.map((e) => e.rule)
+    ).toContain("lifecycle-property-unknown");
+  });
+
+  it("an adopts lifecycle naming no select property: no enumValues, the validator refuses it", () => {
+    const lifecycle = { property: "nope", adopts: "asset" };
+    const { profile, problems } = resolvedProbe(lifecycle);
+    expect(problems).toEqual([]);
+    expect(profile.properties[1]).not.toHaveProperty("enumValues");
+    expect(
+      validateTemplate(templateWith(lifecycle)).errors.map((e) => e.rule)
+    ).toEqual(["lifecycle-property-unknown"]);
+  });
+
+  it("keeps enumValues the YAML writes (the validator then requires them equal)", () => {
+    const { profile } = resolvedProbe(
+      { property: "status", adopts: "asset" },
+      { enumValues: ["draft"] }
+    );
+    expect(profile.properties[1].enumValues).toEqual(["draft"]);
+    const { errors } = validateTemplate(
+      templateWith(
+        { property: "status", adopts: "asset" },
+        { enumValues: ["draft"] }
+      )
+    );
+    expect(errors.map((e) => e.rule)).toEqual(["lifecycle-options-mismatch"]);
+  });
+
+  it.each([
+    [
+      { adopts: "contract" },
+      "profiles.probe.lifecycle.adopts",
+      /not a base lifecycle/,
+    ],
+    [
+      { adopts: "asset", options: [] },
+      "profiles.probe.lifecycle.options",
+      /adopts a base or lists its options/,
+    ],
+    [
+      { adopts: "asset", renames: {} },
+      "profiles.probe.lifecycle.renames",
+      /not a lifecycle overlay key/,
+    ],
+    [
+      { adopts: "asset", rename: { doing: "x" } },
+      "profiles.probe.lifecycle.rename.doing",
+      /not a step of the asset base/,
+    ],
+    [
+      { adopts: "asset", drop: ["on-hold"] },
+      "profiles.probe.lifecycle.drop[0]",
+      /not a step of the asset base/,
+    ],
+    [
+      { adopts: "asset", drop: ["approved"] },
+      "profiles.probe.lifecycle",
+      /at least one done step/,
+    ],
+    [
+      { adopts: "asset", rename: { draft: "approved" } },
+      "profiles.probe.lifecycle",
+      /appears twice/,
+    ],
+    [
+      {
+        adopts: "asset",
+        add: [{ key: "x", category: "active", after: "nope" }],
+      },
+      "profiles.probe.lifecycle.add[0].after",
+      /not a step/,
+    ],
+    [
+      { adopts: "asset", humanOnly: { nope: true } },
+      "profiles.probe.lifecycle.humanOnly.nope",
+      /not a step/,
+    ],
+    [
+      {
+        adopts: "asset",
+        add: [{ key: "x", category: "active", humanonly: true }],
+      },
+      "profiles.probe.lifecycle.add[0]",
+      /"humanonly" is not a step field/,
+    ],
+    [
+      {
+        adopts: "asset",
+        rename: { "in-review": "studied" },
+        drop: ["in-review"],
+      },
+      "profiles.probe.lifecycle.drop[0]",
+      /both renamed and dropped/,
+    ],
+    [
+      {
+        adopts: "asset",
+        add: [
+          { key: "x", category: "active", after: "draft", before: "approved" },
+        ],
+      },
+      "profiles.probe.lifecycle.add[0]",
+      /after OR before/,
+    ],
+    [
+      { adopts: "asset", add: [{ key: "approved", category: "active" }] },
+      "profiles.probe.lifecycle",
+      /"approved" appears twice/,
+    ],
+    [
+      { adopts: "asset", humanOnly: { draft: "yes" } },
+      "profiles.probe.lifecycle.humanOnly.draft",
+      /must be a boolean/,
+    ],
+  ])("reports %j", (overlay, path, message) => {
+    const lifecycle = { property: "status", ...overlay };
+    const { problems, profile } = resolvedProbe(lifecycle);
+    expect(problems.map((p) => p.path)).toContain(path);
+    expect(problems.find((p) => p.path === path)!.message).toMatch(message);
+    expect(profile.lifecycle).toEqual(lifecycle); // left as authored
+    const { ok, errors } = validateTemplate(templateWith(lifecycle));
+    expect(ok).toBe(false);
+    expect(
+      errors.some((e) => e.rule === "lifecycle-adopts" && e.path === path)
+    ).toBe(true);
+  });
+});
+
+describe("lifecycle presets — every door compiles authored YAML", () => {
+  const tpl = templateWith({
+    property: "status",
+    adopts: "publication",
+    drop: ["on-hold"],
+  });
+  const flat = BASE_LIFECYCLES.publication.filter((s) => s.key !== "on-hold");
+
+  it("validateTemplate accepts an adopts lifecycle with no enumValues", () => {
+    expect(validateTemplate(tpl).errors).toEqual([]);
+  });
+
+  it("both define converters carry the flat declaration and the generated enumValues", () => {
+    for (const profiles of [
+      toPackageDefinition(tpl).profiles,
+      toWorkspaceDefinition(tpl).definition.profiles,
+    ]) {
+      const p = (profiles as TemplateProfile[])[0];
+      expect(p.lifecycle).toEqual({ property: "status", options: flat });
+      expect(p.properties[1].enumValues).toEqual(flat.map((s) => s.key));
+    }
+  });
+
+  it("a define converter refuses an overlay that does not resolve", () => {
+    expect(() =>
+      toPackageDefinition(templateWith({ property: "status", adopts: "nope" }))
+    ).toThrow(/lifecycle presets do not resolve/);
+  });
+
+  it("the validator compiles a raw corpus too (no false lifecycle-diverges against a flat twin)", () => {
+    const foundation = authored("foundation");
+    expect(profileOf(foundation, "client").lifecycle).toHaveProperty("adopts");
+    const compiledFoundation = compiled.get("foundation")!;
+    const twin = {
+      ...compiledFoundation,
+      meta: { ...compiledFoundation.meta, slug: "foundation-twin" },
+    };
+    const diverges = validateTemplate(twin, {
+      corpus: [foundation, twin],
+    }).errors.filter((e) => e.rule === "lifecycle-diverges");
+    expect(diverges).toEqual([]);
+  });
+});