@pixel-point/toolcraft 0.0.15 → 0.0.17

package/templates/starter/scripts/toolcraft-functional-proof-model.mjs

@@ -0,0 +1,198 @@
+import { validateToolcraftDeliveryCatalog } from "./playwright-test-title-selection.mjs";
+import {
+  createToolcraftCanonicalJsonHash,
+  serializeToolcraftCanonicalJson,
+} from "./toolcraft-functional-proof-primitives.mjs";
+import {
+  TOOLCRAFT_VERIFICATION_IMPACT_VERSION,
+  normalizeToolcraftVerificationImpactOwners,
+} from "./toolcraft-verification-impact-inventory.mjs";
+
+export {
+  createToolcraftAcceptanceContractHash,
+  deriveToolcraftAcceptanceDomainId,
+} from "./toolcraft-functional-proof-primitives.mjs";
+
+export const TOOLCRAFT_FUNCTIONAL_PROOF_MODEL_VERSION = 1;
+
+const compareCodeUnits = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const isRecord = (value) =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+const sorted = (values) => [...values].sort(compareCodeUnits);
+
+function exactKeysError(value, expected, label) {
+  if (!isRecord(value)) return `${label} must be an object.`;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    return `${label} must be a plain object.`;
+  }
+  const expectedSet = new Set(expected);
+  const unknown = sorted(
+    Reflect.ownKeys(value)
+      .filter((key) => typeof key !== "string" || !expectedSet.has(key))
+      .map(String),
+  );
+  const missing = expected.filter(
+    (key) => !Object.prototype.hasOwnProperty.call(value, key),
+  );
+  if (unknown.length > 0) return `${label} contains unknown fields: ${unknown.join(", ")}.`;
+  if (missing.length > 0) return `${label} is missing required fields: ${missing.join(", ")}.`;
+  return undefined;
+}
+
+function duplicateOrOrderError(rows, key, label) {
+  for (let index = 1; index < rows.length; index += 1) {
+    const comparison = compareCodeUnits(rows[index - 1][key], rows[index][key]);
+    if (comparison === 0) return `${label} "${rows[index][key]}" must be unique.`;
+    if (comparison > 0) return `${label} rows must be sorted by ${key}.`;
+  }
+  return undefined;
+}
+
+function deeplyFrozen(value, ancestors = new Set()) {
+  if (!(value && typeof value === "object")) return true;
+  if (!Object.isFrozen(value) || ancestors.has(value)) return false;
+  ancestors.add(value);
+  const frozen = Object.values(value).every((entry) => deeplyFrozen(entry, ancestors));
+  ancestors.delete(value);
+  return frozen;
+}
+
+export function getToolcraftFunctionalProofModelError(value) {
+  const shapeError = exactKeysError(
+    value,
+    ["acceptance", "owners", "version"],
+    "Toolcraft functional proof model",
+  );
+  if (shapeError) return shapeError;
+  if (!deeplyFrozen(value)) {
+    return "Toolcraft functional proof model must be deeply frozen.";
+  }
+  try {
+    serializeToolcraftCanonicalJson(value);
+  } catch (error) {
+    return error.message;
+  }
+  if (value.version !== TOOLCRAFT_FUNCTIONAL_PROOF_MODEL_VERSION) {
+    return `Toolcraft functional proof model.version must be ${TOOLCRAFT_FUNCTIONAL_PROOF_MODEL_VERSION}.`;
+  }
+  if (!Array.isArray(value.acceptance) || !Array.isArray(value.owners)) {
+    return "Toolcraft functional proof model acceptance and owners must be arrays.";
+  }
+  const catalogValidation = validateToolcraftDeliveryCatalog({
+    acceptance: value.acceptance,
+    performance: [],
+    version: 2,
+  });
+  if (catalogValidation.errors.length > 0) return catalogValidation.errors[0];
+  const acceptanceOrderError = duplicateOrOrderError(
+    value.acceptance,
+    "acceptanceId",
+    "Functional proof model acceptance id",
+  );
+  if (acceptanceOrderError) return acceptanceOrderError;
+  const ownerValidation = normalizeToolcraftVerificationImpactOwners(
+    value.owners,
+    {
+      acceptanceIds: value.acceptance.map(({ acceptanceId }) => acceptanceId),
+      requireCanonical: true,
+    },
+  );
+  return ownerValidation.errors[0];
+}
+
+function deepFreeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.values(value).forEach(deepFreeze);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+export function createToolcraftFunctionalProofModel({ catalog, inventory }) {
+  const catalogValidation = validateToolcraftDeliveryCatalog(catalog);
+  if (catalogValidation.errors.length > 0) {
+    throw new Error(`Invalid delivery catalog: ${catalogValidation.errors.join("\n")}`);
+  }
+  const inventoryError = exactKeysError(
+    inventory,
+    ["owners", "version"],
+    "Verification impact inventory input",
+  );
+  if (inventoryError) throw new Error(inventoryError);
+  if (inventory.version !== TOOLCRAFT_VERIFICATION_IMPACT_VERSION) {
+    throw new Error(
+      `Verification impact inventory.version must be ${TOOLCRAFT_VERIFICATION_IMPACT_VERSION}.`,
+    );
+  }
+  const acceptance = catalogValidation.catalog.acceptance.map((row) => ({
+    acceptanceId: row.acceptanceId,
+    contractHash: row.contractHash,
+    domainId: row.domainId,
+    file: row.file,
+    testName: row.testName,
+  }));
+  const ownerValidation = normalizeToolcraftVerificationImpactOwners(
+    inventory.owners,
+    {
+      acceptanceIds: acceptance.map(({ acceptanceId }) => acceptanceId),
+    },
+  );
+  if (ownerValidation.errors.length > 0) {
+    throw new Error(ownerValidation.errors.join("\n"));
+  }
+  const model = deepFreeze({
+    acceptance,
+    owners: ownerValidation.owners,
+    version: TOOLCRAFT_FUNCTIONAL_PROOF_MODEL_VERSION,
+  });
+  const modelError = getToolcraftFunctionalProofModelError(model);
+  if (modelError) throw new Error(modelError);
+  return model;
+}
+
+export function createToolcraftFunctionalProofModelHash(model) {
+  const error = getToolcraftFunctionalProofModelError(model);
+  if (error) throw new Error(`Invalid Toolcraft functional proof model: ${error}`);
+  return createToolcraftCanonicalJsonHash(model);
+}
+
+export function diffToolcraftFunctionalProofModels({ current, previous }) {
+  for (const [label, model] of [["Current", current], ["Previous", previous]]) {
+    const error = getToolcraftFunctionalProofModelError(model);
+    if (error) throw new Error(`${label} Toolcraft functional proof model is invalid: ${error}`);
+  }
+  const currentRows = new Map(current.acceptance.map((row) => [row.acceptanceId, row]));
+  const previousRows = new Map(previous.acceptance.map((row) => [row.acceptanceId, row]));
+  const currentOwners = new Map(current.owners.map((owner) => [owner.path, owner]));
+  const previousOwners = new Map(previous.owners.map((owner) => [owner.path, owner]));
+  const acceptanceIds = new Set();
+  for (const [acceptanceId, row] of currentRows) {
+    const prior = previousRows.get(acceptanceId);
+    if (!prior || prior.contractHash !== row.contractHash) acceptanceIds.add(acceptanceId);
+  }
+  const changedOwnerPaths = [];
+  for (const ownerPath of sorted(new Set([...currentOwners.keys(), ...previousOwners.keys()]))) {
+    const currentOwner = currentOwners.get(ownerPath);
+    const previousOwner = previousOwners.get(ownerPath);
+    if (
+      !currentOwner || !previousOwner ||
+      serializeToolcraftCanonicalJson(currentOwner) !==
+      serializeToolcraftCanonicalJson(previousOwner)
+    ) {
+      changedOwnerPaths.push(ownerPath);
+      for (const owner of [previousOwner, currentOwner]) {
+        for (const acceptanceId of owner?.acceptanceIds ?? []) {
+          acceptanceIds.add(acceptanceId);
+        }
+      }
+    }
+  }
+  return deepFreeze({
+    acceptanceIds: sorted(acceptanceIds),
+    changedOwnerPaths,
+    removedAcceptanceIds: sorted(
+      [...previousRows.keys()].filter((acceptanceId) => !currentRows.has(acceptanceId)),
+    ),
+  });
+}

