@pixel-point/toolcraft 0.0.15 → 0.0.17

package/templates/starter/scripts/toolcraft-state-evidence-facade.test.mjs

@@ -0,0 +1,258 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { pathToFileURL } from "node:url";
+
+import ts from "typescript";
+
+const helperPath = path.resolve(
+  import.meta.dirname,
+  "../e2e/browser-state-evidence-helpers.ts",
+);
+
+async function loadStateEvidenceFacade(context) {
+  const outputDir = await fs.mkdtemp(
+    path.join(os.tmpdir(), "toolcraft-state-evidence-"),
+  );
+  context.after(() => fs.rm(outputDir, { force: true, recursive: true }));
+  const outputPath = path.join(outputDir, "browser-state-evidence-helpers.mjs");
+  const source = (await fs.readFile(helperPath, "utf8"))
+    .replaceAll('"@playwright/test"', '"./playwright.mjs"')
+    .replaceAll('"./browser-runtime-evidence"', '"./evidence.mjs"')
+    .replaceAll('"./browser-proof-session"', '"./proof-session.mjs"')
+    .replaceAll(
+      '"./browser-acceptance-transition-helpers"',
+      '"./transition.mjs"',
+    )
+    .replaceAll('"./stable-outcome-helpers"', '"./stable-outcome.mjs"');
+  const { outputText } = ts.transpileModule(source, {
+    compilerOptions: {
+      module: ts.ModuleKind.ESNext,
+      target: ts.ScriptTarget.ES2022,
+    },
+    fileName: helperPath,
+  });
+
+  await Promise.all([
+    fs.writeFile(outputPath, outputText),
+    fs.writeFile(
+      path.join(outputDir, "playwright.mjs"),
+      `
+        import assert from "node:assert/strict";
+        export function expect(actual, message = "Expectation failed") {
+          return {
+            not: {
+              toBe(expected) {
+                assert.notEqual(actual, expected, message);
+              },
+              toEqual(expected) {
+                assert.notDeepEqual(actual, expected, message);
+              },
+            },
+            toBe(expected) {
+              assert.equal(actual, expected, message);
+            },
+            toBeGreaterThan(expected) {
+              assert.ok(actual > expected, message);
+            },
+            toEqual(expected) {
+              assert.deepEqual(actual, expected, message);
+            },
+          };
+        }
+      `,
+    ),
+    fs.writeFile(
+      path.join(outputDir, "evidence.mjs"),
+      `
+        export async function attachToolcraftBrowserRuntimeEvidence(evidence) {
+          globalThis.__toolcraftStateEvidenceTrace.push("evidence");
+          globalThis.__toolcraftStateEvidenceAttachments.push(evidence);
+        }
+      `,
+    ),
+    fs.writeFile(
+      path.join(outputDir, "proof-session.mjs"),
+      `
+        export function assertToolcraftBrowserProofSession(
+          observation,
+          mutate,
+          reload,
+        ) {
+          if (
+            !observation.session ||
+            observation.session !== mutate.session ||
+            observation.session !== reload.session
+          ) {
+            throw new Error("wrong proof session");
+          }
+        }
+        export function getToolcraftBrowserActionTarget(action) {
+          return action.target;
+        }
+        export async function readToolcraftBrowserObservation(observation) {
+          return observation.read();
+        }
+        export async function runToolcraftBrowserAction(action) {
+          globalThis.__toolcraftStateEvidenceTrace.push("action:" + action.kind);
+          await action.run();
+        }
+      `,
+    ),
+    fs.writeFile(
+      path.join(outputDir, "transition.mjs"),
+      `
+        export function createToolcraftSemanticTransitionOptions(message, options) {
+          return { message, ...options };
+        }
+        export async function expectToolcraftExpectedOutcomeAfterAction() {
+          throw new Error("unexpected generic transition");
+        }
+      `,
+    ),
+    fs.writeFile(
+      path.join(outputDir, "stable-outcome.mjs"),
+      `
+        import assert from "node:assert/strict";
+        export async function expectToolcraftPersistentExpectedOutcome(
+          observe,
+          expected,
+        ) {
+          const actual = structuredClone(await observe());
+          globalThis.__toolcraftStateEvidenceAssertionCount += 1;
+          globalThis.__toolcraftStateEvidenceTrace.push(
+            "assert:state:" + globalThis.__toolcraftStateEvidenceAssertionCount,
+          );
+          assert.deepEqual(actual, expected);
+          return actual;
+        }
+        export function snapshotToolcraftOutcome(value) {
+          return structuredClone(value);
+        }
+      `,
+    ),
+  ]);
+
+  return import(`${pathToFileURL(outputPath).href}?test=${Date.now()}`);
+}
+
+function createPersistenceScenario({ restoredState = "persisted" } = {}) {
+  const session = {};
+  let state = "initial";
+  const observation = {
+    read: async () => ({ state }),
+    session,
+  };
+  const mutate = {
+    kind: "mutate",
+    run: async () => {
+      state = "persisted";
+    },
+    session,
+    target: "workspace.persistence",
+  };
+  const reload = {
+    kind: "reload",
+    run: async () => {
+      state = restoredState;
+    },
+    session,
+  };
+  return { mutate, observation, reload };
+}
+
+function resetHarness() {
+  globalThis.__toolcraftStateEvidenceAssertionCount = 0;
+  globalThis.__toolcraftStateEvidenceAttachments = [];
+  globalThis.__toolcraftStateEvidenceTrace = [];
+}
+
+test("persistence recipe asserts restored output before attaching evidence", async (context) => {
+  const facade = await loadStateEvidenceFacade(context);
+  resetHarness();
+  const scenario = createPersistenceScenario();
+
+  await facade.expectToolcraftPersistenceState(
+    scenario.observation,
+    scenario.mutate,
+    scenario.reload,
+    { state: "persisted" },
+    {
+      assertRestoredOutput: async () => {
+        globalThis.__toolcraftStateEvidenceTrace.push("assert:output");
+      },
+      requirementId: "workspace.persistence",
+    },
+  );
+
+  assert.deepEqual(globalThis.__toolcraftStateEvidenceTrace, [
+    "action:mutate",
+    "assert:state:1",
+    "action:reload",
+    "assert:state:2",
+    "assert:output",
+    "evidence",
+  ]);
+  assert.deepEqual(globalThis.__toolcraftStateEvidenceAttachments, [
+    {
+      evidenceType: "persistence-state",
+      requirementId: "workspace.persistence",
+      target: "workspace.persistence",
+    },
+  ]);
+});
+
+test("persistence recipe emits no evidence when restored output assertion fails", async (context) => {
+  const facade = await loadStateEvidenceFacade(context);
+  resetHarness();
+  const scenario = createPersistenceScenario();
+
+  await assert.rejects(
+    facade.expectToolcraftPersistenceState(
+      scenario.observation,
+      scenario.mutate,
+      scenario.reload,
+      { state: "persisted" },
+      {
+        assertRestoredOutput: async () => {
+          globalThis.__toolcraftStateEvidenceTrace.push("assert:output");
+          throw new Error("restored pixels differ");
+        },
+        requirementId: "workspace.persistence",
+      },
+    ),
+    /restored pixels differ/u,
+  );
+  assert.deepEqual(globalThis.__toolcraftStateEvidenceAttachments, []);
+  assert.equal(globalThis.__toolcraftStateEvidenceTrace.at(-1), "assert:output");
+});
+
+test("persistence recipe keeps existing state-only callers compatible and emits no evidence on state failure", async (context) => {
+  const facade = await loadStateEvidenceFacade(context);
+  resetHarness();
+  const valid = createPersistenceScenario();
+
+  await facade.expectToolcraftPersistenceState(
+    valid.observation,
+    valid.mutate,
+    valid.reload,
+    { state: "persisted" },
+    { requirementId: "workspace.persistence" },
+  );
+  assert.equal(globalThis.__toolcraftStateEvidenceTrace.at(-1), "evidence");
+
+  resetHarness();
+  const invalid = createPersistenceScenario({ restoredState: "lost" });
+  await assert.rejects(
+    facade.expectToolcraftPersistenceState(
+      invalid.observation,
+      invalid.mutate,
+      invalid.reload,
+      { state: "persisted" },
+      { requirementId: "workspace.persistence" },
+    ),
+  );
+  assert.deepEqual(globalThis.__toolcraftStateEvidenceAttachments, []);
+});

