@urbicon-ui/design-engine 6.1.8

package/src/linter/markup-rules.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+import { lintDesign } from './linter.js';
+
+/** ruleIds present in a lint of `code`. */
+function ruleIds(code: string): string[] {
+  return lintDesign(code).findings.map((f) => f.ruleId);
+}
+function apiFindings(code: string) {
+  return lintDesign(code).findings.filter((f) => f.ruleId === 'api-hallucination');
+}
+
+describe('api-hallucination (F-J)', () => {
+  it('flags a foreign prop name and suggests the real one', () => {
+    const f = apiFindings('<Button tone="primary">Go</Button>');
+    expect(f).toHaveLength(1);
+    expect(f[0]!.severity).toBe('warning');
+    expect(f[0]!.kind).toBe('deterministic'); // scores against correctness, not slop
+    expect(f[0]!.match).toBe('tone');
+    expect(f[0]!.fix).toContain('intent');
+    expect(f[0]!.line).toBe(1);
+  });
+
+  it('flags the shadcn `variant="outline"` spelling', () => {
+    const f = apiFindings('<Button variant="outline">Go</Button>');
+    expect(f).toHaveLength(1);
+    expect(f[0]!.match).toBe('variant="outline"');
+    expect(f[0]!.fix).toContain('outlined');
+  });
+
+  it('catches a foreign boolean prop and a shorthand prop', () => {
+    expect(apiFindings('<Button isLoading>Go</Button>')[0]?.fix).toContain('loading');
+    expect(apiFindings('<Button {isDisabled} />')[0]?.fix).toContain('disabled');
+  });
+
+  it('does NOT flag a valid per-component value (variant="solid" is real on Tab)', () => {
+    // The proof that the value map is global-safe-only: `solid` is a real Tab variant,
+    // so it must never be flagged. (Per-component validation is deferred to the catalog.)
+    expect(apiFindings('<Tab variant="solid">x</Tab>')).toEqual([]);
+  });
+
+  it('does not flag valid Urbicon usage', () => {
+    expect(
+      apiFindings('<Button intent="primary" variant="outlined" size="md">Go</Button>')
+    ).toEqual([]);
+  });
+
+  it('only fires on Urbicon components, not raw HTML or third-party components', () => {
+    expect(apiFindings('<div tone="x">y</div>')).toEqual([]);
+    expect(apiFindings('<MyButton tone="x">y</MyButton>')).toEqual([]);
+  });
+
+  it('only flags value confusions on string literals, not expressions', () => {
+    // `variant={outline}` passes a JS variable named `outline` — not the bad literal.
+    expect(apiFindings('<Button variant={outline}>x</Button>')).toEqual([]);
+  });
+
+  it('ignores usages inside comments (masked before the scan)', () => {
+    expect(ruleIds('<!-- <Button tone="x">y</Button> -->')).not.toContain('api-hallucination');
+  });
+
+  it('deducts from the correctness axis', () => {
+    const report = lintDesign('<Button tone="primary">Go</Button>');
+    expect(report.scores.correctness).toBeLessThan(100);
+  });
+});
+
+function ariaFindings(code: string) {
+  return lintDesign(code).findings.filter((f) => f.ruleId === 'icon-button-no-label');
+}
+
+describe('icon-button-no-label (F-G)', () => {
+  it('flags an icon-only button with no accessible name', () => {
+    const f = ariaFindings('<button><SearchIcon /></button>');
+    expect(f).toHaveLength(1);
+    expect(f[0]!.severity).toBe('warning');
+    expect(f[0]!.kind).toBe('deterministic');
+    expect(f[0]!.fix).toContain('aria-label');
+  });
+
+  it('flags an icon-only Urbicon <Button> too', () => {
+    expect(ariaFindings('<Button><Icon name="x" /></Button>')).toHaveLength(1);
+  });
+
+  it('does not flag when an accessible name is present', () => {
+    expect(ariaFindings('<button aria-label="Search"><SearchIcon /></button>')).toEqual([]);
+    expect(ariaFindings('<button title="Search"><svg /></button>')).toEqual([]);
+  });
+
+  it('does not flag when visible or sr-only text labels the control', () => {
+    expect(ariaFindings('<button><SearchIcon /> Search</button>')).toEqual([]);
+    expect(
+      ariaFindings('<button><span class="sr-only">Search</span><SearchIcon /></button>')
+    ).toEqual([]);
+  });
+
+  it('skips when a dynamic child or a spread might carry the name', () => {
+    expect(ariaFindings('<button><Icon />{label}</button>')).toEqual([]); // {…} could be the label
+    expect(ariaFindings('<Button {...rest}><Icon /></Button>')).toEqual([]); // spread may add aria-label
+  });
+
+  it('does not flag a button with text but no icon, or a non-button icon holder', () => {
+    expect(ariaFindings('<button>Save</button>')).toEqual([]);
+    expect(ariaFindings('<div><SearchIcon /></div>')).toEqual([]);
+  });
+
+  it('ignores an empty aria-label (still no accessible name)', () => {
+    expect(ariaFindings('<button aria-label=""><SearchIcon /></button>')).toHaveLength(1);
+  });
+});