package/templates/starter/scripts/toolcraft-functional-proof-model.test.mjs

@@ -0,0 +1,453 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import test from "node:test";
+
+import {
+  TOOLCRAFT_FUNCTIONAL_PROOF_MODEL_VERSION,
+  createToolcraftAcceptanceContractHash,
+  createToolcraftFunctionalProofModel as createFunctionalProofModel,
+  createToolcraftFunctionalProofModelHash,
+  deriveToolcraftAcceptanceDomainId,
+  diffToolcraftFunctionalProofModels,
+  getToolcraftFunctionalProofModelError,
+} from "./toolcraft-functional-proof-model.mjs";
+
+const hash = (character) => character.repeat(64);
+const acceptanceRow = (acceptanceId, contractHash = hash("a")) => ({
+  acceptanceId,
+  contractHash,
+  domainId: acceptanceId.split(".")[0],
+  file: `${acceptanceId.split(".")[0]}.spec.ts`,
+  testName: `browser: ${acceptanceId}`,
+});
+const catalog = (acceptance) => ({
+  acceptance,
+  performance: [],
+  version: 2,
+});
+const inventory = (owners) => ({ owners, version: 3 });
+const owner = (ownerPath, acceptanceIds, extra = {}) => ({
+  acceptanceIds,
+  kind: "functional",
+  path: ownerPath,
+  ...extra,
+});
+function deepFreeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.values(value).forEach(deepFreeze);
+    Object.freeze(value);
+  }
+  return value;
+}
+function createModel(input) {
+  const model = createFunctionalProofModel(input);
+  assert.match(createToolcraftFunctionalProofModelHash(model), /^[a-f0-9]{64}$/u);
+  return model;
+}
+function withSymbol(value) {
+  value[Symbol("unexpected")] = true;
+  return value;
+}
+
+test("acceptance contract hashing uses one strict canonical JSON representation", () => {
+  const left = {
+    nested: { z: null, a: [true, 2, "2"] },
+    title: "material",
+  };
+  const right = {
+    title: "material",
+    nested: { a: [true, 2, "2"], z: null },
+  };
+  const expected = createHash("sha256")
+    .update('{"nested":{"a":[true,2,"2"],"z":null},"title":"material"}')
+    .digest("hex");
+
+  assert.equal(createToolcraftAcceptanceContractHash(left), expected);
+  assert.equal(createToolcraftAcceptanceContractHash(right), expected);
+  assert.notEqual(
+    createToolcraftAcceptanceContractHash({ nested: { a: ["2", 2, true], z: null }, title: "material" }),
+    expected,
+  );
+  const primitiveHashes = [null, true, false, 0, 1, "1"].map((value) =>
+    createToolcraftAcceptanceContractHash({ value })
+  );
+  assert.equal(new Set(primitiveHashes).size, primitiveHashes.length);
+});
+
+test("acceptance contract hashing rejects every non-JSON-safe value", () => {
+  const cyclic = {};
+  cyclic.self = cyclic;
+  for (const value of [
+    { value: undefined },
+    { value() {} },
+    { value: Symbol("value") },
+    { value: Number.NaN },
+    { value: Number.POSITIVE_INFINITY },
+    cyclic,
+    { value: new Date(0) },
+  ]) {
+    assert.throws(
+      () => createToolcraftAcceptanceContractHash(value),
+      /canonical JSON/iu,
+    );
+  }
+});
+
+test("acceptance domains use the first stable namespace segment", () => {
+  assert.equal(deriveToolcraftAcceptanceDomainId("material.donut.shape"), "material");
+  assert.equal(deriveToolcraftAcceptanceDomainId("canvas"), "canvas");
+  for (const invalid of ["", " material.shape", ".material", undefined]) {
+    assert.throws(
+      () => deriveToolcraftAcceptanceDomainId(invalid),
+      /acceptance id/iu,
+    );
+  }
+});
+
+test("creates one sorted, duplicate-free, deeply frozen functional proof model", () => {
+  const model = createModel({
+    catalog: catalog([
+      acceptanceRow("material.shape", hash("b")),
+      acceptanceRow("export.image"),
+    ]),
+    inventory: inventory([
+      {
+        acceptanceIds: ["material.shape", "export.image"],
+        kind: "performance",
+        passIds: ["source", "composite"],
+        path: "src/output.ts",
+      },
+      owner("src/app-schema.ts", ["export.image"]),
+    ]),
+  });
+
+  assert.equal(TOOLCRAFT_FUNCTIONAL_PROOF_MODEL_VERSION, 1);
+  assert.deepEqual(model, {
+    acceptance: [
+      acceptanceRow("export.image"),
+      acceptanceRow("material.shape", hash("b")),
+    ],
+    owners: [
+      owner("src/app-schema.ts", ["export.image"]),
+      {
+        acceptanceIds: ["export.image", "material.shape"],
+        kind: "performance",
+        passIds: ["composite", "source"],
+        path: "src/output.ts",
+      },
+    ],
+    version: 1,
+  });
+  assert.equal(getToolcraftFunctionalProofModelError(model), undefined);
+  assert.equal(Object.isFrozen(model), true);
+  assert.equal(Object.isFrozen(model.acceptance[0]), true);
+  assert.equal(Object.isFrozen(model.owners[1].acceptanceIds), true);
+  assert.equal(Object.isFrozen(model.owners[1].passIds), true);
+  assert.match(createToolcraftFunctionalProofModelHash(model), /^[a-f0-9]{64}$/u);
+});
+
+test("proof model validation is exact-key, canonical, and closed over acceptance ids", () => {
+  const model = createModel({
+    catalog: catalog([acceptanceRow("material.shape")]),
+    inventory: inventory([owner("src/output.ts", ["material.shape"])]),
+  });
+  const malformedModels = [
+    [{ ...model, extra: true }, /model.*unknown fields: extra/iu],
+    [
+      { ...model, acceptance: [{ ...model.acceptance[0], extra: true }] },
+      /acceptance row.*unknown fields: extra/iu,
+    ],
+    [
+      { ...model, owners: [{ ...model.owners[0], passIds: ["source"] }] },
+      /owner.*unknown fields: passIds/iu,
+    ],
+    [
+      { ...model, acceptance: [...model.acceptance, model.acceptance[0]] },
+      /duplicate acceptance id/iu,
+    ],
+    [
+      { ...model, owners: [...model.owners, model.owners[0]] },
+      /owner path.*must be unique/iu,
+    ],
+    [
+      {
+        ...model,
+        owners: [owner("src/output.ts", ["missing.acceptance"])],
+      },
+      /unknown acceptance id "missing\.acceptance"/iu,
+    ],
+  ].map(([malformed, expectedError]) => [
+    deepFreeze(malformed),
+    expectedError,
+  ]);
+  for (const [malformed, expectedError] of malformedModels) {
+    assert.match(getToolcraftFunctionalProofModelError(malformed), expectedError);
+    assert.throws(
+      () => createToolcraftFunctionalProofModelHash(malformed),
+      expectedError,
+    );
+  }
+  assert.throws(
+    () => createFunctionalProofModel({
+      catalog: catalog([acceptanceRow("material.shape")]),
+      inventory: inventory([{
+        ...owner("src/output.ts", ["material.shape"]),
+        unknown: true,
+      }]),
+    }),
+    /unknown fields/iu,
+  );
+});
+
+test("model hash is independent of source ordering after canonical construction", () => {
+  const rows = [
+    acceptanceRow("material.shape", hash("b")),
+    acceptanceRow("export.image"),
+  ];
+  const owners = [
+    owner("src/output.ts", ["material.shape"]),
+    owner("src/app-schema.ts", ["export.image"]),
+  ];
+  const first = createModel({
+    catalog: catalog(rows),
+    inventory: inventory(owners),
+  });
+  const second = createModel({
+    catalog: catalog([...rows].reverse()),
+    inventory: inventory([...owners].reverse()),
+  });
+
+  assert.deepEqual(first, second);
+  assert.equal(
+    createToolcraftFunctionalProofModelHash(first),
+    createToolcraftFunctionalProofModelHash(second),
+  );
+});
+
+test("validation and hashing reject mutable models at every object depth", () => {
+  const model = createModel({
+    catalog: catalog([acceptanceRow("material.shape")]),
+    inventory: inventory([owner("src/output.ts", ["material.shape"])]),
+  });
+  const mutableRoot = structuredClone(model);
+  const mutableRow = Object.freeze({
+    ...model,
+    acceptance: Object.freeze([{ ...model.acceptance[0] }]),
+  });
+  const mutableOwnerIds = Object.freeze({
+    ...model,
+    owners: Object.freeze([
+      Object.freeze({
+        ...model.owners[0],
+        acceptanceIds: [...model.owners[0].acceptanceIds],
+      }),
+    ]),
+  });
+
+  for (const mutable of [mutableRoot, mutableRow, mutableOwnerIds]) {
+    assert.match(
+      getToolcraftFunctionalProofModelError(mutable),
+      /deeply frozen/iu,
+    );
+    assert.throws(
+      () => createToolcraftFunctionalProofModelHash(mutable),
+      /deeply frozen/iu,
+    );
+  }
+});
+
+test("diff ignores catalog metadata relocation when contract hash is unchanged", () => {
+  const previous = createModel({
+    catalog: catalog([acceptanceRow("material.shape")]),
+    inventory: inventory([owner("src/output.ts", ["material.shape"])]),
+  });
+  const relocatedRow = {
+    ...acceptanceRow("material.shape"),
+    file: "material-relocated.spec.ts",
+  };
+  const current = createModel({
+    catalog: catalog([relocatedRow]),
+    inventory: inventory([owner("src/output.ts", ["material.shape"])]),
+  });
+
+  assert.deepEqual(diffToolcraftFunctionalProofModels({ current, previous }), {
+    acceptanceIds: [],
+    changedOwnerPaths: [],
+    removedAcceptanceIds: [],
+  });
+});
+
+test("diff selects semantic row and owner deltas while reporting removed ids separately", () => {
+  const previous = createModel({
+    catalog: catalog([
+      acceptanceRow("export.old"),
+      acceptanceRow("material.color"),
+      acceptanceRow("scene.light"),
+    ]),
+    inventory: inventory([
+      owner("src/export.ts", ["export.old"]),
+      owner("src/material.ts", ["material.color"]),
+      owner("src/scene.ts", ["scene.light"]),
+    ]),
+  });
+  const current = createModel({
+    catalog: catalog([
+      acceptanceRow("material.color", hash("b")),
+      acceptanceRow("material.shape"),
+      acceptanceRow("scene.light"),
+    ]),
+    inventory: inventory([
+      owner("src/material.ts", ["material.shape", "material.color"]),
+      owner("src/scene.ts", ["scene.light"]),
+      owner("src/shape.ts", ["material.shape"]),
+    ]),
+  });
+
+  assert.deepEqual(diffToolcraftFunctionalProofModels({ current, previous }), {
+    acceptanceIds: ["export.old", "material.color", "material.shape"],
+    changedOwnerPaths: ["src/export.ts", "src/material.ts", "src/shape.ts"],
+    removedAcceptanceIds: ["export.old"],
+  });
+});
+
+test("diff preserves all coverage of an additive owner delta", () => {
+  const rows = [
+    acceptanceRow("material.color"),
+    acceptanceRow("material.emission"),
+  ];
+  const previous = createModel({
+    catalog: catalog(rows),
+    inventory: inventory([
+      owner("src/material.ts", ["material.color"]),
+      owner("src/emission.ts", ["material.emission"]),
+    ]),
+  });
+  const current = createModel({
+    catalog: catalog(rows),
+    inventory: inventory([
+      owner(
+        "src/material.ts",
+        ["material.color", "material.emission"],
+      ),
+      owner("src/emission.ts", ["material.emission"]),
+    ]),
+  });
+
+  assert.deepEqual(diffToolcraftFunctionalProofModels({ current, previous }), {
+    acceptanceIds: ["material.color", "material.emission"],
+    changedOwnerPaths: ["src/material.ts"],
+    removedAcceptanceIds: [],
+  });
+});
+
+test("diff keeps functional coverage when only owner classification changes", () => {
+  const rows = [acceptanceRow("material.color")];
+  const previous = createModel({
+    catalog: catalog(rows),
+    inventory: inventory([
+      owner("src/material.ts", ["material.color"]),
+    ]),
+  });
+  const current = createModel({
+    catalog: catalog(rows),
+    inventory: inventory([
+      owner("src/material.ts", ["material.color"], {
+        kind: "performance",
+        passIds: ["preview"],
+      }),
+    ]),
+  });
+
+  assert.deepEqual(diffToolcraftFunctionalProofModels({ current, previous }), {
+    acceptanceIds: ["material.color"],
+    changedOwnerPaths: ["src/material.ts"],
+    removedAcceptanceIds: [],
+  });
+});
+
+test("construction uses current catalog and impact validation without partial acceptance", () => {
+  const row = acceptanceRow("material.shape");
+  const validInventory = inventory([owner("src/output.ts", ["material.shape"])]);
+  const malformedPathId = "performance-path:not-json";
+  assert.throws(
+    () => createFunctionalProofModel({
+      catalog: {
+        ...catalog([row]),
+        performance: [{
+          passIds: [],
+          pathId: malformedPathId,
+          testName: `browser perf: toolcraft path ${malformedPathId}`,
+        }],
+      },
+      inventory: validInventory,
+    }),
+    /invalid delivery catalog.*malformed canonical path/iu,
+  );
+  assert.throws(
+    () => createFunctionalProofModel({
+      catalog: catalog([row]),
+      inventory: { ...validInventory, version: 999 },
+    }),
+    /inventory.*version must be 3/iu,
+  );
+});
+
+test("symbol fields are rejected at model, catalog, inventory, and owner boundaries", () => {
+  const model = createModel({
+    catalog: catalog([acceptanceRow("material.shape")]),
+    inventory: inventory([owner("src/output.ts", ["material.shape"])]),
+  });
+  const acceptanceArray = withSymbol([...model.acceptance]);
+  const ownersArray = withSymbol([...model.owners]);
+  const malformedModels = [
+    withSymbol({ ...model }),
+    { ...model, acceptance: [withSymbol({ ...model.acceptance[0] })] },
+    { ...model, owners: [withSymbol({ ...model.owners[0] })] },
+    { ...model, acceptance: acceptanceArray },
+    { ...model, owners: ownersArray },
+    {
+      ...model,
+      owners: [{
+        ...model.owners[0],
+        acceptanceIds: withSymbol([...model.owners[0].acceptanceIds]),
+      }],
+    },
+  ].map(deepFreeze);
+  for (const malformed of malformedModels) {
+    assert.match(getToolcraftFunctionalProofModelError(malformed), /symbol/iu);
+  }
+
+  const row = acceptanceRow("material.shape");
+  const validOwner = owner("src/output.ts", ["material.shape"]);
+  for (const input of [
+    {
+      catalog: withSymbol(catalog([row])),
+      inventory: inventory([validOwner]),
+    },
+    {
+      catalog: catalog([withSymbol({ ...row })]),
+      inventory: inventory([validOwner]),
+    },
+    {
+      catalog: catalog([row]),
+      inventory: withSymbol(inventory([validOwner])),
+    },
+    {
+      catalog: catalog([row]),
+      inventory: inventory(withSymbol([validOwner])),
+    },
+    {
+      catalog: catalog([row]),
+      inventory: inventory([withSymbol({ ...validOwner })]),
+    },
+    {
+      catalog: catalog([row]),
+      inventory: inventory([{
+        ...validOwner,
+        acceptanceIds: withSymbol([...validOwner.acceptanceIds]),
+      }]),
+    },
+  ]) {
+    assert.throws(() => createFunctionalProofModel(input), /symbol/iu);
+  }
+});