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

package/src/eslint-rules/no-throw.cjs

@@ -0,0 +1,132 @@
+const CORE_MODULE = '@craft-ts/core';
+const CRAFT_EXCEPTION_NAME = 'craftException';
+const DEFAULT_EXCEPTION_CODE = 'UNEXPECTED_ERROR';
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    fixable: 'code',
+    docs: {
+      description:
+        'Disallow throw statements in Craft code; return a craftException result instead.',
+    },
+    schema: [],
+    messages: {
+      throw:
+        "throw is forbidden in Craft code. Return craftException({ code: '{{code}}' }, ...) instead.",
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    let importFixClaimed = false;
+
+    return {
+      ThrowStatement(node) {
+        const report = {
+          node,
+          messageId: 'throw',
+          data: { code: DEFAULT_EXCEPTION_CODE },
+        };
+
+        if (canReturnFrom(node)) {
+          report.fix = (fixer) => {
+            const fixes = [
+              fixer.replaceText(node, toCraftExceptionReturn(node, sourceCode)),
+            ];
+
+            if (
+              !hasCraftExceptionBinding(node, sourceCode) &&
+              !importFixClaimed
+            ) {
+              importFixClaimed = true;
+              fixes.push(createImportFix(fixer, sourceCode));
+            }
+
+            return fixes;
+          };
+        }
+
+        context.report(report);
+      },
+    };
+  },
+};
+
+function canReturnFrom(node) {
+  let current = node.parent;
+  while (current) {
+    if (current.type === 'StaticBlock' || current.type === 'Program') {
+      return false;
+    }
+
+    if (
+      current.type === 'ArrowFunctionExpression' ||
+      current.type === 'FunctionDeclaration' ||
+      current.type === 'FunctionExpression'
+    ) {
+      return true;
+    }
+
+    current = current.parent;
+  }
+
+  return false;
+}
+
+function toCraftExceptionReturn(node, sourceCode) {
+  if (!node.argument) {
+    return `return craftException({ code: '${DEFAULT_EXCEPTION_CODE}' });`;
+  }
+
+  return `return craftException({ code: '${DEFAULT_EXCEPTION_CODE}' }, { error: ${sourceCode.getText(node.argument)} });`;
+}
+
+function hasCraftExceptionBinding(node, sourceCode) {
+  let scope = sourceCode.getScope(node);
+  while (scope) {
+    const variable = scope.variables.find(
+      (candidate) => candidate.name === CRAFT_EXCEPTION_NAME,
+    );
+    if (variable) {
+      return variable.defs.some((definition) => {
+        if (definition.type !== 'ImportBinding') return true;
+        return (
+          definition.node.importKind !== 'type' &&
+          definition.parent?.importKind !== 'type'
+        );
+      });
+    }
+    scope = scope.upper;
+  }
+
+  return false;
+}
+
+function createImportFix(fixer, sourceCode) {
+  const coreImport = sourceCode.ast.body.find(
+    (statement) =>
+      statement.type === 'ImportDeclaration' &&
+      statement.importKind !== 'type' &&
+      statement.source.value === CORE_MODULE,
+  );
+
+  if (
+    coreImport &&
+    coreImport.specifiers.some(
+      (specifier) =>
+        specifier.type === 'ImportSpecifier' && specifier.importKind !== 'type',
+    )
+  ) {
+    const lastSpecifier = coreImport.specifiers.at(-1);
+    return fixer.insertTextAfter(lastSpecifier, `, ${CRAFT_EXCEPTION_NAME}`);
+  }
+
+  const importText = `import { ${CRAFT_EXCEPTION_NAME} } from '${CORE_MODULE}';\n`;
+  const firstImport = sourceCode.ast.body.find(
+    (statement) => statement.type === 'ImportDeclaration',
+  );
+  return firstImport
+    ? fixer.insertTextBefore(firstImport, importText)
+    : fixer.insertTextBeforeRange([0, 0], importText);
+}

