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

package/src/eslint-rules/app-start-registry-match.cjs

@@ -0,0 +1,355 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  IndentationText,
+  Node,
+  Project,
+  QuoteKind,
+  SyntaxKind,
+} = require('ts-morph');
+
+const projectCache = new Map();
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ensure craftService definitions using onAppStart are registered in CraftAppStartRegistry.',
+    },
+    fixable: 'code',
+    schema: [],
+  },
+  create(context) {
+    return {
+      'Program:exit'() {
+        const sourceCode = context.sourceCode ?? context.getSourceCode();
+        const filePath = getFilePath(context);
+        if (!filePath || !filePath.endsWith('.ts')) {
+          return;
+        }
+
+        const text = sourceCode.getText();
+        if (!text.includes('onAppStart')) {
+          return;
+        }
+
+        const sourceFile = getProjectSourceFile(
+          getProject(getCwd(context)),
+          filePath,
+          text,
+        );
+        const requiredRegistrations = collectRequiredRegistrations(sourceFile);
+        if (requiredRegistrations.length === 0) {
+          return;
+        }
+
+        const registryState = analyzeRegistryState(
+          sourceFile,
+          requiredRegistrations,
+        );
+        if (
+          registryState.missing.length === 0 &&
+          registryState.outOfDate.length === 0
+        ) {
+          return;
+        }
+
+        ensureRegistryEntries(sourceFile, requiredRegistrations);
+        const fixedText = sourceFile.getFullText();
+        if (fixedText === text) {
+          return;
+        }
+
+        context.report({
+          loc: getNodeLoc(sourceCode, registryState.reportNode),
+          message: formatRegistryMessage(registryState),
+          fix(fixer) {
+            return fixer.replaceTextRange([0, text.length], fixedText);
+          },
+        });
+      },
+    };
+  },
+};
+
+function getProject(cwd) {
+  let project = projectCache.get(cwd);
+  if (project) {
+    return project;
+  }
+
+  const manipulationSettings = {
+    indentationText: IndentationText.TwoSpaces,
+    quoteKind: QuoteKind.Single,
+  };
+  const tsConfigFilePath = path.join(cwd, 'tsconfig.json');
+  project = fs.existsSync(tsConfigFilePath)
+    ? new Project({
+        tsConfigFilePath,
+        manipulationSettings,
+      })
+    : new Project({
+        compilerOptions: {
+          experimentalDecorators: true,
+          target: 9,
+        },
+        manipulationSettings,
+      });
+
+  projectCache.set(cwd, project);
+  return project;
+}
+
+function getProjectSourceFile(project, filePath, text) {
+  const normalizedPath = path.resolve(filePath);
+  const existingSourceFile = project.getSourceFile(normalizedPath);
+  if (existingSourceFile) {
+    existingSourceFile.replaceWithText(text);
+    return existingSourceFile;
+  }
+
+  const sourceFile = project.addSourceFileAtPathIfExists(normalizedPath);
+  if (sourceFile) {
+    sourceFile.replaceWithText(text);
+    return sourceFile;
+  }
+
+  return project.createSourceFile(normalizedPath, text, { overwrite: true });
+}
+
+function getFilePath(context) {
+  const filePath = context.filename ?? context.getFilename();
+  if (!filePath || filePath === '<input>') {
+    return undefined;
+  }
+
+  return filePath;
+}
+
+function getCwd(context) {
+  return context.cwd ?? process.cwd();
+}
+
+function collectRequiredRegistrations(sourceFile) {
+  const registrations = new Map();
+
+  for (const declaration of sourceFile.getVariableDeclarations()) {
+    const initializer = declaration.getInitializerIfKind(
+      SyntaxKind.CallExpression,
+    );
+    if (!initializer || getCallExpressionName(initializer) !== 'craftService') {
+      continue;
+    }
+
+    if (!containsOnAppStartCall(initializer)) {
+      continue;
+    }
+
+    const tag = readCraftServiceName(initializer);
+    const serviceReference = readServiceReferenceName(declaration, tag);
+    if (!tag || !serviceReference || registrations.has(tag)) {
+      continue;
+    }
+
+    registrations.set(tag, {
+      tag,
+      serviceReference,
+      reportNode: initializer,
+    });
+  }
+
+  return [...registrations.values()];
+}
+
+function getCallExpressionName(callExpression) {
+  const expression = callExpression.getExpression();
+  return Node.isIdentifier(expression) ? expression.getText() : undefined;
+}
+
+function containsOnAppStartCall(callExpression) {
+  return callExpression
+    .getDescendantsOfKind(SyntaxKind.CallExpression)
+    .some((innerCall) => getCallExpressionName(innerCall) === 'onAppStart');
+}
+
+function readCraftServiceName(callExpression) {
+  const [definitionArgument] = callExpression.getArguments();
+  if (
+    !definitionArgument ||
+    !Node.isObjectLiteralExpression(definitionArgument)
+  ) {
+    return undefined;
+  }
+
+  const nameProperty = definitionArgument
+    .getProperties()
+    .find(
+      (property) =>
+        Node.isPropertyAssignment(property) && property.getName() === 'name',
+    );
+  if (!nameProperty || !Node.isPropertyAssignment(nameProperty)) {
+    return undefined;
+  }
+
+  const initializer = nameProperty.getInitializer();
+  if (
+    !initializer ||
+    (!Node.isStringLiteral(initializer) &&
+      !Node.isNoSubstitutionTemplateLiteral(initializer))
+  ) {
+    return undefined;
+  }
+
+  return initializer.getLiteralText();
+}
+
+function readServiceReferenceName(declaration, serviceName) {
+  const nameNode = declaration.getNameNode();
+  if (!Node.isObjectBindingPattern(nameNode)) {
+    return undefined;
+  }
+
+  const bindingElement =
+    nameNode
+      .getElements()
+      .find((element) => element.getNameNode().getText() === serviceName) ??
+    (nameNode.getElements().length === 1
+      ? nameNode.getElements()[0]
+      : undefined);
+
+  return bindingElement?.getNameNode().getText();
+}
+
+function analyzeRegistryState(sourceFile, requiredRegistrations) {
+  const moduleDeclaration = getCraftCoreModuleDeclaration(sourceFile);
+  const registryInterface = moduleDeclaration?.getInterface(
+    'CraftAppStartRegistry',
+  );
+  const propertiesByName = new Map(
+    (registryInterface?.getProperties() ?? []).map((property) => [
+      readPropertyName(property),
+      property,
+    ]),
+  );
+  const missing = [];
+  const outOfDate = [];
+
+  for (const registration of requiredRegistrations) {
+    const property = propertiesByName.get(registration.tag);
+    if (!property) {
+      missing.push(registration.tag);
+      continue;
+    }
+
+    const currentType = normalizeText(property.getTypeNode()?.getText() ?? '');
+    const expectedType = normalizeText(
+      `typeof ${registration.serviceReference}`,
+    );
+    if (currentType !== expectedType) {
+      outOfDate.push(registration.tag);
+    }
+  }
+
+  return {
+    missing,
+    outOfDate,
+    reportNode: requiredRegistrations[0].reportNode,
+  };
+}
+
+function getCraftCoreModuleDeclaration(sourceFile) {
+  return sourceFile.getModules().find((moduleDeclaration) => {
+    const nameNode = moduleDeclaration.getNameNode();
+    return (
+      Node.isStringLiteral(nameNode) &&
+      nameNode.getLiteralText() === '@craft-ts/core'
+    );
+  });
+}
+
+function readPropertyName(property) {
+  const nameNode = property.getNameNode();
+  if (Node.isIdentifier(nameNode) || Node.isPrivateIdentifier(nameNode)) {
+    return nameNode.getText();
+  }
+
+  if (Node.isStringLiteral(nameNode) || Node.isNumericLiteral(nameNode)) {
+    return nameNode.getLiteralText();
+  }
+
+  return property.getName();
+}
+
+function ensureRegistryEntries(sourceFile, requiredRegistrations) {
+  const moduleDeclaration =
+    getCraftCoreModuleDeclaration(sourceFile) ??
+    sourceFile.addModule({
+      name: "'@craft-ts/core'",
+      hasDeclareKeyword: true,
+    });
+  const registryInterface =
+    moduleDeclaration.getInterface('CraftAppStartRegistry') ??
+    moduleDeclaration.addInterface({
+      name: 'CraftAppStartRegistry',
+    });
+  const propertiesByName = new Map(
+    registryInterface
+      .getProperties()
+      .map((property) => [readPropertyName(property), property]),
+  );
+
+  for (const registration of requiredRegistrations) {
+    const expectedType = `typeof ${registration.serviceReference}`;
+    const property = propertiesByName.get(registration.tag);
+    if (!property) {
+      registryInterface.addProperty({
+        name: formatPropertyName(registration.tag),
+        type: expectedType,
+      });
+      continue;
+    }
+
+    property.setType(expectedType);
+  }
+}
+
+function formatPropertyName(name) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : `'${name}'`;
+}
+
+function getNodeLoc(sourceCode, node) {
+  return {
+    start: sourceCode.getLocFromIndex(node.getStart()),
+    end: sourceCode.getLocFromIndex(node.getEnd()),
+  };
+}
+
+function formatRegistryMessage({ missing, outOfDate }) {
+  const segments = [];
+  if (missing.length > 0) {
+    segments.push(`missing ${formatNameList(missing)}`);
+  }
+
+  if (outOfDate.length > 0) {
+    segments.push(`out of date for ${formatNameList(outOfDate)}`);
+  }
+
+  return `CraftAppStartRegistry is ${segments.join(' and ')}. Run ESLint --fix on this file to register app-start services.`;
+}
+
+function formatNameList(names) {
+  if (names.length === 1) {
+    return names[0];
+  }
+
+  if (names.length === 2) {
+    return `${names[0]} and ${names[1]}`;
+  }
+
+  return `${names.slice(0, -1).join(', ')}, and ${names[names.length - 1]}`;
+}
+
+function normalizeText(text) {
+  return text.replace(/\s+/g, ' ').trim();
+}

