@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/starter/scripts/toolcraft-delivery-receipt.mjs

@@ -0,0 +1,216 @@
+import {
+  TOOLCRAFT_DELIVERY_PLAN_VERSION,
+  createToolcraftDeliveryPlanHash,
+  getToolcraftDeliveryPlanError,
+} from "./toolcraft-delivery-plan.mjs";
+import {
+  getToolcraftExecutionEvidenceError,
+} from "./toolcraft-delivery-evidence.mjs";
+import {
+  createToolcraftFunctionalProofModelHash,
+  getToolcraftFunctionalProofModelError,
+} from "./toolcraft-functional-proof-model.mjs";
+import { readToolcraftCheckpointBundle } from "./toolcraft-checkpoint-bundle.mjs";
+import {
+  collectToolcraftVerificationInputs,
+  getToolcraftChangedVerificationFiles,
+  getToolcraftVerificationInventoryError,
+} from "./toolcraft-verification-inventory.mjs";
+
+export const TOOLCRAFT_DELIVERY_RECEIPT_VERSION = 7;
+
+const receiptKeys = Object.freeze([
+  "completedAt",
+  "evidence",
+  "files",
+  "functionalProofModel",
+  "functionalProofModelHash",
+  "kind",
+  "manifestHash",
+  "plan",
+  "planHash",
+  "planVersion",
+  "runner",
+  "sourceHash",
+  "status",
+  "version",
+]);
+const hashPattern = /^[a-f0-9]{64}$/u;
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasExactKeys(value, expected) {
+  if (!isRecord(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  const actual = Reflect.ownKeys(value);
+  return (
+    actual.length === expected.length &&
+    actual.every(
+      (key) =>
+        typeof key === "string" &&
+        expected.includes(key) &&
+        Object.prototype.propertyIsEnumerable.call(value, key),
+    )
+  );
+}
+
+function arraysEqual(left, right) {
+  return (
+    Array.isArray(left) &&
+    Array.isArray(right) &&
+    left.length === right.length &&
+    left.every((item, index) => item === right[index])
+  );
+}
+
+function deepFreeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.values(value).forEach(deepFreeze);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+function getCurrentReceiptCommonError(receipt) {
+  if (
+    !hasExactKeys(receipt, receiptKeys) ||
+    receipt.kind !== "delivery-verification" ||
+    receipt.runner !== "protected-delivery" ||
+    receipt.status !== "passed" ||
+    receipt.version !== TOOLCRAFT_DELIVERY_RECEIPT_VERSION ||
+    receipt.planVersion !== TOOLCRAFT_DELIVERY_PLAN_VERSION ||
+    typeof receipt.completedAt !== "string" ||
+    !hashPattern.test(receipt.sourceHash ?? "") ||
+    !hashPattern.test(receipt.functionalProofModelHash ?? "") ||
+    !hashPattern.test(receipt.manifestHash ?? "") ||
+    !hashPattern.test(receipt.planHash ?? "")
+  ) {
+    return "Toolcraft delivery receipt is malformed or has unsupported fields.";
+  }
+  return getToolcraftVerificationInventoryError({
+    entries: receipt.files,
+    label: "Toolcraft delivery receipt file inventory",
+    sourceHash: receipt.sourceHash,
+  });
+}
+
+export function getToolcraftDeliveryReceiptShapeError(receipt) {
+  const commonError = getCurrentReceiptCommonError(receipt);
+  if (commonError) return commonError;
+  const plan = deepFreeze(receipt.plan);
+  const functionalProofModel = deepFreeze(receipt.functionalProofModel);
+  const planError = getToolcraftDeliveryPlanError(plan);
+  if (planError) return planError;
+  const modelError =
+    getToolcraftFunctionalProofModelError(functionalProofModel);
+  if (modelError) {
+    return `Toolcraft delivery receipt functional proof model is invalid: ${modelError}`;
+  }
+  if (
+    createToolcraftFunctionalProofModelHash(functionalProofModel) !==
+      receipt.functionalProofModelHash ||
+    receipt.functionalProofModelHash !== plan.functionalProofModelHash
+  ) {
+    return "Toolcraft delivery receipt functional proof model hash does not match its model and plan.";
+  }
+  if (
+    receipt.sourceHash !== plan.sourceHash ||
+    receipt.manifestHash !== plan.manifestHash
+  ) {
+    return "Toolcraft delivery receipt source or manifest does not match its plan.";
+  }
+  if (createToolcraftDeliveryPlanHash(plan) !== receipt.planHash) {
+    return "Toolcraft delivery receipt plan hash does not match its plan.";
+  }
+  if (
+    plan.basis.kind === "changed" &&
+    !arraysEqual(
+      plan.basis.changedFiles,
+      getToolcraftChangedVerificationFiles(
+        plan.basis.comparisonInventory.entries,
+        receipt.files,
+      ),
+    )
+  ) {
+    return "Toolcraft delivery receipt changed files do not exactly match its inventories.";
+  }
+  return getToolcraftExecutionEvidenceError({
+    evidence: receipt.evidence,
+    finalInventory: {
+      entries: receipt.files,
+      sourceHash: receipt.sourceHash,
+    },
+    plan,
+  });
+}
+
+export function createToolcraftDeliveryReceipt({
+  functionalProofModel,
+  plan,
+  result,
+}) {
+  const modelError =
+    getToolcraftFunctionalProofModelError(functionalProofModel);
+  if (modelError) {
+    throw new Error(
+      `Invalid Toolcraft functional proof model: ${modelError}`,
+    );
+  }
+  const functionalProofModelHash =
+    createToolcraftFunctionalProofModelHash(functionalProofModel);
+  if (functionalProofModelHash !== plan.functionalProofModelHash) {
+    throw new Error(
+      "Toolcraft functional proof model does not match the delivery plan.",
+    );
+  }
+  const planHash = createToolcraftDeliveryPlanHash(plan);
+  const resultError = getToolcraftExecutionEvidenceError({
+    evidence: result?.evidence,
+    finalInventory: result?.finalInventory,
+    plan,
+  });
+  if (resultError) throw new Error(resultError);
+  const receipt = {
+    completedAt: new Date().toISOString(),
+    evidence: result?.evidence,
+    files: result?.finalInventory?.entries,
+    functionalProofModel,
+    functionalProofModelHash,
+    kind: "delivery-verification",
+    manifestHash: plan.manifestHash,
+    plan,
+    planHash,
+    planVersion: TOOLCRAFT_DELIVERY_PLAN_VERSION,
+    runner: "protected-delivery",
+    sourceHash: plan.sourceHash,
+    status: "passed",
+    version: TOOLCRAFT_DELIVERY_RECEIPT_VERSION,
+  };
+  const error = getToolcraftDeliveryReceiptShapeError(receipt);
+  if (error) throw new Error(error);
+  return deepFreeze(receipt);
+}
+
+export async function readToolcraftDeliveryReceipt(rootDir) {
+  const loaded = await readToolcraftCheckpointBundle(rootDir);
+  if (loaded.missing || loaded.error) return loaded;
+  const receipt = loaded.bundle.delivery;
+  const error = getToolcraftDeliveryReceiptShapeError(receipt);
+  return error ? { error } : { receipt: deepFreeze(receipt) };
+}
+
+export async function validateToolcraftDeliveryReceipt({
+  collectInventory = collectToolcraftVerificationInputs,
+  rootDir,
+}) {
+  const loaded = await readToolcraftDeliveryReceipt(rootDir);
+  if (loaded.missing) return ["Toolcraft delivery receipt is missing."];
+  if (loaded.error) return [loaded.error];
+  const inventory = await collectInventory(rootDir);
+  return loaded.receipt.sourceHash === inventory.sourceHash
+    ? []
+    : ["Toolcraft delivery receipt is stale for the current source."];
+}

package/templates/starter/scripts/toolcraft-delivery-receipt.test.mjs

@@ -0,0 +1,195 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import test from "node:test";
+
+import {
+  TOOLCRAFT_DELIVERY_RECEIPT_VERSION,
+  createToolcraftDeliveryReceipt,
+  getToolcraftDeliveryReceiptShapeError,
+  validateToolcraftDeliveryReceipt,
+} from "./toolcraft-delivery-receipt.mjs";
+import {
+  createPlanReceiptFixture,
+  createFunctionalProofModelFixture,
+  writeDeliveryReceiptFixture,
+} from "./toolcraft-delivery-receipt-test-helpers.mjs";
+import {
+  createToolcraftFunctionalProofModelHash,
+} from "./toolcraft-functional-proof-model.mjs";
+import { createReceiptFixture } from "./toolcraft-verification-receipt-test-helpers.mjs";
+
+function assertDeeplyFrozen(value) {
+  if (!value || typeof value !== "object") return;
+  assert.equal(Object.isFrozen(value), true);
+  Object.values(value).forEach(assertDeeplyFrozen);
+}
+
+test("constructs the exact deeply frozen version 7 receipt", () => {
+  const { functionalProofModel, plan, result } = createPlanReceiptFixture();
+  const receipt = createToolcraftDeliveryReceipt({
+    functionalProofModel,
+    plan,
+    result,
+  });
+
+  assert.equal(TOOLCRAFT_DELIVERY_RECEIPT_VERSION, 7);
+  assert.equal(receipt.planVersion, 4);
+  assert.equal(receipt.version, 7);
+  assert.deepEqual(Object.keys(receipt).sort(), [
+    "completedAt",
+    "evidence",
+    "files",
+    "functionalProofModel",
+    "functionalProofModelHash",
+    "kind",
+    "manifestHash",
+    "plan",
+    "planHash",
+    "planVersion",
+    "runner",
+    "sourceHash",
+    "status",
+    "version",
+  ]);
+  assert.equal(receipt.functionalProofModel, functionalProofModel);
+  assert.equal(
+    receipt.functionalProofModelHash,
+    createToolcraftFunctionalProofModelHash(functionalProofModel),
+  );
+  assert.equal(receipt.plan, plan);
+  assert.deepEqual(receipt.evidence, result.evidence);
+  assert.deepEqual(receipt.files, result.finalInventory.entries);
+  assert.equal(getToolcraftDeliveryReceiptShapeError(receipt), undefined);
+  assertDeeplyFrozen(receipt);
+});
+
+test("constructs initial functional proof with exact browser evidence", () => {
+  const fixture = createPlanReceiptFixture("functional-initial");
+  const receipt = createToolcraftDeliveryReceipt(fixture);
+
+  assert.equal(getToolcraftDeliveryReceiptShapeError(receipt), undefined);
+  assert.deepEqual(
+    receipt.evidence.at(-1),
+    fixture.result.evidence.at(-1),
+  );
+});
+
+test("rejects obsolete receipt 6 and plan 3 identities", () => {
+  const receipt = createToolcraftDeliveryReceipt(
+    createPlanReceiptFixture("functional-changed"),
+  );
+
+  assert.match(
+    getToolcraftDeliveryReceiptShapeError({ ...receipt, version: 6 }),
+    /malformed|unsupported/iu,
+  );
+  assert.match(
+    getToolcraftDeliveryReceiptShapeError({ ...receipt, planVersion: 3 }),
+    /malformed|unsupported/iu,
+  );
+});
+
+test("validates only the current receipt source and ignores full-performance state", async (t) => {
+  const rootDir = await createReceiptFixture();
+  t.after(() => fs.rm(rootDir, { force: true, recursive: true }));
+  const { functionalProofModel, plan, result } = createPlanReceiptFixture();
+  const receipt = createToolcraftDeliveryReceipt({
+    functionalProofModel,
+    plan,
+    result,
+  });
+  await writeDeliveryReceiptFixture(rootDir, receipt);
+
+  const bundlePath = `${rootDir}/.toolcraft/verification/checkpoint.json`;
+  const bundle = JSON.parse(await fs.readFile(bundlePath, "utf8"));
+  bundle.currentPerformance = { malformed: true };
+  bundle.performanceBaseline = { malformed: true };
+  await fs.writeFile(bundlePath, `${JSON.stringify(bundle)}\n`);
+
+  assert.deepEqual(await validateToolcraftDeliveryReceipt({
+    collectInventory: async () => result.finalInventory,
+    rootDir,
+  }), []);
+  assert.deepEqual(await validateToolcraftDeliveryReceipt({
+    collectInventory: async () => ({
+      ...result.finalInventory,
+      sourceHash: "0".repeat(64),
+    }),
+    rootDir,
+  }), ["Toolcraft delivery receipt is stale for the current source."]);
+});
+
+test("rejects a different valid model and every model/hash tamper", () => {
+  const fixture = createPlanReceiptFixture();
+  const receipt = createToolcraftDeliveryReceipt(fixture);
+  const differentModel = createFunctionalProofModelFixture({
+    acceptanceId: "export.focused",
+    contractHash: "c".repeat(64),
+  });
+  const differentHash =
+    createToolcraftFunctionalProofModelHash(differentModel);
+  const changedModel = Object.freeze({
+    ...receipt.functionalProofModel,
+    acceptance: Object.freeze([
+      Object.freeze({
+        ...receipt.functionalProofModel.acceptance[0],
+        contractHash: "d".repeat(64),
+      }),
+    ]),
+  });
+
+  for (const altered of [
+    { ...receipt, functionalProofModel: changedModel },
+    { ...receipt, functionalProofModelHash: "0".repeat(64) },
+    {
+      ...receipt,
+      functionalProofModel: differentModel,
+      functionalProofModelHash: differentHash,
+    },
+    {
+      ...receipt,
+      functionalProofModel: Object.freeze({
+        ...receipt.functionalProofModel,
+        unexpected: true,
+      }),
+    },
+  ]) {
+    assert.match(
+      getToolcraftDeliveryReceiptShapeError(altered),
+      /functional proof model|model hash|unknown fields|plan/iu,
+    );
+  }
+});
+
+test("creation rejects a model that does not match its plan", () => {
+  const fixture = createPlanReceiptFixture();
+  const differentModel = createFunctionalProofModelFixture({
+    acceptanceId: "export.focused",
+    contractHash: "c".repeat(64),
+  });
+  assert.throws(
+    () => createToolcraftDeliveryReceipt({
+      ...fixture,
+      functionalProofModel: differentModel,
+    }),
+    /functional proof model|plan/iu,
+  );
+});
+
+test("rejects excess fields outside the plan-backed receipt model", () => {
+  const fixture = createPlanReceiptFixture();
+  const receipt = createToolcraftDeliveryReceipt(fixture);
+  for (const extra of [
+    { unexpectedAuthority: true },
+    { mode: "legacy-delivery" },
+    { baselineSourceHash: "a".repeat(64) },
+    { baselineEvidenceHash: "b".repeat(64) },
+    { checks: ["docs"] },
+    { changedFiles: [] },
+  ]) {
+    assert.match(
+      getToolcraftDeliveryReceiptShapeError({ ...receipt, ...extra }),
+      /malformed|unsupported fields/iu,
+    );
+  }
+});

package/templates/starter/scripts/toolcraft-delivery-receipt.types.test.mts

@@ -0,0 +1,161 @@
+import type {
+  ToolcraftDeliveryExecutionResult,
+  ToolcraftDeliveryReceipt,
+  ToolcraftDeliveryStepEvidence,
+} from "./toolcraft-delivery-receipt.mjs";
+import {
+  createToolcraftDeliveryReceipt,
+} from "./toolcraft-delivery-receipt.mjs";
+import type {
+  FunctionalDeliveryPlan,
+  PerformanceIterationPlan,
+  ToolcraftDeliveryLifecycleState,
+  ToolcraftDeliveryPlan,
+  ToolcraftDeliveryPlanningInputs,
+} from "./toolcraft-delivery-plan.mjs";
+import type {
+  ToolcraftFunctionalProofModel,
+} from "./toolcraft-functional-proof-model.mjs";
+
+const files = [{ path: "src/app/app-schema.ts", sha256: "a".repeat(64) }];
+const comparisonFiles = [
+  { path: "src/app/app-schema.ts", sha256: "b".repeat(64) },
+];
+const lifecycle: ToolcraftDeliveryLifecycleState = {
+  consumedPerformanceRequestAuthorityHashes: ["e".repeat(64)],
+  performanceEscalationOffered: true,
+};
+const plan: ToolcraftDeliveryPlan = {
+  basis: {
+    changedFiles: ["src/app/app-schema.ts"],
+    comparisonFunctionalProofModelHash: "f".repeat(64),
+    comparisonInventory: {
+      entries: comparisonFiles,
+      sourceHash: "b".repeat(64),
+    },
+    kind: "changed",
+  },
+  functionalProofModelHash: "f".repeat(64),
+  kind: "functional",
+  lifecycle,
+  manifestHash: "c".repeat(64),
+  sourceHash: "a".repeat(64),
+  steps: [{ kind: "docs" }],
+};
+const evidence: readonly ToolcraftDeliveryStepEvidence[] = [
+  { kind: "docs" },
+];
+const functionalProofModel: ToolcraftFunctionalProofModel = {
+  acceptance: [{
+    acceptanceId: "canvas.focused",
+    contractHash: "b".repeat(64),
+    domainId: "canvas",
+    file: "app-controls.spec.ts",
+    testName: "browser: focused acceptance",
+  }],
+  owners: [{
+    acceptanceIds: ["canvas.focused"],
+    kind: "functional",
+    path: "src/app/app-schema.ts",
+  }],
+  version: 1,
+};
+const receipt: ToolcraftDeliveryReceipt = {
+  completedAt: "2026-07-24T00:00:00.000Z",
+  evidence,
+  files,
+  functionalProofModel,
+  functionalProofModelHash: plan.functionalProofModelHash,
+  kind: "delivery-verification",
+  manifestHash: plan.manifestHash,
+  plan,
+  planHash: "d".repeat(64),
+  planVersion: 4,
+  runner: "protected-delivery",
+  sourceHash: plan.sourceHash,
+  status: "passed",
+  version: 7,
+};
+
+const withLegacyMode = { ...receipt, mode: "ordinary" as const };
+// @ts-expect-error Current delivery receipts cannot carry a legacy mode.
+const invalidMode: ToolcraftDeliveryReceipt = withLegacyMode;
+const withBaseline = {
+  ...receipt,
+  baselineEvidenceHash: "e".repeat(64),
+  baselineSourceHash: "f".repeat(64),
+};
+// @ts-expect-error Current delivery receipts cannot carry baseline linkage.
+const invalidBaseline: ToolcraftDeliveryReceipt = withBaseline;
+const withOldPlanVersion = { ...receipt, planVersion: 1 as const };
+// @ts-expect-error Current delivery receipts require plan version 4.
+const invalidPlanVersion: ToolcraftDeliveryReceipt = withOldPlanVersion;
+const withOldReceiptVersion = { ...receipt, version: 6 as const };
+// @ts-expect-error Current delivery receipts require receipt version 7.
+const invalidReceiptVersion: ToolcraftDeliveryReceipt = withOldReceiptVersion;
+const { functionalProofModel: _model, ...withoutModel } = receipt;
+// @ts-expect-error Current delivery receipts require the canonical proof model.
+const invalidReceiptModel: ToolcraftDeliveryReceipt = withoutModel;
+declare const executionResult: ToolcraftDeliveryExecutionResult;
+// @ts-expect-error Receipt creation requires the immediate functional proof model.
+createToolcraftDeliveryReceipt({ plan, result: executionResult });
+const { lifecycle: _lifecycle, ...withoutLifecycle } = plan;
+// @ts-expect-error Every current delivery plan requires lifecycle metadata.
+const invalidPlan: ToolcraftDeliveryPlan = withoutLifecycle;
+const invalidFunctional: FunctionalDeliveryPlan = {
+  ...plan,
+  steps: [{
+    // @ts-expect-error Functional plans cannot carry browser-performance proof.
+    kind: "browser-performance",
+    passIds: ["preview"],
+    pathIds: ["path"],
+    testNames: ["browser perf: path"],
+  }],
+};
+const invalidIteration: PerformanceIterationPlan = {
+  ...plan,
+  kind: "performance-iteration",
+  performanceComparison: { kind: "none" },
+  requestAuthorityHash: "e".repeat(64),
+  // @ts-expect-error Performance iterations require a final browser-performance step.
+  steps: [{ kind: "docs" }],
+};
+const initialPerformanceCandidate = {
+  basis: { kind: "initial" as const },
+  functionalProofModelHash: "f".repeat(64),
+  kind: "performance-iteration" as const,
+  lifecycle,
+  manifestHash: "c".repeat(64),
+  performanceComparison: { kind: "none" as const },
+  requestAuthorityHash: "e".repeat(64),
+  sourceHash: "a".repeat(64),
+  steps: [{
+    kind: "browser-performance" as const,
+    passIds: ["preview"],
+    pathIds: ["path"],
+    testNames: ["browser perf: path"],
+  }] as const,
+};
+// @ts-expect-error Performance iterations require a changed delivery basis.
+const invalidInitialIteration: PerformanceIterationPlan =
+  initialPerformanceCandidate;
+// @ts-expect-error Lifecycle authority history is immutable.
+plan.lifecycle.consumedPerformanceRequestAuthorityHashes.push("f".repeat(64));
+declare const planningInputs: ToolcraftDeliveryPlanningInputs;
+const previousLifecycle: ToolcraftDeliveryLifecycleState =
+  planningInputs.previousLifecycle;
+
+void [
+  receipt,
+  invalidMode,
+  invalidBaseline,
+  invalidPlanVersion,
+  invalidReceiptVersion,
+  invalidReceiptModel,
+  invalidPlan,
+  invalidFunctional,
+  invalidIteration,
+  invalidInitialIteration,
+  previousLifecycle,
+  executionResult,
+];

package/templates/starter/scripts/toolcraft-dependency-source-record.mjs

@@ -0,0 +1,59 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  createToolcraftCssSourceRecord,
+} from "./toolcraft-css-source-evidence.mjs";
+import {
+  toolcraftModuleExtensions,
+} from "./toolcraft-product-dependency-resolution.mjs";
+import {
+  createToolcraftTypeScriptDependencyRecord,
+  createToolcraftTypeScriptSourceRecord,
+} from "./toolcraft-typescript-source-evidence.mjs";
+
+export async function createToolcraftDependencySourceRecord({
+  entry,
+  importsOnly,
+  rootDir,
+}) {
+  const extension = path.extname(entry.repoPath);
+  const isModule = toolcraftModuleExtensions.includes(extension);
+  const isCss = /\.css$/u.test(entry.repoPath);
+  if (!isModule && !isCss) return undefined;
+  const rawSource = await fs.readFile(entry.absolutePath, "utf8");
+  if (isCss) {
+    return createToolcraftCssSourceRecord({
+      rawSource,
+      repoPath: entry.repoPath,
+    });
+  }
+  return importsOnly
+    ? createToolcraftTypeScriptDependencyRecord({
+        absolutePath: entry.absolutePath,
+        rawSource,
+      })
+    : createToolcraftTypeScriptSourceRecord({
+        absolutePath: entry.absolutePath,
+        rawSource,
+        repoPath: entry.repoPath,
+        rootDir,
+      });
+}
+
+export function getToolcraftDependencyImports(entry, sourceRecord) {
+  if (!sourceRecord.cssEvidence) return sourceRecord.imports;
+  if (!/\.module\.css$/iu.test(entry.repoPath)) return [];
+  return sourceRecord.cssEvidence.urlFacts
+    .filter(({ local, quoted }) => local && quoted)
+    .map(({ column, line, value }) => Object.freeze({
+      category: "css-url",
+      column,
+      line,
+      specifier:
+        [".", "/", "@/"].some((prefix) => value.startsWith(prefix))
+          ? value
+          : `./${value}`,
+      typeOnly: false,
+    }));
+}