@pixel-point/toolcraft 0.0.16 → 0.0.18

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

@@ -0,0 +1,157 @@
+import ts from "typescript";
+const forbiddenGlobalExportConstructors = new Set([
+  "MediaRecorder",
+  "VideoEncoder",
+]);
+const forbiddenCanvasExportMethods = new Set([
+  "captureStream",
+  "toBlob",
+  "toDataURL",
+]);
+
+export function getToolcraftProductExportModuleKind(
+  normalizedSpecifier,
+  resolvedSpecifier,
+) {
+  if (/^mediabunny(?:\/|$)/u.test(normalizedSpecifier)) {
+    return "runtime-export-mechanics";
+  }
+  if (
+    /^@repo\/toolcraft-runtime\/export(?:\/|$)/u.test(normalizedSpecifier) ||
+    /^[#@]\/toolcraft\/runtime\/export(?:\/|$)/u.test(normalizedSpecifier) ||
+    /\/src\/toolcraft\/runtime\/export(?:\/|$)/u.test(resolvedSpecifier ?? "")
+  ) {
+    return "runtime-export-mechanics";
+  }
+  return null;
+}
+
+export function isForbiddenToolcraftRuntimeExport(moduleKind) {
+  return moduleKind === "runtime-export-mechanics";
+}
+
+function getDeclarationScope(node, sourceFile) {
+  let current = node.parent;
+  while (current) {
+    if (
+      ts.isSourceFile(current) ||
+      ts.isFunctionLike(current) ||
+      ts.isBlock(current) ||
+      ts.isCatchClause(current)
+    ) {
+      return current;
+    }
+    current = current.parent;
+  }
+  return sourceFile;
+}
+
+function collectLexicalDeclarations(sourceFile) {
+  const declarations = [];
+
+  function collectBindingNames(name, scope) {
+    if (ts.isIdentifier(name)) {
+      declarations.push({ name: name.text, scope });
+    } else if (
+      ts.isObjectBindingPattern(name) ||
+      ts.isArrayBindingPattern(name)
+    ) {
+      for (const element of name.elements) {
+        if (ts.isBindingElement(element)) collectBindingNames(element.name, scope);
+      }
+    }
+  }
+
+  function visit(node) {
+    if (ts.isImportClause(node) && node.name) {
+      collectBindingNames(node.name, sourceFile);
+    } else if (ts.isImportSpecifier(node) || ts.isNamespaceImport(node)) {
+      collectBindingNames(node.name, sourceFile);
+    } else if (ts.isVariableDeclaration(node)) {
+      collectBindingNames(node.name, getDeclarationScope(node, sourceFile));
+    } else if (ts.isParameter(node)) {
+      collectBindingNames(node.name, node.parent);
+    } else if (
+      (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) &&
+      node.name
+    ) {
+      collectBindingNames(node.name, getDeclarationScope(node, sourceFile));
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return declarations;
+}
+
+export function createToolcraftProductExportInspector({
+  getNodeLocation,
+  repoPath,
+  sourceFile,
+}) {
+  const lexicalDeclarations = collectLexicalDeclarations(sourceFile);
+
+  function isLexicallyDeclared(identifier) {
+    const ancestorScopes = new Set();
+    let current = identifier.parent;
+    while (current) {
+      if (
+        ts.isSourceFile(current) ||
+        ts.isFunctionLike(current) ||
+        ts.isBlock(current) ||
+        ts.isCatchClause(current)
+      ) {
+        ancestorScopes.add(current);
+      }
+      current = current.parent;
+    }
+    return lexicalDeclarations.some(
+      (declaration) =>
+        declaration.name === identifier.text &&
+        ancestorScopes.has(declaration.scope),
+    );
+  }
+
+  function violation(node, subject) {
+    return {
+      ...getNodeLocation(sourceFile, node),
+      kind: "runtime-export-ownership",
+      message: `Product source must not own ${subject}. Declare exportRenderer and let runtime export actions encode and download the artifact.`,
+      repoPath,
+    };
+  }
+
+  return (node) => {
+    if (
+      ts.isNewExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      forbiddenGlobalExportConstructors.has(node.expression.text) &&
+      !isLexicallyDeclared(node.expression)
+    ) {
+      return [
+        violation(
+          node,
+          `${node.expression.text} encoder or recorder construction`,
+        ),
+      ];
+    }
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression)
+    ) {
+      const propertyName = node.expression.name.text;
+      if (forbiddenCanvasExportMethods.has(propertyName)) {
+        return [violation(node, `canvas.${propertyName}() export mechanics`)];
+      }
+      if (
+        propertyName === "createObjectURL" &&
+        ts.isIdentifier(node.expression.expression) &&
+        node.expression.expression.text === "URL" &&
+        !isLexicallyDeclared(node.expression.expression)
+      ) {
+        return [violation(node, "URL.createObjectURL() artifact delivery")];
+      }
+    }
+    return [];
+  };
+}

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

@@ -0,0 +1,196 @@
+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";
+
+test("keeps artifact encoding and download mechanics runtime-owned", async (context) => {
+  const workspaceRuntimeExportSpecifier = [
+    "@repo",
+    "toolcraft-runtime",
+    "export",
+    "image-artifact-export",
+  ].join("/");
+  const rootDir = await createFixture(context, {
+    "src/features/export-mechanics.ts": `
+      import { createToolcraftVideoEncoderBackend as createAliasBackend } from "@/toolcraft/runtime/export/video-encoding-backend";
+      import { exportToolcraftImageArtifact } from "${workspaceRuntimeExportSpecifier}";
+      import { downloadToolcraftArtifact } from "../toolcraft/runtime/export/artifact-download";
+      import { Output } from "mediabunny";
+      export function exportArtifact(canvas: HTMLCanvasElement) {
+        const recorder = new MediaRecorder(canvas.captureStream());
+        const encoder = new VideoEncoder({ error() {}, output() {} });
+        canvas.toBlob(() => undefined);
+        canvas.toDataURL();
+        URL.createObjectURL(new Blob());
+        void createAliasBackend;
+        void exportToolcraftImageArtifact;
+        void downloadToolcraftArtifact;
+        void Output;
+        void recorder;
+        void encoder;
+      }
+    `,
+    "src/features/safe-renderer.ts": `
+      import * as Runtime from "@/toolcraft/runtime";
+      import {
+        getToolcraftImageExportSize,
+        shouldIncludeToolcraftPreviewBackground,
+        validateToolcraftArtifactSize,
+      } from "@/toolcraft/runtime";
+      import type {
+        ToolcraftExportFrame,
+        ToolcraftProductExportRenderer,
+      } from "@/toolcraft/runtime";
+      export const renderFrame = ({ context }) => context.fillRect(0, 0, 1, 1);
+      void Runtime;
+      void getToolcraftImageExportSize;
+      void shouldIncludeToolcraftPreviewBackground;
+      void validateToolcraftArtifactSize;
+      void (null as unknown as ToolcraftExportFrame);
+      void (null as unknown as ToolcraftProductExportRenderer);
+    `,
+    "src/features/shadowed-globals.ts": `
+      export function localNames(MediaRecorder, VideoEncoder, URL) {
+        void new MediaRecorder();
+        void new VideoEncoder();
+        URL.createObjectURL();
+      }
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({ rootDir });
+
+  assert.equal(result.violations.length, 10);
+  assert.equal(
+    result.violations.every(
+      (violation) => violation.kind === "runtime-export-ownership",
+    ),
+    true,
+  );
+  assert.equal(
+    result.violations.some((violation) =>
+      violation.repoPath.endsWith("shadowed-globals.ts"),
+    ),
+    false,
+  );
+  assert.equal(
+    result.violations.some((violation) =>
+      violation.repoPath.endsWith("safe-renderer.ts"),
+    ),
+    false,
+  );
+});
+
+test("classifies every runtime export mechanics module reference once", async (context) => {
+  const workspaceRuntimeExportRoot = [
+    "@repo",
+    "toolcraft-runtime",
+    "export",
+  ].join("/");
+  const rootDir = await createFixture(context, {
+    "src/features/dynamic-import.ts": `
+      export async function loadMedia() {
+        return import("mediabunny");
+      }
+    `,
+    "src/features/import-equals.ts": `
+      import Backend = require("@/toolcraft/runtime/export/video-encoding-backend");
+      void Backend;
+    `,
+    "src/features/import-type.ts": `
+      type Backend = import("@/toolcraft/runtime/export/video-encoding-backend").ToolcraftVideoEncoderBackend;
+      void (null as unknown as Backend);
+    `,
+    "src/features/regular-export.ts": `
+      export {
+        createToolcraftVideoEncoderBackend as createFirstBackend,
+        createToolcraftVideoEncoderBackend as createSecondBackend,
+      } from "@/toolcraft/runtime/export/video-encoding-backend";
+    `,
+    "src/features/regular-import.ts": `
+      import {
+        createToolcraftVideoEncoderBackend as createFirstBackend,
+        createToolcraftVideoEncoderBackend as createSecondBackend,
+      } from "@/toolcraft/runtime/export/video-encoding-backend";
+      void createFirstBackend;
+      void createSecondBackend;
+    `,
+    "src/features/require.ts": `
+      export const backend = require("${workspaceRuntimeExportRoot}/video-encoding-backend");
+    `,
+    "src/features/safe-root-type-import.ts": `
+      import type { ToolcraftExportFrame } from "@/toolcraft/runtime";
+      void (null as unknown as ToolcraftExportFrame);
+    `,
+    "src/features/side-effect-import.ts": `import "mediabunny";`,
+    "src/features/type-only-export.ts": `
+      export type {
+        ToolcraftImageArtifactExportRequest,
+        ToolcraftImageArtifactExportResult,
+      } from "${workspaceRuntimeExportRoot}/image-artifact-export";
+    `,
+    "src/features/type-only-import-equals.ts": `
+      import type Backend = require("@/toolcraft/runtime/export/video-encoding-backend");
+      void (null as unknown as Backend);
+    `,
+    "src/features/type-only-import.ts": `
+      import type {
+        ToolcraftVideoArtifactExportRequest,
+        ToolcraftVideoArtifactExportResult,
+      } from "${workspaceRuntimeExportRoot}/video-artifact-export";
+      void (null as unknown as ToolcraftVideoArtifactExportRequest);
+      void (null as unknown as ToolcraftVideoArtifactExportResult);
+    `,
+    "src/features/typeof-import-type.ts": `
+      type MediaBunny = typeof import("mediabunny");
+      void (null as unknown as MediaBunny);
+    `,
+    "src/features/export-boundary.test.ts": `
+      import type { ToolcraftVideoEncoderBackend } from "@/toolcraft/runtime/export/video-encoding-backend";
+      void (null as unknown as ToolcraftVideoEncoderBackend);
+    `,
+    "e2e/test-support/export-fixture.ts": `
+      export type { ToolcraftVideoEncoderBackend } from "@/toolcraft/runtime/export/video-encoding-backend";
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({ rootDir });
+
+  assert.deepEqual(
+    result.violations.map(({ repoPath }) => repoPath).sort(),
+    [
+      "src/features/dynamic-import.ts",
+      "src/features/import-equals.ts",
+      "src/features/import-type.ts",
+      "src/features/regular-export.ts",
+      "src/features/regular-import.ts",
+      "src/features/require.ts",
+      "src/features/side-effect-import.ts",
+      "src/features/type-only-export.ts",
+      "src/features/type-only-import-equals.ts",
+      "src/features/type-only-import.ts",
+      "src/features/typeof-import-type.ts",
+    ],
+  );
+  assert.equal(
+    new Set(result.violations.map(({ repoPath }) => repoPath)).size,
+    result.violations.length,
+  );
+  assert.equal(
+    result.violations.every(
+      (violation) => violation.kind === "runtime-export-ownership",
+    ),
+    true,
+  );
+  assert.equal(
+    result.violations.some(({ repoPath }) =>
+      [
+        "src/features/export-boundary.test.ts",
+        "src/features/safe-root-type-import.ts",
+        "e2e/test-support/export-fixture.ts",
+      ].includes(repoPath),
+    ),
+    false,
+  );
+});

package/templates/starter/scripts/toolcraft-typescript-analysis.d.mts

@@ -0,0 +1,73 @@
+import type ts from "typescript";
+
+export type ToolcraftTypeScriptImportedBinding = Readonly<{
+  importedName: string;
+  localName: string;
+  specifier: string;
+}>;
+
+export type ToolcraftTypeScriptImportedCallTarget = Readonly<{
+  callerCallableId: string | null;
+  callerExportNames: readonly string[];
+  importedName: string;
+  localName: string;
+  memberPath: string;
+  operation: string;
+  specifier: string;
+}>;
+
+export type ToolcraftTypeScriptModuleBindings = Readonly<{
+  callables: unknown;
+  exportedCallableBindings: readonly Readonly<{
+    callableId: string;
+    exportedName: string;
+  }>[];
+  exportedRuntimeBindings: readonly string[];
+  importedBindingSymbols: readonly Readonly<{
+    binding: ToolcraftTypeScriptImportedBinding;
+    symbol: ts.Symbol;
+  }>[];
+  importedRuntimeBindings: readonly ToolcraftTypeScriptImportedBinding[];
+}>;
+
+export function createToolcraftTypeScriptChecker(
+  sourceFile: ts.SourceFile,
+  typescript: typeof ts,
+): ts.TypeChecker;
+
+export function collectToolcraftTypeScriptModuleBindings(
+  sourceFile: ts.SourceFile,
+  typescript: typeof ts,
+  checker?: ts.TypeChecker,
+  callables?: unknown,
+): ToolcraftTypeScriptModuleBindings;
+
+export function collectToolcraftTypeScriptCallTargets(input: Readonly<{
+  bindings: ToolcraftTypeScriptModuleBindings;
+  checker: ts.TypeChecker;
+  sourceFile: ts.SourceFile;
+  ts: typeof ts;
+}>): Readonly<{
+  importedCallTargets: readonly ToolcraftTypeScriptImportedCallTarget[];
+  localCallTargets: readonly Readonly<{
+    calleeCallableId: string;
+    callerCallableId: string;
+  }>[];
+}>;
+
+export function getToolcraftTypeScriptImportedCallTarget(input: Readonly<{
+  bindings: ToolcraftTypeScriptModuleBindings;
+  checker: ts.TypeChecker;
+  expression: ts.Expression;
+  ts: typeof ts;
+}>):
+  | Omit<
+      ToolcraftTypeScriptImportedCallTarget,
+      "callerCallableId" | "callerExportNames"
+    >
+  | undefined;
+
+export function unwrapToolcraftTypeScriptExpression(
+  node: ts.Expression,
+  typescript: typeof ts,
+): ts.Expression;

package/templates/starter/scripts/toolcraft-typescript-source-evidence-structure.test.mjs

@@ -41,4 +41,24 @@ test("keeps TypeScript parsing and boundary facts on one canonical path", async
   assert.deepEqual(checkerOwners, [
     "toolcraft-typescript-analysis.mjs",
   ]);
+
+  const productBoundarySource = await fs.readFile(
+    path.join(scriptsDir, "toolcraft-product-boundary-ast.mjs"),
+    "utf8",
+  );
+  const controlBoundarySource = await fs.readFile(
+    path.join(scriptsDir, "toolcraft-product-control-boundary.mjs"),
+    "utf8",
+  );
+  const modulePolicySource = await fs.readFile(
+    path.join(scriptsDir, "toolcraft-product-boundary-module-policy.mjs"),
+    "utf8",
+  );
+
+  assert.match(productBoundarySource, /createToolcraftProductControlInspector/u);
+  assert.match(
+    modulePolicySource,
+    /isToolcraftPrivateControlImplementationModule/u,
+  );
+  assert.doesNotMatch(controlBoundarySource, /(?:ts\.)?createSourceFile\(/u);
 });

package/templates/starter/scripts/toolcraft-typescript-source-evidence.mjs

@@ -300,6 +300,7 @@ export async function createToolcraftTypeScriptSourceRecord({
     inspectors.createToolcraftStaticStringResolver(sourceFile, checker);
   const inspectorInput = {
     absolutePath,
+    checker,
     getNodeLocation,
     repoPath,
     resolveStaticString,