package/src/linter/markup-rules.ts

@@ -0,0 +1,209 @@
+/**
+ * The AST-pass rules (DESIGN-MCP-V2 §6/§10, Funde F-G/F-J): correctness checks that
+ * need to know *which attribute belongs to which element* — what the line-based
+ * regex rules in `rules.ts` structurally cannot see. They run on the flat element
+ * list from {@link scanMarkup}, scanned once per lint and shared via a tiny cache.
+ *
+ * All are scoped to Urbicon UI's own components (a curated name set) so they never
+ * fire on a third-party `<Button>` from another library — the correctness gate
+ * must stay false-positive free.
+ */
+
+import { type Element, innerContent, scanMarkup } from './markup.js';
+import type { Finding, Rule } from './types.js';
+
+/**
+ * Urbicon UI's component names, for scoping the AST rules. A name missing here only
+ * means a missed lint (never a false positive), so lagging a new component is safe;
+ * keep it roughly in sync with the catalog. Not the catalog itself (props/docs) —
+ * just the names, the same kind of design-system lint-data as the token sets.
+ */
+export const URBICON_COMPONENTS: ReadonlySet<string> = new Set([
+  // primitives
+  'Accordion',
+  'Alert',
+  'Avatar',
+  'Badge',
+  'Breadcrumb',
+  'Button',
+  'ButtonGroup',
+  'Card',
+  'Checkbox',
+  'Collapsible',
+  'Combobox',
+  'ConfirmDialog',
+  'Dialog',
+  'Drawer',
+  'FormField',
+  'Input',
+  'Menu',
+  'Pagination',
+  'Popover',
+  'Progress',
+  'RadioGroup',
+  'SegmentGroup',
+  'Select',
+  'Separator',
+  'Sidebar',
+  'Skeleton',
+  'Slider',
+  'Spinner',
+  'Stepper',
+  'Tab',
+  'Textarea',
+  'Toast',
+  'Toggle',
+  'Toolbar',
+  'Tooltip',
+  // components
+  'AreaChart',
+  'BarChart',
+  'Calendar',
+  'ChartFrame',
+  'CommandPalette',
+  'CompositionBar',
+  'CurrencyInput',
+  'DatePicker',
+  'DonutChart',
+  'EmptyState',
+  'FileUpload',
+  'LineChart',
+  'LocaleSwitcher',
+  'Sankey',
+  'SidebarLayout',
+  'Sparkline',
+  'ThemeSwitcher',
+  'Table'
+]);
+
+/**
+ * Prop names from other component libraries (Chakra/MUI/shadcn muscle memory) that
+ * Urbicon UI does not have, mapped to the real prop. Every key is verified absent
+ * from every `*Props` interface in the repo, and every value is a real prop — so
+ * the fix hint is always correct. (`color`/`leftIcon`/`rightIcon` are deliberately
+ * absent: they ARE real props on some components, so flagging them would misfire.)
+ */
+const PROP_NAME_CONFUSIONS: Readonly<Record<string, string>> = {
+  tone: 'intent',
+  colour: 'intent',
+  colorScheme: 'intent',
+  isLoading: 'loading',
+  isDisabled: 'disabled'
+};
+
+/**
+ * String-literal value confusions, per prop. Only values that are valid in NO
+ * Urbicon component go here — variant vocabularies are per-component (`solid` is a
+ * real Tab variant, `default` a real one elsewhere), so a global value map is only
+ * safe for values that exist nowhere. `outline` (the shadcn spelling of `outlined`)
+ * is the one that qualifies. Fuller per-component value validation needs the
+ * catalog and is deferred with the find/init step (F-J, see DESIGN-MCP-V2 §10).
+ */
+const VALUE_CONFUSIONS: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  variant: { outline: 'outlined' }
+};
+
+/** Single-entry scan cache: lintDesign runs the rules sequentially on one source. */
+let cache: { raw: string; els: Element[] } | null = null;
+function scanCached(raw: string): Element[] {
+  if (cache?.raw !== raw) cache = { raw, els: scanMarkup(raw) };
+  return cache.els;
+}
+
+const apiHallucination: Rule = {
+  id: 'api-hallucination',
+  severity: 'warning',
+  description:
+    'Component prop/value from another UI library (e.g. `tone=`, `variant="outline"`) that Urbicon UI does not have.',
+  check(_lines, raw) {
+    const findings: Finding[] = [];
+    for (const el of scanCached(raw)) {
+      if (!el.isComponent || !URBICON_COMPONENTS.has(el.tag)) continue;
+      for (const attr of el.attrs) {
+        const rightName = PROP_NAME_CONFUSIONS[attr.name];
+        if (rightName) {
+          findings.push({
+            ruleId: this.id,
+            severity: this.severity,
+            kind: 'deterministic',
+            message: `\`${el.tag}\` has no \`${attr.name}\` prop — that is another library's name.`,
+            fix: `Use \`${rightName}\` instead.`,
+            line: attr.line,
+            match: attr.name
+          });
+          continue;
+        }
+        if (attr.kind === 'string' && attr.value !== null) {
+          const right = VALUE_CONFUSIONS[attr.name]?.[attr.value];
+          if (right) {
+            findings.push({
+              ruleId: this.id,
+              severity: this.severity,
+              kind: 'deterministic',
+              message: `\`${attr.name}="${attr.value}"\` is not an Urbicon UI value.`,
+              fix: `Use \`${attr.name}="${right}"\`.`,
+              line: attr.line,
+              match: `${attr.name}="${attr.value}"`
+            });
+          }
+        }
+      }
+    }
+    return findings;
+  }
+};
+
+/** Attributes that give an interactive control its accessible name. */
+const LABEL_ATTRS: ReadonlySet<string> = new Set(['aria-label', 'aria-labelledby', 'title']);
+/** Controls that are commonly rendered icon-only and then forgotten a label. */
+const ICON_CONTROL_TAGS: ReadonlySet<string> = new Set(['Button', 'button']);
+
+/** Any non-whitespace text once child tags are stripped (catches visible + sr-only labels). */
+function hasTextLabel(inner: string): boolean {
+  return inner.replace(/<[^>]*>/g, '').trim().length > 0;
+}
+/** An icon child — an `<svg>`, an `<Icon>`, or any `<…Icon>` component. */
+function hasIconChild(inner: string): boolean {
+  return /<svg\b/i.test(inner) || /<[A-Za-z][\w.]*Icon\b/.test(inner) || /<Icon\b/.test(inner);
+}
+
+/**
+ * F-G: an icon-only Button/button with no accessible name — a screen reader
+ * announces nothing. Conservative: skips when a spread might carry the label, when
+ * content holds a `{…}` expression (a dynamic label), when any text (visible or
+ * sr-only) is present, and only fires when an actual icon child is the sole
+ * content. Errs toward silence so a labelled control is never flagged.
+ */
+const iconButtonNoLabel: Rule = {
+  id: 'icon-button-no-label',
+  severity: 'warning',
+  description: 'Icon-only Button/button with no accessible name (aria-label / title / text).',
+  check(_lines, raw) {
+    const findings: Finding[] = [];
+    for (const el of scanCached(raw)) {
+      if (!ICON_CONTROL_TAGS.has(el.tag)) continue;
+      if (el.attrs.some((a) => a.kind === 'spread')) continue; // {...rest} may carry aria-label
+      const labelled = el.attrs.some(
+        (a) => LABEL_ATTRS.has(a.name) && a.value !== null && a.value.trim() !== ''
+      );
+      if (labelled) continue;
+      const inner = innerContent(raw, el);
+      if (inner === null) continue; // self-closing / unbalanced — content unknown, skip
+      if (inner.includes('{')) continue; // a dynamic child like {label} might be the name
+      if (hasTextLabel(inner)) continue; // visible or visually-hidden text present
+      if (!hasIconChild(inner)) continue; // only genuine icon-only controls
+      findings.push({
+        ruleId: this.id,
+        severity: this.severity,
+        kind: 'deterministic',
+        message: `Icon-only \`<${el.tag}>\` has no accessible name — a screen reader announces nothing.`,
+        fix: 'Add an `aria-label="…"` (or visually-hidden text) naming the action.',
+        line: el.line
+      });
+    }
+    return findings;
+  }
+};
+
+/** The AST-pass rules, appended to the linter's RULES registry. */
+export const MARKUP_RULES: Rule[] = [apiHallucination, iconButtonNoLabel];

