@instruments/materia-ui 0.1.0

package/lint/scan-classes.mjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+/**
+ * Class-string lint scanner for the `@instruments/materia-ui/lint` consumer preset.
+ *
+ * Enforces the two rules that
+ * cannot be expressed as import restrictions and therefore need a class-string
+ * scanner:
+ *   - hex        no raw hex / oklch / oklab colour values inside class strings
+ *   - arbitrary  no arbitrary Tailwind values (mt-[13px], bg-[#fff], w-[calc(...)])
+ *
+ * Rules are opt-in per invocation. By default only `hex` is active; `arbitrary`
+ * ships disabled-by-default and is enabled with the `--arbitrary` flag (or
+ * `--all`). See ./README.md for the full rollout rationale.
+ *
+ * @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>]
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const SCANNED_EXTENSIONS = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+]);
+const CLASS_ATTRIBUTE = /\bclass(?:Name)?\s*=\s*/gu;
+const CLASS_HELPER = /\b(?:cn|cx|clsx|cva|tv|twMerge|twJoin|classNames)\s*\(/gu;
+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 parseArgs = (argv) => {
+  const paths = [];
+  const excludes = [];
+  let hex = true;
+  let arbitrary = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--no-hex") {
+      hex = false;
+    } else if (arg === "--arbitrary") {
+      arbitrary = true;
+    } else if (arg === "--all") {
+      hex = true;
+      arbitrary = true;
+    } else if (arg === "--exclude") {
+      index += 1;
+      if (argv[index] !== undefined) {
+        excludes.push(argv[index]);
+      }
+    } else if (arg.startsWith("--exclude=")) {
+      excludes.push(arg.slice("--exclude=".length));
+    } else if (!arg.startsWith("--")) {
+      paths.push(arg);
+    }
+  }
+
+  return { paths, excludes, hex, arbitrary };
+};
+
+const walk = (target, excludes, out) => {
+  if (excludes.some((fragment) => target.includes(fragment))) {
+    return;
+  }
+  const stats = statSync(target);
+  if (stats.isDirectory()) {
+    for (const entry of readdirSync(target)) {
+      if (entry === "node_modules" || entry.startsWith(".")) {
+        continue;
+      }
+      walk(path.join(target, entry), excludes, out);
+    }
+    return;
+  }
+  const dot = target.lastIndexOf(".");
+  if (dot !== -1 && SCANNED_EXTENSIONS.has(target.slice(dot))) {
+    out.push(target);
+  }
+};
+
+const findStringEnd = (text, openIndex, quote) => {
+  for (let index = openIndex + 1; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === "\\") {
+      index += 1;
+      continue;
+    }
+    if (char === quote) {
+      return index;
+    }
+  }
+  return text.length - 1;
+};
+
+const findMatching = (text, openIndex, open, close) => {
+  let depth = 0;
+  for (let index = openIndex; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === open) {
+      depth += 1;
+    } else if (char === close) {
+      depth -= 1;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return text.length - 1;
+};
+
+/**
+ * Extract the character ranges of every class string in a file: className/class
+ * 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.
+ */
+const extractClassRegions = (text) => {
+  const regions = [];
+
+  CLASS_ATTRIBUTE.lastIndex = 0;
+  let attrMatch = CLASS_ATTRIBUTE.exec(text);
+  while (attrMatch !== null) {
+    const valueStart = attrMatch.index + attrMatch[0].length;
+    const opener = text[valueStart];
+    let end = valueStart;
+    if (opener === '"' || opener === "'" || opener === "`") {
+      end = findStringEnd(text, valueStart, opener);
+    } else if (opener === "{") {
+      end = findMatching(text, valueStart, "{", "}");
+    }
+    if (end > valueStart) {
+      regions.push({
+        start: valueStart,
+        body: text.slice(valueStart, end + 1),
+      });
+      CLASS_ATTRIBUTE.lastIndex = end + 1;
+    }
+    attrMatch = CLASS_ATTRIBUTE.exec(text);
+  }
+
+  CLASS_HELPER.lastIndex = 0;
+  let callMatch = CLASS_HELPER.exec(text);
+  while (callMatch !== null) {
+    const openParen = callMatch.index + callMatch[0].length - 1;
+    const end = findMatching(text, openParen, "(", ")");
+    regions.push({ start: openParen, body: text.slice(openParen, end + 1) });
+    CLASS_HELPER.lastIndex = end + 1;
+    callMatch = CLASS_HELPER.exec(text);
+  }
+
+  return regions;
+};
+
+const lineColumnAt = (text, offset) => {
+  let line = 1;
+  let lineStart = 0;
+  for (let index = 0; index < offset; index += 1) {
+    if (text[index] === "\n") {
+      line += 1;
+      lineStart = index + 1;
+    }
+  }
+  return { line, column: offset - lineStart + 1 };
+};
+
+const collectMatches = (region, pattern, rule, text, seen, violations) => {
+  pattern.lastIndex = 0;
+  let match = pattern.exec(region.body);
+  while (match !== null) {
+    const offset = region.start + match.index;
+    const key = `${offset}:${rule}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      const position = lineColumnAt(text, offset);
+      violations.push({ rule, value: match[0], ...position });
+    }
+    match = pattern.exec(region.body);
+  }
+};
+
+const scanFile = (file, rules) => {
+  const text = readFileSync(file, "utf-8");
+  const regions = extractClassRegions(text);
+  const violations = [];
+  const seen = new Set();
+
+  for (const region of regions) {
+    if (rules.hex) {
+      collectMatches(region, HEX_PATTERN, "hex", text, seen, violations);
+      collectMatches(region, COLOR_FUNCTION, "hex", text, seen, violations);
+    }
+    if (rules.arbitrary) {
+      collectMatches(
+        region,
+        ARBITRARY_PATTERN,
+        "arbitrary",
+        text,
+        seen,
+        violations
+      );
+    }
+  }
+
+  violations.sort((a, b) => a.line - b.line || a.column - b.column);
+  return violations;
+};
+
+const main = () => {
+  const { paths, excludes, hex, arbitrary } = parseArgs(process.argv.slice(2));
+  if (paths.length === 0) {
+    process.stderr.write("scan-classes: no paths supplied\n");
+    process.exit(2);
+  }
+
+  const files = [];
+  for (const target of paths) {
+    walk(target, excludes, files);
+  }
+
+  const messages = {
+    hex: "raw hex/oklch colour in class string - use a design token",
+    arbitrary: "arbitrary Tailwind value - use a token or theme utility",
+  };
+
+  let total = 0;
+  for (const file of files) {
+    const violations = scanFile(file, { hex, arbitrary });
+    for (const violation of violations) {
+      total += 1;
+      process.stdout.write(
+        `${file}:${violation.line}:${violation.column}  ${violation.rule}  ${violation.value}  ${messages[violation.rule]}\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);
+  }
+};
+
+main();