package/templates/starter/scripts/toolcraft-state-evidence-reporter.test.mjs

@@ -0,0 +1,78 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { pathToFileURL } from "node:url";
+
+import ts from "typescript";
+
+const contractPath = path.resolve(
+  import.meta.dirname,
+  "../src/app/test-evidence/browser-runtime-contract.ts",
+);
+
+async function loadRuntimeEvidenceContract(context) {
+  const outputDir = await fs.mkdtemp(
+    path.join(os.tmpdir(), "toolcraft-state-reporter-"),
+  );
+  context.after(() => fs.rm(outputDir, { force: true, recursive: true }));
+  const outputPath = path.join(outputDir, "browser-runtime-contract.mjs");
+  const { outputText } = ts.transpileModule(
+    await fs.readFile(contractPath, "utf8"),
+    {
+      compilerOptions: {
+        module: ts.ModuleKind.ESNext,
+        target: ts.ScriptTarget.ES2022,
+      },
+      fileName: contractPath,
+    },
+  );
+  await fs.writeFile(outputPath, outputText);
+  return import(`${pathToFileURL(outputPath).href}?test=${Date.now()}`);
+}
+
+function evaluate(contract, includeEvidence) {
+  const testName = "browser: restores workspace";
+  const attachments = includeEvidence
+    ? [
+        {
+          body: contract.serializeToolcraftBrowserRuntimeEvidence({
+            evidenceType: "persistence-state",
+            requirementId: "workspace.persistence",
+            target: "workspace.persistence",
+          }),
+          contentType:
+            contract.TOOLCRAFT_BROWSER_RUNTIME_EVIDENCE_CONTENT_TYPE,
+          name: contract.TOOLCRAFT_BROWSER_RUNTIME_EVIDENCE_ATTACHMENT_NAME,
+        },
+      ]
+    : [];
+
+  return contract.evaluateToolcraftBrowserRuntimeEvidence({
+    requirements: [
+      {
+        evidenceType: "persistence-state",
+        requirementId: "workspace.persistence",
+        target: "workspace.persistence",
+        testName,
+      },
+    ],
+    tests: [
+      {
+        expectedStatus: "passed",
+        results: [{ attachments, retry: 0, status: "passed" }],
+        title: testName,
+      },
+    ],
+  });
+}
+
+test("runtime reporter accepts persistence evidence only when it was attached", async (context) => {
+  const contract = await loadRuntimeEvidenceContract(context);
+
+  assert.deepEqual(evaluate(contract, true), []);
+  const errors = evaluate(contract, false);
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /type "persistence-state"/u);
+});