package/src/eslint-rules/no-transition-actions.cjs

@@ -0,0 +1,133 @@
+const CORE_PACKAGE = '@craft-ts/core';
+
+const TRANSITION_ACTIONS = new Map([
+  ['call', 'query.call'],
+  ['mutate', 'mutation.mutate'],
+  ['method', 'asyncProcess.method'],
+  ['restore', 'state.restore'],
+  ['emit', 'source$.emit'],
+]);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow imperative state, query, mutation, and asyncProcess actions inside craftStateMachine transitions.',
+    },
+    schema: [],
+    messages: {
+      forbidden:
+        'Imperative {{action}}(...) is forbidden inside a transitionStep. Derive a source and let the resource react to it instead.',
+    },
+  },
+
+  create(context) {
+    const transitionStepNames = new Set(['transitionStep']);
+    const namespaceNames = new Set();
+    const transitionCallbacks = [];
+
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value !== CORE_PACKAGE) return;
+
+        for (const specifier of node.specifiers) {
+          if (specifier.type === 'ImportSpecifier') {
+            const importedName = getIdentifierName(specifier.imported);
+            if (importedName === 'transitionStep') {
+              transitionStepNames.add(specifier.local.name);
+            }
+            continue;
+          }
+
+          if (specifier.type === 'ImportNamespaceSpecifier') {
+            namespaceNames.add(specifier.local.name);
+          }
+        }
+      },
+
+      CallExpression(node) {
+        if (!isTransitionStepCall(node)) return;
+
+        const callback = node.arguments.find(isFunction);
+        if (callback) transitionCallbacks.push(callback);
+      },
+
+      'Program:exit'() {
+        const reported = new Set();
+
+        for (const callback of transitionCallbacks) {
+          walk(callback.body, (node) => {
+            if (node.type !== 'CallExpression') return;
+
+            const action = getResourceAction(node);
+            if (!action || reported.has(node)) return;
+
+            reported.add(node);
+            context.report({
+              node,
+              messageId: 'forbidden',
+              data: { action },
+            });
+          });
+        }
+      },
+    };
+
+    function isTransitionStepCall(node) {
+      if (node.callee.type === 'Identifier') {
+        return transitionStepNames.has(node.callee.name);
+      }
+
+      return (
+        node.callee.type === 'MemberExpression' &&
+        !node.callee.computed &&
+        node.callee.object.type === 'Identifier' &&
+        namespaceNames.has(node.callee.object.name) &&
+        node.callee.property.type === 'Identifier' &&
+        node.callee.property.name === 'transitionStep'
+      );
+    }
+  },
+};
+
+function getResourceAction(node) {
+  if (node.callee.type !== 'MemberExpression') return undefined;
+
+  const property = node.callee.computed
+    ? node.callee.property.type === 'Literal'
+      ? String(node.callee.property.value)
+      : undefined
+    : node.callee.property.name;
+
+  const action = TRANSITION_ACTIONS.get(property);
+  return action;
+}
+
+function isFunction(node) {
+  return (
+    node &&
+    (node.type === 'FunctionExpression' ||
+      node.type === 'ArrowFunctionExpression')
+  );
+}
+
+function walk(node, visitor) {
+  if (!node || typeof node !== 'object') return;
+  if (node.type) visitor(node);
+
+  for (const [key, value] of Object.entries(node)) {
+    if (key === 'parent' || key === 'tokens' || key === 'comments') continue;
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (child && typeof child.type === 'string') walk(child, visitor);
+      }
+    } else if (value && typeof value.type === 'string') {
+      walk(value, visitor);
+    }
+  }
+}
+
+function getIdentifierName(node) {
+  return node.type === 'Identifier' ? node.name : undefined;
+}

package/src/eslint-rules/no-type-assertions-in-template.cjs

