@craft-ts/dev-tools 0.7.0-beta.13

package/src/eslint-rules/require-route-heading-outline.cjs

@@ -0,0 +1,166 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { walk } = require('./hyperscript-walk.cjs');
+
+const ROUTES_FACTORY = 'craftRoutes';
+const HEADING_CALL = /\bheading\s*\(/;
+
+function propertyName(property) {
+  if (!property || property.computed) return undefined;
+  if (property.key.type === 'Identifier') return property.key.name;
+  if (property.key.type === 'Literal') return property.key.value;
+  return undefined;
+}
+
+function isCallNamed(node, name) {
+  return (
+    !!node &&
+    node.type === 'CallExpression' &&
+    node.callee.type === 'Identifier' &&
+    node.callee.name === name
+  );
+}
+
+function hasHeadingCall(node, sourceCode) {
+  let found = false;
+  walk(node, sourceCode, (candidate) => {
+    if (isCallNamed(candidate, 'heading')) {
+      found = true;
+      return 'skip';
+    }
+  });
+  return found;
+}
+
+function collectImportSpecifiers(node, sourceCode) {
+  const specifiers = [];
+  walk(node, sourceCode, (candidate) => {
+    if (candidate.type !== 'ImportExpression') return;
+    const source = candidate.source;
+    if (source.type === 'Literal' && typeof source.value === 'string') {
+      specifiers.push(source.value);
+      return;
+    }
+    if (
+      source.type === 'TemplateLiteral' &&
+      source.expressions.length === 0 &&
+      source.quasis.length === 1
+    ) {
+      specifiers.push(source.quasis[0].value.cooked);
+    }
+  });
+  return specifiers;
+}
+
+function fileExists(filePath) {
+  try {
+    return fs.existsSync(filePath) && fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function resolveImportedFile(fromFile, specifier) {
+  if (!fromFile || !specifier || !specifier.startsWith('.')) return undefined;
+  if (!fileExists(fromFile)) return undefined;
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  const candidates = [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    `${base}.js`,
+    path.join(base, 'index.ts'),
+    path.join(base, 'index.tsx'),
+  ];
+  return candidates.find((candidate) => fileExists(candidate));
+}
+
+function fileHasHeading(filePath) {
+  try {
+    return HEADING_CALL.test(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+function checkLoadFactory(context, sourceCode, factory, reportNode) {
+  if (!factory) return;
+  const specifiers = collectImportSpecifiers(factory, sourceCode);
+  if (specifiers.length > 0) {
+    const filename = context.filename ?? context.getFilename?.() ?? '';
+    for (const specifier of specifiers) {
+      const resolved = resolveImportedFile(filename, specifier);
+      if (!resolved) continue;
+      if (!fileHasHeading(resolved)) {
+        context.report({ node: reportNode, messageId: 'missing' });
+        return;
+      }
+    }
+    return;
+  }
+  if (hasHeadingCall(factory, sourceCode)) return;
+  if (
+    factory.type === 'ArrowFunctionExpression' ||
+    factory.type === 'FunctionExpression'
+  ) {
+    context.report({ node: reportNode, messageId: 'missing' });
+  }
+}
+
+function visitRouteConfig(context, sourceCode, node) {
+  if (!node) return;
+  if (node.type === 'ArrayExpression') {
+    for (const element of node.elements) {
+      visitRouteConfig(context, sourceCode, element);
+    }
+    return;
+  }
+  if (isCallNamed(node, 'craftRoute')) {
+    visitRouteConfig(context, sourceCode, node.arguments[1]);
+    return;
+  }
+  if (isCallNamed(node, 'loadCraftComponent')) {
+    checkLoadFactory(context, sourceCode, node.arguments[0], node);
+    return;
+  }
+  if (node.type !== 'ObjectExpression') return;
+  for (const prop of node.properties) {
+    if (prop.type === 'SpreadElement') {
+      visitRouteConfig(context, sourceCode, prop.argument);
+      continue;
+    }
+    if (prop.type !== 'Property') continue;
+    const name = propertyName(prop);
+    if (name === 'loadComponent') {
+      checkLoadFactory(context, sourceCode, prop.value, prop.value);
+    } else if (name === 'children') {
+      visitRouteConfig(context, sourceCode, prop.value);
+    }
+  }
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require each craftRoutes loadComponent SFC to call heading() (not headingRoot). Layouts wrap the outlet in headingSection; shells do not put heading() above the outlet.',
+    },
+    schema: [],
+    messages: {
+      missing:
+        'Route loadComponent must call heading(...). Layouts wrap CraftRouterOutlet in headingSection(...); shells must not put heading() above the outlet.',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    return {
+      CallExpression(node) {
+        if (!isCallNamed(node, ROUTES_FACTORY)) return;
+        visitRouteConfig(context, sourceCode, node.arguments[1]);
+      },
+    };
+  },
+};

package/src/eslint-rules/require-yieldable-insertion-write.cjs

@@ -0,0 +1,98 @@
+const WRITE_METHODS = new Set(['set', 'patch', 'update']);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require set, patch, and update insertion writes to be delegated with yield* inside generator functions.',
+    },
+    schema: [],
+    messages: {
+      requireYield:
+        'Insertion writes through set(...), patch(...), and update(...) must be delegated with `yield*` inside a generator function.',
+    },
+  },
+
+  create(context) {
+    const insertionWriteBindings = new Set();
+
+    return {
+      FunctionDeclaration: collectInsertionWriteBindings,
+      FunctionExpression: collectInsertionWriteBindings,
+      ArrowFunctionExpression: collectInsertionWriteBindings,
+
+      CallExpression(node) {
+        if (
+          !isInsideGeneratorFunction(node) ||
+          isDelegated(node) ||
+          !isInsertionWrite(node)
+        ) {
+          return;
+        }
+
+        context.report({ node, messageId: 'requireYield' });
+      },
+    };
+
+    function isInsertionWrite(node) {
+      const callee = node.callee;
+      if (callee.type === 'Identifier') {
+        return insertionWriteBindings.has(callee.name);
+      }
+      return false;
+    }
+
+    function collectInsertionWriteBindings(node) {
+      for (const parameter of node.params) {
+        if (parameter.type !== 'ObjectPattern') continue;
+
+        for (const property of parameter.properties) {
+          if (
+            property.type !== 'Property' ||
+            property.computed ||
+            property.key.type !== 'Identifier'
+          ) {
+            continue;
+          }
+
+          const key = property.key.name;
+          if (!WRITE_METHODS.has(key)) continue;
+
+          if (property.value.type === 'Identifier') {
+            insertionWriteBindings.add(property.value.name);
+          }
+        }
+      }
+    }
+
+  },
+};
+
+function isInsideGeneratorFunction(node) {
+  let current = node.parent;
+  while (current) {
+    if (current.type === 'ArrowFunctionExpression') return false;
+    if (
+      current.type === 'FunctionDeclaration' ||
+      current.type === 'FunctionExpression'
+    ) {
+      return current.generator === true;
+    }
+    current = current.parent;
+  }
+  return false;
+}
+
+function isDelegated(node) {
+  let parent = node.parent;
+  while (
+    parent &&
+    ['ChainExpression', 'TSAsExpression', 'TSTypeAssertion'].includes(
+      parent.type,
+    )
+  ) {
+    parent = parent.parent;
+  }
+  return parent?.type === 'YieldExpression' && parent.delegate === true;
+}

package/src/eslint-rules/require-yieldable-reactive-read.cjs

@@ -0,0 +1,102 @@
+const REACTIVE_VALUE_BRAND = 'RAW_REACTIVE_VALUE';
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require Craft reactive readers to be delegated with yield* inside generator functions.',
+    },
+    schema: [],
+    messages: {
+      requireYield:
+        'Craft reactive values must be read with `yield*` inside a generator function.',
+      requireGenerator:
+        'A function that reads a Craft reactive value must be a generator and delegate the read with `yield*`.',
+      missingTypeInfo:
+        'This rule requires TypeScript type information to identify Craft reactive readers.',
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    const parserServices = sourceCode.parserServices ?? context.parserServices;
+    const checker = parserServices?.program?.getTypeChecker?.();
+    const nodeMap = parserServices?.esTreeNodeToTSNodeMap;
+    let reportedMissingTypeInfo = false;
+
+    return {
+      Program() {
+        if (!checker || !nodeMap) {
+          context.report({
+            node: sourceCode.ast,
+            messageId: 'missingTypeInfo',
+          });
+          reportedMissingTypeInfo = true;
+        }
+      },
+      CallExpression(node) {
+        if (reportedMissingTypeInfo || !checker || !nodeMap) return;
+        if (isConsumed(node) || !isReactiveReader(node)) return;
+
+        const fn = nearestFunction(node);
+        context.report({
+          node,
+          messageId: fn?.generator ? 'requireYield' : 'requireGenerator',
+        });
+      },
+    };
+
+    function isReactiveReader(node) {
+      const tsNode = nodeMap.get(node.callee);
+      if (!tsNode) return false;
+      return hasBrand(checker.getTypeAtLocation(tsNode), new Set());
+    }
+
+    function hasBrand(type, seen) {
+      if (!type || seen.has(type)) return false;
+      seen.add(type);
+      if (type.isUnion?.() || type.isIntersection?.()) {
+        return type.types.some((part) => hasBrand(part, seen));
+      }
+      return checker
+        .getPropertiesOfType(type)
+        .some((property) =>
+          String(property.escapedName).includes(REACTIVE_VALUE_BRAND),
+        );
+    }
+  },
+};
+
+function isConsumed(node) {
+  let parent = node.parent;
+  while (
+    parent &&
+    ['ChainExpression', 'TSAsExpression', 'TSTypeAssertion'].includes(
+      parent.type,
+    )
+  ) {
+    parent = parent.parent;
+  }
+  if (parent?.type === 'YieldExpression' && parent.delegate) return true;
+  return (
+    parent?.type === 'CallExpression' &&
+    parent.callee.type === 'Identifier' &&
+    parent.callee.name === 'craftUse'
+  );
+}
+
+function nearestFunction(node) {
+  let current = node.parent;
+  while (current) {
+    if (
+      current.type === 'ArrowFunctionExpression' ||
+      current.type === 'FunctionExpression' ||
+      current.type === 'FunctionDeclaration'
+    ) {
+      return current;
+    }
+    current = current.parent;
+  }
+  return undefined;
+}