@qds.dev/tools 0.11.2 → 0.13.0

package/linter/qds.unit.ts

@@ -0,0 +1,158 @@
+import { describe, it } from "vitest";
+import qdsPlugin from "./qds";
+import { createRuleTester } from "./rule-tester";
+
+describe("qds-public/no-outside-getter-usage", () => {
+  const { valid, invalid } = createRuleTester({
+    name: "qds-public/no-outside-getter-usage",
+    rule: qdsPlugin.rules["no-outside-getter-usage"]
+  });
+
+  it("allows getter inside component$ with matching root", () => {
+    valid(`
+      import { select } from "@qds.dev/ui";
+      import { component$, useTask$ } from "@qwik.dev/core";
+      export default component$(() => {
+        useTask$(() => { console.log(select.getIsOpen.value); });
+        return <select.root><div /></select.root>;
+      });
+    `);
+  });
+
+  it("allows getter in nested function inside component$", () => {
+    valid(`
+      import { select } from "@qds.dev/ui";
+      import { component$ } from "@qwik.dev/core";
+      export default component$(() => {
+        function helper() { console.log(select.getIsOpen.value); }
+        return <select.root><div /></select.root>;
+      });
+    `);
+  });
+
+  it("allows getter in JSX expression (plugin handles it)", () => {
+    valid(`
+      import { select } from "@qds.dev/ui";
+      import { component$ } from "@qwik.dev/core";
+      export default component$(() => (
+        <select.root><div>{select.getIsOpen.value}</div></select.root>
+      ));
+    `);
+  });
+
+  it("allows destructured getter inside component$ with root", () => {
+    valid(`
+      import { select } from "@qds.dev/ui";
+      import { component$, useTask$ } from "@qwik.dev/core";
+      export default component$(() => {
+        const { getIsOpen } = select;
+        useTask$(() => { console.log(getIsOpen.value); });
+        return <select.root><div /></select.root>;
+      });
+    `);
+  });
+
+  it("errors on getter at module scope", () => {
+    invalid({
+      code: `
+        import { select } from "@qds.dev/ui";
+        const labels = select.getSelectedLabels;
+      `,
+      errors: ["moduleScope"]
+    });
+  });
+
+  it("errors on destructured getter at module scope", () => {
+    invalid({
+      code: `
+        import { select } from "@qds.dev/ui";
+        const { getSelectedLabels } = select;
+        console.log(getSelectedLabels.value);
+      `,
+      errors: ["moduleScope"]
+    });
+  });
+
+  it("errors on getter in function defined outside component$", () => {
+    invalid({
+      code: `
+        import { select } from "@qds.dev/ui";
+        import { component$ } from "@qwik.dev/core";
+        function myHelper() {
+          console.log(select.getIsOpen.value);
+        }
+        export default component$(() => {
+          myHelper();
+          return <select.root><div /></select.root>;
+        });
+      `,
+      errors: ["outsideComponent"]
+    });
+  });
+
+  it("errors on getter in component$ with no matching root", () => {
+    invalid({
+      code: `
+        import { select } from "@qds.dev/ui";
+        import { component$, useTask$ } from "@qwik.dev/core";
+        export default component$(() => {
+          useTask$(() => { console.log(select.getIsOpen.value); });
+          return <div>No root here</div>;
+        });
+      `,
+      errors: ["noMatchingRoot"]
+    });
+  });
+
+  it("allows getter in child component$ when parent component$ has root", () => {
+    valid(`
+      import { select } from "@qds.dev/ui";
+      import { component$ } from "@qwik.dev/core";
+      export default component$(() => {
+        return (
+          <select.root value="jim">
+            <Inner />
+          </select.root>
+        );
+      });
+      export const Inner = component$(() => {
+        const { getIsOpen, getSelectedLabels } = select;
+        return (
+          <>
+            <select.trigger>{getSelectedLabels.value}</select.trigger>
+            <p>Status: {getIsOpen.value ? "Open" : "Closed"}</p>
+          </>
+        );
+      });
+    `);
+  });
+
+  it("allows getter via member expression in child component$ when parent has root", () => {
+    valid(`
+      import { select } from "@qds.dev/ui";
+      import { component$ } from "@qwik.dev/core";
+      export default component$(() => (
+        <select.root><Inner /></select.root>
+      ));
+      const Inner = component$(() => (
+        <div>{select.getIsOpen.value ? "Open" : "Closed"}</div>
+      ));
+    `);
+  });
+
+  it("errors on getter in component$ when no sibling component$ has root", () => {
+    invalid({
+      code: `
+        import { select } from "@qds.dev/ui";
+        import { component$ } from "@qwik.dev/core";
+        export default component$(() => {
+          return <div>{select.getIsOpen.value}</div>;
+        });
+        export const Other = component$(() => {
+          return <div>No root here either</div>;
+        });
+      `,
+      errors: ["noMatchingRoot"]
+    });
+  });
+});