@@ -0,0 +1,211 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Forbid TypeScript type assertions while constructing a Craft component template.',
+    },
+    schema: [],
+    messages: {
+      forbidden:
+        'Do not use type assertions in a Craft template. Fix the type in the component logic or expose a correctly typed derived value.',
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    return {
+      CallExpression(node) {
+        if (
+          node.callee.type !== 'Identifier' ||
+          node.callee.name !== 'craftComponent' ||
+          node.arguments.length < 4
+        ) {
+          return;
+        }
+
+        inspectTemplate(node.arguments[3]);
+      },
+    };
+
+    function inspectTemplate(template) {
+      walk(template, (node) => {
+        if (node !== template && isNestedCraftComponent(node)) {
+          return 'skip';
+        }
+
+        if (isTemplatePipe(node)) {
+          return 'skip';
+        }
+
+        if (
+          node.type === 'TSAsExpression' ||
+          node.type === 'TSTypeAssertion'
+        ) {
+          context.report({ node, messageId: 'forbidden' });
+          return 'skip';
+        }
+      });
+    }
+
+    function walk(node, visit) {
+      if (!node || typeof node.type !== 'string') return;
+      if (visit(node) === 'skip') return;
+
+      // DOM event and output callbacks are executable action boundaries. Type
+      // assertions used to narrow an external event payload are not template
+      // render logic, so keep them outside this restriction.
+      if (isEventProperty(node)) return;
+
+      const keys = sourceCode.visitorKeys[node.type] ?? [];
+      for (const key of keys) {
+        const child = node[key];
+        if (Array.isArray(child)) {
+          for (const item of child) walk(item, visit);
+        } else {
+          walk(child, visit);
+        }
+      }
+    }
+  },
+};
+
+const DOM_EVENT_NAMES = new Set([
+  'abort',
+  'animationcancel',
+  'animationend',
+  'animationiteration',
+  'animationstart',
+  'auxclick',
+  'beforeinput',
+  'beforematch',
+  'beforetoggle',
+  'blur',
+  'canplay',
+  'canplaythrough',
+  'change',
+  'click',
+  'close',
+  'compositionend',
+  'compositionstart',
+  'compositionupdate',
+  'contextmenu',
+  'copy',
+  'cuechange',
+  'cut',
+  'dblclick',
+  'drag',
+  'dragend',
+  'dragenter',
+  'dragleave',
+  'dragover',
+  'dragstart',
+  'drop',
+  'durationchange',
+  'emptied',
+  'ended',
+  'error',
+  'focus',
+  'formdata',
+  'fullscreenchange',
+  'fullscreenerror',
+  'gotpointercapture',
+  'input',
+  'invalid',
+  'keydown',
+  'keypress',
+  'keyup',
+  'load',
+  'loadeddata',
+  'loadedmetadata',
+  'loadstart',
+  'lostpointercapture',
+  'mousedown',
+  'mouseenter',
+  'mouseleave',
+  'mousemove',
+  'mouseout',
+  'mouseover',
+  'mouseup',
+  'paste',
+  'pause',
+  'play',
+  'playing',
+  'pointercancel',
+  'pointerdown',
+  'pointerenter',
+  'pointerleave',
+  'pointermove',
+  'pointerout',
+  'pointerover',
+  'pointerup',
+  'progress',
+  'ratechange',
+  'reset',
+  'resize',
+  'scroll',
+  'scrollend',
+  'securitypolicyviolation',
+  'seeked',
+  'seeking',
+  'select',
+  'selectionchange',
+  'selectstart',
+  'slotchange',
+  'stalled',
+  'submit',
+  'suspend',
+  'timeupdate',
+  'toggle',
+  'touchcancel',
+  'touchend',
+  'touchmove',
+  'touchstart',
+  'transitioncancel',
+  'transitionend',
+  'transitionrun',
+  'transitionstart',
+  'volumechange',
+  'waiting',
+  'wheel',
+]);
+
+function isEventProperty(node) {
+  if (node.type !== 'Property' || node.computed) return false;
+
+  const propertyName =
+    node.key.type === 'Identifier'
+      ? node.key.name
+      : node.key.type === 'Literal' && typeof node.key.value === 'string'
+        ? node.key.value
+        : undefined;
+
+  return Boolean(
+    propertyName &&
+      (DOM_EVENT_NAMES.has(propertyName) || /^on[A-Z]/.test(propertyName)),
+  );
+}
+
+function isNestedCraftComponent(node) {
+  return (
+    node.type === 'CallExpression' &&
+    node.callee.type === 'Identifier' &&
+    node.callee.name === 'craftComponent'
+  );
+}
+
+function isTemplatePipe(node) {
+  if (node.type !== 'CallExpression') return false;
+
+  if (node.callee.type === 'Identifier') {
+    return node.callee.name === 'pipe';
+  }
+
+  return (
+    node.callee.type === 'MemberExpression' &&
+    !node.callee.computed &&
+    node.callee.property.type === 'Identifier' &&
+    node.callee.property.name === 'pipe'
+  );
+}

