@pixel-point/toolcraft 0.0.17 → 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-export-boundary.mjs

@@ -1,8 +1,4 @@
 import ts from "typescript";
-
-const forbiddenRuntimeExportNames = new Set([
-  "createToolcraftPngExportCanvas",
-]);
 const forbiddenGlobalExportConstructors = new Set([
   "MediaRecorder",
   "VideoEncoder",
@@ -21,24 +17,17 @@ export function getToolcraftProductExportModuleKind(
     return "runtime-export-mechanics";
   }
   if (
-    normalizedSpecifier === "@repo/toolcraft-runtime" ||
-    /^[#@]\/toolcraft\/runtime\/?$/u.test(normalizedSpecifier) ||
-    /\/src\/toolcraft\/runtime$/u.test(resolvedSpecifier ?? "")
+    /^@repo\/toolcraft-runtime\/export(?:\/|$)/u.test(normalizedSpecifier) ||
+    /^[#@]\/toolcraft\/runtime\/export(?:\/|$)/u.test(normalizedSpecifier) ||
+    /\/src\/toolcraft\/runtime\/export(?:\/|$)/u.test(resolvedSpecifier ?? "")
   ) {
-    return "runtime-export-api";
+    return "runtime-export-mechanics";
   }
   return null;
 }
 
-export function isForbiddenToolcraftRuntimeExport(
-  moduleKind,
-  importedName,
-) {
-  return (
-    moduleKind === "runtime-export-mechanics" ||
-    (moduleKind === "runtime-export-api" &&
-      forbiddenRuntimeExportNames.has(importedName))
-  );
+export function isForbiddenToolcraftRuntimeExport(moduleKind) {
+  return moduleKind === "runtime-export-mechanics";
 }
 
 function getDeclarationScope(node, sourceFile) {