package/src/eslint-rules/button-has-type.cjs

@@ -0,0 +1,50 @@
+'use strict';
+
+const { parseHyperscriptCall, hasProp } = require('./hyperscript-walk.cjs');
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require an explicit type on button() so it cannot silently submit a parent form.',
+    },
+    schema: [],
+    fixable: 'code',
+    messages: {
+      missingType:
+        'button() must set type ("button", "submit", or "reset"). Craft does not default it.',
+    },
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const call = parseHyperscriptCall(node);
+        if (!call || call.tag !== 'button') return;
+        if (hasProp(call.props, 'type')) return;
+        context.report({
+          node,
+          messageId: 'missingType',
+          fix(fixer) {
+            if (call.props && call.props.type === 'ObjectExpression') {
+              const open = call.props.range[0];
+              return fixer.insertTextAfterRange(
+                [open, open + 1],
+                " type: 'button',",
+              );
+            }
+            const firstArg = node.arguments[0];
+            if (firstArg) {
+              return fixer.insertTextBefore(firstArg, "{ type: 'button' }, ");
+            }
+            const paren = node.range[1] - 1;
+            return fixer.insertTextBeforeRange(
+              [paren, paren],
+              "{ type: 'button' }",
+            );
+          },
+        });
+      },
+    };
+  },
+};

