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

package/src/eslint-rules/craft-name-match-utils.cjs

@@ -0,0 +1,179 @@
+function createNameMatchRule({
+  calleeName,
+  description,
+  supportsObjectConfigForm = false,
+}) {
+  return {
+    meta: {
+      type: 'problem',
+      docs: { description },
+      fixable: 'code',
+      schema: [],
+      messages: {
+        missingName: `${calleeName} must be called with a string literal name matching '{{declaredName}}' as the first argument.`,
+        mismatchedName: `${calleeName} first argument '{{actual}}' must match the declared name '{{declaredName}}'.`,
+      },
+    },
+    create(context) {
+      const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+      return {
+        CallExpression(node) {
+          if (
+            node.callee.type !== 'Identifier' ||
+            node.callee.name !== calleeName
+          ) {
+            return;
+          }
+
+          const declaredName = getDeclaredName(node);
+          if (!declaredName) {
+            return;
+          }
+
+          const firstArg = node.arguments[0];
+
+          if (!firstArg) {
+            context.report({
+              node,
+              messageId: 'missingName',
+              data: { declaredName },
+              fix(fixer) {
+                const openParen = sourceCode.getTokenAfter(
+                  node.callee,
+                  (token) => token.type === 'Punctuator' && token.value === '(',
+                );
+                if (!openParen) return null;
+                return fixer.insertTextAfter(openParen, `'${declaredName}'`);
+              },
+            });
+            return;
+          }
+
+          if (supportsObjectConfigForm && firstArg.type === 'ObjectExpression') {
+            const nameProp = firstArg.properties.find(
+              (p) =>
+                p.type === 'Property' &&
+                !p.computed &&
+                p.key.type === 'Identifier' &&
+                p.key.name === 'name',
+            );
+            if (!nameProp) {
+              context.report({
+                node: firstArg,
+                messageId: 'missingName',
+                data: { declaredName },
+              });
+              return;
+            }
+            const nameValue = nameProp.value;
+            if (isStringLiteral(nameValue)) {
+              const actual = getStringLiteralValue(nameValue);
+              if (actual === declaredName) {
+                return;
+              }
+              context.report({
+                node: nameValue,
+                messageId: 'mismatchedName',
+                data: { declaredName, actual },
+                fix(fixer) {
+                  return fixer.replaceText(nameValue, `'${declaredName}'`);
+                },
+              });
+            } else {
+              context.report({
+                node: nameValue,
+                messageId: 'mismatchedName',
+                data: { declaredName, actual: sourceCode.getText(nameValue) },
+              });
+            }
+            return;
+          }
+
+          if (isStringLiteral(firstArg)) {
+            const actual = getStringLiteralValue(firstArg);
+            if (actual === declaredName) {
+              return;
+            }
+            context.report({
+              node: firstArg,
+              messageId: 'mismatchedName',
+              data: { declaredName, actual },
+              fix(fixer) {
+                return fixer.replaceText(firstArg, `'${declaredName}'`);
+              },
+            });
+            return;
+          }
+
+          context.report({
+            node: firstArg,
+            messageId: 'missingName',
+            data: { declaredName },
+            fix(fixer) {
+              return fixer.insertTextBefore(firstArg, `'${declaredName}', `);
+            },
+          });
+        },
+      };
+    },
+  };
+}
+
+function getDeclaredName(callNode) {
+  const parent = callNode.parent;
+  if (!parent) return undefined;
+
+  if (
+    parent.type === 'VariableDeclarator' &&
+    parent.init === callNode &&
+    parent.id.type === 'Identifier'
+  ) {
+    return parent.id.name;
+  }
+
+  if (
+    parent.type === 'PropertyDefinition' &&
+    parent.value === callNode &&
+    !parent.computed &&
+    parent.key.type === 'Identifier'
+  ) {
+    return parent.key.name;
+  }
+
+  if (
+    parent.type === 'Property' &&
+    parent.value === callNode &&
+    !parent.computed &&
+    parent.key.type === 'Identifier' &&
+    parent.parent &&
+    parent.parent.type === 'ObjectExpression'
+  ) {
+    return parent.key.name;
+  }
+
+  return undefined;
+}
+
+function isStringLiteral(node) {
+  if (node.type === 'Literal' && typeof node.value === 'string') {
+    return true;
+  }
+  if (
+    node.type === 'TemplateLiteral' &&
+    node.expressions.length === 0 &&
+    node.quasis.length === 1
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function getStringLiteralValue(node) {
+  if (node.type === 'Literal') {
+    return node.value;
+  }
+  return node.quasis[0].value.cooked;
+}
+
+module.exports = { createNameMatchRule };

package/src/eslint-rules/craft-primitive-context.cjs

@@ -0,0 +1,46 @@
+const PRIMITIVE_CALLS = new Set([
+  'asyncProcess',
+  'craftPipe',
+  'mutation',
+  'query',
+  'queryParams',
+  'state',
+]);
+
+/**
+ * Angular computed() remains valid while configuring a Craft primitive. Those
+ * computations are part of the primitive's tracked graph, not component
+ * orchestration logic.
+ */
+function isInsideCraftPrimitive(node) {
+  let current = node.parent;
+
+  while (current) {
+    if (
+      current.type === 'CallExpression' &&
+      isPrimitiveCallee(current.callee)
+    ) {
+      return true;
+    }
+
+    current = current.parent;
+  }
+
+  return false;
+}
+
+function isPrimitiveCallee(callee) {
+  if (callee.type === 'Identifier') {
+    return PRIMITIVE_CALLS.has(callee.name) || callee.name.startsWith('insert');
+  }
+
+  return (
+    callee.type === 'MemberExpression' &&
+    !callee.computed &&
+    callee.property.type === 'Identifier' &&
+    (PRIMITIVE_CALLS.has(callee.property.name) ||
+      callee.property.name.startsWith('insert'))
+  );
+}
+
+module.exports = { isInsideCraftPrimitive };

package/src/eslint-rules/craft-signal-source-name-match.cjs

@@ -0,0 +1,8 @@
+const { createNameMatchRule } = require('./craft-name-match-utils.cjs');
+
+module.exports = createNameMatchRule({
+  calleeName: 'signalSource',
+  description:
+    "Ensure signalSource(name, ...) is called with a string literal first argument that matches the declared variable, class property, or object property name.",
+  supportsObjectConfigForm: false,
+});

package/src/eslint-rules/craft-source-name-match.cjs

@@ -0,0 +1,8 @@
+const { createNameMatchRule } = require('./craft-name-match-utils.cjs');
+
+module.exports = createNameMatchRule({
+  calleeName: 'source$',
+  description:
+    "Ensure source$(name) is called with a string literal first argument that matches the declared variable, class property, or object property name.",
+  supportsObjectConfigForm: false,
+});

package/src/eslint-rules/craft-styles-scope-safe.cjs

@@ -0,0 +1,25 @@
+const { componentInfo, kebab } = require('./css-rule-utils.cjs');
+
+module.exports = {
+  meta: { type: 'problem', schema: [], messages: { unsafe: '{{message}}' } },
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    return { CallExpression(node) {
+      const info = componentInfo(context, sourceCode, node);
+      if (!info?.css) return;
+      const css = info.css;
+      const report = (message) => context.report({ node: info.styles?.value ?? info.stylesUrl.value, messageId: 'unsafe', data: { message } });
+      if (/@import\b/i.test(css)) report('@import is global; move it to the application stylesheet.');
+      if (/(^|})\s*(?::root\b|html\b|body\b)/im.test(css)) report(':root, html and body selectors are not allowed in component styles.');
+      for (const match of css.matchAll(/@(?:-webkit-)?keyframes\s+([\w-]+)/gi)) {
+        if (!match[1].startsWith(`${info.name}-`)) report(`@keyframes "${match[1]}" must be renamed "${info.name}-${match[1]}".`);
+      }
+      const prefix = `--${kebab(info.name)}-`;
+      for (const match of css.matchAll(/@property\s+(--[\w-]+)\s*\{([\s\S]*?)\}/gi)) {
+        if (!match[1].startsWith(prefix)) report(`@property "${match[1]}" is not owned by ${info.name}; expected ${prefix}*.`);
+        if (/inherits\s*:\s*false\b/i.test(match[2]) && css.includes(`var(${match[1]}`)) report(`@property "${match[1]}" uses inherits: false but participates in the component contract.`);
+      }
+    } };
+  },
+};
+

