basalt-ui 1.23.0 → 1.24.0

package/src/guard/check-source.test.ts

@@ -66,6 +66,58 @@ describe('raw-hex', () => {
     const f = find(`// use #ff0000 from the palette`)
     expect(kinds(f)).not.toContain('raw-hex')
   })
+
+  /**
+   * Round 9, rollhook: `{` / `}` — the escaped braces an Astro template writes to show a
+   * literal `${…}` in prose — were read as the hex colors `#123` / `#125`, and 4 findings blocked a
+   * release on a page with no color in it at all. The hole was in the KIND, not in the extension:
+   * the same string produced the same two findings in `.html`, `.tsx`, `.css` and `.vue`.
+   */
+  describe('HTML numeric character references', () => {
+    const ENTITIES = `<p>image: $&#123;IMAGE_TAG&#125;</p>`
+
+    for (const rel of [
+      'index.html',
+      'src/App.tsx',
+      'src/a.css',
+      'src/Hero.vue',
+      'src/pages/index.astro',
+    ]) {
+      it(`does NOT read &#123;/&#125; as a hex color in ${rel}`, () => {
+        expect(kinds(find(ENTITIES, rel))).not.toContain('raw-hex')
+      })
+    }
+
+    // The exemption is the ENTITY, never the file type — a template that hardcodes a color is
+    // exactly what making `.astro`/`.vue` scannable was for.
+    it('still flags a real hex in an .astro file', () => {
+      const f = find(`<div style="color: #ff0000">x</div>`, 'src/pages/index.astro')
+      expect(kinds(f)).toContain('raw-hex')
+      expect(f.find((x) => x.kind === 'raw-hex')?.token).toBe('#ff0000')
+    })
+
+    it('still flags a real hex in a .vue file', () => {
+      const f = find(`<style>\n  .hero { color: #ff0000; }\n</style>`, 'src/Hero.vue')
+      expect(kinds(f)).toContain('raw-hex')
+      expect(f.find((x) => x.kind === 'raw-hex')?.token).toBe('#ff0000')
+    })
+
+    it('flags a hex after a bare & — an entity needs its terminating semicolon', () => {
+      expect(kinds(find(`<p>a&#fff b</p>`, 'index.html'))).toContain('raw-hex')
+    })
+
+    it('flags a plain #123 with no entity around it', () => {
+      expect(kinds(find(`const c = '#123'`))).toContain('raw-hex')
+    })
+
+    // The neighbouring raw-text kinds were checked for the same blind spot and do NOT share it: a
+    // character reference contains no `(`, so `raw-color-fn`'s `rgba?|hsla?\(` anchor cannot occur
+    // inside one, and every other raw-text kind anchors on a property name, `var(`, or a JSX `=`.
+    it('leaves the sibling color kinds unchanged — nothing else fires inside an entity', () => {
+      const src = `<p>&amp; &mdash; &nbsp; &#8212; &hellip; &#x1F600; &copy;</p>`
+      expect(find(src, 'index.html')).toHaveLength(0)
+    })
+  })
 })
 
 // ── 2. raw-color-fn ──────────────────────────────────────────────────────────
@@ -800,6 +852,79 @@ describe('chart-missing-aria-label', () => {
     const f = find(text)
     expect(kinds(f)).not.toContain('chart-missing-aria-label')
   })