package/src/eslint-rules/control-has-accessible-name.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+const { parseHyperscriptCall, hasAccessibleName, staticPropString } = require('./hyperscript-walk.cjs');
+
+const NAMED_CONTROLS = new Set(['button', 'a', 'textarea', 'select', 'svg']);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require an accessible name on buttons, links, labelled form controls, and interactive SVG.',
+    },
+    schema: [],
+    messages: {
+      missingName:
+        '<{{tag}}> must have an accessible name (text children, aria-label, aria-labelledby, or a <label>).',
+    },
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const call = parseHyperscriptCall(node);
+        if (!call || !call.tag) return;
+        if (call.tag === 'input') {
+          const type = staticPropString(call.props, 'type') ?? 'text';
+          if (type === 'hidden') return;
+          if (hasAccessibleName(call)) return;
+          // An input may be named by a sibling label[htmlFor] — checked by label-has-associated-control.
+          // Still require a name on the control itself when it is a button-like type.
+          if (type === 'button' || type === 'submit' || type === 'reset' || type === 'image') {
+            context.report({ node, messageId: 'missingName', data: { tag: `input[type=${type}]` } });
+          }
+          return;
+        }
+        if (!NAMED_CONTROLS.has(call.tag)) return;
+        if (call.tag === 'svg') {
+          const role = staticPropString(call.props, 'role');
+          const hasHandler =
+            call.props &&
+            call.props.properties.some(
+              (entry) =>
+                entry.type === 'Property' &&
+                ((entry.key.type === 'Identifier' &&
+                  (entry.key.name === 'click' || entry.key.name === 'onClick')) ||
+                  (entry.key.type === 'Literal' &&
+                    (entry.key.value === 'click' || entry.key.value === 'onClick'))),
+            );
+          if (role !== 'button' && role !== 'img' && !hasHandler) return;
+        }
+        if (hasAccessibleName(call)) return;
+        context.report({ node, messageId: 'missingName', data: { tag: call.tag } });
+      },
+    };
+  },
+};

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