package/src/eslint-rules/no-widened-route-provider-context.cjs

@@ -0,0 +1,39 @@
+'use strict';
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Reject widened string or any provider contexts in RouteCheckedDI.',
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      TSTypeReference(node) {
+        if (
+          node.typeName.type !== 'Identifier' ||
+          node.typeName.name !== 'RouteCheckedDI'
+        ) {
+          return;
+        }
+        const availableNames = node.typeArguments?.params?.[1];
+        if (!isWidened(availableNames)) return;
+        context.report({
+          node: availableNames,
+          message:
+            'RouteCheckedDI provider names are widened to string/any. Restore the inferred app provider type; do not bypass the check with a broad fallback.',
+        });
+      },
+    };
+  },
+};
+
+function isWidened(node) {
+  if (!node) return false;
+  if (node.type === 'TSStringKeyword' || node.type === 'TSAnyKeyword') {
+    return true;
+  }
+  return node.type === 'TSUnionType' && node.types.some(isWidened);
+}

package/src/eslint-rules/prefer-browser-boundaries.cjs

@@ -0,0 +1,92 @@
+const BLOCKED_GLOBALS = new Map([
+  ['window', 'BrowserWindow'],
+  ['document', 'BrowserDocument'],
+  ['localStorage', 'LocalStorage'],
+  ['sessionStorage', 'SessionStorage'],
+  ['location', 'BrowserLocation'],
+  ['history', 'BrowserHistory'],
+  ['navigator', 'BrowserNavigator'],
+  ['performance', 'BrowserPerformance'],
+  ['crypto', 'BrowserCrypto'],
+  ['console', 'Console'],
+  ['alert', 'BrowserWindow.alert'],
+  ['confirm', 'BrowserWindow.confirm'],
+  ['scrollTo', 'BrowserWindow.scrollTo'],
+]);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow direct browser globals when an @craft-ts browser boundary exists.',
+    },
+    schema: [],
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    function report(node, actualName) {
+      const preferredBoundary = BLOCKED_GLOBALS.get(actualName);
+
+      if (!preferredBoundary) {
+        return;
+      }
+
+      context.report({
+        node,
+        message: `Use the @craft-ts browser boundary ${preferredBoundary} instead of direct ${actualName} access.`,
+      });
+    }
+
+    function findReference(node) {
+      let scope = sourceCode.getScope(node);
+
+      while (scope) {
+        const reference = scope.references.find(
+          (candidate) => candidate.identifier === node,
+        );
+
+        if (reference) {
+          return reference;
+        }
+
+        scope = scope.upper;
+      }
+
+      return undefined;
+    }
+
+    function isGlobalReference(node) {
+      const reference = findReference(node);
+      return Boolean(
+        reference &&
+          (reference.resolved == null || reference.resolved.defs.length === 0),
+      );
+    }
+
+    return {
+      Identifier(node) {
+        if (!BLOCKED_GLOBALS.has(node.name) || !isGlobalReference(node)) {
+          return;
+        }
+
+        report(node, node.name);
+      },
+      MemberExpression(node) {
+        if (
+          node.object.type !== 'Identifier' ||
+          node.object.name !== 'globalThis' ||
+          !isGlobalReference(node.object) ||
+          node.property.type !== 'Identifier' ||
+          node.computed ||
+          !BLOCKED_GLOBALS.has(node.property.name)
+        ) {
+          return;
+        }
+
+        report(node, node.property.name);
+      },
+    };
+  },
+};

