@qds.dev/tools 0.11.1 → 0.13.0

package/linter/qds-internal.unit.ts

@@ -0,0 +1,399 @@
+import { describe, it } from "vitest";
+import qdsPlugin, { requireContextProxyRule } from "./qds-internal";
+import { createRuleTester } from "./rule-tester";
+
+describe("qds/no-default-name", () => {
+  const { valid, invalid } = createRuleTester({
+    name: "qds/no-default-name",
+    rule: qdsPlugin.rules["no-default-name"]
+  });
+
+  it("allows value-based props", () => {
+    valid("interface Props { value?: string; checked?: boolean; }");
+  });
+
+  it("allows QRL props", () => {
+    valid("interface Props { onChange$?: QRL<() => void>; }");
+  });
+
+  it("flags defaultValue pattern", () => {
+    invalid("interface Props { defaultValue?: string; }");
+  });
+
+  it("flags multiple default patterns", () => {
+    invalid({
+      code: "interface Props { defaultChecked?: boolean; defaultOpen?: boolean; }",
+      errors: ["defaultChecked", "defaultOpen"]
+    });
+  });
+
+  it("flags default pattern in type alias", () => {
+    invalid({
+      code: "type Props = { defaultPressed?: boolean; };",
+      errors: ["defaultPressed"]
+    });
+  });
+
+  it("flags default pattern in .ts files", () => {
+    invalid({
+      code: "interface Props { defaultValue?: string; }",
+      filename: "utils.ts",
+      errors: ["defaultValue"]
+    });
+  });
+});
+
+describe("qds/event-handlers-array-pattern", () => {
+  const { valid, invalid } = createRuleTester({
+    name: "qds/event-handlers-array-pattern",
+    rule: qdsPlugin.rules["event-handlers-array-pattern"]
+  });
+
+  it("allows array pattern", () => {
+    valid("<button onClick$={[handleClick$, props.onClick$]} />");
+  });
+
+  it("allows ternary expressions", () => {
+    valid("<button onClick$={isDisabled ? undefined : handleClick$} />");
+  });
+
+  it("flags non-array event handler", () => {
+    invalid({
+      code: "<button onClick$={handleClick$} />",
+      errors: ["onClick$"]
+    });
+  });
+
+  it("flags multiple non-array handlers", () => {
+    invalid({
+      code: "<input onKeyDown$={handleKeyDown$} onChange$={handleChange$} />",
+      errors: ["onKeyDown$", "onChange$"]
+    });
+  });
+
+  it("allows events without $ suffix", () => {
+    valid("<button onClick={handleClick} />");
+  });
+});
+
+describe("qds/one-element-composition", () => {
+  const { valid, invalid } = createRuleTester({
+    name: "qds/one-element-composition",
+    rule: qdsPlugin.rules["one-element-composition"]
+  });
+
+  it("allows single element type", () => {
+    valid(`
+      const Button = component$(() => {
+        return <button>Click</button>;
+      });
+    `);
+  });
+
+  it("allows components with custom components", () => {
+    valid(`
+      const Wrapper = component$(() => {
+        return <div><CustomComponent /><AnotherComponent /></div>;
+      });
+    `);
+  });
+
+  it("flags multiple HTML element types", () => {
+    invalid({
+      code: `
+        const BadComponent = component$(() => {
+          return <div><span>Text</span></div>;
+        });
+      `,
+      errors: ["div, span"]
+    });
+  });
+
+  it("flags multiple different elements", () => {
+    invalid({
+      code: `
+        const Complex = component$(() => {
+          return (
+            <section>
+              <div>Content</div>
+              <p>More</p>
+            </section>
+          );
+        });
+      `,
+      errors: 1
+    });
+  });
+
+  it("allows single element with nested same type", () => {
+    valid(`
+      const List = component$(() => {
+        return <div><div>Nested</div></div>;
+      });
+    `);
+  });
+});
+
+describe("qds/require-use-bindings", () => {
+  const { valid, invalid } = createRuleTester({
+    name: "qds/require-use-bindings",
+    rule: qdsPlugin.rules["require-use-bindings"],
+    filename: "button-root.tsx"
+  });
+
+  it("allows root component with useBindings", () => {
+    valid({
+      code: `
+        const Button = component$(() => {
+          const { valueSig } = useBindings(props, { value: "" });
+          return <button />;
+        });
+      `,
+      filename: "button-root.tsx"
+    });
+  });
+
+  it("flags root component without useBindings", () => {
+    invalid({
+      code: `
+        const Button = component$(() => {
+          return <button />;
+        });
+      `,
+      filename: "checkbox-root.tsx",
+      errors: 1
+    });
+  });
+
+  it("allows non-root component without useBindings", () => {
+    valid({
+      code: `
+        const Helper = component$(() => {
+          return <span />;
+        });
+      `,
+      filename: "helper.tsx"
+    });
+  });
+});
+
+describe("qds/require-destructure-bindings", () => {
+  const { valid, invalid } = createRuleTester({
+    name: "qds/require-destructure-bindings",
+    rule: qdsPlugin.rules["require-destructure-bindings"]
+  });
+
+  it("allows file with both useBindings and destructureBindings", () => {
+    valid(`
+      const { valueSig } = useBindings(props, { value: "" });
+      const { value } = destructureBindings(props, { value: "" });
+    `);
+  });
+
+  it("flags file with useBindings but missing destructureBindings", () => {
+    invalid({
+      code: `
+        const { valueSig } = useBindings(props, { value: "" });
+      `,
+      errors: 1
+    });
+  });
+
+  it("allows file without useBindings", () => {
+    valid(`
+      const { value } = destructureBindings(props, { value: "" });
+    `);
+  });
+});
+
+describe("qds/require-research-file", () => {
+  const { valid, invalid } = createRuleTester({
+    name: "qds/require-research-file",
+    rule: qdsPlugin.rules["require-research-file"],
+    filename: "button-root.tsx"
+  });
+
+  it("flags root component (note: actual file check is in CI)", () => {
+    // Note: This rule can't actually check the filesystem from oxlint
+    // It serves as documentation/reminder, enforced by GitHub Actions
+    // Users can disable it per-file once they've added the research file
+    invalid({
+      code: `
+        const Button = component$(() => {
+          return <button />;
+        });
+      `,
+      filename: "checkbox-root.tsx",
+      errors: 1
+    });
+  });
+
+  it("allows non-root component", () => {
+    valid({
+      code: `
+        const Helper = component$(() => {
+          return <span />;
+        });
+      `,
+      filename: "helper.tsx"
+    });
+  });
+});
+
+describe("qds/require-test-file", () => {
+  const { valid, invalid } = createRuleTester({
+    name: "qds/require-test-file",
+    rule: qdsPlugin.rules["require-test-file"],
+    filename: "button-root.tsx"
+  });
+
+  it("flags root component (note: actual file check is in CI)", () => {
+    // Note: This rule can't actually check the filesystem from oxlint
+    // It serves as documentation/reminder, enforced by GitHub Actions
+    // Users can disable it per-file once they've added the test file
+    invalid({
+      code: `
+        const Button = component$(() => {
+          return <button />;
+        });
+      `,
+      filename: "checkbox-root.tsx",
+      errors: 1
+    });
+  });
+
+  it("allows non-root component", () => {
+    valid({
+      code: `
+        const Helper = component$(() => {
+          return <span />;
+        });
+      `,
+      filename: "helper.tsx"
+    });
+  });
+});
+
+describe("qds-internal/require-context-proxy", () => {
+  const { valid, invalid } = createRuleTester({
+    name: "qds-internal/require-context-proxy",
+    rule: requireContextProxyRule
+  });
+
+  it("allows correct createContextProxy usage with string literal argument", () => {
+    valid(`
+      import { createContextProxy } from "@qds.dev/base";
+      const context = createContextProxy();
+      export const getIsOpen = context("isOpen");
+    `);
+  });
+
+  it("allows file with no createContextProxy import (rule skips entirely)", () => {
+    valid(`
+      export const getIsOpen = someFunction("isOpen");
+    `);
+  });
+
+  it("errors when export uses proxy variable without get prefix", () => {
+    invalid({
+      code: `
+        import { createContextProxy } from "@qds.dev/base";
+        const context = createContextProxy();
+        export const something = context("field");
+      `,
+      errors: ["missingGetPrefix"]
+    });
+  });
+
+  it("allows multiple getter exports all using context() correctly", () => {
+    valid(`
+      import { createContextProxy } from "@qds.dev/base";
+      const context = createContextProxy();
+      export const getIsOpen = context("isOpen");
+      export const getLabel = context("label");
+    `);
+  });
+
+  it("errors when context() is called with a variable argument", () => {
+    invalid({
+      code: `
+        import { createContextProxy } from "@qds.dev/base";
+        const context = createContextProxy();
+        export const getIsOpen = context(someVar);
+      `,
+      errors: ["nonStringArg"]
+    });
+  });
+
+  it("errors when getter export uses a function other than context() from createContextProxy", () => {
+    invalid({
+      code: `
+        import { createContextProxy } from "@qds.dev/base";
+        const context = createContextProxy();
+        export const getIsOpen = otherFunction("isOpen");
+      `,
+      errors: ["notContextProxy"]
+    });
+  });
+
+  it("errors when export uses proxy variable but missing get prefix", () => {
+    invalid({
+      code: `
+        import { createContextProxy } from "@qds.dev/base";
+        const context = createContextProxy();
+        export const someIsOpen = context("isOpen");
+      `,
+      errors: ["missingGetPrefix"]
+    });
+  });
+
+  it("errors when context() is called with no arguments", () => {
+    invalid({
+      code: `
+        import { createContextProxy } from "@qds.dev/base";
+        const context = createContextProxy();
+        export const getIsOpen = context();
+      `,
+      errors: ["missingArg"]
+    });
+  });
+
+  it("allows getter name that matches context field", () => {
+    valid(`
+      import { createContextProxy } from "@qds.dev/base";
+      const context = createContextProxy();
+      export const getIsOpen = context("isOpen");
+      export const getSelectedLabels = context("selectedLabels");
+    `);
+  });
+
+  it("errors when getter name does not match context field", () => {
+    invalid({
+      code: `
+        import { createContextProxy } from "@qds.dev/base";
+        const context = createContextProxy();
+        export const getSomeIsOpen = context("isOpen");
+      `,
+      errors: ["getterNameMismatch"]
+    });
+  });
+
+  it("errors when getter name derives wrong field", () => {
+    invalid({
+      code: `
+        import { createContextProxy } from "@qds.dev/base";
+        const context = createContextProxy();
+        export const getOpen = context("isOpen");
+      `,
+      errors: ["getterNameMismatch"]
+    });
+  });
+
+  it("allows getHighlightedIndex matching highlightedIndex", () => {
+    valid(`
+      import { createContextProxy } from "@qds.dev/base";
+      const context = createContextProxy();
+      export const getHighlightedIndex = context("highlightedIndex");
+    `);
+  });
+});

