@pixel-point/toolcraft 0.0.14 → 0.0.15

package/templates/starter/scripts/toolcraft-source-ownership.mjs

@@ -0,0 +1,167 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const toolcraftFrameworkOwnedSourceRoots = Object.freeze([
+  "docs/toolcraft",
+  "scripts",
+  "src/app",
+  "e2e",
+]);
+
+export const toolcraftFrameworkOwnedRootFiles = Object.freeze([
+  "AGENTS.md",
+  "LICENSE.md",
+  "NOTICE.md",
+  "index.html",
+  "playwright.config.ts",
+  "src/main.tsx",
+  "src/router.tsx",
+  "src/routes/index.tsx",
+  "src/routes/root.tsx",
+  "src/styles.css",
+  "tsconfig.json",
+  "vite.config.ts",
+]);
+
+export const toolcraftProductOwnedGeneratedPaths = Object.freeze([
+  "docs/toolcraft/agent-worklog.md",
+  "e2e/app-controls.spec.ts",
+  "src/app/app-acceptance-data.ts",
+  "src/app/app-composition.tsx",
+  "src/app/app-performance.ts",
+  "src/app/app-schema.test.ts",
+  "src/app/app-schema.ts",
+]);
+
+const productOwnedGeneratedPathSet = new Set(
+  toolcraftProductOwnedGeneratedPaths,
+);
+
+function compareCodeUnits(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function toPosixPath(value) {
+  return String(value).split(path.sep).join("/").replace(/^\.\//u, "");
+}
+
+export function toToolcraftGeneratedPath(relativePath) {
+  const normalizedPath = toPosixPath(relativePath);
+
+  return normalizedPath.startsWith("src/app/starter-")
+    ? normalizedPath.replace(/^src\/app\/starter-/u, "src/app/app-")
+    : normalizedPath;
+}
+
+export function isToolcraftFrameworkOwnedPath(relativePath) {
+  const generatedPath = toToolcraftGeneratedPath(relativePath);
+  const isFrameworkCandidate =
+    toolcraftFrameworkOwnedSourceRoots.some(
+      (root) =>
+        generatedPath === root || generatedPath.startsWith(`${root}/`),
+    ) || toolcraftFrameworkOwnedRootFiles.includes(generatedPath);
+
+  return (
+    isFrameworkCandidate && !productOwnedGeneratedPathSet.has(generatedPath)
+  );
+}
+
+async function collectRelativeFiles(rootDir, relativeRoot) {
+  const directory = path.join(rootDir, ...relativeRoot.split("/"));
+  let entries;
+
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+
+  const files = [];
+
+  for (const entry of entries) {
+    const relativePath = path.posix.join(relativeRoot, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...(await collectRelativeFiles(rootDir, relativePath)));
+    } else if (
+      entry.isFile() &&
+      entry.name !== ".toolcraft-manifest.json"
+    ) {
+      files.push(relativePath);
+    }
+  }
+
+  return files;
+}
+
+async function collectOwnershipCandidates(rootDir) {
+  const rootedFiles = (
+    await Promise.all(
+      toolcraftFrameworkOwnedSourceRoots.map((relativeRoot) =>
+        collectRelativeFiles(rootDir, relativeRoot),
+      ),
+    )
+  ).flat();
+  const existingRootFiles = [];
+
+  for (const relativePath of toolcraftFrameworkOwnedRootFiles) {
+    try {
+      const stat = await fs.stat(
+        path.join(rootDir, ...relativePath.split("/")),
+      );
+      if (stat.isFile()) existingRootFiles.push(relativePath);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+  }
+
+  return [...new Set([...existingRootFiles, ...rootedFiles])].sort(
+    compareCodeUnits,
+  );
+}
+
+export async function collectToolcraftFrameworkOwnedLocalPaths(rootDir) {
+  const manifestPath = path.join(
+    rootDir,
+    "src/toolcraft/.toolcraft-manifest.json",
+  );
+
+  try {
+    const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    return Object.keys(manifest.protectedFiles ?? {}).sort(compareCodeUnits);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+
+  const localPolicyPath = path.join(
+    rootDir,
+    "scripts/toolcraft-source-ownership.mjs",
+  );
+  let ownsPolicyRoot = false;
+
+  try {
+    ownsPolicyRoot =
+      (await fs.realpath(localPolicyPath)) ===
+      (await fs.realpath(fileURLToPath(import.meta.url)));
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+
+  if (!ownsPolicyRoot) return [];
+
+  return (await collectOwnershipCandidates(rootDir))
+    .filter(isToolcraftFrameworkOwnedPath)
+    .sort(compareCodeUnits);
+}
+
+export async function collectToolcraftFrameworkOwnedGeneratedPaths(rootDir) {
+  return [
+    ...new Set(
+      (await collectToolcraftFrameworkOwnedLocalPaths(rootDir)).map(
+        toToolcraftGeneratedPath,
+      ),
+    ),
+  ].sort(compareCodeUnits);
+}

package/templates/starter/scripts/toolcraft-source-ownership.test.mjs

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+import {
+  collectToolcraftFrameworkOwnedGeneratedPaths,
+  collectToolcraftFrameworkOwnedLocalPaths,
+  isToolcraftFrameworkOwnedPath,
+  toToolcraftGeneratedPath,
+  toolcraftFrameworkOwnedRootFiles,
+  toolcraftProductOwnedGeneratedPaths,
+} from "./toolcraft-source-ownership.mjs";
+import { requiredProtectedTrustRootFilePaths } from "./toolcraft-integrity-policy.mjs";
+
+const starterRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+
+test("maps starter facade names to generated paths", () => {
+  assert.equal(
+    toToolcraftGeneratedPath("src/app/starter-composition.tsx"),
+    "src/app/app-composition.tsx",
+  );
+  assert.equal(
+    toToolcraftGeneratedPath("src/app/acceptance/validation-pipeline.ts"),
+    "src/app/acceptance/validation-pipeline.ts",
+  );
+});
+
+test("classifies framework infrastructure and product extension points", () => {
+  assert.equal(
+    isToolcraftFrameworkOwnedPath("src/app/acceptance/actions.ts"),
+    true,
+  );
+  assert.equal(
+    isToolcraftFrameworkOwnedPath("src/app/starter-composition.tsx"),
+    false,
+  );
+  assert.equal(
+    isToolcraftFrameworkOwnedPath("src/app/app-composition.tsx"),
+    false,
+  );
+  assert.equal(isToolcraftFrameworkOwnedPath("src/features/product.ts"), false);
+});
+
+test("collects the same ownership policy for starter-local and generated paths", async () => {
+  const localPaths = await collectToolcraftFrameworkOwnedLocalPaths(starterRoot);
+  const generatedPaths =
+    await collectToolcraftFrameworkOwnedGeneratedPaths(starterRoot);
+
+  assert.deepEqual(
+    generatedPaths,
+    [...new Set(localPaths.map(toToolcraftGeneratedPath))].sort(),
+  );
+  assert.ok(localPaths.includes("src/app/acceptance/actions.ts"));
+  assert.equal(
+    localPaths.filter(
+      (relativePath) =>
+        toToolcraftGeneratedPath(relativePath) ===
+        "src/app/app-automated-runtime-evidence.test.ts",
+    ).length,
+    1,
+  );
+  assert.ok(!localPaths.includes("src/app/starter-composition.tsx"));
+
+  for (const relativePath of toolcraftFrameworkOwnedRootFiles) {
+    assert.ok(localPaths.includes(relativePath));
+  }
+  for (const relativePath of toolcraftProductOwnedGeneratedPaths) {
+    assert.ok(!generatedPaths.includes(relativePath));
+  }
+});
+
+test("keeps the signed-manifest trust root small and inside canonical ownership", async () => {
+  const generatedPaths =
+    await collectToolcraftFrameworkOwnedGeneratedPaths(starterRoot);
+  const generatedPathSet = new Set(generatedPaths);
+
+  assert.ok(requiredProtectedTrustRootFilePaths.length > 0);
+  assert.ok(
+    requiredProtectedTrustRootFilePaths.length <= 24,
+    `The trust root must stay small; received ${requiredProtectedTrustRootFilePaths.length} paths.`,
+  );
+  assert.equal(
+    new Set(requiredProtectedTrustRootFilePaths).size,
+    requiredProtectedTrustRootFilePaths.length,
+  );
+  for (const relativePath of requiredProtectedTrustRootFilePaths) {
+    assert.ok(
+      generatedPathSet.has(relativePath),
+      `Trust-root path must be framework-owned: ${relativePath}`,
+    );
+  }
+
+  const subsystemSentinels = [
+    "AGENTS.md",
+    "e2e/browser-runtime-evidence-reporter.ts",
+    "scripts/check-toolcraft-integrity.mjs",
+    "scripts/toolcraft-integrity-policy.mjs",
+    "scripts/toolcraft-source-ownership.mjs",
+    "scripts/toolcraft-vitest-runtime-evidence-reporter.mjs",
+    "scripts/toolcraft-workflow-routes.mjs",
+    "src/app/app-automated-runtime-evidence.test.ts",
+  ];
+  for (const relativePath of subsystemSentinels) {
+    assert.ok(
+      requiredProtectedTrustRootFilePaths.includes(relativePath),
+      `Trust root must retain the ${relativePath} sentinel.`,
+    );
+  }
+});

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

@@ -0,0 +1,104 @@
+import ts from "typescript";
+
+function isConstVariableDeclaration(node) {
+  return (
+    ts.isVariableDeclaration(node) &&
+    ts.isVariableDeclarationList(node.parent) &&
+    (node.parent.flags & ts.NodeFlags.Const) !== 0 &&
+    ts.isIdentifier(node.name) &&
+    node.initializer
+  );
+}
+
+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) {
+  const checker = createTypeChecker(sourceFile);
+
+  function resolve(node, resolvingDeclarations = new Set()) {
+    if (ts.isStringLiteralLike(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+      return node.text;
+    }
+
+    if (ts.isParenthesizedExpression(node)) {
+      return resolve(node.expression, resolvingDeclarations);
+    }
+
+    if (
+      ts.isBinaryExpression(node) &&
+      node.operatorToken.kind === ts.SyntaxKind.PlusToken
+    ) {
+      const left = resolve(node.left, resolvingDeclarations);
+      const right = resolve(node.right, resolvingDeclarations);
+      return left === undefined || right === undefined ? undefined : left + right;
+    }
+
+    if (ts.isTemplateExpression(node)) {
+      let value = node.head.text;
+      for (const span of node.templateSpans) {
+        const expressionValue = resolve(span.expression, resolvingDeclarations);
+        if (expressionValue === undefined) return undefined;
+        value += expressionValue + span.literal.text;
+      }
+      return value;
+    }
+
+    if (ts.isIdentifier(node)) {
+      const declaration = checker
+        .getSymbolAtLocation(node)
+        ?.declarations?.find(isConstVariableDeclaration);
+      if (!declaration || resolvingDeclarations.has(declaration)) return undefined;
+      resolvingDeclarations.add(declaration);
+      const value = resolve(declaration.initializer, resolvingDeclarations);
+      resolvingDeclarations.delete(declaration);
+      return value;
+    }
+
+    return undefined;
+  }
+
+  return resolve;
+}
+
+export function isToolcraftStringCompositionNode(node) {
+  return (
+    ts.isStringLiteralLike(node) ||
+    ts.isNoSubstitutionTemplateLiteral(node) ||
+    ts.isTemplateExpression(node) ||
+    ts.isParenthesizedExpression(node) ||
+    (ts.isBinaryExpression(node) &&
+      node.operatorToken.kind === ts.SyntaxKind.PlusToken)
+  );
+}
+
+export function isNestedToolcraftStringComposition(node) {
+  const parent = node.parent;
+  return Boolean(
+    parent &&
+      (ts.isParenthesizedExpression(parent) ||
+        ts.isTemplateSpan(parent) ||
+        (ts.isBinaryExpression(parent) &&
+          parent.operatorToken.kind === ts.SyntaxKind.PlusToken)),
+  );
+}

package/templates/starter/scripts/toolcraft-verification-inventory.mjs

@@ -0,0 +1,123 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const verificationRoots = ["e2e", "public", "scripts", "src"];
+const verificationRootFiles = [
+  "index.html",
+  "npm-shrinkwrap.json",
+  "package-lock.json",
+  "package.json",
+  "playwright.config.ts",
+  "pnpm-lock.yaml",
+  "tsconfig.json",
+  "vite.config.ts",
+];
+const ignoredDirectoryNames = new Set([
+  ".git",
+  ".toolcraft",
+  ".vite",
+  "coverage",
+  "dist",
+  "node_modules",
+  "playwright-report",
+  "test-results",
+]);
+
+function compareCodeUnits(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function toPosixPath(value) {
+  return value.split(path.sep).join("/");
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+export function createToolcraftVerificationSourceHash(entries) {
+  return sha256(
+    [...entries]
+      .sort((left, right) => compareCodeUnits(left.path, right.path))
+      .map((entry) => `${entry.path}\0${entry.sha256}\n`)
+      .join(""),
+  );
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function collectFiles(directory, rootDir, files) {
+  const entries = await fs.readdir(directory, { withFileTypes: true });
+  entries.sort((left, right) => compareCodeUnits(left.name, right.name));
+
+  for (const entry of entries) {
+    if (ignoredDirectoryNames.has(entry.name)) continue;
+    const absolutePath = path.join(directory, entry.name);
+    if (entry.isSymbolicLink()) {
+      throw new Error(
+        `Toolcraft verification inputs must not contain symbolic links: ${toPosixPath(path.relative(rootDir, absolutePath))}.`,
+      );
+    }
+    if (entry.isDirectory()) {
+      await collectFiles(absolutePath, rootDir, files);
+      continue;
+    }
+    if (entry.isFile()) files.push(absolutePath);
+  }
+}
+
+export async function collectToolcraftVerificationInputs(rootDir) {
+  const resolvedRoot = path.resolve(rootDir);
+  const files = [];
+
+  for (const rootName of verificationRoots) {
+    const absoluteRoot = path.join(resolvedRoot, rootName);
+    if (await pathExists(absoluteRoot)) {
+      await collectFiles(absoluteRoot, resolvedRoot, files);
+    }
+  }
+  for (const fileName of verificationRootFiles) {
+    const absolutePath = path.join(resolvedRoot, fileName);
+    if (await pathExists(absolutePath)) files.push(absolutePath);
+  }
+
+  const uniqueFiles = [...new Set(files)].sort((left, right) =>
+    compareCodeUnits(
+      toPosixPath(path.relative(resolvedRoot, left)),
+      toPosixPath(path.relative(resolvedRoot, right)),
+    ),
+  );
+  const entries = [];
+  for (const absolutePath of uniqueFiles) {
+    entries.push({
+      path: toPosixPath(path.relative(resolvedRoot, absolutePath)),
+      sha256: sha256(await fs.readFile(absolutePath)),
+    });
+  }
+
+  return {
+    entries,
+    sourceHash: createToolcraftVerificationSourceHash(entries),
+  };
+}
+
+export function assertToolcraftVerificationInputsUnchanged({
+  baseline,
+  current,
+  phase,
+}) {
+  if (baseline.sourceHash !== current.sourceHash) {
+    throw new Error(
+      `Toolcraft verification inputs changed ${phase}. Rerun pnpm verify:perf after edits stop.`,
+    );
+  }
+}

package/templates/starter/scripts/toolcraft-verification-receipt.d.mts

@@ -0,0 +1,19 @@
+export function validateToolcraftPerformanceReceipt(options: {
+  rootDir: string;
+}): Promise<string[]>;
+
+export function assertToolcraftVerificationInputsUnchanged(options: {
+  baseline: { sourceHash: string };
+  current: { sourceHash: string };
+  phase: string;
+}): void;
+
+export function getToolcraftPerformanceExemptionBlockedFiles(
+  changedFiles: readonly string[],
+): string[];
+
+export function writeToolcraftPerformanceExemption(options: {
+  reasonCode: "post-first-working-non-performance";
+  rootDir: string;
+  verificationTier: 0 | 1 | 2;
+}): Promise<unknown>;