@@ -0,0 +1,8 @@
+const { createNameMatchRule } = require('./craft-name-match-utils.cjs');
+
+module.exports = createNameMatchRule({
+  calleeName: 'craftComponent',
+  description:
+    'Ensure craftComponent(name, ...) is called with a string literal name matching the declared component.',
+  supportsObjectConfigForm: false,
+});

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

@@ -0,0 +1,63 @@
+const { createNameMatchRule } = require('./craft-name-match-utils.cjs');
+
+const namedRule = createNameMatchRule({
+  calleeName: 'craftComputed',
+  description:
+    'Require a matching craftComputed name outside insertion result objects; insertion keys provide the runtime name automatically.',
+  supportsObjectConfigForm: false,
+});
+
+module.exports = {
+  ...namedRule,
+  create(context) {
+    const listeners = namedRule.create(context);
+    return {
+      ...listeners,
+      CallExpression(node) {
+        if (isInsertionResultProperty(node)) return;
+        listeners.CallExpression?.(node);
+      },
+    };
+  },
+};
+
+function isInsertionResultProperty(node) {
+  const property = node.parent;
+  if (
+    property?.type !== 'Property' ||
+    property.value !== node ||
+    property.parent?.type !== 'ObjectExpression'
+  ) {
+    return false;
+  }
+
+  let current = property.parent;
+  while (current) {
+    if (
+      (current.type === 'ArrowFunctionExpression' ||
+        current.type === 'FunctionExpression') &&
+      current.parent?.type === 'CallExpression'
+    ) {
+      const callee = current.parent.callee;
+      const name =
+        callee.type === 'Identifier'
+          ? callee.name
+          : callee.type === 'MemberExpression' &&
+              !callee.computed &&
+              callee.property.type === 'Identifier'
+            ? callee.property.name
+            : undefined;
+      return Boolean(
+        name &&
+          (name.startsWith('insert') ||
+            name === 'craftPipe' ||
+            ['state', 'query', 'mutation', 'asyncProcess', 'queryParams'].includes(
+              name,
+            )),
+      );
+    }
+    if (current.type === 'Program') break;
+    current = current.parent;
+  }
+  return false;
+}

package/src/eslint-rules/craft-css-token-registry.cjs

