@pixel-point/toolcraft 0.0.17 → 0.0.18

package/templates/starter/src/app/acceptance/control-section-entity-cohesion.test.ts

@@ -0,0 +1,215 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  getToolcraftControlSectionEntityCohesionErrors,
+  hasToolcraftInventoryEntityAgreement,
+} from "./control-section-entity-cohesion";
+import type { ToolcraftControlSectionInventoryEntry } from "./types";
+
+function makeSection({
+  count,
+  entity = "Renderable object",
+  entityId = "renderable-object",
+  id = "object",
+  splitReason,
+  workflowStage,
+}: {
+  count: number;
+  entity?: string;
+  entityId?: string;
+  id?: string;
+  splitReason?: string;
+  workflowStage?: string;
+}): ToolcraftControlSectionInventoryEntry {
+  return {
+    entity,
+    entityId,
+    groupingReason: `The ${id} controls edit one coherent part of the entity.`,
+    id,
+    splitReason,
+    targets: Array.from(
+      { length: count },
+      (_, index) => `${id}.value${index + 1}`,
+    ),
+    title: id,
+    workflowStage,
+  };
+}
+
+describe("Toolcraft control section entity cohesion", () => {
+  it.each([1, 7, 8, 10])(
+    "accepts one entity in one section with %s controls",
+    (count) => {
+      expect(
+        getToolcraftControlSectionEntityCohesionErrors([
+          makeSection({ count }),
+        ]),
+      ).toEqual([]);
+    },
+  );
+
+  it("rejects splitting an entity that fits in one section", () => {
+    const errors = getToolcraftControlSectionEntityCohesionErrors([
+      makeSection({ count: 3, id: "object-source" }),
+      makeSection({ count: 4, id: "object-style" }),
+    ]);
+
+    expect(errors).toContain(
+      'Control Section Inventory entity "renderable-object" owns 7 controls across 2 sections (object-source, object-style). Entities with 10 or fewer controls must stay in one section.',
+    );
+  });
+
+  it("rejects an entity above the hard maximum left in one section", () => {
+    expect(
+      getToolcraftControlSectionEntityCohesionErrors([
+        makeSection({ count: 11 }),
+      ]),
+    ).toContain(
+      'Control Section Inventory entity "renderable-object" owns 11 controls in section object. Split entities above 10 controls into explicit workflow stages.',
+    );
+  });
+
+  it("accepts a balanced large-entity workflow split", () => {
+    expect(
+      getToolcraftControlSectionEntityCohesionErrors([
+        makeSection({
+          count: 5,
+          id: "object-structure",
+          splitReason: "Structure is authored before the finishing workflow.",
+          workflowStage: "structure",
+        }),
+        makeSection({
+          count: 6,
+          id: "object-finish",
+          splitReason: "Finish is authored after the structural workflow.",
+          workflowStage: "finish",
+        }),
+      ]),
+    ).toEqual([]);
+  });
+
+  it("rejects a one-control tail in a split entity", () => {
+    expect(
+      getToolcraftControlSectionEntityCohesionErrors([
+        makeSection({
+          count: 10,
+          id: "object-primary",
+          splitReason: "Primary editing precedes the final workflow stage.",
+          workflowStage: "primary",
+        }),
+        makeSection({
+          count: 1,
+          id: "object-final",
+          splitReason: "The final workflow follows primary editing.",
+          workflowStage: "final",
+        }),
+      ]),
+    ).toContain(
+      'Control Section Inventory entity "renderable-object" section object-final owns 1 control. Every section in a split entity must own between 2 and 10 controls.',
+    );
+  });
+
+  it("rejects a split section above the per-section maximum", () => {
+    expect(
+      getToolcraftControlSectionEntityCohesionErrors([
+        makeSection({
+          count: 11,
+          id: "object-primary",
+          splitReason: "Primary editing precedes the final workflow stage.",
+          workflowStage: "primary",
+        }),
+        makeSection({
+          count: 2,
+          id: "object-final",
+          splitReason: "The final workflow follows primary editing.",
+          workflowStage: "final",
+        }),
+      ]),
+    ).toContain(
+      'Control Section Inventory entity "renderable-object" section object-primary owns 11 controls. Every section in a split entity must own between 2 and 10 controls.',
+    );
+  });
+
+  it("requires a workflow stage on every section of a split entity", () => {
+    expect(
+      getToolcraftControlSectionEntityCohesionErrors([
+        makeSection({
+          count: 6,
+          id: "object-primary",
+          splitReason: "Primary editing precedes the final workflow stage.",
+        }),
+        makeSection({
+          count: 6,
+          id: "object-final",
+          splitReason: "The final workflow follows primary editing.",
+          workflowStage: "final",
+        }),
+      ]),
+    ).toContain(
+      'Control Section Inventory entity "renderable-object" section object-primary must declare workflowStage because the entity is split across sections.',
+    );
+  });
+
+  it("requires complete, unique split evidence and a consistent entity name", () => {
+    const errors = getToolcraftControlSectionEntityCohesionErrors([
+      makeSection({ count: 6, id: "object-a", workflowStage: "edit" }),
+      makeSection({
+        count: 6,
+        entity: "Different label",
+        id: "object-b",
+        splitReason: "This section follows the first editing stage.",
+        workflowStage: "edit",
+      }),
+    ]);
+
+    expect(errors).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("uses inconsistent entity names"),
+        expect.stringContaining("object-a must declare splitReason"),
+        expect.stringContaining('repeats workflowStage "edit"'),
+      ]),
+    );
+  });
+
+  it("keeps independent entities independent", () => {
+    expect(
+      getToolcraftControlSectionEntityCohesionErrors([
+        makeSection({ count: 4, entityId: "entity-a", id: "entity-a" }),
+        makeSection({ count: 4, entityId: "entity-b", id: "entity-b" }),
+      ]),
+    ).toEqual([]);
+  });
+
+  it("requires one shared entityId for target-prefix corroboration", () => {
+    const first = makeSection({ count: 6, id: "first" });
+    const second = makeSection({
+      count: 6,
+      entityId: "different-entity",
+      id: "second",
+    });
+    const sectionInventoryById = new Map([
+      [first.id, first],
+      [second.id, second],
+    ]);
+    const sections = new Set([first.id, second.id]);
+
+    expect(
+      hasToolcraftInventoryEntityAgreement({
+        sectionInventoryById,
+        sections,
+      }),
+    ).toBe(false);
+
+    sectionInventoryById.set(second.id, {
+      ...second,
+      entityId: first.entityId,
+    });
+
+    expect(
+      hasToolcraftInventoryEntityAgreement({
+        sectionInventoryById,
+        sections,
+      }),
+    ).toBe(true);
+  });
+});