package/src/eslint-rules/css-rule-utils.cjs

@@ -0,0 +1,109 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+function property(object, name) {
+  return object?.type === 'ObjectExpression'
+    ? object.properties.find(
+        (entry) =>
+          entry.type === 'Property' &&
+          !entry.computed &&
+          ((entry.key.type === 'Identifier' && entry.key.name === name) ||
+            (entry.key.type === 'Literal' && entry.key.value === name)),
+      )
+    : undefined;
+}
+
+function staticString(node) {
+  if (node?.type === 'Literal' && typeof node.value === 'string') return node.value;
+  if (node?.type === 'TemplateLiteral' && node.expressions.length === 0) {
+    return node.quasis[0]?.value.cooked ?? '';
+  }
+  if (node?.type === 'ArrayExpression') {
+    const values = node.elements.map(staticString);
+    return values.every((value) => typeof value === 'string') ? values.join('\n') : undefined;
+  }
+  return undefined;
+}
+
+function resolveImportedCss(context, sourceCode, identifier) {
+  const declaration = sourceCode.ast.body.find(
+    (entry) =>
+      entry.type === 'ImportDeclaration' &&
+      entry.specifiers.some((specifier) => specifier.local.name === identifier),
+  );
+  if (!declaration || typeof declaration.source.value !== 'string') return undefined;
+  const filename = context.filename ?? context.getFilename();
+  if (!filename || filename === '<input>') return undefined;
+  try {
+    return fs.readFileSync(path.resolve(path.dirname(filename), declaration.source.value), 'utf8');
+  } catch {
+    return undefined;
+  }
+}
+
+function componentInfo(context, sourceCode, node) {
+  if (
+    node.callee.type !== 'Identifier' ||
+    node.callee.name !== 'craftComponent' ||
+    node.arguments.length < 2 ||
+    node.arguments[1].type !== 'ObjectExpression'
+  ) return undefined;
+  const name = staticString(node.arguments[0]);
+  if (!name) return undefined;
+  const meta = node.arguments[1];
+  const styles = property(meta, 'styles');
+  const stylesUrl = property(meta, 'stylesUrl');
+  const cssVars = property(meta, 'cssVars');
+  let css;
+  let opaque = false;
+  let external = false;
+  if (styles) {
+    css = staticString(styles.value);
+    opaque = css === undefined;
+  } else if (stylesUrl) {
+    external = true;
+    css = staticString(stylesUrl.value);
+    if (css === undefined && stylesUrl.value.type === 'Identifier') {
+      css = resolveImportedCss(context, sourceCode, stylesUrl.value.name);
+    }
+    opaque = css === undefined;
+  }
+  const contract = new Set();
+  if (cssVars?.value.type === 'ObjectExpression') {
+    for (const entry of cssVars.value.properties) {
+      if (entry.type !== 'Property') continue;
+      const key = entry.key.type === 'Identifier' ? entry.key.name : entry.key.value;
+      if (typeof key === 'string') contract.add(key);
+    }
+  }
+  return { name, meta, styles, stylesUrl, cssVars, css, opaque, external, contract };
+}
+
+function cssFacts(css = '') {
+  const used = new Set([...css.matchAll(/var\(\s*(--[\w-]+)/g)].map((match) => match[1]));
+  const fallback = new Set(
+    [...css.matchAll(/var\(\s*(--[\w-]+)\s*,/g)].map((match) => match[1]),
+  );
+  const declared = new Set([...css.matchAll(/(--[\w-]+)\s*:/g)].map((match) => match[1]));
+  const registered = new Set([...css.matchAll(/@property\s+(--[\w-]+)/g)].map((match) => match[1]));
+  registered.forEach((name) => declared.add(name));
+  return { used, fallback, declared, registered };
+}
+
+function kebab(value) {
+  return value
+    .replace(/Component$/, '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .toLowerCase();
+}
+
+function prefixes(name) {
+  const full = kebab(name);
+  const words = full.split('-');
+  return new Set([`--${full}-`, `--${words.at(-1)}-`]);
+}
+
+module.exports = { componentInfo, cssFacts, kebab, prefixes };
+