@urbicon-ui/design-engine 6.1.8

package/src/linter/markup.ts

@@ -0,0 +1,274 @@
+/**
+ * A small, dependency-free markup scanner — the structural pass the regex rules
+ * cannot be (DESIGN-MCP-V2 §6/§10 "AST pass"). It does NOT build a full Svelte
+ * AST (that would mean a `svelte/compiler` dependency, and this engine is
+ * zero-dep): it extracts the one thing the line-based rules miss — *which
+ * attribute belongs to which element* — by walking the source once and emitting a
+ * flat list of opening tags with their attributes, plus a helper to slice an
+ * element's inner content.
+ *
+ * It is deliberately conservative: anything it cannot parse confidently (an
+ * unterminated tag, an exotic expression) is skipped, never guessed. A rule built
+ * on this therefore never fires on a mis-parse — a missed element is silence, not
+ * a false positive, which is the contract the correctness gate depends on.
+ */
+
+/** How an attribute carries its value. */
+export type AttrKind =
+  | 'string' // attr="literal" / attr='literal' / attr=bare
+  | 'expression' // attr={expr}
+  | 'boolean' // bare attr, no value
+  | 'shorthand' // {value} — name and expression are the same identifier
+  | 'spread'; // {...rest}
+
+export interface Attr {
+  /** Attribute name, e.g. `variant`, `aria-label`, `on:click`. Empty for spread/shorthand. */
+  name: string;
+  /** Raw inner value (no quotes/braces); `null` for a boolean attribute. */
+  value: string | null;
+  kind: AttrKind;
+  /** 1-based line of the attribute name. */
+  line: number;
+}
+
+export interface Element {
+  /** Tag name as written, e.g. `Button`, `button`, `Foo.Bar`. */
+  tag: string;
+  /** PascalCase or dotted tag → a component (not a raw HTML element). */
+  isComponent: boolean;
+  attrs: Attr[];
+  /** 1-based line of the opening `<`. */
+  line: number;
+  selfClosing: boolean;
+  /** Char offset of the opening `<`. */
+  openStart: number;
+  /** Char offset just past the opening tag's `>`. */
+  openEnd: number;
+}
+
+const blankRegion = (s: string): string => s.replace(/[^\n]/g, ' ');
+
+/**
+ * Blank HTML comments and `<script>`/`<style>` blocks (keeping newlines so line
+ * numbers hold) — their bodies are comments/JS/CSS, not markup, and would feed the
+ * tag scanner garbage. Comments are blanked here too (not relying on an upstream
+ * mask) so {@link scanMarkup} and {@link innerContent} are correct on raw input.
+ *
+ * Caveat: the `<script>` match is non-greedy, so a `</script>` literal inside a JS
+ * string ends the blank early and the trailing JS is then scanned as markup. This
+ * is narrower than the line-based rules (which don't blank scripts at all); no real
+ * file hits it, and any mis-scan only ever yields a skipped tag, never a wrong
+ * finding from the curated rules.
+ */
+function blankNonMarkup(src: string): string {
+  return src
+    .replace(/<!--[\s\S]*?-->/g, blankRegion)
+    .replace(/<script[\s\S]*?<\/script>/gi, blankRegion)
+    .replace(/<style[\s\S]*?<\/style>/gi, blankRegion);
+}
+
+const isNameStart = (c: string | undefined): boolean => c !== undefined && /[A-Za-z]/.test(c);
+const isTagNameChar = (c: string | undefined): boolean =>
+  c !== undefined && /[A-Za-z0-9.\-:]/.test(c);
+const isAttrNameChar = (c: string | undefined): boolean =>
+  c !== undefined && !/[\s=/>]/.test(c) && c !== '<';
+
+/** Read a quoted string starting at `src[i]` (a quote char). Returns inner value + index past the close. */
+function readQuoted(src: string, i: number): { value: string; end: number } {
+  const quote = src[i];
+  let j = i + 1;
+  while (j < src.length && src[j] !== quote) j++;
+  return { value: src.slice(i + 1, j), end: j + 1 }; // j+1 steps past the closing quote (or EOF)
+}
+
+/**
+ * Read a balanced `{…}` expression starting at `src[i]` (`{`). Brace depth counts
+ * outside of `"`/`'` strings (so a `}` inside a string literal does not close it,
+ * and a `\"` escape does not end the string early); `${…}` in template literals
+ * balances naturally through the same counter. Returns the inner text + index past
+ * the closing brace, or `end: -1` if never closed.
+ */
+function readBraced(src: string, i: number): { value: string; end: number } {
+  let depth = 0;
+  let str: string | null = null; // active "/' string delimiter, if any
+  for (let j = i; j < src.length; j++) {
+    const c = src[j];
+    if (str !== null) {
+      if (c === '\\') {
+        j++; // a backslash escapes the next char — don't let `\"` close the string early
+        continue;
+      }
+      if (c === str) str = null;
+      continue;
+    }
+    if (c === '"' || c === "'") str = c;
+    else if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (depth === 0) return { value: src.slice(i + 1, j), end: j + 1 };
+    }
+  }
+  return { value: '', end: -1 };
+}
+
+/** Parse one attribute starting at `src[i]` (first name/`{` char). Returns the attr + next index, or null if malformed. */
+function parseAttr(src: string, i: number, line: number): { attr: Attr; end: number } | null {
+  if (src[i] === '{') {
+    const { value, end } = readBraced(src, i);
+    if (end === -1) return null;
+    const trimmed = value.trim();
+    const spread = trimmed.startsWith('...');
+    return {
+      attr: {
+        name: spread ? '' : trimmed,
+        value: spread ? trimmed.slice(3).trim() : trimmed,
+        kind: spread ? 'spread' : 'shorthand',
+        line
+      },
+      end
+    };
+  }
+
+  let j = i;
+  while (isAttrNameChar(src[j])) j++;
+  const name = src.slice(i, j);
+  if (name === '') return null; // not a valid attribute start — bail (caller skips the tag)
+
+  // Optional `= value`, allowing whitespace around `=`.
+  let k = j;
+  while (k < src.length && /\s/.test(src[k]!)) k++;
+  if (src[k] !== '=') {
+    return { attr: { name, value: null, kind: 'boolean', line }, end: j };
+  }
+  k++; // past '='
+  while (k < src.length && /\s/.test(src[k]!)) k++;
+
+  const c = src[k];
+  if (c === '"' || c === "'") {
+    const { value, end } = readQuoted(src, k);
+    return { attr: { name, value, kind: 'string', line }, end };
+  }
+  if (c === '{') {
+    const { value, end } = readBraced(src, k);
+    if (end === -1) return null;
+    return { attr: { name, value, kind: 'expression', line }, end };
+  }
+  // Bare unquoted value: read until whitespace or tag end.
+  let m = k;
+  while (m < src.length && !/[\s/>]/.test(src[m]!)) m++;
+  return { attr: { name, value: src.slice(k, m), kind: 'string', line }, end: m };
+}
+
+/** Parse an opening tag starting at `src[start]` (`<`). Returns the element + index past `>`, or null. */
+function parseOpenTag(
+  src: string,
+  start: number,
+  line: number
+): { element: Element; end: number } | null {
+  let i = start + 1;
+  while (isTagNameChar(src[i])) i++;
+  const tag = src.slice(start + 1, i);
+  if (tag === '') return null;
+
+  const attrs: Attr[] = [];
+  let curLine = line;
+  // Count newlines as we advance so each attr/tag gets the right line.
+  const bump = (from: number, to: number): void => {
+    for (let p = from; p < to; p++) if (src[p] === '\n') curLine++;
+  };
+
+  let selfClosing = false;
+  let closed = false;
+  while (i < src.length) {
+    const before = i;
+    while (i < src.length && /\s/.test(src[i]!)) i++;
+    bump(before, i);
+
+    const c = src[i];
+    if (c === undefined) break; // EOF reached — `closed` stays false, rejected below
+    if (c === '>') {
+      i++;
+      closed = true;
+      break;
+    }
+    if (c === '/' && src[i + 1] === '>') {
+      selfClosing = true;
+      i += 2;
+      closed = true;
+      break;
+    }
+    const parsed = parseAttr(src, i, curLine);
+    if (!parsed) return null; // unparseable attribute — skip the whole tag conservatively
+    attrs.push(parsed.attr);
+    bump(i, parsed.end);
+    i = parsed.end;
+  }
+  if (!closed) return null; // ran off the end without a `>`/`/>` — malformed, skip
+
+  const isComponent = /^[A-Z]/.test(tag) || tag.includes('.');
+  return {
+    element: { tag, isComponent, attrs, line, selfClosing, openStart: start, openEnd: i },
+    end: i
+  };
+}
+
+/** Scan source for opening element/component tags with their attributes. */
+export function scanMarkup(source: string): Element[] {
+  const src = blankNonMarkup(source);
+  const elements: Element[] = [];
+  let line = 1;
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === '\n') {
+      line++;
+      i++;
+      continue;
+    }
+    // A tag opens at `<` immediately followed by a letter (not `</`, `<!`, `< `).
+    if (c === '<' && isNameStart(src[i + 1])) {
+      const parsed = parseOpenTag(src, i, line);
+      if (parsed) {
+        elements.push(parsed.element);
+        for (let p = i; p < parsed.end; p++) if (src[p] === '\n') line++;
+        i = parsed.end;
+        continue;
+      }
+    }
+    i++;
+  }
+  return elements;
+}
+
+/** Does `src` have `<tag`/`</tag` at `pos` with a real tag boundary after the name? */
+function tagAt(src: string, pos: number, tag: string, closing: boolean): boolean {
+  const lead = closing ? `</${tag}` : `<${tag}`;
+  if (!src.startsWith(lead, pos)) return false;
+  const after = src[pos + lead.length];
+  return after === undefined || /[\s/>]/.test(after);
+}
+
+/**
+ * The raw inner content of an element (between its opening `>` and matching
+ * `</tag>`), honouring same-name nesting. Returns `null` for a self-closing
+ * element or when no balanced close is found — callers treat `null` as "unknown",
+ * and skip, so an unbalanced document never produces a false finding.
+ */
+export function innerContent(source: string, el: Element): string | null {
+  if (el.selfClosing) return null;
+  const src = blankNonMarkup(source);
+  let depth = 1;
+  let i = el.openEnd;
+  while (i < src.length) {
+    if (src[i] === '<') {
+      if (tagAt(src, i, el.tag, true)) {
+        depth--;
+        if (depth === 0) return src.slice(el.openEnd, i);
+      } else if (tagAt(src, i, el.tag, false)) {
+        depth++;
+      }
+    }
+    i++;
+  }
+  return null;
+}