package/linter/qds.ts

@@ -0,0 +1,300 @@
+/**
+ * Oxlint plugin for Qwik Design System (public)
+ *
+ * Consumer-facing lint plugin that QDS users install in their own projects.
+ * Contains only the no-outside-getter-usage rule.
+ */
+
+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 CallExpression extends BaseNode {
+    type: "CallExpression";
+    callee: Expression;
+    arguments: BaseNode[];
+  }
+  export interface VariableDeclarator extends BaseNode {
+    type: "VariableDeclarator";
+    id: Identifier | BaseNode;
+    init: Expression | null;
+  }
+  export type Expression = 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;
+}
+
+interface DeferredGetterReport {
+  node: Ranged;
+  getter: string;
+  namespace: string;
+  depth: number;
+}
+
+const QDS_IMPORT_SOURCES = new Set(["@qds.dev/ui"]);
+
+function isGetterProperty(propertyName: string): boolean {
+  return propertyName.startsWith("get") && propertyName.length > 3;
+}
+
+const noOutsideGetterUsageRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Getters from QDS namespaces must be used inside a component$ that renders the matching root element",
+      category: "Best Practices",
+      recommended: true,
+      url: "https://qds.dev/contributing/state/"
+    },
+    messages: {
+      moduleScope:
+        "'{{getter}}' used at module scope. Getters must be used inside a component$ that renders <{{namespace}}.root> or any of its descendants.",
+      outsideComponent:
+        "'{{getter}}' used in a function outside any component$. Move this into a component$ rendered inside <{{namespace}}.root>.",
+      noMatchingRoot:
+        "'{{getter}}' used but no <{{namespace}}.root> found in JSX return. Add <{{namespace}}.root> or move this into a component that renders inside one."
+    },
+    schema: []
+  },
+
+  create(context: Context) {
+    const qdsNamespaces = new Set<string>();
+    const destructuredGetters = new Map<string, string>();
+    const componentCallNodes: Node[] = [];
+    const componentRoots = new Map<number, Set<string>>();
+    const deferredReports: DeferredGetterReport[] = [];
+    const fileRoots = new Set<string>();
+    const fileDeferredReports: DeferredGetterReport[] = [];
+    let functionDepthOutsideComponent = 0;
+
+    function componentDepth(): number {
+      return componentCallNodes.length;
+    }
+
+    function handleGetterReference(
+      reportNode: Ranged,
+      getter: string,
+      namespace: string
+    ): void {
+      if (componentDepth() === 0 && functionDepthOutsideComponent === 0) {
+        context.report({
+          node: reportNode,
+          messageId: "moduleScope",
+          data: { getter, namespace }
+        });
+        return;
+      }
+
+      if (componentDepth() === 0 && functionDepthOutsideComponent > 0) {
+        context.report({
+          node: reportNode,
+          messageId: "outsideComponent",
+          data: { getter, namespace }
+        });
+        return;
+      }
+
+      deferredReports.push({
+        node: reportNode,
+        getter,
+        namespace,
+        depth: componentDepth()
+      });
+    }
+
+    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 (!QDS_IMPORT_SOURCES.has(source.value)) 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 local = specifier.local as Record<string, unknown> | undefined;
+          if (local?.type === "Identifier" && typeof local.name === "string") {
+            qdsNamespaces.add(local.name);
+          }
+        }
+      },
+
+      CallExpression(node: Node) {
+        const callNode = node as unknown as ESTree.CallExpression;
+        const callee = callNode.callee;
+        if (callee.type !== "Identifier") return;
+        if ((callee as unknown as ESTree.Identifier).name !== "component$") return;
+
+        componentCallNodes.push(node);
+        componentRoots.set(componentDepth(), new Set());
+      },
+
+      "CallExpression:exit"(node: Node) {
+        if (componentCallNodes.length === 0) return;
+        if (componentCallNodes[componentCallNodes.length - 1] !== node) return;
+
+        const depth = componentDepth();
+        const roots = componentRoots.get(depth) ?? new Set<string>();
+
+        const reportsAtDepth = deferredReports.filter((r) => r.depth === depth);
+        for (const report of reportsAtDepth) {
+          if (!roots.has(report.namespace)) {
+            fileDeferredReports.push(report);
+          }
+        }
+
+        const remaining = deferredReports.filter((r) => r.depth !== depth);
+        deferredReports.length = 0;
+        deferredReports.push(...remaining);
+
+        componentCallNodes.pop();
+        componentRoots.delete(depth);
+      },
+
+      "Program:exit"() {
+        for (const report of fileDeferredReports) {
+          if (!fileRoots.has(report.namespace)) {
+            context.report({
+              node: report.node,
+              messageId: "noMatchingRoot",
+              data: { getter: report.getter, namespace: report.namespace }
+            });
+          }
+        }
+      },
+
+      FunctionDeclaration(node: Node) {
+        if (componentDepth() === 0) {
+          functionDepthOutsideComponent++;
+        }
+        void node;
+      },
+
+      "FunctionDeclaration:exit"(node: Node) {
+        if (componentDepth() === 0 && functionDepthOutsideComponent > 0) {
+          functionDepthOutsideComponent--;
+        }
+        void node;
+      },
+
+      JSXMemberExpression(node: Node) {
+        if (componentDepth() === 0) return;
+
+        const jsxMember = node as unknown as Record<string, unknown>;
+        const obj = jsxMember.object as Record<string, unknown> | undefined;
+        const prop = jsxMember.property as Record<string, unknown> | undefined;
+
+        if (!obj || !prop) return;
+        if (obj.type !== "JSXIdentifier" || prop.type !== "JSXIdentifier") return;
+
+        const namespaceName = obj.name as string;
+        const propertyName = prop.name as string;
+
+        if (!qdsNamespaces.has(namespaceName)) return;
+        if (propertyName !== "root") return;
+
+        fileRoots.add(namespaceName);
+        const roots = componentRoots.get(componentDepth());
+        if (roots) {
+          roots.add(namespaceName);
+        }
+      },
+
+      MemberExpression(node: Node) {
+        const memberNode = node as unknown as Record<string, unknown>;
+        const obj = memberNode.object as Record<string, unknown> | undefined;
+        const prop = memberNode.property as Record<string, unknown> | undefined;
+
+        if (!obj || !prop) return;
+        if (obj.type !== "Identifier" || prop.type !== "Identifier") return;
+
+        const namespaceName = obj.name as string;
+        const propertyName = prop.name as string;
+
+        if (!qdsNamespaces.has(namespaceName)) return;
+        if (!isGetterProperty(propertyName)) return;
+
+        handleGetterReference(node, `${namespaceName}.${propertyName}`, namespaceName);
+      },
+
+      VariableDeclarator(node: Node) {
+        const decl = node as unknown as ESTree.VariableDeclarator;
+        if (!decl.init) return;
+        if (decl.init.type !== "Identifier") return;
+
+        const initName = (decl.init as unknown as ESTree.Identifier).name;
+        if (!qdsNamespaces.has(initName)) return;
+
+        if (decl.id.type !== "ObjectPattern") return;
+
+        const pattern = decl.id as unknown as Record<string, unknown>;
+        const properties = pattern.properties as
+          | Array<Record<string, unknown>>
+          | undefined;
+        if (!Array.isArray(properties)) return;
+
+        for (const prop of properties) {
+          if (prop.type !== "ObjectProperty" && prop.type !== "Property") continue;
+          const key = prop.key as Record<string, unknown> | undefined;
+          const value = prop.value as Record<string, unknown> | undefined;
+          if (!key || key.type !== "Identifier") continue;
+
+          const keyName = key.name as string;
+          if (!isGetterProperty(keyName)) continue;
+
+          const localName =
+            value && value.type === "Identifier" ? (value.name as string) : keyName;
+
+          destructuredGetters.set(localName, initName);
+          handleGetterReference(node, keyName, initName);
+        }
+      }
+    };
+  }
+});
+
+const qdsPlugin = definePlugin({
+  meta: {
+    name: "qds"
+  },
+  rules: {
+    "no-outside-getter-usage": noOutsideGetterUsageRule
+  }
+});
+
+export default qdsPlugin;