@pixel-point/toolcraft 0.0.14 → 0.0.15

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

@@ -0,0 +1,219 @@
+import ts from "typescript";
+import postcss from "postcss";
+import selectorParser from "postcss-selector-parser";
+
+function compoundNodeHasLocalClass(node) {
+  if (node.type === "class") return true;
+  if (node.type !== "pseudo") return false;
+
+  if ([":is", ":where"].includes(node.value)) {
+    return Boolean(
+      node.nodes?.length > 0 &&
+        node.nodes.every(
+          (branch) =>
+            branch.type === "selector" &&
+            selectorFirstCompoundHasLocalClass(branch),
+        ),
+    );
+  }
+
+  if (node.value !== ":local") return false;
+
+  let hasLocalClass = false;
+  node.walkClasses(() => {
+    hasLocalClass = true;
+  });
+  return hasLocalClass;
+}
+
+function selectorFirstCompoundHasLocalClass(selector) {
+  for (const node of selector.nodes) {
+    if (node.type === "combinator") break;
+    if (compoundNodeHasLocalClass(node)) return true;
+  }
+  return false;
+}
+
+function inspectSiblingEscapes(selector, reasons, displaySelector = selector) {
+  let currentCompoundHasLocalClass = false;
+  let pendingSiblingCombinator;
+
+  for (const node of selector.nodes) {
+    if (node.type === "combinator") {
+      if (pendingSiblingCombinator && !currentCompoundHasLocalClass) {
+        reasons.push(
+          `selector "${displaySelector}" escapes through sibling combinator ${pendingSiblingCombinator}`,
+        );
+      }
+
+      const combinator = node.value.trim();
+      pendingSiblingCombinator =
+        combinator === "+" || combinator === "~" ? combinator : undefined;
+      currentCompoundHasLocalClass = false;
+      continue;
+    }
+
+    if (compoundNodeHasLocalClass(node)) {
+      currentCompoundHasLocalClass = true;
+    }
+
+    if (node.type === "pseudo") {
+      for (const branch of node.nodes ?? []) {
+        if (branch.type === "selector") {
+          inspectSiblingEscapes(branch, reasons, displaySelector);
+        }
+      }
+    }
+  }
+
+  if (pendingSiblingCombinator && !currentCompoundHasLocalClass) {
+    reasons.push(
+      `selector "${displaySelector}" escapes through sibling combinator ${pendingSiblingCombinator}`,
+    );
+  }
+}
+
+function getNodeLocation(sourceFile, node) {
+  const location = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  return { column: location.character + 1, line: location.line + 1 };
+}
+
+export function inspectToolcraftProductCss({ rawSource, repoPath }) {
+  const isCssModule = /\.module\.css$/iu.test(repoPath);
+  const reasons = [];
+
+  if (!isCssModule) reasons.push("the file is not a CSS Module");
+
+  try {
+    const root = postcss.parse(rawSource, { from: repoPath });
+    root.walkAtRules("import", () => {
+      reasons.push("CSS @import can pull unscoped styles into the product bundle");
+    });
+    root.walkRules((rule) => {
+      selectorParser((selectors) => {
+        selectors.each((selector) => {
+          inspectSiblingEscapes(selector, reasons);
+
+          selector.walk((node) => {
+            if (node.type === "pseudo" && node.value === ":global") {
+              reasons.push(`selector "${selector}" uses :global`);
+            }
+            if (
+              (node.type === "tag" && ["body", "html"].includes(node.value.toLowerCase())) ||
+              (node.type === "id" && node.value === "root") ||
+              (node.type === "pseudo" && node.value === ":root")
+            ) {
+              reasons.push(`selector "${selector}" targets a document root`);
+            }
+            if (
+              node.type === "attribute" &&
+              ((node.attribute === "data-slot" && /^toolcraft-/u.test(node.value ?? "")) ||
+                (node.attribute.startsWith("data-toolcraft-") &&
+                  !["data-toolcraft-product-output", "data-toolcraft-product-text"].includes(
+                    node.attribute,
+                  )))
+            ) {
+              reasons.push(`selector "${selector}" targets a Toolcraft host attribute`);
+            }
+          });
+
+          if (!selectorFirstCompoundHasLocalClass(selector)) {
+            reasons.push(`selector "${selector}" is not anchored to a local class`);
+          }
+        });
+      }).processSync(rule.selector);
+    });
+  } catch (error) {
+    reasons.push(
+      `CSS could not be parsed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  if (reasons.length === 0) return [];
+
+  return [{
+    column: 1,
+    kind: "product-global-css",
+    line: 1,
+    message:
+      `Product styles must use selector-local *.module.css rules and must not escape into the signed Toolcraft host. ${[...new Set(reasons)].join("; ")}.`,
+    repoPath,
+  }];
+}
+
+export function inspectToolcraftProductStyleNode({
+  node,
+  repoPath,
+  resolveStaticString,
+  sourceFile,
+}) {
+  const violations = [];
+  const isStyleElement =
+    (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) &&
+    node.tagName.getText(sourceFile) === "style";
+  const createsStyleElement =
+    ts.isCallExpression(node) &&
+    ts.isPropertyAccessExpression(node.expression) &&
+    node.expression.name.text === "createElement" &&
+    node.arguments[0] &&
+    ts.isStringLiteralLike(node.arguments[0]) &&
+    node.arguments[0].text.toLowerCase() === "style";
+  const createsStyleSheet =
+    ts.isNewExpression(node) &&
+    ts.isIdentifier(node.expression) &&
+    node.expression.text === "CSSStyleSheet";
+
+  if (isStyleElement || createsStyleElement || createsStyleSheet) {
+    violations.push({
+      ...getNodeLocation(sourceFile, node),
+      kind: "global-style-injection",
+      message:
+        "Product source must not inject global style elements or stylesheets. Use a local *.module.css file so product styling cannot modify the signed Toolcraft host.",
+      repoPath,
+    });
+  }
+
+  let styleModuleSpecifier;
+  let styleModuleNode;
+  if (
+    (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+    node.moduleSpecifier &&
+    ts.isStringLiteralLike(node.moduleSpecifier)
+  ) {
+    styleModuleSpecifier = node.moduleSpecifier.text;
+    styleModuleNode = node.moduleSpecifier;
+  } else if (
+    ts.isImportEqualsDeclaration(node) &&
+    ts.isExternalModuleReference(node.moduleReference) &&
+    node.moduleReference.expression &&
+    ts.isStringLiteralLike(node.moduleReference.expression)
+  ) {
+    styleModuleSpecifier = node.moduleReference.expression.text;
+    styleModuleNode = node.moduleReference.expression;
+  } else if (
+    ts.isCallExpression(node) &&
+    (node.expression.kind === ts.SyntaxKind.ImportKeyword ||
+      (ts.isIdentifier(node.expression) && node.expression.text === "require")) &&
+    node.arguments.length > 0
+  ) {
+    styleModuleSpecifier = resolveStaticString?.(node.arguments[0]);
+    styleModuleNode = node.arguments[0];
+  }
+
+  if (
+    styleModuleSpecifier &&
+    /\.(?:css|less|sass|scss|styl|stylus)(?:\?|$)/iu.test(styleModuleSpecifier) &&
+    (!/\.module\.css(?:\?|$)/iu.test(styleModuleSpecifier) ||
+      !/^(?:\.|@\/|#\/|\/src\/)/u.test(styleModuleSpecifier))
+  ) {
+    violations.push({
+      ...getNodeLocation(sourceFile, styleModuleNode),
+      kind: "product-global-css-import",
+      message:
+        "Product source may import only local *.module.css styles. Package or plain CSS imports can restyle the signed Toolcraft host.",
+      repoPath,
+    });
+  }
+
+  return violations;
+}

package/templates/starter/scripts/toolcraft-source-inventory.d.mts

@@ -0,0 +1,46 @@
+export type ToolcraftSourceOwner = "framework" | "platform" | "product";
+export type ToolcraftSourceRole = "generated" | "production" | "test" | "test-support";
+
+export type ToolcraftSourceInventoryEntry = {
+  absolutePath: string;
+  owner: ToolcraftSourceOwner;
+  repoPath: string;
+  role: ToolcraftSourceRole;
+};
+
+export type ToolcraftSourceFilesystemViolation = {
+  reason: string;
+  repoPath: string;
+};
+
+export type ToolcraftSourceInventory = {
+  entries: ToolcraftSourceInventoryEntry[];
+  filesystemViolations: ToolcraftSourceFilesystemViolation[];
+};
+
+export type ToolcraftSourceInventoryOptions = {
+  frameworkPathPrefixes?: readonly string[];
+  generatedFilePatterns?: readonly RegExp[];
+  ignoredFilePatterns?: readonly RegExp[];
+  protectedFilePaths?: readonly string[];
+  rootDir: string;
+  sourceExtensions?: ReadonlySet<string>;
+  sourceRoots?: readonly string[];
+  testFilePatterns?: readonly RegExp[];
+  testSupportPatterns?: readonly RegExp[];
+};
+
+export const toolcraftSourceExtensions: ReadonlySet<string>;
+
+export function classifyToolcraftSourcePath(
+  repoPath: string,
+  options?: Omit<ToolcraftSourceInventoryOptions, "rootDir" | "sourceRoots">,
+): { owner: ToolcraftSourceOwner; role: ToolcraftSourceRole };
+
+export function collectToolcraftSourceInventorySync(
+  options: ToolcraftSourceInventoryOptions,
+): ToolcraftSourceInventory;
+
+export function collectToolcraftSourceInventory(
+  options: ToolcraftSourceInventoryOptions,
+): Promise<ToolcraftSourceInventory>;

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

@@ -0,0 +1,187 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const toolcraftSourceExtensions = new Set([
+  ".cjs",
+  ".css",
+  ".cts",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".mts",
+  ".ts",
+  ".tsx",
+]);
+
+const defaultGeneratedFilePatterns = [/\/route-tree\.gen\.ts$/u];
+const defaultTestFilePatterns = [
+  /(?:^|\/)[^/]+\.(?:test|spec)\.[cm]?[jt]sx?$/u,
+];
+const defaultTestSupportPatterns = [
+  /^e2e\//u,
+  /(?:^|\/)test-evidence\//u,
+  /(?:^|\/)[^/]*(?:test-utils|fixtures)\.[cm]?[jt]sx?$/u,
+];
+
+function toPosixPath(value) {
+  return value.split(path.sep).join("/");
+}
+
+function compareCodeUnits(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function matchesAny(repoPath, patterns) {
+  return patterns.some((pattern) => {
+    pattern.lastIndex = 0;
+    return pattern.test(repoPath);
+  });
+}
+
+function normalizePrefix(prefix) {
+  const normalized = toPosixPath(prefix).replace(/^\.\//u, "");
+  return normalized.endsWith("/") ? normalized : `${normalized}/`;
+}
+
+export function classifyToolcraftSourcePath(
+  repoPath,
+  {
+    frameworkPathPrefixes = ["src/toolcraft/"],
+    generatedFilePatterns = defaultGeneratedFilePatterns,
+    protectedFilePaths = [],
+    testFilePatterns = defaultTestFilePatterns,
+    testSupportPatterns = defaultTestSupportPatterns,
+  } = {},
+) {
+  const normalizedPath = toPosixPath(repoPath).replace(/^\.\//u, "");
+  const protectedPathSet = new Set(
+    protectedFilePaths.map((filePath) =>
+      toPosixPath(filePath).replace(/^\.\//u, ""),
+    ),
+  );
+  const normalizedFrameworkPrefixes = frameworkPathPrefixes.map(normalizePrefix);
+
+  const owner = protectedPathSet.has(normalizedPath)
+    ? "platform"
+    : normalizedFrameworkPrefixes.some((prefix) =>
+          normalizedPath.startsWith(prefix),
+        )
+      ? "framework"
+      : "product";
+  const role = matchesAny(normalizedPath, generatedFilePatterns)
+    ? "generated"
+    : matchesAny(normalizedPath, testFilePatterns)
+      ? "test"
+      : matchesAny(normalizedPath, testSupportPatterns)
+        ? "test-support"
+        : "production";
+
+  return { owner, role };
+}
+
+export function collectToolcraftSourceInventorySync({
+  frameworkPathPrefixes = ["src/toolcraft/"],
+  generatedFilePatterns = defaultGeneratedFilePatterns,
+  ignoredFilePatterns = [],
+  protectedFilePaths = [],
+  rootDir,
+  sourceExtensions = toolcraftSourceExtensions,
+  sourceRoots = ["src"],
+  testFilePatterns = defaultTestFilePatterns,
+  testSupportPatterns = defaultTestSupportPatterns,
+}) {
+  const entriesByRepoPath = new Map();
+  const filesystemViolationsByRepoPath = new Map();
+
+  function recordSymbolicLink(repoPath) {
+    filesystemViolationsByRepoPath.set(repoPath, {
+      reason:
+        "Symbolic links can move checked source outside the Toolcraft source boundary.",
+      repoPath,
+    });
+  }
+
+  function visit(directory) {
+    let entries;
+
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        return;
+      }
+      throw error;
+    }
+
+    for (const entry of entries) {
+      const absolutePath = path.join(directory, entry.name);
+      const repoPath = toPosixPath(path.relative(rootDir, absolutePath));
+
+      if (entry.isSymbolicLink()) {
+        recordSymbolicLink(repoPath);
+        continue;
+      }
+
+      if (matchesAny(repoPath, ignoredFilePatterns)) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        visit(absolutePath);
+        continue;
+      }
+
+      if (!entry.isFile() || !sourceExtensions.has(path.extname(entry.name))) {
+        continue;
+      }
+
+      const classification = classifyToolcraftSourcePath(repoPath, {
+        frameworkPathPrefixes,
+        generatedFilePatterns,
+        protectedFilePaths,
+        testFilePatterns,
+        testSupportPatterns,
+      });
+
+      entriesByRepoPath.set(repoPath, {
+        absolutePath,
+        repoPath,
+        ...classification,
+      });
+    }
+  }
+
+  for (const sourceRoot of sourceRoots) {
+    const absoluteSourceRoot = path.join(rootDir, sourceRoot);
+    let sourceRootStat;
+
+    try {
+      sourceRootStat = fs.lstatSync(absoluteSourceRoot);
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      throw error;
+    }
+
+    if (sourceRootStat.isSymbolicLink()) {
+      recordSymbolicLink(
+        toPosixPath(path.relative(rootDir, absoluteSourceRoot)),
+      );
+      continue;
+    }
+
+    visit(absoluteSourceRoot);
+  }
+
+  return {
+    entries: [...entriesByRepoPath.values()].sort((left, right) =>
+      compareCodeUnits(left.repoPath, right.repoPath),
+    ),
+    filesystemViolations: [...filesystemViolationsByRepoPath.values()].sort(
+      (left, right) => compareCodeUnits(left.repoPath, right.repoPath),
+    ),
+  };
+}
+
+export async function collectToolcraftSourceInventory(options) {
+  return collectToolcraftSourceInventorySync(options);
+}

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

@@ -0,0 +1,132 @@
+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 {
+  classifyToolcraftSourcePath,
+  collectToolcraftSourceInventory,
+  collectToolcraftSourceInventorySync,
+} from "./toolcraft-source-inventory.mjs";
+
+test("classifies platform, framework, product, test, and generated source", () => {
+  const options = {
+    protectedFilePaths: ["src/main.tsx", "src/routes/index.tsx"],
+  };
+
+  assert.deepEqual(classifyToolcraftSourcePath("src/main.tsx", options), {
+    owner: "platform",
+    role: "production",
+  });
+  assert.deepEqual(
+    classifyToolcraftSourcePath("src/toolcraft/runtime/react/index.ts", options),
+    { owner: "framework", role: "production" },
+  );
+  assert.deepEqual(
+    classifyToolcraftSourcePath("src/features/renderer.tsx", options),
+    { owner: "product", role: "production" },
+  );
+  assert.deepEqual(
+    classifyToolcraftSourcePath("src/features/renderer.test.tsx", options),
+    { owner: "product", role: "test" },
+  );
+  assert.deepEqual(
+    classifyToolcraftSourcePath("src/features/renderer-test-utils.ts", options),
+    { owner: "product", role: "test-support" },
+  );
+  assert.deepEqual(
+    classifyToolcraftSourcePath("src/features/renderer.fixtures.ts", options),
+    { owner: "product", role: "test-support" },
+  );
+  assert.deepEqual(
+    classifyToolcraftSourcePath("src/routes/route-tree.gen.ts", options),
+    { owner: "product", role: "generated" },
+  );
+});
+
+test("collects each source path once and rejects symbolic links", async (context) => {
+  const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-inventory-"));
+  context.after(() => fs.rm(rootDir, { force: true, recursive: true }));
+
+  await fs.mkdir(path.join(rootDir, "src/features"), { recursive: true });
+  await fs.writeFile(path.join(rootDir, "src/main.tsx"), "export {};\n");
+  await fs.writeFile(
+    path.join(rootDir, "src/features/renderer.tsx"),
+    "export function Renderer() { return null; }\n",
+  );
+  await fs.symlink(
+    path.join(rootDir, "src/features/renderer.tsx"),
+    path.join(rootDir, "src/features/renderer-link.tsx"),
+  );
+  await fs.symlink(
+    path.join(rootDir, "src/features/renderer.tsx"),
+    path.join(rootDir, "src/features/ignored-link.tsx"),
+  );
+
+  const inventory = await collectToolcraftSourceInventory({
+    ignoredFilePatterns: [/ignored-link/u],
+    protectedFilePaths: ["src/main.tsx"],
+    rootDir,
+    sourceRoots: ["src", "src/features"],
+  });
+
+  assert.deepEqual(
+    inventory.entries.map(({ owner, repoPath, role }) => ({ owner, repoPath, role })),
+    [
+      { owner: "product", repoPath: "src/features/renderer.tsx", role: "production" },
+      { owner: "platform", repoPath: "src/main.tsx", role: "production" },
+    ],
+  );
+  assert.deepEqual(inventory.filesystemViolations, [
+    {
+      reason:
+        "Symbolic links can move checked source outside the Toolcraft source boundary.",
+      repoPath: "src/features/ignored-link.tsx",
+    },
+    {
+      reason:
+        "Symbolic links can move checked source outside the Toolcraft source boundary.",
+      repoPath: "src/features/renderer-link.tsx",
+    },
+  ]);
+
+  assert.deepEqual(
+    collectToolcraftSourceInventorySync({
+      ignoredFilePatterns: [/ignored-link/u],
+      protectedFilePaths: ["src/main.tsx"],
+      rootDir,
+      sourceRoots: ["src", "src/features"],
+    }),
+    inventory,
+  );
+});
+
+test("rejects a symbolic link used as a configured source root", async (context) => {
+  const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-inventory-root-"));
+  context.after(() => fs.rm(rootDir, { force: true, recursive: true }));
+
+  await fs.mkdir(path.join(rootDir, "outside-source"), { recursive: true });
+  await fs.writeFile(
+    path.join(rootDir, "outside-source/product.ts"),
+    "export const product = true;\n",
+  );
+  await fs.symlink(
+    path.join(rootDir, "outside-source"),
+    path.join(rootDir, "linked-source"),
+  );
+
+  const inventory = collectToolcraftSourceInventorySync({
+    rootDir,
+    sourceRoots: ["linked-source"],
+  });
+
+  assert.deepEqual(inventory.entries, []);
+  assert.deepEqual(inventory.filesystemViolations, [
+    {
+      reason:
+        "Symbolic links can move checked source outside the Toolcraft source boundary.",
+      repoPath: "linked-source",
+    },
+  ]);
+});