package/templates/starter/src/app/acceptance/control-section-entity-cohesion.ts

@@ -0,0 +1,132 @@
+import type { ToolcraftControlSectionInventoryEntry } from "./types";
+
+export const TOOLCRAFT_DENSE_SECTION_MIN_CONTROLS = 8;
+
+const TOOLCRAFT_MAX_CONTROLS_PER_SECTION = 10;
+const TOOLCRAFT_MIN_CONTROLS_PER_SPLIT_SECTION = 2;
+const TOOLCRAFT_MIN_SPLIT_REASON_LENGTH = 12;
+
+export function hasToolcraftInventoryEntityAgreement({
+  sectionInventoryById,
+  sections,
+}: {
+  sectionInventoryById: ReadonlyMap<
+    string,
+    ToolcraftControlSectionInventoryEntry
+  >;
+  sections: ReadonlySet<string>;
+}): boolean {
+  const entries = [...sections].map((sectionId) =>
+    sectionInventoryById.get(sectionId),
+  );
+  const entityIds = entries.map((entry) => entry?.entityId?.trim() ?? "");
+
+  return entityIds.every(Boolean) && new Set(entityIds).size === 1;
+}
+
+export function getToolcraftControlSectionEntityCohesionErrors(
+  sectionInventory: readonly ToolcraftControlSectionInventoryEntry[],
+): string[] {
+  const errors: string[] = [];
+  const entriesByEntityId = new Map<
+    string,
+    ToolcraftControlSectionInventoryEntry[]
+  >();
+
+  for (const entry of sectionInventory) {
+    const entityId = entry.entityId?.trim() ?? "";
+    const entity = entry.entity?.trim() ?? "";
+
+    if (
+      !entityId ||
+      !entity ||
+      (entry.id?.trim().length ?? 0) === 0 ||
+      !Array.isArray(entry.targets) ||
+      entry.targets.length === 0
+    ) {
+      continue;
+    }
+
+    const entries = entriesByEntityId.get(entityId) ?? [];
+    entries.push(entry);
+    entriesByEntityId.set(entityId, entries);
+  }
+
+  for (const [entityId, entries] of entriesByEntityId) {
+    const controlCount = entries.reduce(
+      (total, entry) => total + entry.targets.length,
+      0,
+    );
+    const sectionNames = entries.map((entry) => entry.title.trim() || entry.id);
+    const entityNames = new Set(entries.map((entry) => entry.entity.trim()));
+
+    if (entityNames.size > 1) {
+      errors.push(
+        `Control Section Inventory entity "${entityId}" uses inconsistent entity names: ${[
+          ...entityNames,
+        ].join(", ")}. Reuse one human-readable entity name for every section in the entity.`,
+      );
+    }
+
+    if (controlCount <= TOOLCRAFT_MAX_CONTROLS_PER_SECTION) {
+      if (entries.length > 1) {
+        errors.push(
+          `Control Section Inventory entity "${entityId}" owns ${controlCount} controls across ${entries.length} sections (${sectionNames.join(", ")}). Entities with ${TOOLCRAFT_MAX_CONTROLS_PER_SECTION} or fewer controls must stay in one section.`,
+        );
+      }
+      continue;
+    }
+
+    if (entries.length === 1) {
+      errors.push(
+        `Control Section Inventory entity "${entityId}" owns ${controlCount} controls in section ${sectionNames[0]}. Split entities above ${TOOLCRAFT_MAX_CONTROLS_PER_SECTION} controls into explicit workflow stages.`,
+      );
+      continue;
+    }
+
+    const sectionsByStage = new Map<string, string[]>();
+
+    for (const entry of entries) {
+      const sectionName = entry.title.trim() || entry.id;
+      const sectionControlCount = entry.targets.length;
+      const workflowStage = entry.workflowStage?.trim() ?? "";
+      const splitReason = entry.splitReason?.trim() ?? "";
+
+      if (
+        sectionControlCount < TOOLCRAFT_MIN_CONTROLS_PER_SPLIT_SECTION ||
+        sectionControlCount > TOOLCRAFT_MAX_CONTROLS_PER_SECTION
+      ) {
+        errors.push(
+          `Control Section Inventory entity "${entityId}" section ${sectionName} owns ${sectionControlCount} ${sectionControlCount === 1 ? "control" : "controls"}. Every section in a split entity must own between ${TOOLCRAFT_MIN_CONTROLS_PER_SPLIT_SECTION} and ${TOOLCRAFT_MAX_CONTROLS_PER_SECTION} controls.`,
+        );
+      }
+
+      if (!workflowStage) {
+        errors.push(
+          `Control Section Inventory entity "${entityId}" section ${sectionName} must declare workflowStage because the entity is split across sections.`,
+        );
+      } else {
+        const normalizedStage = workflowStage.toLowerCase();
+        const stageSections = sectionsByStage.get(normalizedStage) ?? [];
+        stageSections.push(sectionName);
+        sectionsByStage.set(normalizedStage, stageSections);
+      }
+
+      if (splitReason.length < TOOLCRAFT_MIN_SPLIT_REASON_LENGTH) {
+        errors.push(
+          `Control Section Inventory entity "${entityId}" section ${sectionName} must declare splitReason of at least ${TOOLCRAFT_MIN_SPLIT_REASON_LENGTH} characters because the entity is split across sections.`,
+        );
+      }
+    }
+
+    for (const [stage, stageSections] of sectionsByStage) {
+      if (stageSections.length > 1) {
+        errors.push(
+          `Control Section Inventory entity "${entityId}" repeats workflowStage "${stage}" across sections ${stageSections.join(", ")}. Workflow stages must be unique within one entity.`,
+        );
+      }
+    }
+  }
+
+  return errors;
+}

