@qds.dev/tools 0.11.1 → 0.13.0

package/linter/qds-internal.ts

@@ -0,0 +1,707 @@
+/**
+ * Oxlint plugin for Qwik Design System
+ *
+ * Custom linting rules specific to Qwik patterns and conventions
+ */
+
+interface Ranged {
+  range: [number, number];
+}
+
+interface Node extends Ranged {
+  type: string;
+  start: number;
+  end: number;
+}
+
+interface Context {
+  filename: string;
+  report(descriptor: {
+    node: Ranged;
+    messageId?: string;
+    message?: string;
+    data?: Record<string, string>;
+  }): void;
+}
+
+namespace ESTree {
+  interface BaseNode extends Ranged {
+    type: string;
+    [key: string]: unknown;
+  }
+  export interface Identifier extends BaseNode {
+    type: "Identifier";
+    name: string;
+  }
+  export interface TSPropertySignature extends BaseNode {
+    type: "TSPropertySignature";
+    key: Identifier | BaseNode;
+    computed: boolean;
+    optional: boolean;
+    readonly: boolean;
+  }
+  export interface JSXIdentifier extends BaseNode {
+    type: "JSXIdentifier";
+    name: string;
+  }
+  export interface JSXExpressionContainer extends BaseNode {
+    type: "JSXExpressionContainer";
+    expression: Expression;
+  }
+  export interface JSXAttribute extends BaseNode {
+    type: "JSXAttribute";
+    name: JSXIdentifier | BaseNode;
+    value: JSXExpressionContainer | BaseNode | null;
+  }
+  export interface CallExpression extends BaseNode {
+    type: "CallExpression";
+    callee: Expression;
+    arguments: BaseNode[];
+  }
+  export interface VariableDeclarator extends BaseNode {
+    type: "VariableDeclarator";
+    id: Identifier | BaseNode;
+    init: Expression | null;
+  }
+  export interface ReturnStatement extends BaseNode {
+    type: "ReturnStatement";
+    argument: Expression | null;
+  }
+  export interface VariableDeclaration extends BaseNode {
+    type: "VariableDeclaration";
+    declarations: VariableDeclarator[];
+  }
+  export type Expression = BaseNode;
+  export type JSXElement = BaseNode;
+}
+
+function defineRule<const T extends Record<string, unknown>>(rule: T): T {
+  return rule;
+}
+function definePlugin<const T extends Record<string, unknown>>(plugin: T): T {
+  return plugin;
+}
+
+const noDefaultXNamingRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow 'defaultX' naming pattern in component props - use Qwik's signal/value-based patterns instead",
+      category: "Best Practices",
+      recommended: true,
+      url: "https://qds.dev/contributing/state/"
+    },
+    messages: {
+      defaultXPattern:
+        "'{{name}}' uses React's defaultX pattern. Qwik uses signal-based (two-way binding) or value-based (one-way binding) patterns instead. See: https://qds.dev/contributing/state/"
+    },
+    schema: []
+  },
+
+  createOnce(context: Context) {
+    const defaultPattern = /^default[A-Z][a-zA-Z0-9]*$/;
+
+    return {
+      TSPropertySignature(node: Node) {
+        const tsNode = node as unknown as ESTree.TSPropertySignature;
+        if (tsNode.key.type !== "Identifier") return;
+        const key = tsNode.key as ESTree.Identifier;
+        if (!key.name) return;
+
+        const name = key.name;
+        if (!defaultPattern.test(name)) return;
+
+        context.report({
+          node: key,
+          messageId: "defaultXPattern",
+          data: { name }
+        });
+      }
+    };
+  }
+});
+
+const eventHandlersArrayPatternRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Event handlers should use array pattern to combine local handlers with props",
+      category: "Best Practices",
+      recommended: true,
+      url: "https://qds.dev/contributing/"
+    },
+    messages: {
+      requireArrayPattern:
+        "Event handler '{{name}}' should use array pattern: [localHandler$, props.{{name}}]."
+    },
+    schema: []
+  },
+
+  createOnce(context: Context) {
+    return {
+      JSXAttribute(node: Node) {
+        const jsxAttr = node as unknown as ESTree.JSXAttribute;
+
+        if (jsxAttr.name.type !== "JSXIdentifier") return;
+
+        const attrName = (jsxAttr.name as ESTree.JSXIdentifier).name;
+        if (!attrName.startsWith("on") || !attrName.endsWith("$")) return;
+
+        const value = jsxAttr.value;
+        if (!value || value.type !== "JSXExpressionContainer") return;
+
+        const expr = (value as ESTree.JSXExpressionContainer).expression;
+
+        // Allow array expressions: onXxx$={[handler$, props.onXxx$]}
+        if (expr.type === "ArrayExpression") return;
+
+        // Allow ternary expressions (single-line ternaries are valid)
+        if (expr.type === "ConditionalExpression") return;
+
+        context.report({
+          node: jsxAttr.name,
+          messageId: "requireArrayPattern",
+          data: { name: attrName }
+        });
+      }
+    };
+  }
+});
+
+function collectHTMLElements(node: ESTree.Expression): string[] {
+  const elements: string[] = [];
+
+  const walk = (n: unknown): void => {
+    if (!n || typeof n !== "object") return;
+
+    const record = n as Record<string, unknown>;
+    if (record.type === "JSXElement") {
+      const openingElement = record.openingElement as Record<string, unknown> | undefined;
+      if (openingElement?.name) {
+        const name = openingElement.name as Record<string, unknown>;
+        if (name.type === "JSXIdentifier") {
+          const tagName = name.name as string;
+          // Only collect lowercase tags (HTML elements, not components)
+          if (tagName && tagName[0] === tagName[0].toLowerCase()) {
+            elements.push(tagName);
+          }
+        }
+      }
+    }
+
+    // Recursively walk children
+    for (const key in record) {
+      const value = record[key];
+      if (key === "children" && Array.isArray(value)) {
+        value.forEach(walk);
+      } else if (value && typeof value === "object") {
+        walk(value);
+      }
+    }
+  };
+
+  walk(node);
+  return elements;
+}
+
+const oneElementCompositionRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Components should follow 'One Component, One Markup Element' principle",
+      category: "Best Practices",
+      recommended: true,
+      url: "https://qds.dev/contributing/composition/"
+    },
+    messages: {
+      multipleElements:
+        "Component returns multiple HTML element types: {{elements}}. Each component should correspond to ONE type of markup element. Add '// no-composition-check' to exempt."
+    },
+    schema: []
+  },
+
+  createOnce(context: Context) {
+    let hasCompositionCheckDisable = false;
+    const componentReturnElements = new Map<string, Set<string>>();
+    let currentComponentName: string | null = null;
+
+    return {
+      Program() {
+        // Check for no-composition-check comment
+        // Note: In a real implementation, we'd check context.sourceCode.getAllComments()
+        // For now, we'll skip this feature in the linter
+        hasCompositionCheckDisable = false;
+      },
+
+      VariableDeclarator(node: Node) {
+        const decl = node as unknown as ESTree.VariableDeclarator;
+        if (decl.init?.type !== "CallExpression") return;
+
+        const callee = (decl.init as ESTree.CallExpression).callee as ESTree.Identifier;
+        if (callee.type !== "Identifier") return;
+        if (callee.name !== "component$") return;
+        if (decl.id.type !== "Identifier") return;
+
+        currentComponentName = (decl.id as ESTree.Identifier).name;
+        componentReturnElements.set(currentComponentName, new Set());
+      },
+
+      ReturnStatement(node: Node) {
+        if (!currentComponentName || hasCompositionCheckDisable) return;
+
+        const returnStmt = node as unknown as ESTree.ReturnStatement;
+        if (!returnStmt.argument) return;
+
+        // Collect HTML elements from the return statement
+        const elements = collectHTMLElements(returnStmt.argument);
+        const elementSet = componentReturnElements.get(currentComponentName);
+
+        if (elementSet) {
+          elements.forEach((el) => elementSet.add(el));
+        }
+      },
+
+      "VariableDeclarator:exit"(node: Node) {
+        const decl = node as unknown as ESTree.VariableDeclarator;
+        if (decl.init?.type !== "CallExpression") return;
+
+        const callee = (decl.init as ESTree.CallExpression).callee as ESTree.Identifier;
+        if (callee.type !== "Identifier") return;
+        if (callee.name !== "component$") return;
+        if (!currentComponentName) return;
+        if (decl.id.type !== "Identifier") return;
+
+        const elementSet = componentReturnElements.get(currentComponentName);
+
+        if (elementSet && elementSet.size > 1) {
+          const elements = Array.from(elementSet).toSorted().join(", ");
+          context.report({
+            node: decl.id,
+            messageId: "multipleElements",
+            data: { elements }
+          });
+        }
+
+        currentComponentName = null;
+      }
+    };
+  }
+});
+
+const requireUseBindingsRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Root components (*-root.tsx) should use useBindings or include '// no-bindings' comment",
+      category: "Best Practices",
+      recommended: true,
+      url: "https://qds.dev/contributing/state/#useBindings"
+    },
+    messages: {
+      missingBindings:
+        "Root component is missing useBindings. Add useBindings or include '// no-bindings' comment if not needed."
+    },
+    schema: []
+  },
+
+  createOnce(context: Context) {
+    let hasUseBindings = false;
+    let hasNoBindingsComment = false;
+    let hasComponent = false;
+    let componentNode: Ranged | null = null;
+    let isRootComponent = false;
+
+    return {
+      Program() {
+        // Check if this is a root component file
+        const filename = context.filename;
+        isRootComponent =
+          filename.endsWith("-root.tsx") || filename.endsWith("-root.jsx");
+
+        // Note: In a real implementation, we'd check for comments here
+        hasNoBindingsComment = false;
+      },
+
+      CallExpression(node: Node) {
+        if (!isRootComponent) return;
+
+        const call = node as unknown as ESTree.CallExpression;
+        const callee = call.callee;
+        if (callee.type !== "Identifier") return;
+
+        // Check for component$
+        if (callee.name === "component$") {
+          hasComponent = true;
+          componentNode = node;
+        }
+
+        // Check for useBindings
+        if (callee.name === "useBindings") {
+          hasUseBindings = true;
+        }
+      },
+
+      "Program:exit"() {
+        if (!isRootComponent) return;
+        if (!hasComponent) return;
+        if (hasUseBindings) return;
+        if (hasNoBindingsComment) return;
+        if (!componentNode) return;
+
+        context.report({
+          node: componentNode,
+          messageId: "missingBindings"
+        });
+      }
+    };
+  }
+});
+
+const requireResearchFileRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Root components (*-root.tsx) require a research file (research.md or research.mdx)",
+      category: "Best Practices",
+      recommended: true,
+      url: "https://qwik.design/contributing/research/"
+    },
+    messages: {
+      missingResearch:
+        "Root component requires a research file. Create research.md or research.mdx in this directory documenting component research, accessibility, design decisions, and usage guidelines."
+    },
+    schema: []
+  },
+
+  createOnce(context: Context) {
+    let isRootComponent = false;
+    let hasComponent = false;
+    let componentNode: Ranged | null = null;
+
+    return {
+      Program() {
+        const filename = context.filename;
+        isRootComponent =
+          filename.endsWith("-root.tsx") || filename.endsWith("-root.jsx");
+      },
+
+      CallExpression(node: Node) {
+        if (!isRootComponent) return;
+
+        const call = node as unknown as ESTree.CallExpression;
+        const callee = call.callee;
+        if (callee.type !== "Identifier") return;
+
+        if (callee.name === "component$") {
+          hasComponent = true;
+          componentNode = node;
+        }
+      },
+
+      "Program:exit"() {
+        if (!isRootComponent) return;
+        if (!hasComponent) return;
+        if (!componentNode) return;
+
+        // Note: We can't actually check the filesystem from oxlint
+        // This rule serves as a reminder/documentation
+        // The actual enforcement is done by the GitHub Actions workflow
+        context.report({
+          node: componentNode,
+          messageId: "missingResearch"
+        });
+      }
+    };
+  }
+});
+
+const requireTestFileRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Root components (*-root.tsx) require a test file (*.browser.tsx)",
+      category: "Best Practices",
+      recommended: true,
+      url: "https://qwik.design/contributing/testing/"
+    },
+    messages: {
+      missingTest:
+        "Root component requires a test file. Create a *.browser.tsx file in this directory with component tests."
+    },
+    schema: []
+  },
+
+  createOnce(context: Context) {
+    let isRootComponent = false;
+    let hasComponent = false;
+    let componentNode: Ranged | null = null;
+
+    return {
+      Program() {
+        const filename = context.filename;
+        isRootComponent =
+          filename.endsWith("-root.tsx") || filename.endsWith("-root.jsx");
+      },
+
+      CallExpression(node: Node) {
+        if (!isRootComponent) return;
+
+        const call = node as unknown as ESTree.CallExpression;
+        const callee = call.callee;
+        if (callee.type !== "Identifier") return;
+
+        if (callee.name === "component$") {
+          hasComponent = true;
+          componentNode = node;
+        }
+      },
+
+      "Program:exit"() {
+        if (!isRootComponent) return;
+        if (!hasComponent) return;
+        if (!componentNode) return;
+
+        // Note: We can't actually check the filesystem from oxlint
+        // This rule serves as a reminder/documentation
+        // The actual enforcement is done by the GitHub Actions workflow
+        context.report({
+          node: componentNode,
+          messageId: "missingTest"
+        });
+      }
+    };
+  }
+});
+
+const requireDestructureBindingsRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "If useBindings is used, destructureBindings must also be used in the same file to ensure proper prop handling",
+      category: "Best Practices",
+      recommended: true,
+      url: "https://qds.dev/contributing/state/#destructureBindings"
+    },
+    messages: {
+      missingDestructureBindings:
+        "File uses useBindings but is missing destructureBindings. Both are required for proper QDS component state management. Example: const { ... } = destructureBindings(props, initialValues);"
+    },
+    schema: []
+  },
+
+  createOnce(context: Context) {
+    let hasUseBindings = false;
+    let hasDestructureBindings = false;
+    let useBindingsNode: Ranged | null = null;
+
+    return {
+      CallExpression(node: Node) {
+        const call = node as unknown as ESTree.CallExpression;
+        const callee = call.callee;
+        if (callee.type !== "Identifier") return;
+
+        if (callee.name === "useBindings") {
+          hasUseBindings = true;
+          useBindingsNode = node;
+        }
+
+        if (callee.name === "destructureBindings") {
+          hasDestructureBindings = true;
+        }
+      },
+
+      "Program:exit"() {
+        if (hasUseBindings && !hasDestructureBindings && useBindingsNode) {
+          context.report({
+            node: useBindingsNode,
+            messageId: "missingDestructureBindings"
+          });
+        }
+      }
+    };
+  }
+});
+
+export const requireContextProxyRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Enforce createContextProxy pattern for getter exports",
+      recommended: true
+    },
+    messages: {
+      nonStringArg:
+        "Getter export '{{name}}' calls context() with a non-string argument. Use a string literal: context('fieldName').",
+      notContextProxy:
+        "Getter export '{{name}}' is not created via createContextProxy. Use: const context = createContextProxy<T>(); export const {{name}} = context('fieldName');",
+      missingArg:
+        "Getter export '{{name}}' calls context() without arguments. Provide the context field name: context('fieldName').",
+      missingGetPrefix:
+        "Export '{{name}}' uses createContextProxy but is missing the 'get' prefix. Rename to 'get{{suggested}}' so the UI plugin can detect it.",
+      getterNameMismatch:
+        "Getter '{{name}}' does not match context field '{{field}}'. Expected export name: 'get{{expected}}' (derived: '{{derived}}', actual field: '{{field}}'). The UI plugin uses deriveContextField which strips 'get' and lowercases the next char."
+    },
+    schema: []
+  },
+
+  create(context: Context) {
+    let createContextProxyLocalName: string | null = null;
+    const proxyVariableNames = new Set<string>();
+
+    return {
+      ImportDeclaration(node: Node) {
+        const importNode = node as unknown as Record<string, unknown>;
+        const source = importNode.source as Record<string, unknown> | undefined;
+        if (!source || typeof source.value !== "string") return;
+        if (source.value !== "@qds.dev/base") return;
+
+        const specifiers = importNode.specifiers as
+          | Array<Record<string, unknown>>
+          | undefined;
+        if (!Array.isArray(specifiers)) return;
+
+        for (const specifier of specifiers) {
+          if (specifier.type !== "ImportSpecifier") continue;
+          const imported = specifier.imported as Record<string, unknown> | undefined;
+          const local = specifier.local as Record<string, unknown> | undefined;
+          if (!imported || !local) continue;
+          if (typeof imported.name !== "string") continue;
+          if (imported.name !== "createContextProxy") continue;
+          if (typeof local.name === "string") {
+            createContextProxyLocalName = local.name;
+          }
+        }
+      },
+
+      VariableDeclarator(node: Node) {
+        if (!createContextProxyLocalName) return;
+
+        const decl = node as unknown as ESTree.VariableDeclarator;
+        if (!decl.init) return;
+        if (decl.init.type !== "CallExpression") return;
+
+        const callExpr = decl.init as unknown as ESTree.CallExpression;
+        if (callExpr.callee.type !== "Identifier") return;
+
+        const calleeName = (callExpr.callee as unknown as ESTree.Identifier).name;
+        if (calleeName !== createContextProxyLocalName) return;
+        if (decl.id.type !== "Identifier") return;
+
+        const varName = (decl.id as unknown as ESTree.Identifier).name;
+        proxyVariableNames.add(varName);
+      },
+
+      ExportNamedDeclaration(node: Node) {
+        if (!createContextProxyLocalName) return;
+
+        const exportNode = node as unknown as Record<string, unknown>;
+        const declaration = exportNode.declaration as Record<string, unknown> | undefined;
+        if (!declaration) return;
+        if (declaration.type !== "VariableDeclaration") return;
+
+        const declarations = declaration.declarations as
+          | Array<Record<string, unknown>>
+          | undefined;
+        if (!Array.isArray(declarations)) return;
+
+        for (const declarator of declarations) {
+          const id = declarator.id as Record<string, unknown> | undefined;
+          if (!id || id.type !== "Identifier") continue;
+
+          const exportName = id.name as string;
+          const init = declarator.init as Record<string, unknown> | undefined;
+          if (!init) continue;
+          if (init.type !== "CallExpression") continue;
+
+          const callee = init.callee as Record<string, unknown> | undefined;
+          if (!callee || callee.type !== "Identifier") continue;
+
+          const calleeName = callee.name as string;
+          const hasGetPrefix = exportName.startsWith("get") && exportName.length > 3;
+
+          if (!hasGetPrefix && proxyVariableNames.has(calleeName)) {
+            const suggested = exportName.charAt(0).toUpperCase() + exportName.slice(1);
+            context.report({
+              node: node as unknown as Ranged,
+              messageId: "missingGetPrefix",
+              data: { name: exportName, suggested }
+            });
+            continue;
+          }
+
+          if (!hasGetPrefix) continue;
+
+          if (!proxyVariableNames.has(calleeName)) {
+            context.report({
+              node: node as unknown as Ranged,
+              messageId: "notContextProxy",
+              data: { name: exportName }
+            });
+            continue;
+          }
+
+          const args = init.arguments as Array<Record<string, unknown>> | undefined;
+          if (!Array.isArray(args) || args.length === 0) {
+            context.report({
+              node: node as unknown as Ranged,
+              messageId: "missingArg",
+              data: { name: exportName }
+            });
+            continue;
+          }
+
+          const firstArg = args[0];
+          const isStringLiteral =
+            firstArg.type === "Literal" && typeof firstArg.value === "string";
+          if (!isStringLiteral) {
+            context.report({
+              node: node as unknown as Ranged,
+              messageId: "nonStringArg",
+              data: { name: exportName }
+            });
+            continue;
+          }
+
+          const contextField = firstArg.value as string;
+          const derived = exportName.slice(3, 4).toLowerCase() + exportName.slice(4);
+          if (derived !== contextField) {
+            context.report({
+              node: node as unknown as Ranged,
+              messageId: "getterNameMismatch",
+              data: {
+                name: exportName,
+                field: contextField,
+                expected: contextField.charAt(0).toUpperCase() + contextField.slice(1),
+                derived
+              }
+            });
+          }
+        }
+      }
+    };
+  }
+});
+
+const qdsPlugin = definePlugin({
+  meta: {
+    name: "qds-internal"
+  },
+  rules: {
+    "no-default-name": noDefaultXNamingRule,
+    "event-handlers-array-pattern": eventHandlersArrayPatternRule,
+    "one-element-composition": oneElementCompositionRule,
+    "require-use-bindings": requireUseBindingsRule,
+    "require-destructure-bindings": requireDestructureBindingsRule,
+    "require-research-file": requireResearchFileRule,
+    "require-test-file": requireTestFileRule,
+    "require-context-proxy": requireContextProxyRule
+  }
+});
+
+export default qdsPlugin;