@instruments/materia-ui 0.4.0 → 0.4.2

package/lint/scan-classes.d.mts

@@ -1,5 +1,58 @@
-/**
- * The class-string scanner is a command, run as the `materia-ui-lint` bin. It
- * exports nothing; importing it runs the scan.
- */
-export {};
+// GENERATED by scripts/generate-lint-types.ts from the JSDoc in lint/scan-classes.mjs - do not edit.
+// Regenerate with `pnpm --filter @instruments/materia-ui generate:lint-types`.
+
+export interface Options {
+  /**
+   * Files and directories to scan.
+   */
+  paths: string[];
+  /**
+   * Path fragments to skip.
+   */
+  excludes: string[];
+  /**
+   * Whether the `hex` rule is on.
+   */
+  hex: boolean;
+  /**
+   * Whether the `arbitrary` rule is on.
+   */
+  arbitrary: boolean;
+  /**
+   * Whether to print a JSON document instead of text lines.
+   */
+  json: boolean;
+  /**
+   * Whether to print usage and stop.
+   */
+  help: boolean;
+}
+export type RuleName = "hex" | "arbitrary";
+export interface Region {
+  /**
+   * Offset of the region in the file.
+   */
+  start: number;
+  /**
+   * The region's text.
+   */
+  body: string;
+}
+export interface Violation {
+  /**
+   * The rule that matched.
+   */
+  rule: RuleName;
+  /**
+   * The offending text.
+   */
+  value: string;
+  /**
+   * One-based line of the match.
+   */
+  line: number;
+  /**
+   * One-based column of the match.
+   */
+  column: number;
+}

package/lint/scan-classes.mjs

@@ -15,7 +15,15 @@
  * @doctrine Class strings carry no raw hex/oklch/oklab colours and no arbitrary Tailwind values - only design tokens and theme utilities.
  *
  * Usage:
- *   node scan-classes.mjs <path...> [--arbitrary] [--all] [--no-hex] [--exclude <substr>]
+ *   materia-ui-lint <path...> [--arbitrary] [--all] [--no-hex]
+ *                             [--exclude <substr>] [--json]
+ *   materia-ui-lint --help
+ *
+ * Exit codes:
+ *   0  no violations (or --help)
+ *   1  violations found
+ *   2  usage error (unknown flag, missing value, no paths)
+ *   3  a path could not be read
  */
 
 import { readFileSync, readdirSync, statSync } from "node:fs";
@@ -36,14 +44,106 @@ const HEX_PATTERN = /#[0-9a-fA-F]{3,8}\b/gu;
 const COLOR_FUNCTION = /\bokl(?:ch|ab)\(/giu;
 const ARBITRARY_PATTERN = /[a-z][a-z0-9]*(?:-[a-z0-9]+)*-\[[^\]]+\]/gu;
 