+
+  // ── tag provenance ─────────────────────────────────────────────────────────
+  //
+  // The rule keys on a tag NAME, so a consumer's OWN component sharing a shipped kind's name
+  // collected an unactionable `ariaLabel` demand (reported against 1.23.0: a hand-composed local
+  // `MirroredBars`, 235 lines, nothing to do with the kind). The gate is a one-directional
+  // narrowing — skip only what this file DEFINES and does not import from basalt-ui.
+
+  it('does NOT flag a tag this file DEFINES itself (a local component sharing a kind name)', () => {
+    const text = [
+      'function MirroredBars({ data }: Props) {',
+      '  return <svg />',
+      '}',
+      'export function Panel() {',
+      '  return <MirroredBars data={points} />',
+      '}',
+    ].join('\n')
+    expect(kinds(find(text))).not.toContain('chart-missing-aria-label')
+  })
+
+  it('skips a locally defined kind name however it is declared (const/memo, not just function)', () => {
+    const text = ['const BandStrip = memo(Inner)', '<BandStrip data={rows} />'].join('\n')
+    expect(kinds(find(text))).not.toContain('chart-missing-aria-label')
+  })
+
+  it('STILL flags when the same file also imports that name from basalt-ui (a real shadow)', () => {
+    const text = [
+      "import { MirroredBars } from 'basalt-ui/charts'",
+      'function Panel() {',
+      '  return <MirroredBars data={points} />',
+      '}',
+    ].join('\n')
+    expect(kinds(find(text))).toContain('chart-missing-aria-label')
+  })
+
+  it('STILL flags a tag imported from a consumer BARREL that re-exports the kind', () => {
+    const text = ["import { MultiLine } from '../charts'", '<MultiLine data={points} />'].join('\n')
+    expect(kinds(find(text))).toContain('chart-missing-aria-label')
+  })
+
+  it('STILL flags a file with no imports and no local definition (coverage is not import-gated)', () => {
+    expect(kinds(find('<Donut data={slices} />'))).toContain('chart-missing-aria-label')
+  })
+
+  it('honours an aliased basalt import, since the alias is the tag the JSX writes', () => {
+    const text = [
+      "import { Bars as BasaltBars } from 'basalt-ui/charts'",
+      'const Bars = () => null',
+      '<Bars data={points} />',
+    ].join('\n')
+    // `Bars` is defined locally here and only `BasaltBars` came from basalt — the local one is skipped.
+    expect(kinds(find(text))).not.toContain('chart-missing-aria-label')
+  })
+})
+
+describe('unframed-chart — the same provenance gate', () => {
+  it('does NOT flag a consumer’s OWN ChartLegend taking an items array', () => {
+    const text = [
+      'function ChartLegend({ items }: Props) {',
+      '  return <ul />',
+      '}',
+      'const view = <ChartLegend items={[{ label: "a" }]} />',
+    ].join('\n')
+    expect(kinds(find(text))).not.toContain('unframed-chart')
+  })
+
+  it('still flags the shipped ChartLegend built from an inline array', () => {
+    const text = [
+      "import { ChartLegend } from 'basalt-ui/charts'",
+      'const view = <ChartLegend items={[{ label: "a" }]} />',
+    ].join('\n')
+    expect(kinds(find(text))).toContain('unframed-chart')
+  })
 })
 
 // ── 16. card-with-border ─────────────────────────────────────────────────────
@@ -2507,6 +2632,95 @@ describe('markup files (index.html / *.webmanifest)', () => {
   })
 })
 