package/templates/starter/src/app/acceptance/control-section-inventory.test.ts

@@ -40,6 +40,7 @@ function createSchema({
 
 const inventoryEntry = {
   entity: "Appearance",
+  entityId: "appearance",
   groupingReason: "These controls define the visible appearance of the output.",
   id: "appearance",
   targets: ["appearance.opacity"],
@@ -56,6 +57,53 @@ describe("Toolcraft Control Section Inventory identity", () => {
     ).toEqual([]);
   });
 
+  it("preserves inventory ownership when runtime Setup relocates product background controls", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                background: {
+                  applicability: { mode: "always" },
+                  defaultValue: "#101010",
+                  target: "appearance.background",
+                  type: "color",
+                },
+                includeBackground: {
+                  applicability: { mode: "always" },
+                  defaultValue: true,
+                  target: "export.includeBackground",
+                  type: "switch",
+                },
+              },
+              id: "background",
+              title: "Background",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+    const backgroundInventory = {
+      entity: "Output background",
+      entityId: "output-background",
+      groupingReason:
+        "Inclusion and color jointly define the exported background.",
+      id: "background",
+      targets: ["export.includeBackground", "appearance.background"],
+      title: "Background",
+    } as const;
+
+    expect(schema.panels.controls?.sections[0]?.id).toBe("runtime.setup");
+    expect(
+      getToolcraftControlSectionInventoryErrors(schema, [
+        backgroundInventory,
+      ]),
+    ).toEqual([]);
+  });
+
   it("rejects an inventory id that does not match the schema section", () => {
     const errors = getToolcraftControlSectionInventoryErrors(createSchema(), [
       { ...inventoryEntry, id: "different-section" },
@@ -80,6 +128,45 @@ describe("Toolcraft Control Section Inventory identity", () => {
     );
   });
 
+  it.each([
+    [
+      "blank entityId",
+      { ...inventoryEntry, entityId: "" },
+      'Control Section Inventory entry "Original title" must declare a non-empty stable entityId.',
+    ],
+    [
+      "blank entity",
+      { ...inventoryEntry, entity: "" },
+      'Control Section Inventory entry "Original title" must declare a human-readable entity name.',
+    ],
+  ])("rejects %s", (_label, entry, expectedMessage) => {
+    expect(
+      getToolcraftControlSectionInventoryErrors(createSchema(), [entry]),
+    ).toContain(expectedMessage);
+  });
+
+  it("rejects a missing entityId without throwing", () => {
+    const { entityId: _entityId, ...entryWithoutEntityId } = inventoryEntry;
+    const malformedInventory = [
+      entryWithoutEntityId,
+    ] as unknown as readonly ToolcraftControlSectionInventoryEntry[];
+
+    expect(() =>
+      getToolcraftControlSectionInventoryErrors(
+        createSchema(),
+        malformedInventory,
+      ),
+    ).not.toThrow();
+    expect(
+      getToolcraftControlSectionInventoryErrors(
+        createSchema(),
+        malformedInventory,
+      ),
+    ).toContain(
+      'Control Section Inventory entry "Original title" must declare a non-empty stable entityId.',
+    );
+  });
+
   it.each([
     ["missing", undefined],
     ["non-string", 42],

package/templates/starter/src/app/acceptance/control-section-inventory.ts

@@ -7,6 +7,12 @@ import {
 import { getToolcraftSectionLabel } from "./sections";
 import type { ToolcraftControlSectionInventoryEntry } from "./types";
 
+type ToolcraftInventorySchemaSection = Readonly<{
+  id: string;
+  label: string;
+  targets: readonly string[];
+}>;
+
 function getToolcraftControlSectionInventoryEntryId(
   entry: ToolcraftControlSectionInventoryEntry,
 ): string | null {
@@ -36,44 +42,31 @@ export function getToolcraftSectionInventoryById(
   return new Map(entries);
 }
 
-export function hasToolcraftInventorySplitEvidence({
-  sectionInventoryById,
-  sections,
-}: {
-  sectionInventoryById: ReadonlyMap<string, ToolcraftControlSectionInventoryEntry>;
-  sections: ReadonlySet<string>;
-}): boolean {
-  const entries = [...sections].map((sectionId) =>
-    sectionInventoryById.get(sectionId),
-  );
+function getToolcraftInventoryEntryByTarget(
+  sectionInventory: readonly ToolcraftControlSectionInventoryEntry[],
+): ReadonlyMap<string, ToolcraftControlSectionInventoryEntry> {
+  const entries = new Map<string, ToolcraftControlSectionInventoryEntry>();
 
-  return (
-    entries.length === sections.size &&
-    entries.every(
-      (entry) =>
-        entry &&
-        (entry.workflowStage?.trim().length ?? 0) > 0 &&
-        (entry.splitReason?.trim().length ?? 0) >= 12,
-    )
-  );
+  for (const entry of sectionInventory) {
+    for (const target of entry.targets) {
+      if (!entries.has(target)) {
+        entries.set(target, entry);
+      }
+    }
+  }
+
+  return entries;
 }
 
-export function getToolcraftControlSectionInventoryErrors(
+function collectToolcraftInventorySchemaSections(
   schema: ResolvedToolcraftAppSchema,
   sectionInventory: readonly ToolcraftControlSectionInventoryEntry[],
-): string[] {
-  const errors: string[] = [];
-
-  if (sectionInventory.length === 0) {
-    return errors;
-  }
+): ToolcraftInventorySchemaSection[] {
+  const inventoryEntryByTarget =
+    getToolcraftInventoryEntryByTarget(sectionInventory);
 
-  const schemaSections = (schema.panels.controls?.sections ?? []).flatMap(
+  return (schema.panels.controls?.sections ?? []).flatMap(
     (section, sectionIndex) => {
-      if (section.id === "runtime.setup") {
-        return [];
-      }
-
       const targets = Object.values(section.controls)
         .filter(isToolcraftProductSectionControl)
         .map((control) => control.target);
@@ -82,15 +75,53 @@ export function getToolcraftControlSectionInventoryErrors(
         return [];
       }
 
-      return [
-        {
+      if (section.id !== "runtime.setup") {
+        return [{
           id: section.id,
           label: getToolcraftSectionLabel(section.title, sectionIndex),
           targets,
-        },
-      ];
+        }];
+      }
+
+      const relocatedSections = new Map<string, ToolcraftInventorySchemaSection>();
+
+      for (const target of targets) {
+        const inventoryEntry = inventoryEntryByTarget.get(target);
+        const inventoryId = inventoryEntry
+          ? getToolcraftControlSectionInventoryEntryId(inventoryEntry)
+          : null;
+        const id = inventoryId ?? section.id;
+        const existing = relocatedSections.get(id);
+
+        relocatedSections.set(id, {
+          id,
+          label:
+            inventoryId && inventoryEntry
+              ? inventoryEntry.title
+              : getToolcraftSectionLabel(section.title, sectionIndex),
+          targets: [...(existing?.targets ?? []), target],
+        });
+      }
+
+      return [...relocatedSections.values()];
     },
   );
+}
+
+export function getToolcraftControlSectionInventoryErrors(
+  schema: ResolvedToolcraftAppSchema,
+  sectionInventory: readonly ToolcraftControlSectionInventoryEntry[],
+): string[] {
+  const errors: string[] = [];
+
+  if (sectionInventory.length === 0) {
+    return errors;
+  }
+
+  const schemaSections = collectToolcraftInventorySchemaSections(
+    schema,
+    sectionInventory,
+  );
   const schemaSectionIds = new Set(schemaSections.map((section) => section.id));
   const schemaTargetToSection = new Map<string, string>();
 
@@ -107,9 +138,8 @@ export function getToolcraftControlSectionInventoryErrors(
     const id = getToolcraftControlSectionInventoryEntryId(entry);
     const title = entry.title.trim();
     const entity = entry.entity?.trim() ?? "";
-    const workflowStage = entry.workflowStage?.trim() ?? "";
+    const entityId = entry.entityId?.trim() ?? "";
     const groupingReason = entry.groupingReason.trim();
-    const splitReason = entry.splitReason?.trim() ?? "";
 
     if (!id) {
       errors.push(
@@ -133,21 +163,21 @@ export function getToolcraftControlSectionInventoryErrors(
       );
     }
 
-    if (!entity && !workflowStage) {
+    if (!entityId) {
       errors.push(
-        `Control Section Inventory entry "${title}" must declare entity or workflowStage so grouping is based on product meaning, not UI layout.`,
+        `Control Section Inventory entry "${title}" must declare a non-empty stable entityId.`,
       );
     }
 
-    if (groupingReason.length < 12) {
+    if (!entity) {
       errors.push(
-        `Control Section Inventory entry "${title}" must include a concrete groupingReason explaining why these controls belong together.`,
+        `Control Section Inventory entry "${title}" must declare a human-readable entity name.`,
       );
     }
 
-    if (splitReason && splitReason.length < 12) {
+    if (groupingReason.length < 12) {
       errors.push(
-        `Control Section Inventory entry "${title}" splitReason is too vague. Explain the product workflow split or omit splitReason.`,
+        `Control Section Inventory entry "${title}" must include a concrete groupingReason explaining why these controls belong together.`,
       );
     }
 
@@ -208,7 +238,7 @@ export function getToolcraftControlSectionInventoryErrors(
 
     if (!entry) {
       errors.push(
-        `Control Section Inventory is missing product section id "${section.id}" (${section.label}). Add the same explicit id, entity/workflow stage, targets, and groupingReason.`,
+        `Control Section Inventory is missing product section id "${section.id}" (${section.label}). Add the same explicit id, entityId, entity, targets, and groupingReason.`,
       );
       continue;
     }

package/templates/starter/src/app/acceptance/custom-controls.ts

@@ -109,10 +109,18 @@ export function getBuiltInFitCheckErrors(
     );
   }
 
+  const ownsRepeatedItems = capabilities.some((capability) =>
+    ["collection", "reorder", "selection"].includes(capability),
+  );
+
+  if (ownsRepeatedItems && !checkedBuiltIns.includes("sourceCollection")) {
+    errors.push(
+      `${label} builtInFitCheck.checkedBuiltIns must include sourceCollection when the custom control owns a repeated runtime item set whose cardinality could be source-owned.`,
+    );
+  }
+
   if (
-    capabilities.some((capability) =>
-      ["collection", "reorder", "selection"].includes(capability),
-    ) &&
+    ownsRepeatedItems &&
     !checkedBuiltIns.includes("collectionActions")
   ) {
     errors.push(