package/src/linter/rules.ts

@@ -0,0 +1,354 @@
+/**
+ * Deterministic design rules. Each is a fact about the code — a regex/string
+ * match with no judgement — so it can carry `error`/`warning` severity and be
+ * covered by regression tests. The prose source is the Anti-Patterns section of
+ * `design-system/principles.md` plus the documented known failure modes
+ * (token hallucination, dynamic Tailwind classes).
+ */
+
+import { MARKUP_RULES } from './markup-rules.js';
+import {
+  INTENT_NAMES,
+  INTENT_PREFIXES,
+  KNOWN_BAD_NAMESPACES,
+  KNOWN_FOREIGN_CORES,
+  SEMANTIC_NAMESPACES,
+  VALID_TOKEN_CORES
+} from './tokens.js';
+import type { Finding, Rule } from './types.js';
+
+const SHADCN_FIX =
+  'This is shadcn/ui vocabulary, not Urbicon UI. Use surface tokens (`bg-surface-base`/`-elevated`), text tokens (`text-text-primary`/`-secondary`), or intents (`bg-primary`, `text-success`).';
+
+/** shadcn/ui-family cores (bare set + `-foreground` suffix + `fg`/`fg-`). */
+function isForeignVocab(core: string): boolean {
+  return (
+    KNOWN_FOREIGN_CORES.has(core) ||
+    core.endsWith('-foreground') ||
+    core === 'fg' ||
+    core.startsWith('fg-')
+  );
+}
+
+/** Tailwind's default chromatic palette names — none are Urbicon UI tokens. `neutral` is ours, so it is excluded. */
+const RAW_PALETTE =
+  'slate|gray|zinc|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose';
+
+/** Colour-bearing Tailwind prefixes (longest first so `border-l` wins over `border`). */
+const COLOR_PREFIXES = [
+  'ring-offset',
+  'border-x',
+  'border-y',
+  'border-t',
+  'border-r',
+  'border-b',
+  'border-l',
+  'border-s',
+  'border-e',
+  'bg',
+  'text',
+  'border',
+  'ring',
+  'divide',
+  'outline',
+  'decoration',
+  'fill',
+  'stroke',
+  'from',
+  'via',
+  'to',
+  'accent',
+  'caret',
+  'placeholder'
+];
+
+/** Tailwind utility roots that take a scale/value — used to catch broken dynamic interpolation. */
+const DYNAMIC_UTILITY_ROOTS = [
+  'gap',
+  'gap-x',
+  'gap-y',
+  'space-x',
+  'space-y',
+  'p',
+  'px',
+  'py',
+  'pt',
+  'pb',
+  'pl',
+  'pr',
+  'm',
+  'mx',
+  'my',
+  'mt',
+  'mb',
+  'ml',
+  'mr',
+  'w',
+  'h',
+  'min-w',
+  'min-h',
+  'max-w',
+  'max-h',
+  'size',
+  'text',
+  'bg',
+  'border',
+  'rounded',
+  'grid-cols',
+  'grid-rows',
+  'col-span',
+  'row-span',
+  'top',
+  'left',
+  'right',
+  'bottom',
+  'inset',
+  'z',
+  'leading',
+  'tracking',
+  'opacity',
+  'scale',
+  'rotate',
+  'translate-x',
+  'translate-y',
+  'duration',
+  'delay'
+];
+
+function dedupeByLine(findings: Finding[]): Finding[] {
+  const seen = new Set<string>();
+  const out: Finding[] = [];
+  for (const f of findings) {
+    const key = `${f.ruleId}:${f.line}:${f.match}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(f);
+  }
+  return out;
+}
+
+const rawTailwindColor: Rule = {
+  id: 'raw-tailwind-color',
+  severity: 'error',
+  description: 'Raw Tailwind palette colour (e.g. `bg-blue-500`) instead of a semantic token.',
+  check(lines) {
+    // Trailing `(?![a-z0-9-])` (not `\b`) so an optional `/NN` opacity suffix stays in the match.
+    const re = new RegExp(
+      `\\b(?:${COLOR_PREFIXES.join('|')})-(?:${RAW_PALETTE})-(?:50|100|200|300|400|500|600|700|800|900|950)(?:\\/\\d{1,3})?(?![a-z0-9-])`,
+      'g'
+    );
+    const findings: Finding[] = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message: `Raw Tailwind colour \`${m[0]}\` bypasses the token system (no dark-mode adaptation, no theming).`,
+          fix: 'Use a semantic token: `bg-surface-*`, `text-text-*`, `border-border-*`, or an intent (`bg-primary`, `text-success`).',
+          line: i + 1,
+          match: m[0]
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+
+const darkModeOverride: Rule = {
+  id: 'dark-mode-override',
+  severity: 'error',
+  description: 'Manual `dark:` override instead of automatic `light-dark()` semantic tokens.',
+  check(lines) {
+    // `!` covers the Tailwind important modifier (`dark:!bg-…`).
+    const re = /\bdark:[a-z[!]/g;
+    const findings: Finding[] = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message:
+            'Manual `dark:` override. Dark mode resolves automatically via `light-dark()` semantic tokens.',
+          fix: 'Remove the `dark:` variant and rely on semantic tokens (`bg-surface-elevated` etc.), which already switch.',
+          line: i + 1,
+          match: m[0].slice(0, -1)
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+
+const focusNotVisible: Rule = {
+  id: 'focus-not-visible',
+  severity: 'error',
+  description: 'Plain `focus:` ring instead of keyboard-only `focus-visible:`.',
+  check(lines) {
+    // `focus:` followed by a utility start, but never `focus-visible:`/`focus-within:`
+    // (those contain `focus-`, not `focus:`). Catches `group-focus:` / `peer-focus:` too.
+    const re = /\bfocus:(?=[a-z[])/g;
+    const findings: Finding[] = [];
+    lines.forEach((line, i) => {
+      for (const _ of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message:
+            '`focus:` shows a focus ring on mouse clicks too. Keyboard-only rings are the house style.',
+          fix: 'Use `focus-visible:` instead of `focus:`.',
+          line: i + 1,
+          match: 'focus:'
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+
+const hardcodedZIndex: Rule = {
+  id: 'hardcoded-z-index',
+  severity: 'error',
+  description: 'Hardcoded z-index instead of a `z-[var(--z-*)]` token.',
+  check(lines) {
+    // `z-10`, `z-50`, `z-[999]` — but not `z-[var(--z-modal)]` or `z-auto`.
+    // Trailing `(?![\w-])` (not `\b`) so the bracket form terminates correctly after `]`.
+    const re = /\bz-(?:\d{1,4}|\[\d{1,4}\])(?![\w-])/g;
+    const findings: Finding[] = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message: `Hardcoded z-index \`${m[0]}\` collides with the layering scale and can sit behind/above the wrong overlay.`,
+          fix: 'Use a z-index token: `z-[var(--z-modal)]`, `z-[var(--z-dropdown)]`, `z-[var(--z-tooltip)]`, …',
+          line: i + 1,
+          match: m[0]
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+
+const dynamicClassInterpolation: Rule = {
+  id: 'dynamic-class-interpolation',
+  severity: 'error',
+  description:
+    'String-interpolated Tailwind class fragment (e.g. `gap-{x}`) — never compiled by Tailwind.',
+  check(lines) {
+    // A Tailwind utility root immediately glued to a `{` or `${` interpolation.
+    // Tailwind needs static class names; `gap-${x}` produces no CSS at all.
+    const re = new RegExp(`\\b(?:${DYNAMIC_UTILITY_ROOTS.join('|')})-(\\$\\{|\\{)`, 'g');
+    const findings: Finding[] = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message: `Interpolated class fragment \`${m[0]}…\` — Tailwind only compiles static class names, so this utility is never generated.`,
+          fix: "Switch the whole class string per state: `class={isHero ? 'gap-4' : 'gap-3'}` — keep each utility a complete literal.",
+          line: i + 1,
+          match: m[0]
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+
+/**
+ * Token hallucination: a colour utility whose core *looks* like an Urbicon UI
+ * semantic token (right namespace / intent prefix) but is not in the validated
+ * whitelist. Narrow by construction — only fires on our own namespaces, so it
+ * never flags `bg-transparent`, `bg-cover`, or arbitrary `bg-[#fff]`.
+ */
+const tokenHallucination: Rule = {
+  id: 'token-hallucination',
+  severity: 'warning',
+  description:
+    'Colour utility referencing a non-existent semantic token (e.g. `bg-status-danger`).',
+  check(lines, _raw, ctx) {
+    // The effective whitelist for this run: per-call project tokens merged in by
+    // lintDesign, or the built-in set when the rule is invoked standalone.
+    const validCores = ctx?.validTokenCores ?? VALID_TOKEN_CORES;
+    const prefixAlt = COLOR_PREFIXES.join('|');
+    // capture: prefix, then the core up to a class boundary / opacity / end
+    const re = new RegExp(`\\b(${prefixAlt})-([a-z][a-z0-9-]*)(?:\\/\\d{1,3})?\\b`, 'g');
+    const findings: Finding[] = [];
+
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        const core = m[2]!;
+        if (!looksSemantic(core)) continue;
+        if (validCores.has(core)) continue;
+
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message: `\`${m[1]}-${core}\` is not a real token — likely hallucinated.`,
+          fix: suggestForBadCore(core),
+          line: i + 1,
+          match: m[0] // full token incl. any `/NN` opacity suffix
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+
+/** Does this utility core sit in one of our semantic namespaces / intent families? */
+function looksSemantic(core: string): boolean {
+  // Font-size cores (`text-sm`, `text-2xl`) share the `text-` namespace but are not colour tokens.
+  if (/^text-(?:xs|sm|base|lg|\d?xl)$/.test(core)) return false;
+  if (isForeignVocab(core)) return true; // shadcn/ui vocabulary — always foreign
+  if (SEMANTIC_NAMESPACES.some((ns) => core.startsWith(ns))) return true;
+  if (core.startsWith('status-')) return true; // owned-looking, never valid → flag
+  // intent-with-suffix: `primary-muted`, `success-foo` (bare `primary` is valid and caught by the whitelist)
+  for (const intent of INTENT_PREFIXES) {
+    if (core.startsWith(`${intent}-`)) return true;
+  }
+  if (core.endsWith('-fg')) return true; // `-foreground` is already covered by isForeignVocab above
+  return false;
+}
+
+function suggestForBadCore(core: string): string {
+  // The `-foreground` family is the most common shadcn pattern — give the precise replacement first.
+  if (
+    core === 'foreground' ||
+    core.endsWith('-foreground') ||
+    core === 'fg' ||
+    core.endsWith('-fg')
+  ) {
+    return 'Use `text-on-primary` / `text-on-surface` for foreground-on-intent text, or `text-text-primary`/`-secondary` for general text.';
+  }
+  if (isForeignVocab(core)) return SHADCN_FIX;
+  for (const [bad, hint] of Object.entries(KNOWN_BAD_NAMESPACES)) {
+    if (bad.endsWith('-') ? core.startsWith(bad) : core.endsWith(bad)) return hint;
+  }
+  if (core.startsWith('surface-'))
+    return 'Valid surfaces: surface-base/quiet/subtle/elevated/overlay/hover/active/selected/inverted.';
+  if (core.startsWith('feedback-'))
+    return 'Valid feedback tokens: feedback-{info,success,warning,error}[-subtle].';
+  const intent = INTENT_NAMES.find((n) => core.startsWith(`${n}-`));
+  if (intent)
+    return `Valid \`${intent}\` variants: ${intent}, ${intent}-hover, ${intent}-active, ${intent}-subtle, ${intent}-emphasis, or a scale step ${intent}-50…${intent}-950.`;
+  return 'Check `get_css_reference()` for the exact token name.';
+}
+
+/** All deterministic rules, in report order. The line-based regex rules first, then
+ * the AST-pass rules (which read whole elements, not single lines). */
+export const RULES: Rule[] = [
+  rawTailwindColor,
+  darkModeOverride,
+  focusNotVisible,
+  hardcodedZIndex,
+  dynamicClassInterpolation,
+  tokenHallucination,
+  ...MARKUP_RULES
+];