@pixel-point/toolcraft 0.0.16 → 0.0.18

package/templates/starter/scripts/toolcraft-product-control-bindings.mjs

@@ -0,0 +1,182 @@
+import ts from "typescript";
+
+const workspaceUiPrimitiveModulePattern =
+  /^@repo\/ui(?:$|\/(?:src\/)?(?:components\/)?primitives(?:\/|$))/u;
+
+function isToolcraftPublicUiPrimitiveModule(moduleSpecifier) {
+  const normalizedSpecifier = moduleSpecifier.replaceAll("\\", "/");
+
+  return (
+    workspaceUiPrimitiveModulePattern.test(normalizedSpecifier) ||
+    /^[#@]\/toolcraft\/ui$/u.test(normalizedSpecifier) ||
+    /^[#@]\/toolcraft\/ui\/primitives(?:\/|$)/u.test(normalizedSpecifier) ||
+    /^[#@]\/toolcraft\/ui\/components\/primitives(?:\/|$)/u.test(
+      normalizedSpecifier,
+    )
+  );
+}
+
+function unwrapExpression(node) {
+  let current = node;
+
+  while (
+    ts.isAwaitExpression(current) ||
+    ts.isParenthesizedExpression(current) ||
+    ts.isAsExpression(current) ||
+    ts.isTypeAssertionExpression(current) ||
+    ts.isSatisfiesExpression(current) ||
+    ts.isNonNullExpression(current)
+  ) {
+    current = current.expression;
+  }
+
+  return current;
+}
+
+function getImportModuleSpecifier(declaration) {
+  if (ts.isImportSpecifier(declaration)) {
+    const importDeclaration = declaration.parent.parent.parent;
+    return ts.isImportDeclaration(importDeclaration) &&
+      ts.isStringLiteralLike(importDeclaration.moduleSpecifier)
+      ? importDeclaration.moduleSpecifier.text
+      : null;
+  }
+
+  if (ts.isNamespaceImport(declaration)) {
+    const importDeclaration = declaration.parent.parent;
+    return ts.isImportDeclaration(importDeclaration) &&
+      ts.isStringLiteralLike(importDeclaration.moduleSpecifier)
+      ? importDeclaration.moduleSpecifier.text
+      : null;
+  }
+
+  if (ts.isImportClause(declaration)) {
+    const importDeclaration = declaration.parent;
+    return ts.isImportDeclaration(importDeclaration) &&
+      ts.isStringLiteralLike(importDeclaration.moduleSpecifier)
+      ? importDeclaration.moduleSpecifier.text
+      : null;
+  }
+
+  return null;
+}
+
+export function createToolcraftUiInputBindingTracker({
+  checker,
+  resolveStaticString,
+}) {
+  const bindingKinds = new Map();
+  const resolvingSymbols = new Set();
+
+  function classifyExpression(expression) {
+    const current = unwrapExpression(expression);
+
+    if (ts.isIdentifier(current)) {
+      const symbol = checker.getSymbolAtLocation(current);
+      return symbol ? classifySymbol(symbol) : null;
+    }
+
+    if (
+      ts.isPropertyAccessExpression(current) &&
+      current.name.text === "Input" &&
+      classifyExpression(current.expression) === "namespace"
+    ) {
+      return "input";
+    }
+
+    if (
+      ts.isCallExpression(current) &&
+      current.arguments.length > 0 &&
+      (current.expression.kind === ts.SyntaxKind.ImportKeyword ||
+        (ts.isIdentifier(current.expression) &&
+          current.expression.text === "require"))
+    ) {
+      const moduleSpecifier = resolveStaticString(current.arguments[0]);
+      return moduleSpecifier &&
+        isToolcraftPublicUiPrimitiveModule(moduleSpecifier)
+        ? "namespace"
+        : null;
+    }
+
+    return null;
+  }
+
+  function classifyDeclaration(declaration) {
+    if (ts.isImportSpecifier(declaration)) {
+      const importedName = declaration.propertyName?.text ?? declaration.name.text;
+      const moduleSpecifier = getImportModuleSpecifier(declaration);
+      return importedName === "Input" &&
+        moduleSpecifier &&
+        isToolcraftPublicUiPrimitiveModule(moduleSpecifier)
+        ? "input"
+        : null;
+    }
+
+    if (ts.isNamespaceImport(declaration)) {
+      const moduleSpecifier = getImportModuleSpecifier(declaration);
+      return moduleSpecifier &&
+        isToolcraftPublicUiPrimitiveModule(moduleSpecifier)
+        ? "namespace"
+        : null;
+    }
+
+    if (ts.isImportClause(declaration)) {
+      const moduleSpecifier = getImportModuleSpecifier(declaration);
+      return moduleSpecifier &&
+        isToolcraftPublicUiPrimitiveModule(moduleSpecifier) &&
+        /(?:^|\/)input(?:\.[cm]?[jt]sx?)?$/iu.test(moduleSpecifier)
+        ? "input"
+        : null;
+    }
+
+    if (
+      ts.isImportEqualsDeclaration(declaration) &&
+      ts.isExternalModuleReference(declaration.moduleReference) &&
+      declaration.moduleReference.expression &&
+      ts.isStringLiteralLike(declaration.moduleReference.expression) &&
+      isToolcraftPublicUiPrimitiveModule(declaration.moduleReference.expression.text)
+    ) {
+      return "namespace";
+    }
+
+    if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
+      return classifyExpression(declaration.initializer);
+    }
+
+    if (
+      ts.isBindingElement(declaration) &&
+      !declaration.dotDotDotToken &&
+      (declaration.propertyName?.getText() ?? declaration.name.getText()) ===
+        "Input"
+    ) {
+      const variableDeclaration = declaration.parent.parent;
+      return ts.isVariableDeclaration(variableDeclaration) &&
+        variableDeclaration.initializer &&
+        classifyExpression(variableDeclaration.initializer) === "namespace"
+        ? "input"
+        : null;
+    }
+
+    return null;
+  }
+
+  function classifySymbol(symbol) {
+    if (bindingKinds.has(symbol)) return bindingKinds.get(symbol);
+    if (resolvingSymbols.has(symbol)) return null;
+
+    resolvingSymbols.add(symbol);
+    const bindingKind =
+      symbol.declarations
+        ?.map(classifyDeclaration)
+        .find((candidate) => candidate !== null) ?? null;
+    resolvingSymbols.delete(symbol);
+    bindingKinds.set(symbol, bindingKind);
+    return bindingKind;
+  }
+
+  function isTrackedInputTag(tagName) {
+    return classifyExpression(tagName) === "input";
+  }
+
+  return { isTrackedInputTag };
+}

package/templates/starter/scripts/toolcraft-product-control-boundary.mjs

@@ -0,0 +1,146 @@
+import ts from "typescript";
+
+import { createToolcraftUiInputBindingTracker } from "./toolcraft-product-control-bindings.mjs";
+
+const workspacePrivateControlModulePattern =
+  /^@repo\/ui\/(?:src\/)?(?:components\/controls(?:\/|$)|controls\/)/u;
+
+const forbiddenInputTypes = new Map([
+  ["checkbox", "checkbox or switch"],
+  ["color", "color or colorOpacity"],
+  ["file", "fileDrop"],
+  ["radio", "segmented or select"],
+  ["range", "slider or rangeSlider"],
+]);
+
+function normalizeSpecifier(value) {
+  return value.replaceAll("\\", "/");
+}
+
+export function isToolcraftPrivateControlImplementationModule({
+  moduleSpecifier,
+  resolvedSpecifier,
+}) {
+  const normalizedSpecifier = normalizeSpecifier(moduleSpecifier);
+  const normalizedResolvedSpecifier = resolvedSpecifier
+    ? normalizeSpecifier(resolvedSpecifier)
+    : "";
+
+  return (
+    workspacePrivateControlModulePattern.test(normalizedSpecifier) ||
+    /^[#@]\/toolcraft\/ui\/(?:components\/)?controls\//u.test(
+      normalizedSpecifier,
+    ) ||
+    /^[#@]\/toolcraft\/ui\/components\/controls(?:\/|$)/u.test(
+      normalizedSpecifier,
+    ) ||
+    /\/src\/toolcraft\/ui\/components\/controls(?:\/|$)/u.test(
+      normalizedResolvedSpecifier,
+    ) ||
+    /\/packages\/ui\/src\/components\/controls(?:\/|$)/u.test(
+      normalizedResolvedSpecifier,
+    )
+  );
+}
+
+function getJsxTagName(tagName) {
+  if (ts.isIdentifier(tagName)) return tagName.text;
+  if (ts.isPropertyAccessExpression(tagName)) return tagName.name.text;
+  return null;
+}
+
+export function createToolcraftProductControlInspector({
+  checker,
+  getNodeLocation,
+  repoPath,
+  resolveStaticString,
+  sourceFile,
+}) {
+  const { isTrackedInputTag } = createToolcraftUiInputBindingTracker({
+    checker,
+    resolveStaticString,
+  });
+
+  function createViolation(node, message) {
+    return {
+      ...getNodeLocation(sourceFile, node),
+      kind: "native-control-recreation",
+      message,
+      repoPath,
+    };
+  }
+
+  function getInputType(attributes) {
+    let inputType = "text";
+    for (const property of attributes.properties) {
+      if (ts.isJsxSpreadAttribute(property)) {
+        inputType = null;
+        continue;
+      }
+      if (!ts.isIdentifier(property.name) || property.name.text !== "type") {
+        continue;
+      }
+      if (!property.initializer) {
+        inputType = null;
+      } else if (ts.isStringLiteral(property.initializer)) {
+        inputType = property.initializer.text;
+      } else if (
+        ts.isJsxExpression(property.initializer) &&
+        property.initializer.expression
+      ) {
+        inputType = resolveStaticString(property.initializer.expression) ?? null;
+      } else {
+        inputType = null;
+      }
+    }
+    return inputType?.toLowerCase() ?? null;
+  }
+
+  function inspectNode(node) {
+    if (!ts.isJsxOpeningElement(node) && !ts.isJsxSelfClosingElement(node)) {
+      return [];
+    }
+
+    const tagName = getJsxTagName(node.tagName);
+    if (tagName === "select") {
+      return [
+        createViolation(
+          node.tagName,
+          "Product source must not recreate the built-in Select with a native <select>. Declare a select schema control.",
+        ),
+      ];
+    }
+    if (tagName === "textarea") {
+      return [
+        createViolation(
+          node.tagName,
+          "Product source must not recreate built-in text or code controls with a native <textarea>. Declare a text or code schema control.",
+        ),
+      ];
+    }
+
+    if (tagName !== "input" && !isTrackedInputTag(node.tagName)) return [];
+
+    const inputType = getInputType(node.attributes);
+    if (inputType === null) {
+      return [
+        createViolation(
+          node.tagName,
+          "Product Input type must be statically resolvable so the Toolcraft boundary can verify that it does not recreate a built-in control.",
+        ),
+      ];
+    }
+
+    const builtInSchemaType = forbiddenInputTypes.get(inputType);
+    if (!builtInSchemaType) return [];
+
+    return [
+      createViolation(
+        node.tagName,
+        `Product source must not recreate a built-in control with input type "${inputType}". Declare the built-in ${builtInSchemaType} schema control.`,
+      ),
+    ];
+  }
+
+  return { inspectNode };
+}

package/templates/starter/scripts/toolcraft-product-control-boundary.test.mjs

@@ -0,0 +1,186 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { evaluateToolcraftProductBoundary } from "./toolcraft-product-boundary.mjs";
+import { createToolcraftProductBoundaryFixture as createFixture } from "./toolcraft-product-boundary-test-fixtures.mjs";
+
+const workspaceUiModule = ["@", "repo/ui"].join("");
+
+test("finds built-in controls through every module form", async (context) => {
+  const rootDir = await createFixture(context, {
+    "src/features/control-bridge.ts": `
+      export { SliderControl as ProductSlider } from "@repo/ui/controls";
+      export { Color as ProductColor } from "@/toolcraft/ui";
+    `,
+    "src/features/dynamic.ts": `
+      export async function loadControls() {
+        return import("@/toolcraft/ui/components/controls/slider");
+      }
+    `,
+    "src/features/namespace.ts": `
+      import * as Controls from "@repo/ui";
+      export const Slider = Controls.Slider;
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({ rootDir });
+
+  assert.deepEqual(
+    result.violations.map((violation) => violation.kind),
+    [
+      "built-in-control",
+      "built-in-control",
+      "built-in-control-implementation",
+      "built-in-control",
+    ],
+  );
+});
+
+test("rejects every deep import path into built-in control implementations", async (context) => {
+  const rootDir = await createFixture(context, {
+    "src/features/direct.tsx": `
+      import { ColorPickerPopover } from "@/toolcraft/ui/components/controls/color/color-picker-popover";
+      export const Direct = ColorPickerPopover;
+    `,
+    "src/features/directory-index.ts": `
+      import * as PrivateControls from "${workspaceUiModule}/components/controls";
+      export const DirectoryIndex = PrivateControls;
+    `,
+    "src/features/dynamic.ts": `
+      export const loadPrivateControl = () => import("${workspaceUiModule}/components/controls/color/color-value-utils");
+    `,
+    "src/features/namespace.ts": `
+      import * as PrivateColor from "@/toolcraft/ui/components/controls/color";
+      export const Namespace = PrivateColor;
+    `,
+    "src/features/reexport.ts": `
+      export { getCommittedHexColor } from "@/toolcraft/ui/components/controls/color/color-value-utils";
+    `,
+    "src/features/require.ts": `
+      export const privateControl = require("@/toolcraft/ui/components/controls/color/color-picker-popover");
+    `,
+    "src/features/workspace-source.ts": `
+      import { ColorPickerPopover } from "${workspaceUiModule}/src/components/controls/color/color-picker-popover";
+      export const WorkspaceSource = ColorPickerPopover;
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({ rootDir });
+
+  assert.equal(result.violations.length, 7);
+  assert.equal(
+    result.violations.every(
+      (violation) => violation.kind === "built-in-control-implementation",
+    ),
+    true,
+  );
+  assert.equal(
+    result.violations.every((violation) =>
+      /deep control implementation|public schema control/u.test(
+        violation.message,
+      ),
+    ),
+    true,
+  );
+});
+
+test("rejects the badge color-control copy at both private imports", async (context) => {
+  const rootDir = await createFixture(context, {
+    "src/features/badge-color-control.tsx": `
+      import { ColorPickerPopover } from "@/toolcraft/ui/components/controls/color/color-picker-popover";
+      import { getCommittedHexColor } from "@/toolcraft/ui/components/controls/color/color-value-utils";
+      export const BadgeColorControl = { ColorPickerPopover, getCommittedHexColor };
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({ rootDir });
+
+  assert.deepEqual(
+    result.violations.map(({ column, kind, line, repoPath }) => ({
+      column,
+      kind,
+      line,
+      repoPath,
+    })),
+    [
+      {
+        column: 7,
+        kind: "built-in-control-implementation",
+        line: 2,
+        repoPath: "src/features/badge-color-control.tsx",
+      },
+      {
+        column: 7,
+        kind: "built-in-control-implementation",
+        line: 3,
+        repoPath: "src/features/badge-color-control.tsx",
+      },
+    ],
+  );
+});
+
+test("rejects native and kit-primitive recreations of built-in controls", async (context) => {
+  const rootDir = await createFixture(context, {
+    "src/features/kit-inputs.tsx": `
+      import { Input as FieldInput } from "@/toolcraft/ui/primitives";
+      import * as Primitives from "@/toolcraft/ui/primitives";
+      const AliasedInput = FieldInput;
+      const { Input: RequiredInput } = require("@/toolcraft/ui/primitives");
+      export const Color = <FieldInput type="color" />;
+      export const File = <AliasedInput type={"file"} />;
+      export const Range = <Primitives.Input type="range" />;
+      export const Radio = <RequiredInput type="radio" />;
+      export function Dynamic({ kind }) {
+        return <FieldInput type={kind} />;
+      }
+    `,
+    "src/features/native.tsx": `
+      const rangeType = "range";
+      export const Range = <input type={rangeType} />;
+      export const Checkbox = <input type="checkbox" />;
+      export const Radio = <input type="radio" />;
+      export const Select = <select><option>One</option></select>;
+      export const Notes = <textarea />;
+    `,
+    "src/features/private-primitive.tsx": `
+      import PrimitiveInput from "${workspaceUiModule}/components/primitives/input";
+      export const PrivatePrimitiveColor = <PrimitiveInput type="color" />;
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({ rootDir });
+
+  assert.equal(result.violations.length, 11);
+  assert.equal(
+    result.violations.every(
+      (violation) => violation.kind === "native-control-recreation",
+    ),
+    true,
+  );
+});
+
+test("allows generic text inputs, buttons, canvas, and product components", async (context) => {
+  const rootDir = await createFixture(context, {
+    "src/features/safe-controls.tsx": `
+      import { Button, Input as FieldInput } from "@/toolcraft/ui/primitives";
+      function ProductInput() { return <div>Product value</div>; }
+      function ShadowedInput(FieldInput) { return <FieldInput type="color" />; }
+      export const Safe = (
+        <>
+          <FieldInput type="text" />
+          <input type="email" />
+          <input type="hidden" />
+          <Button>Run</Button>
+          <button type="button">Local action</button>
+          <canvas />
+          <ProductInput />
+          <ShadowedInput />
+        </>
+      );
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({ rootDir });
+
+  assert.deepEqual(result.violations, []);
+});

package/templates/starter/scripts/toolcraft-product-evidence-boundary.test.mjs

@@ -12,6 +12,44 @@ const starterRoot = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
   "..",
 );
+const unavailableImageEvidenceFacadePath =
+  "e2e/browser-infinity-canvas-evidence.ts";
+const unavailableImageEvidencePrivatePath =
+  "e2e/browser-infinity-canvas-unavailable-image-evidence.ts";
+
+async function evaluateUnavailableImageEvidenceImport(context, specifier) {
+  const rootDir = await createFixture(context, {
+    "e2e/app-canvas.spec.ts": `
+      import { createToolcraftUnavailableImageResourceFixture } from "${specifier}";
+      void createToolcraftUnavailableImageResourceFixture;
+    `,
+    [unavailableImageEvidenceFacadePath]: `
+      export {
+        createToolcraftUnavailableImageResourceFixture,
+      } from "./browser-infinity-canvas-unavailable-image-evidence";
+    `,
+    [unavailableImageEvidencePrivatePath]: `
+      export function createToolcraftUnavailableImageResourceFixture() {}
+    `,
+    "tsconfig.json": JSON.stringify({
+      compilerOptions: {
+        baseUrl: ".",
+        paths: {
+          "@private-proof": [`./${unavailableImageEvidencePrivatePath}`],
+          "@public-proof": [`./${unavailableImageEvidenceFacadePath}`],
+        },
+      },
+    }),
+  });
+
+  return evaluateToolcraftProductBoundary({
+    protectedFilePaths: [
+      unavailableImageEvidenceFacadePath,
+      unavailableImageEvidencePrivatePath,
+    ],
+    rootDir,
+  });
+}
 
 test("protects every starter helper that writes reserved runtime evidence", async () => {
   const e2eRoot = path.join(starterRoot, "e2e");
@@ -201,27 +239,54 @@ test("allows product layer specs to use the public proof facade without reserved
   assert.deepEqual(result.violations, []);
 });
 
-test("allows product specs to use the unavailable-resource facade but rejects its reserved bridge", async (context) => {
-  const allowedRoot = await createFixture(context, {
-    "e2e/app-canvas.spec.ts": `
-      import {
-        createToolcraftUnavailableImageResourceFixture,
-        expectToolcraftInfinityCanvasUnavailableImageExportEvidence,
-      } from "./browser-infinity-canvas-evidence";
-      void createToolcraftUnavailableImageResourceFixture;
-      void expectToolcraftInfinityCanvasUnavailableImageExportEvidence;
-    `,
-    "e2e/browser-infinity-canvas-evidence.ts": `
-      export function createToolcraftUnavailableImageResourceFixture() {}
-      export async function expectToolcraftInfinityCanvasUnavailableImageExportEvidence() {}
-    `,
-  });
-  const allowed = await evaluateToolcraftProductBoundary({
-    protectedFilePaths: ["e2e/browser-infinity-canvas-evidence.ts"],
-    rootDir: allowedRoot,
-  });
-  assert.deepEqual(allowed.violations, []);
+test("rejects relative and configured-alias imports of private unavailable-image evidence", async (context) => {
+  const results = await Promise.all(
+    [
+      "./browser-infinity-canvas-unavailable-image-evidence",
+      "@private-proof",
+    ].map((specifier) =>
+      evaluateUnavailableImageEvidenceImport(context, specifier),
+    ),
+  );
+  assert.deepEqual(
+    results.map((result) =>
+      result.violations.map((violation) => violation.kind),
+    ),
+    [
+      ["reserved-runtime-evidence"],
+      ["reserved-runtime-evidence"],
+    ],
+  );
+  for (const result of results) {
+    assert.match(result.violations[0].message, /browser-infinity-canvas-evidence/u);
+  }
+});
+
+test("allows relative and configured-alias imports of the public unavailable-image facade", async (context) => {
+  for (const specifier of [
+    "./browser-infinity-canvas-evidence",
+    "@public-proof",
+  ]) {
+    const result = await evaluateUnavailableImageEvidenceImport(
+      context,
+      specifier,
+    );
+    assert.deepEqual(result.violations, []);
+  }
+});
+
+test("normalizes private unavailable-image evidence import paths before enforcing policy", async (context) => {
+  const result = await evaluateUnavailableImageEvidenceImport(
+    context,
+    "./nested/../browser-infinity-canvas-unavailable-image-evidence",
+  );
+  assert.deepEqual(
+    result.violations.map((violation) => violation.kind),
+    ["reserved-runtime-evidence"],
+  );
+});
 
+test("rejects product access to the reserved unavailable-resource bridge", async (context) => {
   const rejectedRoot = await createFixture(context, {
     "e2e/app-canvas.spec.ts": `
       const fixtureEvent =

package/templates/starter/scripts/toolcraft-product-evidence-import-policy.mjs

@@ -0,0 +1,43 @@
+const PRIVATE_EVIDENCE_MESSAGE =
+  "Product-owned source must use the protected public evidence facade instead of importing its private implementation module.";
+
+export const toolcraftProductEvidenceModulePolicies = Object.freeze([
+  Object.freeze({
+    capability: "unavailable-image-resource-evidence",
+    privateModuleRepoPath:
+      "e2e/browser-infinity-canvas-unavailable-image-evidence.ts",
+    publicFacadeRepoPath: "e2e/browser-infinity-canvas-evidence.ts",
+  }),
+]);
+
+const privateEvidencePolicyByRepoPath = new Map(
+  toolcraftProductEvidenceModulePolicies.map((policy) => [
+    policy.privateModuleRepoPath,
+    policy,
+  ]),
+);
+
+function normalizeRepoPath(repoPath) {
+  return String(repoPath).replaceAll("\\", "/").replace(/^\.\//u, "");
+}
+
+export function createToolcraftPrivateEvidenceImportViolation({
+  importerRepoPath,
+  moduleImport,
+}) {
+  if (moduleImport.resolution !== "resolved") return null;
+  const policy = privateEvidencePolicyByRepoPath.get(
+    normalizeRepoPath(moduleImport.resolvedRepoPath),
+  );
+  if (!policy) return null;
+
+  return {
+    column: moduleImport.column,
+    kind: "reserved-runtime-evidence",
+    line: moduleImport.line,
+    message:
+      `${PRIVATE_EVIDENCE_MESSAGE} Import ${policy.publicFacadeRepoPath} ` +
+      `for ${policy.capability}.`,
+    repoPath: importerRepoPath,
+  };
+}