@pixel-point/toolcraft 0.0.14 → 0.0.15

package/templates/starter/scripts/check-ai-skills.test.mjs

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const scriptPath = fileURLToPath(new URL("./check-ai-skills.mjs", import.meta.url));
+const skillNames = [
+  "brainstorming",
+  "writing-plans",
+  "systematic-debugging",
+  "figma",
+  "figma-implement-design",
+  "browser",
+];
+
+async function withCleanHome(callback) {
+  const home = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-skills-"));
+  const env = {
+    ...process.env,
+    CLAUDE_HOME: path.join(home, ".claude"),
+    CODEX_HOME: path.join(home, ".codex"),
+    HOME: home,
+    XDG_CONFIG_HOME: path.join(home, ".config"),
+  };
+
+  try {
+    await callback({ env, home });
+  } finally {
+    await fs.rm(home, { force: true, recursive: true });
+  }
+}
+
+test("missing external skills use the signed local contract fallback", async () => {
+  await withCleanHome(async ({ env }) => {
+    const result = await execFileAsync(process.execPath, [scriptPath], { env });
+
+    assert.match(result.stderr, /Optional AI workflow skills are not installed/);
+    assert.match(result.stderr, /Signed local AGENTS\.md and docs\/toolcraft/);
+    assert.match(result.stderr, /continue with the local Toolcraft workflow/i);
+  });
+});
+
+test("installed external skills are still discovered and reported", async () => {
+  await withCleanHome(async ({ env, home }) => {
+    for (const skillName of skillNames) {
+      const skillPath = path.join(home, ".codex", "skills", skillName, "SKILL.md");
+      await fs.mkdir(path.dirname(skillPath), { recursive: true });
+      await fs.writeFile(skillPath, `# ${skillName}\n`);
+    }
+
+    const result = await execFileAsync(process.execPath, [scriptPath], { env });
+
+    assert.match(result.stdout, /AI workflow skills are installed/);
+    for (const skillName of skillNames) {
+      assert.match(result.stdout, new RegExp(`- ${skillName}:`));
+    }
+    assert.equal(result.stderr, "");
+  });
+});