+// ── 29b. single-file components (.astro / .vue) ───────────────────────────────
+
+/**
+ * Round 9: `.astro` and `.vue` became scannable and fell through to the `ts` dialect, so `<!-- … -->`
+ * was never stripped — a `theme-allow` written in an HTML comment waived nothing there, and a color
+ * inside a commented-out block still reported. They resolve as `sfc` now: BOTH comment dialects,
+ * and the full 25-kind set (not `MARKUP_KINDS` — an `.astro` template is JSX-shaped and a `.vue`
+ * `<script setup>` is real TS).
+ */
+describe('single-file components (.astro / .vue)', () => {
+  const ASTRO = 'src/pages/index.astro'
+  const VUE = 'src/Hero.vue'
+
+  for (const rel of [ASTRO, VUE]) {
+    it(`strips an HTML comment in ${rel}`, () => {
+      expect(kinds(find(`<!-- <div style="color: #ff0000" /> -->`, rel))).not.toContain('raw-hex')
+    })
+
+    it(`honours a theme-allow inside an HTML comment in ${rel}`, () => {
+      const f = find(
+        `<!-- theme-allow raw-hex — brand asset -->\n<div style="color: #ff0000" />`,
+        rel,
+      )
+      expect(kinds(f)).not.toContain('raw-hex')
+    })
+
+    it(`honours a theme-allow-file inside an HTML comment in ${rel}`, () => {
+      const f = find(
+        `<!-- theme-allow-file raw-hex — brand asset -->\n<b style="color: #ff0000" />`,
+        rel,
+      )
+      expect(kinds(f)).not.toContain('raw-hex')
+    })
+
+    it(`honours a multi-line HTML comment annotation in ${rel}`, () => {
+      const f = find(
+        `<!--\n  theme-allow raw-hex — brand asset\n-->\n<b style="color: #ff0000" />`,
+        rel,
+      )
+      expect(kinds(f)).not.toContain('raw-hex')
+    })
+
+    it(`still strips the JS dialect in ${rel} — an SFC carries both`, () => {
+      expect(kinds(find(`// const c = '#ff0000'`, rel))).not.toContain('raw-hex')
+      expect(kinds(find(`/* const c = '#ff0000' */`, rel))).not.toContain('raw-hex')
+    })
+
+    it(`honours a theme-allow in the script fence of ${rel}`, () => {
+      const f = find(`// theme-allow raw-hex — brand asset\nconst c = '#ff0000'`, rel)
+      expect(kinds(f)).not.toContain('raw-hex')
+    })
+
+    it(`keeps the non-markup kinds — an SFC is not MARKUP_KINDS-restricted in ${rel}`, () => {
+      expect(kinds(find(`const s = { border: '1px solid #ccc' }`, rel))).toContain('raw-surface')
+      expect(kinds(find(`<div style={{ padding: 18 }} />`, rel))).toContain('inline-spacing')
+    })
+  }
+
+  it('does not let an HTML comment open a runaway JS block comment', () => {
+    const f = find(`<!-- a /* unclosed -->\n<div style="color: #ff0000" />`, ASTRO)
+    expect(kinds(f)).toContain('raw-hex')
+  })
+
+  /**
+   * Asserted LIMITS, so "unsupported" and "silently broken" don't read the same. Both are
+   * false-negative-only — the direction a release-blocking false positive says to take.
+   */
+  describe('known limits', () => {
+    it('does not fire the kebab-CSS surface kinds inside a <style> fence', () => {
+      const src = `<style>\n  .card { border-radius: 8px; }\n</style>`
+      expect(kinds(find(src, ASTRO))).not.toContain('css-raw-surface')
+      // The same text in a real .css file still reports — the limit is the SFC dialect, not the rule.
+      expect(kinds(find(src.replace(/<\/?style>/g, ''), 'src/a.css'))).toContain('css-raw-surface')
+    })
+
+    it('over-strips a `<!--` that lives inside a script string', () => {
+      expect(
+        kinds(find(`const s = '<!--'\nconst c = '#ff0000'\nconst e = '-->'`, ASTRO)),
+      ).not.toContain('raw-hex')
+    })
+
+    it('over-strips after an unquoted `https://` in template prose', () => {
+      expect(
+        kinds(find(`<p>see https://x.test <b style="color: #ff0000" /></p>`, ASTRO)),
+      ).not.toContain('raw-hex')
+    })
+  })
+})
+
 // ── 30. tokens-only profile ──────────────────────────────────────────────────
 
 describe("profile: 'tokens-only'", () => {

package/src/guard/index.ts

@@ -10,7 +10,32 @@ export type { Finding, GuardConfig, GuardKind, GuardSeverity }
 
 // ── Static regex consts ──────────────────────────────────────────────────────────────────────────
 
-const HEX = /#[0-9a-fA-F]{3,8}\b/g
+/**
+ * A raw hex color literal.
+ *
+ * The `(?!(?<=&#)\d+;)` guard drops an HTML NUMERIC CHARACTER REFERENCE. `&#123;` is the escaped
+ * `{` and `&#125;` the escaped `}` — the two an Astro/JSX template writes to show a literal brace
+ * in prose — and their `#123` / `#125` read as three-digit hex. It is not markup-specific: the same
+ * string produced the same two findings in `.html`, `.tsx`, `.css` and `.vue`, so this was a hole
+ * in the kind itself that `.astro` merely walked into first (rollhook, round 9).
+ *
+ * The lookahead is deliberately the FULL reference — `&#`, digits, `;` — not a bare `(?<!&)`. Only
+ * the decimal form can collide at all (`&#x1F600;` never matches: `x` is not a hex digit), and a
+ * `#` that follows an `&` without terminating in `;` is not an entity, so `color: red&#fff` still
+ * flags. Nothing is exempted by file type; a real `#ff0000` in an `.astro` file fires exactly as it
+ * does in a `.tsx` one.
+ *
+ * The sibling raw-text kinds do NOT share this blind spot, and the reason is structural rather than
+ * lucky: a character reference contains no `(`, so `raw-color-fn`'s `rgba?|hsla?\(` anchor cannot
+ * occur inside one, and every other raw-text kind is anchored on a property name, `var(`, or a JSX
+ * `=`. Probed across `.html`/`.astro`/`.tsx` over 20 entity shapes — `raw-hex` was the only kind
+ * that fired.
+ *
+ * Known and NOT covered, because the fix would cost real findings: an all-hex URL fragment or SVG
+ * reference (`href="#cafe"`, `fill="url(#abcdef)"`) is indistinguishable from a color by text
+ * alone, and both still report. `theme-allow` is the escape there.
+ */
+const HEX = /#(?!(?<=&#)\d+;)[0-9a-fA-F]{3,8}\b/g
 
 /**
  * A raw `rgb()`/`rgba()`/`hsl()`/`hsla()` color function.
@@ -400,9 +425,55 @@ const RAW_CHART_LEGEND_ARRAY = /<ChartLegend\b[^>]*?\bitems\s*=\s*\{\s*\[/g
 // alternative so their `>` never terminates the tag early. A bare `>` comparison inside a prop
 // expression still ends the match (accepted limitation of the bounded scan).
 const CHART_ENTRY_POINT_TAG =
-  /<(?:MultiLine|Bars|BandStrip|Donut|DualPanel|Heatmap|MirroredBars|ZonedLine|StackedArea|LineSparkline|BarSparkline)\b(?:<[^<>]*>)?(?:=>|[^>])*?>/g
+  /<(MultiLine|Bars|BandStrip|Donut|DualPanel|Heatmap|MirroredBars|ZonedLine|StackedArea|LineSparkline|BarSparkline)\b(?:<[^<>]*>)?(?:=>|[^>])*?>/g
 const HAS_ARIA_LABEL_PROP = /\bariaLabel\s*=/
 
+// ── Tag provenance, shared by the two chart tag rules ────────────────────────────────────────────
+//
+// Both `chart-missing-aria-label` and `unframed-chart` key on a JSX tag NAME, which is the whole of
+// their signal — so a consumer's OWN component that merely shares a shipped kind's name collected
+// the finding too. Reported by a consumer on 1.23.0: a hand-composed local `<MirroredBars>` was
+// told to pass an `ariaLabel` prop it does not accept, by a rule that presents as a correctness
+// finding rather than as a naming one. `shadow-basalt-export` / `ai-sdk-major` scope through
+// `isBasaltScopedFile` (package-level); the analogous file-level signal here is where the name in
+// THIS file came from.
+//
+// The gate is deliberately a one-directional NARROWING: a tag is skipped only when the file DEFINES
+// a component of that name and does not also import it from basalt-ui. Everything else still fires
+// — a tag imported from basalt-ui, one imported from a consumer barrel that re-exports it (`import
+// { MultiLine } from '../charts'`, the shape a downstream component library uses), and one the scan
+// cannot attribute at all. Requiring a POSITIVE basalt import instead would have silently switched
+// both rules off for every barrel-wrapping consumer and for every file with no import statements —
+// a far bigger hole than the false positive it closes.
+const LOCAL_COMPONENT_DEF =
+  /(?:^|[\n;}])\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|const|let|var)\s+([A-Z]\w*)/g
+// `from 'basalt-ui'` and every subpath (`basalt-ui/charts`, `basalt-ui/tokens`, …).
+const BASALT_NAMED_IMPORT =
+  /import\s+(?:type\s+)?\{([^}]*)\}\s+from\s+['"]basalt-ui(?:\/[^'"]*)?['"]/g
+
+/** Component-shaped names DEFINED in this file — the provable "not the shipped kind" signal. */
+function localComponentNames(codeText: string): ReadonlySet<string> {
+  const out = new Set<string>()
+  for (const m of codeText.matchAll(LOCAL_COMPONENT_DEF)) out.add(m[1] as string)
+  return out
+}
+
+/** Names bound in this file by a named import from `basalt-ui` — the local binding, so
+ * `{ Bars as BasaltBars }` records `BasaltBars`, which is the name the JSX tag will use. */
+function basaltImportedNames(codeText: string): ReadonlySet<string> {
+  const out = new Set<string>()
+  for (const m of codeText.matchAll(BASALT_NAMED_IMPORT)) {
+    for (const raw of (m[1] as string).split(',')) {
+      const spec = raw.trim().replace(/^type\s+/, '')
+      if (spec.length === 0) continue
+      const parts = spec.split(/\s+as\s+/)
+      const bound = (parts[parts.length - 1] as string).trim()
+      if (bound.length > 0) out.add(bound)
+    }
+  }
+  return out
+}
+
 // Raw lowercase form-control element — line-scoped, same shape as RAW_VISX_AXIS. `\b` after the
 // tag name rejects a same-prefixed custom component (`<inputRef`, `<selectAll`).
 const RAW_FORM_CONTROL = /<(?:input|select|textarea)\b/g
@@ -485,6 +556,21 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
  * into an unplanned refactor, which is exactly what the grace minor exists to prevent. The five
  * entries below all landed together in the round-4 guard minor and all promote one minor later.
  *
+ * **A `SCANNABLE_EXT` widening cannot be expressed here, and 1.23.2's was deliberately not.**
+ * Adding `.astro`/`.jsx`/`.vue` widens the FILE SET for all 25 kinds at once — there is no kind to
+ * key an entry on, and the nearest one (`raw-hex`, which is what actually fired) is keyed per KIND,
+ * not per extension: an entry for it would demote basalt's most load-bearing kind to `warn` in
+ * every `.tsx` and `.css` in every consumer for a minor, to buy runway on a file type only one
+ * consumer has. `css-raw-surface` is the shape that DOES fit — the new dialect got its own kind
+ * because kebab CSS is a distinct pattern set; more files running the same patterns is not.
+ *
+ * The measurement agreed with the structure. Once the two defects the widening exposed were fixed
+ * (`&#123;` read as a hex; `<!-- … -->` never stripped in an SFC), rollhook's marketing site scans
+ * 6 files with 0 findings, and no other consumer has a single `.astro`, `.vue` or `.jsx` file — so
+ * grace would have covered zero incumbent violations. The doctrine protects code that "passed every
+ * previous release"; a violation in a newly-scanned file type is code the consumer is writing now,
+ * with `theme-allow`, `basalt.severity` and `exemptRules` all still available.
+ *
  * @example
  * const GRACE: Partial<Record<GuardKind, string>> = {
  *   'raw-font-family': 'introduced 1.4.0 — promote to error in 1.5.0',
@@ -800,10 +886,13 @@ function commentBlockEnd(
   syntax: GuardSyntax,
 ): number {
   const line = lines[index] ?? ''
+  // An SFC carries both dialects, so the closer is resolved from the opener the token actually sits
+  // behind rather than from the extension: whichever of `<!--` / `/*` is NEAREST on its left wins.
+  const markup = syntax === 'markup' || (syntax === 'sfc' && opensMarkupComment(line, tokenAt))
   // A line comment closes at its own end of line. CSS has no `//`, so the test is TS-only: there,
   // a `//`-looking sequence is text and the conservative same-line answer is the right one anyway.
-  if (syntax === 'ts' && /\/\/\s*$/.test(line.slice(0, tokenAt))) return index
-  const closer = syntax === 'markup' ? '-->' : '*/'
+  if (!markup && syntax !== 'css' && /\/\/\s*$/.test(line.slice(0, tokenAt))) return index
+  const closer = markup ? '-->' : '*/'
   if (line.slice(tokenAt).includes(closer)) return index
   for (let ahead = index + 1; ahead < lines.length; ahead++) {
     if ((lines[ahead] ?? '').includes(closer)) return ahead
@@ -811,6 +900,18 @@ function commentBlockEnd(
   return index
 }
 
+/**
+ * In an `sfc` file, is the comment the token sits in an HTML one?
+ *
+ * Both dialects are legal in the same file, so the extension cannot answer it — the nearest opener
+ * on the token's left does. A tie (neither present) reads as the JS dialect, which is what an
+ * annotation on a bare frontmatter line is.
+ */
+function opensMarkupComment(line: string, tokenAt: number): boolean {
+  const before = line.slice(0, tokenAt)
+  return before.lastIndexOf('<!--') > before.lastIndexOf('/*')
+}
+
 /**
  * A comment opener sitting immediately before the annotation token.
  *
@@ -1086,8 +1187,8 @@ function annotationsCover(annotations: AllowAnnotation[] | undefined, kind: Guar
   return (annotations ?? []).some((a) => annotationCovers(a, kind))
 }
 
-/** The 3 comment dialects the stripper understands, resolved from the file's own extension. */
-type GuardSyntax = 'ts' | 'css' | 'markup'
+/** The 4 comment dialects the stripper understands, resolved from the file's own extension. */
+type GuardSyntax = 'ts' | 'css' | 'markup' | 'sfc'
 
 /**
  * CSS (including `.module.css`) has no `//` line-comment syntax at all — an unquoted `//`, e.g.
@@ -1097,13 +1198,50 @@ type GuardSyntax = 'ts' | 'css' | 'markup'
  * `markup` covers the two files whose colors nothing re-derives on a theme change and which the
  * scan never reached — `index.html` and `*.webmanifest` (plus plain `.json`, which a webmanifest
  * often is). Only the color/typography kinds apply there; see `MARKUP_KINDS`.
+ *
+ * `sfc` is the single-file-component dialect — `.astro` and `.vue`, which carry BOTH regions:
+ * `<!-- … -->` in the template and `//` / `/* … *\/` in the frontmatter/`<script>` fence. They used
+ * to fall through to `ts`, so an HTML comment was never stripped: a `theme-allow` written in one
+ * waived nothing, and a color inside a commented-out block still reported (rollhook, round 9 —
+ * `.astro` became scannable in the same minor that exposed it). They are NOT `markup`: an `.astro`
+ * template is JSX-shaped and a `.vue` `<script setup>` is real TS, so restricting them to
+ * {@link MARKUP_KINDS} would drop 22 of the 25 kinds on a file type that can violate all of them.
+ *
+ * `.jsx` needs no entry — it is TS syntax with no HTML-comment region.
+ *
+ * **Two asserted limits, both false-NEGATIVE-only** (pinned in `check-source.test.ts`):
+ *
+ * 1. The kebab-CSS kinds (`css-raw-surface`) do not fire inside a `<style>` fence — that branch
+ *    keys on `syntax === 'css'`, and an SFC is one file with three dialects, not three files. The
+ *    color kinds, which are what an unguarded template layer actually leaks, do fire there.
+ * 2. Stripping is region-BLIND: `<!-- … -->` is blanked anywhere in the file, and `//` anywhere
+ *    outside a string. A `<!--` inside a script string, or an unquoted `https://` in template
+ *    prose, over-strips the rest of that construct. Both directions lose findings rather than
+ *    inventing them, which is the side of the trade a release-blocking false positive says to take.
  */
 function guardSyntaxFor(relPath: string): GuardSyntax {
   if (relPath.endsWith('.css')) return 'css'
   if (/\.(?:html?|webmanifest|json)$/.test(relPath)) return 'markup'
+  if (/\.(?:astro|vue)$/.test(relPath)) return 'sfc'
   return 'ts'
 }
 
+/**
+ * The comment-stripped twin of `text`, same length and same newline positions, for any dialect.
+ *
+ * One place rather than the two call sites (`checkSource` and `findAllowAnnotations`) that used to
+ * spell the `markup ? … : …` ternary out independently — adding `sfc` to one and not the other is
+ * exactly how the scan and `--audit-allows` drift apart on what counts as a comment.
+ *
+ * The SFC order is markup-first: an HTML comment may legally contain `//` or an unterminated `/*`,
+ * and blanking it before the TS pass keeps that text from opening a comment that runs to EOF.
+ */
+function stripGuardComments(text: string, syntax: GuardSyntax): string {
+  if (syntax === 'markup') return stripMarkupComments(text)
+  if (syntax === 'sfc') return stripComments(stripMarkupComments(text), 'ts')
+  return stripComments(text, syntax)
+}
+
 /** The only kinds meaningful in an HTML document or a JSON manifest — no JSX, no CSS-in-JS. */
 const MARKUP_KINDS: ReadonlySet<GuardKind> = new Set(['raw-hex', 'raw-color-fn', 'raw-font-family'])
 
@@ -1794,7 +1932,7 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
   // stripped text has already blanked out. Same length / same newline positions as `text`, so line
   // numbers computed off either one agree.
   const syntax = guardSyntaxFor(relPath)
-  const codeText = syntax === 'markup' ? stripMarkupComments(text) : stripComments(text, syntax)
+  const codeText = stripGuardComments(text, syntax)
   const codeLines = codeText.split('\n')
   const { waivers, fileScoped, declared } = collectAllowAnnotations(
     lines,
@@ -1974,7 +2112,9 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
         if (syntax === 'css' && isSubScaleCssSpacing(line, m.index)) continue
         const hasUnit = /^[a-z%]/.test(line.slice(m.index + m[0].length))
         if (
-          syntax === 'ts' &&
+          // An SFC's script fence IS TS, so it takes the same gate — without it a unitless
+          // `padding: 8` in `.astro`/`.vue` frontmatter reports with no style-object behind it.
+          (syntax === 'ts' || syntax === 'sfc') &&
           !hasUnit &&
           !isStyleObjectContext(codeText, lineStarts[i]! + m.index, styleIdentifiers)
         )
@@ -2047,10 +2187,25 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
     }
   }
 
+  // Both chart tag rules below gate on tag PROVENANCE (see the block above LOCAL_COMPONENT_DEF).
+  // Computed once, and only if one of the two actually runs.
+  const unframedChartRuns =
+    GUARD_RULES['unframed-chart'].enabled!(cfg) && ruleApplies('unframed-chart', relPath)
+  const ariaLabelRuns =
+    GUARD_RULES['chart-missing-aria-label'].enabled!(cfg) &&
+    ruleApplies('chart-missing-aria-label', relPath)
+  const localNames =
+    unframedChartRuns || ariaLabelRuns ? localComponentNames(codeText) : new Set<string>()
+  const basaltNames =
+    unframedChartRuns || ariaLabelRuns ? basaltImportedNames(codeText) : new Set<string>()
+  const isShippedTag = (tag: string): boolean => basaltNames.has(tag) || !localNames.has(tag)
+
   // unframed-chart — full-text tag-scoped scan (not per-line, see RAW_CHART_LEGEND_ARRAY comment).
   // Scans `codeText` (comment-stripped) so a legend example inside a comment can't match; reports
-  // at the line of the `items={[` token itself.
-  if (GUARD_RULES['unframed-chart'].enabled!(cfg) && ruleApplies('unframed-chart', relPath)) {
+  // at the line of the `items={[` token itself. Skipped wholesale when `ChartLegend` is this file's
+  // OWN component: a consumer's legend taking an `items` array is not the shipped one that derives
+  // its entries, and the remedy ("pass deriveLegend(series)") is unreachable there.
+  if (unframedChartRuns && isShippedTag('ChartLegend')) {
     for (const m of codeText.matchAll(RAW_CHART_LEGEND_ARRAY)) {
       const lineNo = codeText.slice(0, (m.index ?? 0) + m[0].length).split('\n').length
       push('unframed-chart', lineNo, 'items={[')
@@ -2064,12 +2219,11 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
   // which is what `Finding.text` would then quote back — the closing bracket rather than the tag
   // that is missing the prop. The allow-comment is honored anywhere in the tag's span, so a
   // `theme-allow` that used to sit on the closing line keeps working.
-  if (
-    GUARD_RULES['chart-missing-aria-label'].enabled!(cfg) &&
-    ruleApplies('chart-missing-aria-label', relPath)
-  ) {
+  if (ariaLabelRuns) {
     for (const m of codeText.matchAll(CHART_ENTRY_POINT_TAG)) {
       const tagText = m[0]
+      // A tag this file defines itself is not the shipped kind — it does not take `ariaLabel`.
+      if (!isShippedTag(m[1] as string)) continue
       if (HAS_ARIA_LABEL_PROP.test(tagText)) continue
       const startLine = codeText.slice(0, m.index ?? 0).split('\n').length
       const endLine = startLine + (tagText.split('\n').length - 1)
@@ -2196,7 +2350,7 @@ export function findAllowAnnotations(
 ): AllowAnnotationSite[] {
   const lines = text.split('\n')
   const syntax = guardSyntaxFor(relPath)
-  const codeText = syntax === 'markup' ? stripMarkupComments(text) : stripComments(text, syntax)
+  const codeText = stripGuardComments(text, syntax)
   const { declared } = collectAllowAnnotations(
     lines,
     codeText.split('\n'),

package/src/index.ts

@@ -95,6 +95,15 @@ export {
   type SettingsRowProps,
   DangerZone,
   type DangerZoneProps,
+  QueryState,
+  type QueryStateProps,
+  type QueryStateLike,
+  type QueryStateVariant,
+  type QueryEmptyCopy,
+  LoadingState,
+  type LoadingStateProps,
+  ErrorState,
+  type ErrorStateProps,
 } from './dashboard'
 
 // ── Connectivity (auto-mounted by BasaltProvider) ────────────────────────────────────────────────

package/src/query/error-message.test.ts

@@ -0,0 +1,67 @@
+/**
+ * `toErrorMessage`'s job is to never hand a human a string that says nothing. The decode ladder
+ * was already right; what was missing is the floor under it — an opaque envelope decoded to the
+ * literal `"{}"`, and `toErrorMessage(undefined)` returned `JSON.stringify(undefined)`, which is
+ * not a string at all despite the `string` return type. Both are the shape a page renders straight
+ * into an Alert, so both are asserted here.
+ */
+import { describe, expect, test } from 'bun:test'
+import { errorStatus, toErrorMessage } from './error-message'
+
+describe('toErrorMessage — decode ladder', () => {
+  test('Error instance → message', () => {
+    expect(toErrorMessage(new Error('slug already in use'))).toBe('slug already in use')
+  })
+
+  test('{ message } → message', () => {
+    expect(toErrorMessage({ message: 'recursive is rejected' })).toBe('recursive is rejected')
+  })
+
+  test('Eden { status, value } envelope → one level down', () => {
+    expect(toErrorMessage({ status: 409, value: { message: 'slug taken' } })).toBe('slug taken')
+  })
+
+  test('plain string → itself', () => {
+    expect(toErrorMessage('boom')).toBe('boom')
+  })
+})
+
+describe('toErrorMessage — the unusable floor', () => {
+  test('an opaque object falls back instead of rendering "{}"', () => {
+    expect(toErrorMessage({}, 'Could not create share')).toBe('Could not create share')
+  })
+
+  test('undefined returns a real string, not the undefined value', () => {
+    const message = toErrorMessage(undefined)
+    expect(typeof message).toBe('string')
+    expect(message).toBe('The request failed.')
+  })
+
+  test('an opaque envelope WITH a status folds the status into the fallback', () => {
+    expect(toErrorMessage({ status: 502, value: {} }, 'Could not load images')).toBe(
+      'Could not load images (HTTP 502)',
+    )
+  })
+
+  test('a readable body wins over the status — the server message is never replaced', () => {
+    expect(toErrorMessage({ status: 403, value: { message: 'forbidden' } }, 'Nope')).toBe(
+      'forbidden',
+    )
+  })
+
+  test('whitespace-only decodes as unusable', () => {
+    expect(toErrorMessage({ message: '   ' }, 'Fallback')).toBe('Fallback')
+  })
+})
+
+describe('errorStatus', () => {
+  test('reads a numeric status off an envelope', () => {
+    expect(errorStatus({ status: 404, value: null })).toBe(404)
+  })
+
+  test('is undefined for anything else', () => {
+    expect(errorStatus(new Error('x'))).toBeUndefined()
+    expect(errorStatus(null)).toBeUndefined()
+    expect(errorStatus({ status: '404' })).toBeUndefined()
+  })
+})