package/templates/starter/scripts/toolcraft-static-string.mjs

@@ -1,5 +1,34 @@
 import ts from "typescript";
 
+import { createToolcraftTypeScriptChecker } from "./toolcraft-typescript-analysis.mjs";
+
+const mutatingArrayMethods = new Set([
+  "copyWithin",
+  "fill",
+  "pop",
+  "push",
+  "reverse",
+  "shift",
+  "sort",
+  "splice",
+  "unshift",
+]);
+const readOnlyArrayMethods = new Set([
+  "at",
+  "entries",
+  "includes",
+  "indexOf",
+  "join",
+  "keys",
+  "lastIndexOf",
+  "slice",
+  "toReversed",
+  "toSpliced",
+  "toString",
+  "values",
+  "with",
+]);
+
 function isConstVariableDeclaration(node) {
   return (
     ts.isVariableDeclaration(node) &&
@@ -10,33 +39,212 @@ function isConstVariableDeclaration(node) {
   );
 }
 
-function createTypeChecker(sourceFile) {
-  const compilerOptions = {
-    allowJs: true,
-    noLib: true,
-    noResolve: true,
-    target: ts.ScriptTarget.Latest,
-  };
-  const defaultHost = ts.createCompilerHost(compilerOptions);
-  const host = {
-    ...defaultHost,
-    fileExists: (fileName) => fileName === sourceFile.fileName,
-    getSourceFile: (fileName) =>
-      fileName === sourceFile.fileName ? sourceFile : undefined,
-    readFile: (fileName) =>
-      fileName === sourceFile.fileName ? sourceFile.text : undefined,
-    writeFile: () => undefined,
-  };
-
-  return ts
-    .createProgram([sourceFile.fileName], compilerOptions, host)
-    .getTypeChecker();
-}
+export function createToolcraftStaticStringResolver(
+  sourceFile,
+  checker = createToolcraftTypeScriptChecker(sourceFile, ts),
+) {
+
+  function isTransparentExpression(node) {
+    return (
+      ts.isParenthesizedExpression(node) ||
+      ts.isAsExpression(node) ||
+      ts.isTypeAssertionExpression(node) ||
+      ts.isSatisfiesExpression(node) ||
+      ts.isNonNullExpression(node)
+    );
+  }
+
+  function unwrapStaticExpression(node) {
+    let current = node;
+    while (isTransparentExpression(current)) {
+      current = current.expression;
+    }
+    return current;
+  }
+
+  function getConstDeclaration(node) {
+    return checker
+      .getSymbolAtLocation(node)
+      ?.declarations?.find(isConstVariableDeclaration);
+  }
+
+  function getReferenceSymbol(node) {
+    return ts.isShorthandPropertyAssignment(node.parent)
+      ? checker.getShorthandAssignmentValueSymbol(node.parent)
+      : checker.getSymbolAtLocation(node);
+  }
+
+  function getStaticMemberAccess(node) {
+    const value = unwrapStaticExpression(node);
+    if (ts.isPropertyAccessExpression(value)) {
+      return { member: value.name.text, node: value };
+    }
+    if (!ts.isElementAccessExpression(value) || !value.argumentExpression) {
+      return undefined;
+    }
+    const argument = unwrapStaticExpression(value.argumentExpression);
+    return ts.isStringLiteralLike(argument) ||
+      ts.isNoSubstitutionTemplateLiteral(argument)
+      ? { member: argument.text, node: value }
+      : undefined;
+  }
+
+  function isAssignmentOperator(kind) {
+    return (
+      kind >= ts.SyntaxKind.FirstAssignment &&
+      kind <= ts.SyntaxKind.LastAssignment
+    );
+  }
+
+  function isUnsafeArrayReference(reference) {
+    let usage = reference;
+    while (
+      usage.parent &&
+      isTransparentExpression(usage.parent) &&
+      usage.parent.expression === usage
+    ) {
+      usage = usage.parent;
+    }
+    const member = unwrapStaticExpression(usage.parent);
+    if (
+      (ts.isPropertyAccessExpression(member) ||
+        ts.isElementAccessExpression(member)) &&
+      member.expression === usage
+    ) {
+      const memberAccess = getStaticMemberAccess(member);
+      const parent = member.parent;
+      if (
+        ts.isCallExpression(parent) &&
+        parent.expression === member
+      ) {
+        return (
+          !memberAccess ||
+          mutatingArrayMethods.has(memberAccess.member) ||
+          !readOnlyArrayMethods.has(memberAccess.member)
+        );
+      }
+      return (
+        (ts.isBinaryExpression(parent) &&
+          parent.left === member &&
+          isAssignmentOperator(parent.operatorToken.kind)) ||
+        ((ts.isPrefixUnaryExpression(parent) ||
+          ts.isPostfixUnaryExpression(parent)) &&
+          parent.operand === member) ||
+        (ts.isDeleteExpression(parent) && parent.expression === member)
+      );
+    }
+    const parent = usage.parent;
+    if (!parent) return true;
+    if (
+      (ts.isVoidExpression(parent) ||
+        ts.isTypeOfExpression(parent)) &&
+      parent.expression === usage
+    ) {
+      return false;
+    }
+    if (
+      ts.isExpressionStatement(parent) &&
+      parent.expression === usage
+    ) {
+      return false;
+    }
+    if (
+      ts.isBinaryExpression(parent) &&
+      isAssignmentOperator(parent.operatorToken.kind) &&
+      (parent.left === usage || parent.right === usage)
+    ) {
+      return true;
+    }
+    if (
+      ((ts.isPrefixUnaryExpression(parent) ||
+        ts.isPostfixUnaryExpression(parent)) &&
+        parent.operand === usage) ||
+      (ts.isDeleteExpression(parent) && parent.expression === usage)
+    ) {
+      return true;
+    }
+    return true;
+  }
 
-export function createToolcraftStaticStringResolver(sourceFile) {
-  const checker = createTypeChecker(sourceFile);
+  function isArrayBindingSafeAt(declaration, evaluationNode) {
+    const symbol = checker.getSymbolAtLocation(declaration.name);
+    if (!symbol) return false;
+    let safe = true;
+    const evaluationOffset = evaluationNode.getStart(sourceFile);
+    function visit(node) {
+      if (!safe || node.getStart(sourceFile) >= evaluationOffset) return;
+      if (
+        ts.isIdentifier(node) &&
+        node !== declaration.name &&
+        getReferenceSymbol(node) === symbol
+      ) {
+        safe = !isUnsafeArrayReference(node);
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return safe;
+  }
+
+  function resolveArray(node, resolvingDeclarations, evaluationNode) {
+    const value = unwrapStaticExpression(node);
+    if (ts.isArrayLiteralExpression(value)) {
+      if (value.elements.some((element) => ts.isSpreadElement(element))) {
+        return undefined;
+      }
+      const elements = value.elements.map((element) =>
+        resolve(element, resolvingDeclarations),
+      );
+      return elements.some((element) => element === undefined)
+        ? undefined
+        : elements;
+    }
+    if (!ts.isIdentifier(value)) return undefined;
+    const declaration = getConstDeclaration(value);
+    if (
+      !declaration ||
+      resolvingDeclarations.has(declaration) ||
+      !isArrayBindingSafeAt(declaration, evaluationNode)
+    ) {
+      return undefined;
+    }
+    resolvingDeclarations.add(declaration);
+    const elements = resolveArray(
+      declaration.initializer,
+      resolvingDeclarations,
+      evaluationNode,
+    );
+    resolvingDeclarations.delete(declaration);
+    return elements;
+  }
+
+  function resolveConstantJoin(node, resolvingDeclarations) {
+    const memberAccess = ts.isCallExpression(node)
+      ? getStaticMemberAccess(node.expression)
+      : undefined;
+    if (
+      !ts.isCallExpression(node) ||
+      node.arguments.length > 1 ||
+      memberAccess?.member !== "join"
+    ) {
+      return undefined;
+    }
+    const values = resolveArray(
+      memberAccess.node.expression,
+      resolvingDeclarations,
+      node,
+    );
+    if (!values) return undefined;
+    const delimiter = node.arguments.length === 0
+      ? ","
+      : resolve(node.arguments[0], resolvingDeclarations);
+    if (delimiter === undefined) return undefined;
+    return values.join(delimiter);
+  }
 
   function resolve(node, resolvingDeclarations = new Set()) {
+    const value = unwrapStaticExpression(node);
+    if (value !== node) return resolve(value, resolvingDeclarations);
     if (ts.isStringLiteralLike(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
       return node.text;
     }
@@ -65,9 +273,7 @@ export function createToolcraftStaticStringResolver(sourceFile) {
     }
 
     if (ts.isIdentifier(node)) {
-      const declaration = checker
-        .getSymbolAtLocation(node)
-        ?.declarations?.find(isConstVariableDeclaration);
+      const declaration = getConstDeclaration(node);
       if (!declaration || resolvingDeclarations.has(declaration)) return undefined;
       resolvingDeclarations.add(declaration);
       const value = resolve(declaration.initializer, resolvingDeclarations);
@@ -75,7 +281,7 @@ export function createToolcraftStaticStringResolver(sourceFile) {
       return value;
     }
 
-    return undefined;
+    return resolveConstantJoin(node, resolvingDeclarations);
   }
 
   return resolve;