package/templates/starter/scripts/check-toolcraft-code-health.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  codeHealthPassed,
+  evaluateCodeHealth,
+  printCodeHealthResult,
+} from "./toolcraft-code-health-core.mjs";
+import { loadToolcraftLocalModuleAliases } from "./toolcraft-product-dependency-graph.mjs";
+import { collectToolcraftFrameworkOwnedLocalPaths } from "./toolcraft-source-ownership.mjs";
+
+const scriptPath = fileURLToPath(import.meta.url);
+const appRoot = path.resolve(path.dirname(scriptPath), "..");
+
+const generatedCodeHealthPolicy = {
+  globalLineBudget: {
+    maxLines: 1000,
+    reason: "Generated product source must not become a giant mixed-responsibility module.",
+  },
+  ignoredFilePatterns: [
+    /^src\/toolcraft(?:\/|$)/u,
+    /\/route-tree\.gen\.ts$/u,
+  ],
+  scopedLineBudgets: [
+    {
+      maxLines: 700,
+      prefix: "src/app/",
+      reason:
+        "Generated app modules should split schema, renderer, exports, and product behavior before they become one policy dump.",
+    },
+    {
+      maxLines: 400,
+      prefix: "src/routes/",
+      reason: "Generated routes should remain thin Toolcraft composition boundaries.",
+    },
+    {
+      maxLines: 700,
+      prefix: "src/",
+      reason:
+        "Generated product modules should split rendering, state, and behavior before they become mixed-responsibility files.",
+    },
+    {
+      maxLines: 500,
+      prefix: "e2e/",
+      reason: "Generated browser tests should stay split by behavior and evidence role.",
+    },
+    {
+      maxLines: 350,
+      prefix: "scripts/",
+      reason: "Generated operational scripts should stay focused and independently testable.",
+    },
+  ],
+  sourceRoots: ["src", "e2e", "scripts"],
+  testLineBudget: {
+    maxLines: 500,
+    reason: "Generated test/spec files should stay focused instead of becoming behavior dumps.",
+  },
+};
+
+export async function evaluateGeneratedCodeHealth(rootDir = appRoot) {
+  const [dependencyCycleAliases, frameworkOwnedLocalPaths] = await Promise.all([
+    loadToolcraftLocalModuleAliases({
+      rootDir,
+      tsconfigPaths: ["tsconfig.json"],
+    }),
+    collectToolcraftFrameworkOwnedLocalPaths(rootDir),
+  ]);
+  return evaluateCodeHealth({
+    ...generatedCodeHealthPolicy,
+    dependencyCycleAliases,
+    dependencyCycleIncludedFilePatterns: [/^src\//u],
+    frameworkPathPrefixes: ["src/toolcraft/"],
+    protectedFilePaths: frameworkOwnedLocalPaths,
+    rootDir,
+  });
+}
+
+export async function runGeneratedCodeHealth({
+  logger = console,
+  rootDir = appRoot,
+} = {}) {
+  const result = await evaluateGeneratedCodeHealth(rootDir);
+
+  printCodeHealthResult(result, logger);
+  if (!codeHealthPassed(result)) {
+    logger.error(
+      "\nToolcraft code health check failed. Split the file, move logic behind a focused product boundary, or make the typed contract explicit.",
+    );
+    return false;
+  }
+
+  logger.log(`Toolcraft code health check passed (${result.sourceFileCount} files).`);
+  return true;
+}
+
+const isDirectExecution =
+  process.argv[1] &&
+  fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(scriptPath);
+
+if (isDirectExecution) {
+  const passed = await runGeneratedCodeHealth();
+  if (!passed) {
+    process.exitCode = 1;
+  }
+}

package/templates/starter/scripts/check-toolcraft-code-health.test.mjs

@@ -0,0 +1,213 @@
+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 { evaluateGeneratedCodeHealth } from "./check-toolcraft-code-health.mjs";
+import {
+  codeHealthPassed,
+  getLineBudgetViolations,
+} from "./toolcraft-code-health-core.mjs";
+
+async function withFixture(files, assertion, prepare = async () => undefined) {
+  const fixtureRoot = await fs.mkdtemp(
+    path.join(os.tmpdir(), "toolcraft-code-health-"),
+  );
+
+  try {
+    for (const [relativePath, source] of Object.entries(files)) {
+      const filePath = path.join(fixtureRoot, relativePath);
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await fs.writeFile(filePath, source);
+    }
+
+    await prepare(fixtureRoot);
+    await assertion(await evaluateGeneratedCodeHealth(fixtureRoot));
+  } finally {
+    await fs.rm(fixtureRoot, { force: true, recursive: true });
+  }
+}
+
+test("generated code health rejects oversized product source", async () => {
+  await withFixture(
+    { "src/app/app-schema.ts": "export const value = 1;\n".repeat(1001) },
+    (result) => {
+      assert.equal(result.lineBudgetViolations.length > 0, true);
+      assert.match(result.lineBudgetViolations[0].repoPath, /app-schema\.ts$/);
+    },
+  );
+});
+
+test("generated code health applies the product budget outside src/app", async () => {
+  await withFixture(
+    { "src/features/large-renderer.ts": "export const value = 1;\n".repeat(701) },
+    (result) => {
+      assert.deepEqual(
+        result.lineBudgetViolations.map((violation) => violation.scope),
+        ["src/"],
+      );
+    },
+  );
+});
+
+test("scoped budgets use the most specific prefix independent of declaration order", () => {
+  const policy = {
+    scopedLineBudgets: [
+      { maxLines: 700, prefix: "src/", reason: "general source" },
+      { maxLines: 400, prefix: "src/features/", reason: "feature source" },
+      { maxLines: 500, prefix: "src/features/", reason: "weaker duplicate" },
+    ],
+  };
+
+  assert.deepEqual(
+    getLineBudgetViolations("src/features/renderer.ts", 450, policy).map(
+      ({ maxLines, scope }) => ({ maxLines, scope }),
+    ),
+    [{ maxLines: 400, scope: "src/features/" }],
+  );
+});
+
+test("generated code health rejects oversized product tests", async () => {
+  await withFixture(
+    { "e2e/app-controls.spec.ts": "test('product', () => {});\n".repeat(501) },
+    (result) => {
+      assert.equal(
+        result.lineBudgetViolations.some(
+          (violation) => violation.scope === "test-file",
+        ),
+        true,
+      );
+    },
+  );
+});
+
+test("generated code health rejects unreviewed type and lint escape hatches", async () => {
+  await withFixture(
+    {
+      "src/app/renderer.ts": [
+        "const value = input as " + "any; // claimed review",
+        "// eslint-" + "disable-next-line no-console",
+      ].join("\n"),
+    },
+    (result) => {
+      assert.deepEqual(
+        result.forbiddenPatternViolations.map((violation) => violation.label),
+        ["as " + "any", "eslint-" + "disable"],
+      );
+    },
+  );
+});
+
+test("generated code health applies an explicit escape-hatch policy to tests", async () => {
+  await withFixture(
+    {
+      "e2e/app-controls.spec.ts": [
+        "// @ts-" + "ignore",
+        "const value = input as " + "any;",
+      ].join("\n"),
+    },
+    (result) => {
+      assert.deepEqual(
+        result.forbiddenPatternViolations.map((violation) => violation.label),
+        ["@ts-" + "ignore", "as " + "any"],
+      );
+    },
+  );
+});
+
+test("generated code health permits localized expected type failures in tests", async () => {
+  await withFixture(
+    {
+      "src/app/value.test.ts":
+        "// @ts-" + "expect-error intentional negative type assertion\nvalue();\n",
+    },
+    (result) => {
+      assert.deepEqual(result.forbiddenPatternViolations, []);
+    },
+  );
+});
+
+test("generated code health includes CSS in the canonical source inventory", async () => {
+  await withFixture(
+    { "src/features/renderer.css": ".item {}\n".repeat(1001) },
+    (result) => {
+      assert.equal(result.sourceFileCount, 1);
+      assert.match(result.lineBudgetViolations[0].repoPath, /renderer\.css$/u);
+    },
+  );
+});
+
+test("generated code health ignores immutable copied runtime source", async () => {
+  await withFixture(
+    {
+      "src/app/app-schema.ts": "export const value = 1;\n",
+      "src/toolcraft/runtime/large.ts": "export const runtime = 1;\n".repeat(1500),
+    },
+    (result) => {
+      assert.equal(result.sourceFileCount, 1);
+      assert.deepEqual(result.lineBudgetViolations, []);
+      assert.deepEqual(result.forbiddenPatternViolations, []);
+    },
+  );
+});
+
+test("generated code health rejects product cycles resolved through tsconfig aliases", async () => {
+  await withFixture(
+    {
+      "src/app/first.ts": 'import { second } from "@/app/second";\nexport const first = second;\n',
+      "src/app/second.ts": 'import { first } from "@/app/first";\nexport const second = first;\n',
+      "tsconfig.json": JSON.stringify({
+        compilerOptions: {
+          baseUrl: ".",
+          paths: { "@/*": ["src/*"] },
+        },
+      }),
+    },
+    (result) => {
+      assert.deepEqual(result.dependencyCycleViolations, [
+        {
+          cycle: ["src/app/first.ts", "src/app/second.ts", "src/app/first.ts"],
+          reason:
+            "Product production modules must form an acyclic dependency graph.",
+          repoPath: "src/app/first.ts",
+        },
+      ]);
+      assert.equal(codeHealthPassed(result), false);
+    },
+  );
+});
+
+test("generated code health scans supported JavaScript and TypeScript module extensions", async () => {
+  await withFixture(
+    { "src/features/oversized.jsx": "export const value = 1;\n".repeat(1001) },
+    (result) => {
+      assert.equal(result.lineBudgetViolations.length > 0, true);
+      assert.match(result.lineBudgetViolations[0].repoPath, /oversized\.jsx$/);
+    },
+  );
+});
+
+test("generated code health rejects symbolic links inside product source roots", async () => {
+  await withFixture(
+    { "external-product-module.ts": "export const value = 1;\n" },
+    (result) => {
+      assert.deepEqual(result.filesystemViolations, [
+        {
+          reason:
+            "Symbolic links can move checked source outside the Toolcraft source boundary.",
+          repoPath: "src/app/linked-product-module.ts",
+        },
+      ]);
+      assert.equal(codeHealthPassed(result), false);
+    },
+    async (fixtureRoot) => {
+      const appDir = path.join(fixtureRoot, "src/app");
+      await fs.mkdir(appDir, { recursive: true });
+      await fs.symlink(
+        path.join(fixtureRoot, "external-product-module.ts"),
+        path.join(appDir, "linked-product-module.ts"),
+      );
+    },
+  );
+});

package/templates/starter/scripts/check-toolcraft-docs.mjs

@@ -2,6 +2,15 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import {
+  getToolcraftContractFragmentFailures,
+  toolcraftDecisionRuleIds,
+} from "./toolcraft-contract-manifest.mjs";
+import {
+  getToolcraftWorkflowRouteFailures,
+  toolcraftWorkflowRequiredDocPaths,
+} from "./toolcraft-workflow-routes.mjs";
+
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const projectRoot = path.resolve(scriptDir, "..");
 
@@ -30,50 +39,28 @@ const requiredCoreDocs = [
   "core/reference-study.md",
 ];
 
-const requiredProjectFiles = ["LICENSE.md", "NOTICE.md"];
+const workflowMetaDocs = new Set([
+  "README.md",
+  "workflow.md",
+  "agent-worklog.md",
+]);
+const requiredWorkflowDocPaths = [...requiredDocs, ...requiredCoreDocs].filter(
+  (relativePath) => !workflowMetaDocs.has(relativePath),
+);
 
-const requiredRuleIds = [
-  "runtime-shell-required",
-  "canvas-no-app-ui",
-  "canvas-surface-preserved",
-  "canvas-handle-placement",
-  "panel-host-behavior",
-  "layers-enable-only-when-needed",
-  "layers-enabled-behavior",
-  "timeline-mode-choice",
-  "timeline-enabled-behavior",
-  "controls-product-coverage",
-  "output-export-required",
-  "controls-layout-heuristics",
-  "renderer-technique-inventory",
-  "video-reference-analysis",
-  "reference-clone-source-of-truth",
-  "acceptance-product-observable",
-  "performance-coverage-levels",
-  "persistence-policy-explicit",
-  "workflow-required",
-];
+const requiredProjectFiles = ["LICENSE.md", "NOTICE.md"];
 
 const requiredAgentsEntryLinks = [
   "workflow.md",
   "core/",
 ];
 
-const requiredWorkflowLinks = [
-  ...requiredCoreDocs,
-  "assembly-workflow.md",
-  "decision-contract.md",
-  "schema-reference.md",
-  "component-rules.md",
-  "acceptance-testing.md",
-  "performance.md",
-  "renderer-technique.md",
-  "custom-controls.md",
-];
+const requiredWorkflowLinks = [...toolcraftWorkflowRequiredDocPaths];
 
 const requiredWorkflowTerms = [
   "Verification Tier Classifier",
   "Verification tier: Tier N",
+  "Open exactly one listed document per terminal or tool read",
   "pnpm verify:quick",
   "pnpm verify:perf",
   "pnpm verify:final",
@@ -123,7 +110,7 @@ const agentsSource = await readText("AGENTS.md");
 const decisionSource = await readText("docs/toolcraft/decision-contract.md");
 const docsSources = [agentsSource, decisionSource];
 
-for (const ruleId of requiredRuleIds) {
+for (const ruleId of toolcraftDecisionRuleIds) {
   if (!agentsSource.includes(ruleId)) {
     failures.push(`AGENTS.md must list decision rule "${ruleId}"`);
   }
@@ -133,6 +120,24 @@ for (const ruleId of requiredRuleIds) {
   }
 }
 
+failures.push(
+  ...getToolcraftContractFragmentFailures({
+    fragmentIds: ["decision-rule-list"],
+    label: "AGENTS.md",
+    source: agentsSource,
+  }),
+  ...getToolcraftContractFragmentFailures({
+    fragmentIds: ["decision-rule-table"],
+    label: "docs/toolcraft/decision-contract.md",
+    source: decisionSource,
+  }),
+  ...getToolcraftContractFragmentFailures({
+    fragmentIds: ["built-in-control-table"],
+    label: "docs/toolcraft/schema-reference.md",
+    source: await readText("docs/toolcraft/schema-reference.md"),
+  }),
+);
+
 for (const fileName of [...requiredDocs, ...requiredCoreDocs]) {
   const source = await readText(`docs/toolcraft/${fileName}`);
   docsSources.push(source);
@@ -141,6 +146,14 @@ for (const fileName of [...requiredDocs, ...requiredCoreDocs]) {
 const combinedSource = docsSources.join("\n");
 const workflowSource = await readText("docs/toolcraft/workflow.md");
 
+failures.push(
+  ...(await getToolcraftWorkflowRouteFailures({
+    projectRoot,
+    requiredDocPaths: requiredWorkflowDocPaths,
+    workflowSource,
+  })),
+);
+
 for (const pattern of forbiddenTextPatterns) {
   if (pattern.test(combinedSource)) {
     failures.push(`local Toolcraft docs contain forbidden text pattern ${pattern}`);