package/lint/tokens.d.mts

@@ -0,0 +1,16 @@
+/** 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`.
+ */
+export const rawColorsRule: {
+  readonly "shadcn/no-raw-colors": readonly [
+    "error",
+    { readonly allow: readonly string[] },
+  ];
+};

package/lint/tokens.mjs

@@ -0,0 +1,130 @@
+// GENERATED by scripts/generate-lint-tokens.mjs 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>`. */
+export const colorTokens = [
+  "accent",
+  "accent-foreground",
+  "affirmative-accent",
+  "affirmative-border",
+  "affirmative-foreground",
+  "affirmative-soft",
+  "alpha-10",
+  "alpha-20",
+  "alpha-30",
+  "alpha-40",
+  "alpha-5",
+  "alpha-50",
+  "alpha-60",
+  "alpha-70",
+  "alpha-80",
+  "alpha-90",
+  "background",
+  "black-alpha-10",
+  "black-alpha-20",
+  "black-alpha-30",
+  "black-alpha-40",
+  "black-alpha-5",
+  "black-alpha-50",
+  "black-alpha-60",
+  "black-alpha-70",
+  "black-alpha-80",
+  "black-alpha-90",
+  "border",
+  "border-subtle",
+  "brand",
+  "brand-accent",
+  "brand-foreground",
+  "brand-soft",
+  "card",
+  "card-background",
+  "card-border",
+  "card-foreground",
+  "card-muted",
+  "destructive",
+  "destructive-foreground",
+  "error-accent",
+  "error-border",
+  "error-foreground",
+  "error-soft",
+  "favorite",
+  "foreground",
+  "foreground-wash",
+  "info-accent",
+  "info-border",
+  "info-foreground",
+  "info-soft",
+  "input",
+  "muted",
+  "muted-foreground",
+  "paper",
+  "popover",
+  "popover-foreground",
+  "primary",
+  "primary-foreground",
+  "ring",
+  "secondary",
+  "secondary-foreground",
+  "sidebar",
+  "sidebar-accent",
+  "sidebar-accent-foreground",
+  "sidebar-border",
+  "sidebar-foreground",
+  "sidebar-primary",
+  "sidebar-primary-foreground",
+  "sidebar-ring",
+  "surface-0",
+  "surface-1",
+  "surface-2",
+  "surface-inset",
+  "surface-raised",
+  "surface-sunk",
+  "text-muted",
+  "text-primary",
+  "text-secondary",
+  "tool-scrim",
+  "tool-scrim-hover",
+  "warning-accent",
+  "warning-border",
+  "warning-foreground",
+  "warning-soft",
+];
+
+/** Every `--text-<name>` type role the stylesheet declares, as `<name>`. */
+export const textRoles = [
+  "2xs",
+  "calendar",
+  "caption",
+  "grid-header",
+  "heading",
+  "heading-lg",
+  "heading-sm",
+  "micro",
+  "paragraph",
+  "paragraph-lg",
+  "paragraph-sm",
+  "subheading",
+  "subheading-lg",
+  "title",
+];
+
+/**
+ * `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 = {
+  "shadcn/no-raw-colors": [
+    "error",
+    {
+      allow: [
+        ...colorTokens.map((name) => `*-${name}`),
+        ...textRoles.map((name) => `text-${name}`),
+      ],
+    },
+  ],
+};

package/lint/type-case.d.mts

@@ -0,0 +1,12 @@
+/** The `no-raw-type-utilities` options: the modifiers allowed beside a type role. */
+export interface TypeCase {
+  readonly allow: readonly string[];
+}
+
+/** 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`. */
+export const typeCaseRule: {
+  readonly "howells/no-raw-type-utilities": readonly ["error", TypeCase];
+};