package/src/linter/markup.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest';
+import { type Element, innerContent, scanMarkup } from './markup.js';
+
+/** Find the first scanned element with a given tag. */
+function tag(els: Element[], name: string): Element | undefined {
+  return els.find((e) => e.tag === name);
+}
+
+describe('scanMarkup', () => {
+  it('extracts a component with string, expression, and boolean attributes', () => {
+    const els = scanMarkup('<Button intent="primary" onclick={save} disabled>Save</Button>');
+    expect(els).toHaveLength(1);
+    const b = els[0]!;
+    expect(b.tag).toBe('Button');
+    expect(b.isComponent).toBe(true);
+    expect(b.selfClosing).toBe(false);
+    expect(b.attrs).toEqual([
+      { name: 'intent', value: 'primary', kind: 'string', line: 1 },
+      { name: 'onclick', value: 'save', kind: 'expression', line: 1 },
+      { name: 'disabled', value: null, kind: 'boolean', line: 1 }
+    ]);
+  });
+
+  it('distinguishes components from raw HTML elements', () => {
+    const els = scanMarkup('<div><Button /><Foo.Bar /><button /></div>');
+    expect(tag(els, 'div')?.isComponent).toBe(false);
+    expect(tag(els, 'Button')?.isComponent).toBe(true);
+    expect(tag(els, 'Foo.Bar')?.isComponent).toBe(true);
+    expect(tag(els, 'button')?.isComponent).toBe(false);
+  });
+
+  it('marks self-closing tags', () => {
+    const els = scanMarkup('<Icon name="x" />');
+    expect(els[0]!.selfClosing).toBe(true);
+    expect(els[0]!.attrs[0]).toEqual({ name: 'name', value: 'x', kind: 'string', line: 1 });
+  });
+
+  it('does not let a `>` inside an expression terminate the tag early', () => {
+    const els = scanMarkup('<Box class={a > b ? "x" : "y"} role="grid">hi</Box>');
+    const box = tag(els, 'Box')!;
+    expect(box.attrs.map((a) => a.name)).toEqual(['class', 'role']);
+    expect(box.attrs[1]).toEqual({ name: 'role', value: 'grid', kind: 'string', line: 1 });
+  });
+
+  it('handles object literals and template strings inside an expression attribute', () => {
+    const els = scanMarkup('<C style={{ a: `${x}`, b: "}" }} id="z" />');
+    const c = tag(els, 'C')!;
+    expect(c.attrs.map((a) => a.name)).toEqual(['style', 'id']);
+    expect(c.attrs[1]!.value).toBe('z');
+  });
+
+  it('reads shorthand and spread attributes', () => {
+    const els = scanMarkup('<C {value} {...rest} />');
+    expect(els[0]!.attrs).toEqual([
+      { name: 'value', value: 'value', kind: 'shorthand', line: 1 },
+      { name: '', value: 'rest', kind: 'spread', line: 1 }
+    ]);
+  });
+
+  it('tracks line numbers across a multiline tag', () => {
+    const src = '<div>\n  <Button\n    intent="primary"\n  >Go</Button>\n</div>';
+    const els = scanMarkup(src);
+    const b = tag(els, 'Button')!;
+    expect(b.line).toBe(2);
+    expect(b.attrs[0]).toEqual({ name: 'intent', value: 'primary', kind: 'string', line: 3 });
+  });
+
+  it('ignores markup inside <script> and <style> blocks', () => {
+    const src =
+      '<script>\n  const html = "<Button bad>";\n</script>\n<Button intent="primary" />\n<style>\n  .x { color: red }\n</style>';
+    const els = scanMarkup(src);
+    expect(els).toHaveLength(1);
+    expect(els[0]!.tag).toBe('Button');
+    expect(els[0]!.line).toBe(4); // script newlines were preserved
+  });
+
+  it('skips a malformed (unterminated) tag without crashing or guessing', () => {
+    const els = scanMarkup('<Button intent="primary'); // no closing quote or >
+    expect(els).toEqual([]);
+  });
+
+  it('ignores closing tags, fragments, and svelte blocks', () => {
+    const els = scanMarkup('{#if x}<Button />{/if}</wrap>< notATag>');
+    expect(els.map((e) => e.tag)).toEqual(['Button']);
+  });
+
+  it('keeps an escaped quote from mis-terminating an expression attribute', () => {
+    // The string inside the expression contains an escaped quote then a `}` —
+    // neither must end the attribute early, so the following `y` is still parsed.
+    const els = scanMarkup('<C x={"a\\"}"} y="z" />');
+    const c = tag(els, 'C')!;
+    expect(c.attrs.find((a) => a.name === 'y')?.value).toBe('z');
+  });
+
+  it('ignores tags inside HTML comments (self-contained, no upstream mask needed)', () => {
+    const els = scanMarkup('<!-- <Button tone="x" /> -->\n<Input />');
+    expect(els.map((e) => e.tag)).toEqual(['Input']);
+  });
+});
+
+describe('innerContent', () => {
+  const only = (src: string): { el: Element; src: string } => ({ el: scanMarkup(src)[0]!, src });
+
+  it('returns the inner text of an element', () => {
+    const { el, src } = only('<Button>Save</Button>');
+    expect(innerContent(src, el)).toBe('Save');
+  });
+
+  it('honours same-name nesting', () => {
+    const src = '<Menu><Menu>inner</Menu>outer</Menu>';
+    const el = scanMarkup(src)[0]!;
+    expect(innerContent(src, el)).toBe('<Menu>inner</Menu>outer');
+  });
+
+  it('returns null for a self-closing element', () => {
+    const { el, src } = only('<Icon name="x" />');
+    expect(innerContent(src, el)).toBe(null);
+  });
+
+  it('returns null when no balanced close exists', () => {
+    const { el, src } = only('<Button>oops');
+    expect(innerContent(src, el)).toBe(null);
+  });
+
+  it('sees only an icon child for an icon-only button (no text)', () => {
+    const { el, src } = only('<button><SearchIcon /></button>');
+    const inner = innerContent(src, el)!;
+    expect(inner.includes('SearchIcon')).toBe(true);
+    expect(inner.replace(/<[^>]*>/g, '').trim()).toBe(''); // no human text once tags are stripped
+  });
+
+  it('does not count a </tag> inside an HTML comment', () => {
+    // The comment's `</button>` must not close the element early — the real label
+    // after it has to be seen. (Self-contained: innerContent masks comments too.)
+    const src = '<button><!-- </button> -->Save</button>';
+    const el = scanMarkup(src)[0]!;
+    expect(innerContent(src, el)).toContain('Save');
+  });
+});