@@ -0,0 +1,17 @@
+const { componentInfo, cssFacts } = require('./css-rule-utils.cjs');
+const registrations = new Map();
+module.exports = {
+  meta: { type: 'problem', schema: [], messages: { duplicate: '@property {{name}} is also registered by {{owner}}. A custom property may have only one owner.' } },
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    return { CallExpression(node) {
+      const info = componentInfo(context, sourceCode, node); if (!info?.css) return;
+      cssFacts(info.css).registered.forEach((name) => {
+        const previous = registrations.get(name);
+        if (previous && previous !== info.name) context.report({ node: info.styles?.value ?? info.stylesUrl.value, messageId: 'duplicate', data: { name, owner: previous } });
+        else registrations.set(name, info.name);
+      });
+    } };
+  },
+};
+

package/src/eslint-rules/craft-css-var-naming.cjs

@@ -0,0 +1,18 @@
+const { componentInfo, cssFacts, prefixes } = require('./css-rule-utils.cjs');
+module.exports = {
+  meta: { type: 'suggestion', schema: [], messages: { naming: '{{name}} must use the component namespace ({{expected}}).' } },
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    return { CallExpression(node) {
+      const info = componentInfo(context, sourceCode, node); if (!info?.css) return;
+      const accepted = prefixes(info.name); const facts = cssFacts(info.css);
+      const templateText = node.arguments[3] ? sourceCode.getText(node.arguments[3]) : '';
+      facts.declared.forEach((name) => {
+        const inheritedChildVariable = new RegExp(
+          `['\"]${name.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&')}['\"]\\s*:\\s*inherit\\b`,
+        ).test(templateText);
+        if (!inheritedChildVariable && ![...accepted].some((prefix) => name.startsWith(prefix))) context.report({ node: info.styles?.value ?? info.stylesUrl.value, messageId: 'naming', data: { name, expected: [...accepted].join(' or ') } });
+      });
+    } };
+  },
+};

package/src/eslint-rules/craft-css-vars-contract.cjs

@@ -0,0 +1,34 @@
+const { componentInfo, cssFacts } = require('./css-rule-utils.cjs');
+
+module.exports = {
+  meta: {
+    type: 'problem', schema: [],
+    messages: {
+      opaque: 'Craft component styles are dynamic and their CSS variable contract cannot be checked.',
+      missing: 'External styles use {{name}} but ComponentMeta.cssVars does not declare it.',
+      absent: 'External styles use CSS variables but ComponentMeta.cssVars is missing.',
+      unused: 'ComponentMeta.cssVars declares {{name}}, but the stylesheet never declares or consumes it.',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    return { CallExpression(node) {
+      const info = componentInfo(context, sourceCode, node);
+      if (!info || (!info.styles && !info.stylesUrl)) return;
+      if (info.opaque) return context.report({ node: info.styles?.value ?? info.stylesUrl.value, messageId: 'opaque' });
+      const facts = cssFacts(info.css);
+      if (info.external && facts.used.size && !info.cssVars) {
+        context.report({ node: info.stylesUrl.value, messageId: 'absent' });
+      }
+      if (info.cssVars) {
+        facts.used.forEach((name) => {
+          if (!info.contract.has(name)) context.report({ node: info.cssVars.value, messageId: 'missing', data: { name } });
+        });
+        info.contract.forEach((name) => {
+          if (!facts.used.has(name) && !facts.declared.has(name)) context.report({ node: info.cssVars.value, messageId: 'unused', data: { name } });
+        });
+      }
+    } };
+  },
+};
+

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

@@ -0,0 +1,8 @@
+const { createNameMatchRule } = require('./craft-name-match-utils.cjs');
+
+module.exports = createNameMatchRule({
+  calleeName: 'craftDirective',
+  description:
+    'Ensure craftDirective(name, ...) is called with a string literal name matching the declared directive.',
+  supportsObjectConfigForm: false,
+});

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

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