package/lint/type-case.mjs

@@ -0,0 +1,33 @@
+// Published as `@instruments/materia-ui/lint/type-case`, so a consuming app
+// enforces the same case: spread `typeCaseRule` into its oxlint `rules`.
+//
+// The type case: text takes its shape (size, leading, tracking, case) from one
+// named role on the ramp in packages/ui/src/styles/index.css, never from raw
+// Tailwind typography written inline. Each role owns its leading and tracking,
+// so `leading-*`, `tracking-*` and `uppercase` have no place beside it.
+//
+// The roles are the `--text-*` theme steps, from `text-2xs` to `text-title`,
+// plus the surface-named one-offs beside them (`text-micro`, `text-calendar`,
+// `text-grid-header`). Those names sit outside the governed namespace, so they
+// need no entry below. What `allow` lists are the modifiers that may sit beside
+// a role: the three weights the system uses, mono for code and data, the
+// folder tile's named tracking, italic, and `capitalize` for casing a data value.
+//
+// @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-*.
+
+export const typeCase = {
+  allow: [
+    "font-normal",
+    "font-medium",
+    "font-semibold",
+    "font-mono",
+    "tracking-folder-label",
+    "italic",
+    "not-italic",
+    "capitalize",
+  ],
+};
+
+export const typeCaseRule = {
+  "howells/no-raw-type-utilities": ["error", typeCase],
+};