package/src/eslint-rules/prefer-craft-http-transport.cjs

@@ -0,0 +1,103 @@
+const GLOBAL_OBJECTS = new Set(['globalThis', 'window']);
+
+const FETCH_MESSAGE =
+  'Do not call fetch() directly in authored Craft code. Use query() for reads or mutation() for writes, backed by CraftHttpClient.';
+const XHR_MESSAGE =
+  'Do not use XMLHttpRequest directly in authored Craft code. Use query() for reads or mutation() for writes, backed by CraftHttpClient.';
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Prefer Craft query/mutation primitives backed by CraftHttpClient over fetch and XMLHttpRequest.',
+    },
+    schema: [],
+    messages: {
+      fetch: FETCH_MESSAGE,
+      xhr: XHR_MESSAGE,
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    return {
+      CallExpression(node) {
+        if (isDirectGlobalCall(node, 'fetch', sourceCode)) {
+          context.report({ node: node.callee, messageId: 'fetch' });
+          return;
+        }
+
+        if (isGlobalObjectCall(node, 'fetch', sourceCode)) {
+          context.report({ node: node.callee.property, messageId: 'fetch' });
+        }
+      },
+
+      NewExpression(node) {
+        if (isDirectGlobalConstructor(node, 'XMLHttpRequest', sourceCode)) {
+          context.report({ node: node.callee, messageId: 'xhr' });
+          return;
+        }
+
+        if (isGlobalObjectConstructor(node, 'XMLHttpRequest', sourceCode)) {
+          context.report({ node: node.callee.property, messageId: 'xhr' });
+        }
+      },
+    };
+  },
+};
+
+function isDirectGlobalCall(node, name, sourceCode) {
+  return (
+    node.callee.type === 'Identifier' &&
+    node.callee.name === name &&
+    isUnshadowedGlobal(node.callee, sourceCode)
+  );
+}
+
+function isGlobalObjectCall(node, name, sourceCode) {
+  return (
+    node.callee.type === 'MemberExpression' &&
+    !node.callee.computed &&
+    node.callee.object.type === 'Identifier' &&
+    GLOBAL_OBJECTS.has(node.callee.object.name) &&
+    node.callee.property.type === 'Identifier' &&
+    node.callee.property.name === name &&
+    isUnshadowedGlobal(node.callee.object, sourceCode)
+  );
+}
+
+function isDirectGlobalConstructor(node, name, sourceCode) {
+  return (
+    node.callee.type === 'Identifier' &&
+    node.callee.name === name &&
+    isUnshadowedGlobal(node.callee, sourceCode)
+  );
+}
+
+function isGlobalObjectConstructor(node, name, sourceCode) {
+  return (
+    node.callee.type === 'MemberExpression' &&
+    !node.callee.computed &&
+    node.callee.object.type === 'Identifier' &&
+    GLOBAL_OBJECTS.has(node.callee.object.name) &&
+    node.callee.property.type === 'Identifier' &&
+    node.callee.property.name === name &&
+    isUnshadowedGlobal(node.callee.object, sourceCode)
+  );
+}
+
+function isUnshadowedGlobal(node, sourceCode) {
+  let scope = sourceCode.getScope(node);
+
+  while (scope) {
+    const variable = scope.set?.get(node.name);
+    if (variable) {
+      return variable.defs.length === 0;
+    }
+    scope = scope.upper;
+  }
+
+  return true;
+}