+const EXIT_VIOLATIONS = 1;
+const EXIT_USAGE = 2;
+const EXIT_IO = 3;
+
+/** @type {Record<RuleName, string>} */
+const MESSAGES = {
+  hex: "raw hex/oklch colour in class string - use a design token",
+  arbitrary: "arbitrary Tailwind value - use a token or theme utility",
+};
+
+const USAGE = `Usage: materia-ui-lint <path...> [options]
+
+Scan class strings for raw colours and arbitrary Tailwind values.
+Files (.ts .tsx .js .jsx .mjs .cjs) are found by walking each path.
+
+Options:
+  --arbitrary         Also flag arbitrary Tailwind values such as mt-[13px]
+  --all               Turn on every rule (hex and arbitrary)
+  --no-hex            Turn the hex rule off
+  --exclude <substr>  Skip paths containing <substr> (repeatable;
+                      --exclude=<substr> also works)
+  --json              Print one JSON document instead of text lines:
+                      { "violations": [{ file, line, column, rule, value,
+                      message }], "rules": [...], "files": <count> }
+  -h, --help          Show this help
+
+Exit codes:
+  0  no violations
+  1  violations found
+  2  usage error
+  3  a path could not be read
+`;
+
+/** A failure that ends the run with a message and a specific exit code. */
+class ScanError extends Error {
+  /**
+   * @param {string} message What to print to stderr.
+   * @param {number} exitCode The process exit code.
+   * @param {ErrorOptions} [options] The underlying cause, if any.
+   */
+  constructor(message, exitCode, options) {
+    super(message, options);
+    this.name = "ScanError";
+    this.exitCode = exitCode;
+  }
+}
+
+/**
+ * @param {string} message What was wrong with the command line.
+ * @returns {ScanError} An exit-2 error that points at `--help`.
+ */
+const usageError = (message) =>
+  new ScanError(`${message} (see --help)`, EXIT_USAGE);
+
+/**
+ * @typedef {object} Options
+ * @property {string[]} paths Files and directories to scan.
+ * @property {string[]} excludes Path fragments to skip.
+ * @property {boolean} hex Whether the `hex` rule is on.
+ * @property {boolean} arbitrary Whether the `arbitrary` rule is on.
+ * @property {boolean} json Whether to print a JSON document instead of text lines.
+ * @property {boolean} help Whether to print usage and stop.
+ */
+
+/** @typedef {"hex" | "arbitrary"} RuleName */
+
+/**
+ * @typedef {object} Region
+ * @property {number} start Offset of the region in the file.
+ * @property {string} body The region's text.
+ */
+
+/**
+ * @typedef {object} Violation
+ * @property {RuleName} rule The rule that matched.
+ * @property {string} value The offending text.
+ * @property {number} line One-based line of the match.
+ * @property {number} column One-based column of the match.
+ */
+
+/**
+ * @param {string[]} argv The command-line arguments after the script name.
+ * @returns {Options} What to scan and which rules are on.
+ * @throws {ScanError} On an unknown flag or an `--exclude` without a value.
+ */
 const parseArgs = (argv) => {
+  /** @type {string[]} */
   const paths = [];
+  /** @type {string[]} */
   const excludes = [];
   let hex = true;
   let arbitrary = false;
+  let json = false;
 
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
+  // `--exclude <substr>` takes the next argument, so walk an iterator.
+  const args = argv.values();
+  for (const arg of args) {
+    if (arg === "--help" || arg === "-h") {
+      return { paths, excludes, hex, arbitrary, json, help: true };
+    }
     if (arg === "--no-hex") {
       hex = false;
     } else if (arg === "--arbitrary") {
@@ -51,32 +151,94 @@ const parseArgs = (argv) => {
     } else if (arg === "--all") {
       hex = true;
       arbitrary = true;
+    } else if (arg === "--json") {
+      json = true;
     } else if (arg === "--exclude") {
-      index += 1;
-      if (argv[index] !== undefined) {
-        excludes.push(argv[index]);
+      const next = args.next();
+      if (next.done === true || next.value.startsWith("-")) {
+        throw usageError("--exclude needs a value");
       }
+      excludes.push(next.value);
     } else if (arg.startsWith("--exclude=")) {
-      excludes.push(arg.slice("--exclude=".length));
-    } else if (!arg.startsWith("--")) {
+      const value = arg.slice("--exclude=".length);
+      if (value === "") {
+        throw usageError("--exclude needs a value");
+      }
+      excludes.push(value);
+    } else if (arg.startsWith("-")) {
+      throw usageError(`unknown flag ${arg}`);
+    } else {
       paths.push(arg);
     }
   }
 
-  return { paths, excludes, hex, arbitrary };
+  return { paths, excludes, hex, arbitrary, json, help: false };
+};
+
+/**
+ * @param {unknown} error Whatever a filesystem call threw.
+ * @returns {string} Its error code, or its message when it has none.
+ */
+const describeFsError = (error) => {
+  if (error instanceof Error && "code" in error) {
+    return String(error.code);
+  }
+  return error instanceof Error ? error.message : String(error);
+};
+
+/**
+ * Run a filesystem call, naming the path if it fails.
+ *
+ * @template T
+ * @param {string} target The path the call touches.
+ * @param {() => T} action The filesystem call.
+ * @returns {T} What the call returned.
+ * @throws {ScanError} When the call throws.
+ */
+const reading = (target, action) => {
+  try {
+    return action();
+  } catch (error) {
+    throw new ScanError(
+      `cannot read ${target} (${describeFsError(error)})`,
+      EXIT_IO,
+      { cause: error }
+    );
+  }
 };
 
-const walk = (target, excludes, out) => {
-  if (excludes.some((fragment) => target.includes(fragment))) {
+/**
+ * @param {string[]} fragments Path fragments to skip.
+ * @returns {RegExp | undefined} A pattern matching any of them, if there are any.
+ */
+const excludePattern = (fragments) =>
+  fragments.length === 0
+    ? undefined
+    : new RegExp(
+        fragments
+          .map((fragment) =>
+            fragment.replaceAll(/[$()*+.?[\\\]^{|}]/gu, String.raw`\$&`)
+          )
+          .join("|"),
+        "u"
+      );
+
+/**
+ * @param {string} target A file or directory.
+ * @param {RegExp | undefined} excluded Matches the paths to skip.
+ * @param {string[]} out Collects the scannable files.
+ */
+const walk = (target, excluded, out) => {
+  if (excluded?.test(target) === true) {
     return;
   }
-  const stats = statSync(target);
+  const stats = reading(target, () => statSync(target));
   if (stats.isDirectory()) {
-    for (const entry of readdirSync(target)) {
+    for (const entry of reading(target, () => readdirSync(target))) {
       if (entry === "node_modules" || entry.startsWith(".")) {
         continue;
       }
-      walk(path.join(target, entry), excludes, out);
+      walk(path.join(target, entry), excluded, out);
     }
     return;
   }
@@ -86,6 +248,12 @@ const walk = (target, excludes, out) => {
   }
 };
 
+/**
+ * @param {string} text The file text.
+ * @param {number} openIndex Offset of the opening quote.
+ * @param {string} quote The quote character that closes the string.
+ * @returns {number} Offset of the closing quote, or the last offset if unclosed.
+ */
 const findStringEnd = (text, openIndex, quote) => {
   for (let index = openIndex + 1; index < text.length; index += 1) {
     const char = text[index];
@@ -100,6 +268,13 @@ const findStringEnd = (text, openIndex, quote) => {
   return text.length - 1;
 };
 
+/**
+ * @param {string} text The file text.
+ * @param {number} openIndex Offset of the opening bracket.
+ * @param {string} open The opening bracket character.
+ * @param {string} close The closing bracket character.
+ * @returns {number} Offset of the matching close, or the last offset if unbalanced.
+ */
 const findMatching = (text, openIndex, open, close) => {
   let depth = 0;
   for (let index = openIndex; index < text.length; index += 1) {
@@ -121,8 +296,12 @@ const findMatching = (text, openIndex, open, close) => {
  * attribute values plus the argument lists of the common class-composition
  * helpers. Scanning only these ranges keeps hex detection off inline styles and
  * ordinary colour constants.
+ *
+ * @param {string} text The file text.
+ * @returns {Region[]} The class-string ranges, in source order within each kind.
  */
 const extractClassRegions = (text) => {
+  /** @type {Region[]} */
   const regions = [];
 
   CLASS_ATTRIBUTE.lastIndex = 0;
@@ -159,6 +338,11 @@ const extractClassRegions = (text) => {
   return regions;
 };
 
+/**
+ * @param {string} text The file text.
+ * @param {number} offset A character offset into it.
+ * @returns {{ line: number, column: number }} The one-based line and column.
+ */
 const lineColumnAt = (text, offset) => {
   let line = 1;
   let lineStart = 0;
@@ -171,6 +355,14 @@ const lineColumnAt = (text, offset) => {
   return { line, column: offset - lineStart + 1 };
 };
 
+/**
+ * @param {Region} region The class-string range to search.
+ * @param {RegExp} pattern The global pattern to match.
+ * @param {RuleName} rule The rule a match counts against.
+ * @param {string} text The whole file, for line and column.
+ * @param {Set<string>} seen Offset and rule pairs already reported.
+ * @param {Violation[]} violations Collects the matches.
+ */
 const collectMatches = (region, pattern, rule, text, seen, violations) => {
   pattern.lastIndex = 0;
   let match = pattern.exec(region.body);
@@ -186,10 +378,17 @@ const collectMatches = (region, pattern, rule, text, seen, violations) => {
   }
 };
 
+/**
+ * @param {string} file The file to scan.
+ * @param {{ hex: boolean, arbitrary: boolean }} rules Which rules are on.
+ * @returns {Violation[]} The violations, ordered by position.
+ */
 const scanFile = (file, rules) => {
-  const text = readFileSync(file, "utf-8");
+  const text = reading(file, () => readFileSync(file, "utf-8"));
   const regions = extractClassRegions(text);
+  /** @type {Violation[]} */
   const violations = [];
+  /** @type {Set<string>} */
   const seen = new Set();
 
   for (const region of regions) {
@@ -213,42 +412,79 @@ const scanFile = (file, rules) => {
   return violations;
 };
 
-const main = () => {
-  const { paths, excludes, hex, arbitrary } = parseArgs(process.argv.slice(2));
+/**
+ * @param {Options} options The parsed command line.
+ * @returns {number} The exit code.
+ * @throws {ScanError} When no paths are given or a path cannot be read.
+ */
+const run = (options) => {
+  const { paths, excludes, hex, arbitrary, json } = options;
   if (paths.length === 0) {
-    process.stderr.write("scan-classes: no paths supplied\n");
-    process.exit(2);
+    throw usageError("no paths supplied");
   }
 
+  /** @type {string[]} */
   const files = [];
+  const excluded = excludePattern(excludes);
   for (const target of paths) {
-    walk(target, excludes, files);
+    walk(target, excluded, files);
+  }
+
+  /** @type {RuleName[]} */
+  const rules = [];
+  if (hex) {
+    rules.push("hex");
+  }
+  if (arbitrary) {
+    rules.push("arbitrary");
   }
 
-  const messages = {
-    hex: "raw hex/oklch colour in class string - use a design token",
-    arbitrary: "arbitrary Tailwind value - use a token or theme utility",
-  };
+  const reported = files.flatMap((file) =>
+    scanFile(file, { hex, arbitrary }).map((violation) => ({
+      file,
+      line: violation.line,
+      column: violation.column,
+      rule: violation.rule,
+      value: violation.value,
+      message: MESSAGES[violation.rule],
+    }))
+  );
 
-  let total = 0;
-  for (const file of files) {
-    const violations = scanFile(file, { hex, arbitrary });
-    for (const violation of violations) {
-      total += 1;
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify({ violations: reported, rules, files: files.length })}\n`
+    );
+  } else {
+    for (const v of reported) {
       process.stdout.write(
-        `${file}:${violation.line}:${violation.column}  ${violation.rule}  ${violation.value}  ${messages[violation.rule]}\n`
+        `${v.file}:${v.line}:${v.column}  ${v.rule}  ${v.value}  ${v.message}\n`
+      );
+    }
+    if (reported.length > 0) {
+      process.stderr.write(
+        `\nscan-classes: ${reported.length} violation(s) [rules: ${rules.join(", ")}]\n`
       );
     }
   }
 
-  if (total > 0) {
-    const active = [hex ? "hex" : null, arbitrary ? "arbitrary" : null]
-      .filter(Boolean)
-      .join(", ");
-    process.stderr.write(
-      `\nscan-classes: ${total} violation(s) [rules: ${active}]\n`
-    );
-    process.exit(1);
+  return reported.length > 0 ? EXIT_VIOLATIONS : 0;
+};
+
+const main = () => {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+      process.stdout.write(USAGE);
+      return;
+    }
+    // Set rather than `process.exit()` so piped output is flushed first.
+    process.exitCode = run(options);
+  } catch (error) {
+    if (!(error instanceof ScanError)) {
+      throw error;
+    }
+    process.stderr.write(`scan-classes: ${error.message}\n`);
+    process.exitCode = error.exitCode;
   }
 };
 

package/lint/tokens.d.mts

@@ -1,16 +1,24 @@
-/** Every `--color-<name>` the stylesheet declares, as `<name>`. */
-export const colorTokens: readonly string[];
+// GENERATED by scripts/generate-lint-types.ts from the JSDoc in lint/tokens.mjs - do not edit.
+// Regenerate with `pnpm --filter @instruments/materia-ui generate:lint-types`.
 
-/** Every `--text-<name>` type role the stylesheet declares, as `<name>`. */
+/**
+ * Every `--color-<name>` the stylesheet declares, as `<name>`.
+ */
+export const colorTokens: readonly string[];
+/**
+ * Every `--text-<name>` type role the stylesheet declares, as `<name>`.
+ */
 export const textRoles: readonly string[];
-
 /**
- * `shadcn/no-raw-colors` with Materia's tokens allowed: any utility on a
- * declared colour and every `text-<role>`. Spread it into an oxlint `rules`.
+ * `shadcn/no-raw-colors` with Materia's tokens allowed: any utility on a declared
+ * colour (`bg-primary`, `border-muted-foreground`) and every `text-<role>`,
+ * which the rule would otherwise read as an undeclared colour.
  */
 export const rawColorsRule: {
-  readonly "shadcn/no-raw-colors": readonly [
+  readonly "shadcn/no-raw-colors": [
     "error",
-    { readonly allow: readonly string[] },
+    {
+      readonly allow: readonly string[];
+    },
   ];
 };

package/lint/tokens.mjs

@@ -1,11 +1,15 @@
-// GENERATED by scripts/generate-lint-tokens.mjs from src/styles/index.css - do not edit.
+// GENERATED by scripts/generate-lint-tokens.ts from src/styles/index.css - do not edit.
 // Regenerate with `pnpm --filter @instruments/materia-ui generate:lint-tokens`.
 //
 // Published as `@instruments/materia-ui/lint/tokens`. `shadcn/no-raw-colors`
 // skips stylesheets under node_modules, so it cannot see the tokens this package
 // declares; spread `rawColorsRule` into an app's oxlint `rules` to allow them.
 
-/** Every `--color-<name>` the stylesheet declares, as `<name>`. */
+/**
+ * Every `--color-<name>` the stylesheet declares, as `<name>`.
+ *
+ * @type {readonly string[]}
+ */
 export const colorTokens = [
   "accent",
   "accent-foreground",
@@ -95,7 +99,11 @@ export const colorTokens = [
   "warning-soft",
 ];
 
-/** Every `--text-<name>` type role the stylesheet declares, as `<name>`. */
+/**
+ * Every `--text-<name>` type role the stylesheet declares, as `<name>`.
+ *
+ * @type {readonly string[]}
+ */
 export const textRoles = [
   "2xs",
   "calendar",
@@ -117,6 +125,8 @@ export const textRoles = [
  * `shadcn/no-raw-colors` with Materia's tokens allowed: any utility on a declared
  * colour (`bg-primary`, `border-muted-foreground`) and every `text-<role>`,
  * which the rule would otherwise read as an undeclared colour.
+ *
+ * @type {{ readonly "shadcn/no-raw-colors": ["error", { readonly allow: readonly string[] }] }}
  */
 export const rawColorsRule = {
   "shadcn/no-raw-colors": [

package/lint/type-case.d.mts

@@ -1,12 +1,20 @@
-/** The `no-raw-type-utilities` options: the modifiers allowed beside a type role. */
-export interface TypeCase {
-  readonly allow: readonly string[];
-}
+// GENERATED by scripts/generate-lint-types.ts from the JSDoc in lint/type-case.mjs - do not edit.
+// Regenerate with `pnpm --filter @instruments/materia-ui generate:lint-types`.
 
-/** The modifiers that may sit beside a role: weights, mono, italic and the like. */
+/**
+ * The modifiers that may sit beside a role: weights, mono, italic and the like.
+ */
 export const typeCase: TypeCase;
-
-/** `howells/no-raw-type-utilities` with the type case. Spread it into an oxlint `rules`. */
+/**
+ * `howells/no-raw-type-utilities` with the type case. Spread it into an oxlint
+ * `rules`.
+ */
 export const typeCaseRule: {
-  readonly "howells/no-raw-type-utilities": readonly ["error", TypeCase];
+  readonly "howells/no-raw-type-utilities": ["error", TypeCase];
 };
+/**
+ * The `no-raw-type-utilities` options: the modifiers allowed beside a type role.
+ */
+export interface TypeCase {
+  readonly allow: readonly string[];
+}

package/lint/type-case.mjs

@@ -15,6 +15,17 @@
 //
 // @doctrine Text takes its size, leading and tracking from a role on the type ramp (text-caption to text-title) or the Text and Heading size props, never from raw Tailwind typography such as text-sm, leading-* or tracking-*.
 
+/**
+ * The `no-raw-type-utilities` options: the modifiers allowed beside a type role.
+ *
+ * @typedef {{ readonly allow: readonly string[] }} TypeCase
+ */
+
+/**
+ * The modifiers that may sit beside a role: weights, mono, italic and the like.
+ *
+ * @type {TypeCase}
+ */
 export const typeCase = {
   allow: [
     "font-normal",
@@ -28,6 +39,12 @@ export const typeCase = {
   ],
 };
 
+/**
+ * `howells/no-raw-type-utilities` with the type case. Spread it into an oxlint
+ * `rules`.
+ *
+ * @type {{ readonly "howells/no-raw-type-utilities": ["error", TypeCase] }}
+ */
 export const typeCaseRule = {
   "howells/no-raw-type-utilities": ["error", typeCase],
 };