package/linter/rule-tester.ts

@@ -0,0 +1,395 @@
+/**
+ * RuleTester for oxlint rules
+ *
+ * Provides a clean API similar to ESLint's RuleTester but designed for oxc/oxlint.
+ * Works seamlessly with Vitest for testing custom lint rules.
+ */
+import { parseSync } from "oxc-parser";
+import { walk, type WalkerEnter } from "oxc-walker";
+import { describe, expect, it } from "vitest";
+
+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;
+}
+
+type VisitorWithHooks = Record<string, unknown> & {
+  before?: () => boolean | void;
+  after?: () => void;
+};
+
+type Rule =
+  | { meta: Record<string, unknown>; createOnce: (context: Context) => VisitorWithHooks }
+  | { meta: Record<string, unknown>; create: (context: Context) => VisitorWithHooks };
+
+export interface ValidTestCase {
+  /** The code that should not trigger any errors */
+  code: string;
+  /** Optional filename (defaults to test.tsx) */
+  filename?: string;
+  /** Optional description for the test case */
+  description?: string;
+}
+
+export interface InvalidTestCase {
+  /** The code that should trigger errors */
+  code: string;
+  /** Expected error messages or count */
+  errors:
+    | number // Just the count of errors
+    | string[] // Array of strings that should appear in error messages
+    | Array<
+        | string // Just the message
+        | { message: string; line?: number; column?: number } // Message with optional position
+        | { messageId: string; data?: Record<string, string> } // MessageId with data
+      >;
+  /** Optional filename (defaults to test.tsx) */
+  filename?: string;
+  /** Optional description for the test case */
+  description?: string;
+}
+
+export interface RuleTesterConfig {
+  /** Default filename for test cases */
+  filename?: string;
+}
+
+interface ReportedError {
+  node: Ranged;
+  messageId?: string;
+  message?: string;
+  data?: Record<string, string>;
+}
+
+/**
+ * RuleTester - Test utility for oxlint rules
+ *
+ * @example
+ * ```ts
+ * import { RuleTester } from './rule-tester';
+ * import myRule from './my-rule';
+ *
+ * const ruleTester = new RuleTester();
+ *
+ * ruleTester.run('my-rule', myRule, {
+ *   valid: [
+ *     'const x = 1;',
+ *     { code: 'const y = 2;', filename: 'test.ts' }
+ *   ],
+ *   invalid: [
+ *     {
+ *       code: 'var x = 1;',
+ *       errors: ['Use const instead of var']
+ *     }
+ *   ]
+ * });
+ * ```
+ */
+export class RuleTester {
+  private config: RuleTesterConfig;
+
+  constructor(config: RuleTesterConfig = {}) {
+    this.config = {
+      filename: "test.tsx",
+      ...config
+    };
+  }
+
+  run(
+    ruleName: string,
+    rule: Rule,
+    tests: {
+      valid?: Array<string | ValidTestCase>;
+      invalid?: Array<string | InvalidTestCase>;
+    }
+  ) {
+    describe(ruleName, () => {
+      const valid = tests.valid || [];
+      const invalid = tests.invalid || [];
+
+      if (valid.length > 0) {
+        describe("valid", () => {
+          for (const testCase of valid) {
+            const normalized = this.normalizeValidTestCase(testCase);
+            const title = normalized.description || normalized.code.trim().slice(0, 50);
+
+            it(title, () => {
+              const errors = this.runRule(rule, normalized.code, normalized.filename);
+              expect(errors).toHaveLength(0);
+            });
+          }
+        });
+      }
+
+      if (invalid.length > 0) {
+        describe("invalid", () => {
+          for (const testCase of invalid) {
+            const normalized: InvalidTestCase =
+              typeof testCase === "string" ? { code: testCase, errors: 1 } : testCase;
+
+            const title = normalized.description || normalized.code.trim().slice(0, 50);
+
+            it(title, () => {
+              const errors = this.runRule(rule, normalized.code, normalized.filename);
+
+              expect(errors.length).toBeGreaterThan(0);
+
+              if (typeof normalized.errors === "number") {
+                expect(errors).toHaveLength(normalized.errors);
+                return;
+              }
+
+              // If errors is a string array, check each string appears in error messages
+              if (
+                Array.isArray(normalized.errors) &&
+                normalized.errors.every((e) => typeof e === "string")
+              ) {
+                this.validateStringArrayErrors(errors, normalized.errors as string[]);
+                return;
+              }
+
+              expect(errors).toHaveLength(normalized.errors.length);
+
+              for (let i = 0; i < normalized.errors.length; i++) {
+                const expectedError = normalized.errors[i];
+                const actualError = errors[i];
+
+                if (typeof expectedError === "string") {
+                  const actualMessage = this.formatErrorMessage(actualError);
+                  expect(actualMessage).toContain(expectedError);
+                } else if ("message" in expectedError) {
+                  const actualMessage = this.formatErrorMessage(actualError);
+                  expect(actualMessage).toContain(expectedError.message);
+                } else if ("messageId" in expectedError) {
+                  expect(actualError.messageId).toBe(expectedError.messageId);
+
+                  if (expectedError.data) {
+                    expect(actualError.data).toMatchObject(expectedError.data);
+                  }
+                }
+              }
+            });
+          }
+        });
+      }
+    });
+  }
+
+  private runRule(rule: Rule, code: string, filename?: string): ReportedError[] {
+    const errors: ReportedError[] = [];
+    const actualFilename = filename || this.config.filename!;
+
+    const ext = actualFilename.split(".").pop() || "tsx";
+    const lang = (["js", "jsx", "ts", "tsx", "dts"].includes(ext) ? ext : "tsx") as
+      | "js"
+      | "jsx"
+      | "ts"
+      | "tsx"
+      | "dts";
+
+    const parseResult = parseSync(actualFilename, code, { lang });
+
+    if (parseResult.errors.length > 0) {
+      throw new Error(
+        `Parse error in test code:\n${parseResult.errors.map((e) => e.message).join("\n")}`
+      );
+    }
+
+    const context: Context = this.createMockContext(code, actualFilename, errors);
+
+    const ruleInstance: VisitorWithHooks =
+      "createOnce" in rule ? rule.createOnce(context) : rule.create(context);
+
+    if (ruleInstance.before) {
+      const result = ruleInstance.before();
+      if (result === false) {
+        return errors;
+      }
+    }
+
+    const visitEnter: WalkerEnter = function (node) {
+      const visitor = ruleInstance[node.type as keyof VisitorWithHooks];
+      if (typeof visitor === "function") {
+        (visitor as (node: Node) => void)(node as unknown as Node);
+      }
+    };
+
+    walk(parseResult.program, {
+      enter: visitEnter,
+      leave(node) {
+        const exitKey = `${node.type}:exit`;
+        const exitVisitor = ruleInstance[exitKey];
+        if (typeof exitVisitor === "function") {
+          (exitVisitor as (node: Node) => void)(node as unknown as Node);
+        }
+      }
+    });
+
+    if (ruleInstance.after) {
+      ruleInstance.after();
+    }
+
+    return errors;
+  }
+
+  private createMockContext(
+    code: string,
+    filename: string,
+    errors: ReportedError[]
+  ): Context {
+    return {
+      filename,
+      report(descriptor: {
+        node: Ranged;
+        messageId?: string;
+        message?: string;
+        data?: Record<string, string>;
+      }) {
+        errors.push({
+          node: descriptor.node,
+          messageId: descriptor.messageId,
+          message: descriptor.message,
+          data: descriptor.data
+        });
+      }
+    };
+  }
+
+  private normalizeValidTestCase(testCase: string | ValidTestCase): ValidTestCase {
+    if (typeof testCase === "string") {
+      return { code: testCase };
+    }
+    return testCase;
+  }
+
+  private formatErrorMessage(error: ReportedError): string {
+    if (error.message) {
+      return error.message;
+    }
+
+    // Include both messageId and data values for matching
+    const parts: string[] = [error.messageId || ""];
+
+    if (error.data) {
+      parts.push(...Object.values(error.data));
+    }
+
+    return parts.join(" ");
+  }
+
+  private validateStringArrayErrors(errors: ReportedError[], expected: string[]): void {
+    expect(errors).toHaveLength(expected.length);
+    for (let i = 0; i < expected.length; i++) {
+      const expectedFragment = expected[i];
+      const actualMessage = this.formatErrorMessage(errors[i]);
+      expect(actualMessage).toContain(expectedFragment);
+    }
+  }
+}
+
+/**
+ * Creates explicit test helpers for better DX
+ * Inspired by eslint-vitest-rule-tester but with our intuitive error format
+ */
+export function createRuleTester(options: {
+  name: string;
+  rule: Rule;
+  filename?: string;
+}) {
+  const tester = new RuleTester({
+    filename: options.filename || "test.tsx"
+  });
+
+  /**
+   * Test a valid code case
+   */
+  function valid(code: string | ValidTestCase) {
+    const normalized = typeof code === "string" ? { code } : code;
+    const errors = tester["runRule"](options.rule, normalized.code, normalized.filename);
+    expect(errors).toHaveLength(0);
+  }
+
+  /**
+   * Test an invalid code case
+   * Returns errors for further assertions (e.g., snapshots)
+   */
+  function invalid(
+    testCase:
+      | string
+      | {
+          code: string;
+          errors:
+            | number
+            | string[]
+            | Array<
+                | string
+                | { message: string; line?: number; column?: number }
+                | { messageId: string; data?: Record<string, string> }
+              >;
+          filename?: string;
+          output?: string;
+        }
+  ) {
+    const normalized: InvalidTestCase =
+      typeof testCase === "string" ? { code: testCase, errors: 1 } : testCase;
+
+    const errors = tester["runRule"](options.rule, normalized.code, normalized.filename);
+
+    expect(errors.length).toBeGreaterThan(0);
+
+    // If errors is just a number, only check the count
+    if (typeof normalized.errors === "number") {
+      expect(errors).toHaveLength(normalized.errors);
+      return { errors };
+    }
+
+    // If errors is a string array, check each string appears in error messages
+    if (
+      Array.isArray(normalized.errors) &&
+      normalized.errors.every((e) => typeof e === "string")
+    ) {
+      tester["validateStringArrayErrors"](errors, normalized.errors as string[]);
+      return { errors };
+    }
+
+    expect(errors).toHaveLength(normalized.errors.length);
+
+    for (let i = 0; i < normalized.errors.length; i++) {
+      const expectedError = normalized.errors[i];
+      const actualError = errors[i];
+
+      if (typeof expectedError === "string") {
+        const actualMessage = tester["formatErrorMessage"](actualError);
+        expect(actualMessage).toContain(expectedError);
+      } else if ("message" in expectedError) {
+        const actualMessage = tester["formatErrorMessage"](actualError);
+        expect(actualMessage).toContain(expectedError.message);
+      } else if ("messageId" in expectedError) {
+        expect(actualError.messageId).toBe(expectedError.messageId);
+
+        if (expectedError.data) {
+          expect(actualError.data).toMatchObject(expectedError.data);
+        }
+      }
+    }
+
+    return { errors };
+  }
+
+  return { valid, invalid };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qds.dev/tools",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "private": false,
   "description": "Tools and utilities for Qwik Design System",
   "repository": {
@@ -8,7 +8,8 @@
     "url": "https://github.com/kunai-consulting/qwik-design-system"
   },
   "files": [
-    "lib"
+    "lib",
+    "linter"
   ],
   "type": "module",
   "sideEffects": false,
@@ -45,12 +46,12 @@
   "dependencies": {
     "@iconify/json": "^2.2.382",
     "@iconify/utils": "^3.0.1",
-    "@oxc-project/types": "^0.111.0",
+    "@oxc-project/types": "^0.115.0",
     "magic-regexp": "^0.10.0",
-    "oxc-minify": "^0.111.0",
-    "oxc-parser": "^0.111.0",
-    "oxc-transform": "^0.111.0",
-    "oxc-walker": "^0.5.2",
+    "oxc-minify": "^0.115.0",
+    "oxc-parser": "^0.115.0",
+    "oxc-transform": "^0.115.0",
+    "oxc-walker": "^0.7.0",
     "remark": "^15.0.1",
     "remark-mdx": "^3.1.1"
   },

package/lib/rolldown/icons.qwik.mjs

@@ -1,107 +0,0 @@
-import { CollectionLoader } from "../utils/icons/collections/loader.qwik.mjs";
-import { resolveImportAliases } from "../utils/icons/import-resolver.qwik.mjs";
-import { transformMDXFile } from "../utils/icons/transform/mdx.qwik.mjs";
-import { transformTSXFile } from "../utils/icons/transform/tsx.qwik.mjs";
-import { anyOf, createRegExp, exactly } from "magic-regexp";
-import { parseSync } from "oxc-parser";
-
-//#region rolldown/icons.ts
-/**
-* Rolldown plugin that transforms icon JSX elements to direct <svg /> calls
-* @param options - Plugin configuration options
-* @returns Rolldown-compatible plugin object
-*/ const icons = (options = {}) => {
-	const importSources = options.importSources ?? ["@qds.dev/ui"];
-	const isDebugMode = !!options.debug;
-	const collectionNames = /* @__PURE__ */ new Map();
-	const debug = (message, ...data) => {
-		if (!isDebugMode) return;
-		console.log(`[icons] ${message}`, ...data);
-	};
-	const collectionLoader = new CollectionLoader(debug);
-	/**
-	* Parse and validate a file, returning the AST if valid
-	* @param code - Source code to parse
-	* @param id - File ID for debugging
-	* @returns AST program if valid, null if invalid
-	*/ function parseAndValidateFile(code, id) {
-		try {
-			const parsed = parseSync(id, code);
-			if (parsed.errors.length > 0) {
-				debug(`Parse errors in ${id}:`, parsed.errors.map((e) => e.message));
-				return null;
-			}
-			return parsed.program;
-		} catch (error) {
-			debug(`Error parsing ${id}:`, error);
-			return null;
-		}
-	}
-	const isTSXJSXOrMDX = createRegExp(exactly(".").and(anyOf("tsx", "jsx", "mdx")).at.lineEnd());
-	const isVirtualIconsImport = createRegExp(exactly("virtual:icons/").at.lineStart());
-	const isVirtualIconsModule = createRegExp(exactly(String.fromCharCode(0)).and("virtual:icons/"));
-	return {
-		name: "vite-plugin-qds-icons",
-		enforce: "pre",
-		transform: {
-			filter: { id: isTSXJSXOrMDX },
-			handler(code, id) {
-				if (collectionLoader.getAvailableCollections().size === 0) collectionLoader.discoverCollections();
-				if (id.endsWith(".mdx")) return transformMDXFile(code, id, importSources, collectionLoader.getAvailableCollections(), collectionNames, options.packs, debug);
-				debug(`[TRANSFORM] Starting transformation for ${id}`);
-				try {
-					const ast = parseAndValidateFile(code, id);
-					if (!ast) {
-						debug(`[TRANSFORM] Failed to parse ${id}`);
-						return null;
-					}
-					const aliasToPack = resolveImportAliases(ast, importSources, collectionLoader.getAvailableCollections(), collectionNames, options.packs, debug);
-					if (aliasToPack.size === 0) {
-						debug(`[TRANSFORM] No icon imports found in ${id}`);
-						return null;
-					}
-					return transformTSXFile(code, id, ast, aliasToPack, collectionNames, collectionLoader.getAvailableCollections(), options.packs, debug);
-				} catch (error) {
-					debug(`[TRANSFORM] Error during transformation of ${id}:`, error);
-					return null;
-				}
-			}
-		},
-		resolveId: {
-			filter: { id: isVirtualIconsImport },
-			handler(source) {
-				if (source.startsWith("virtual:icons/")) return `\0${source}`;
-				return null;
-			}
-		},
-		load: {
-			filter: { id: isVirtualIconsModule },
-			async handler(id) {
-				const virtualPath = id.slice(1);
-				const parts = virtualPath.split("/");
-				const prefix = parts[1];
-				const name = parts[2];
-				if (!prefix || !name) {
-					debug(`Invalid virtual icon path: ${virtualPath}`);
-					return null;
-				}
-				try {
-					const iconData = name.includes("-") ? await collectionLoader.loadIconDataLazy(prefix, name) : await collectionLoader.loadIconDataByLowercase(prefix, name);
-					if (!iconData) {
-						debug(`Failed to load icon data for ${prefix}:${name}`);
-						return { code: `export default '<path d="M12 2L2 7l10 5 10-5z"/><path d="M2 17l10 5 10-5M2 12l10 5 10-5"/>';\n` };
-					}
-					const code = `export default \`${iconData.body}\`;`;
-					debug(`Generated virtual module for ${prefix}:${name}`);
-					return { code };
-				} catch (error) {
-					debug(`Error loading virtual module ${virtualPath}:`, error);
-					return { code: `export default '<circle cx="12" cy="12" r="10"/><path d="M12 6v6l4 2"/>';\n` };
-				}
-			}
-		}
-	};
-};
-
-//#endregion
-export { icons };