basalt-ui 1.22.0 → 1.23.1

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

@@ -800,6 +800,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 ─────────────────────────────────────────────────────
@@ -2738,59 +2811,134 @@ describe('inline-spacing — the style-object test', () => {
   })
 })
 
-// ── theme-allow comment shapes ───────────────────────────────────────────────────────────────────
+// ── theme-allow shape grid ───────────────────────────────────────────────────────────────────────
 
 /**
- * The prefix contract, pinned per comment shape.
+ * The whole shape space of an annotation, pinned cell by cell.
+ *
+ * FIVE holes have been found in this one contract in four rounds — two false positives, one false
+ * negative, and twice the guard and the oxlint plugin disagreeing about what an annotation IS. Each
+ * was found by a consumer writing a shape nobody had thought to test, and round 6's answer (a
+ * thirteen-shape list of "every shape a consumer actually writes") missed the next three anyway,
+ * because a list of observed shapes cannot cover the ones not yet observed.
+ *
+ * So this is a GRID over the four things that actually vary, not a list of anecdotes:
  *
- * Three holes have been found in this rule in three rounds — two false positives and one false
- * NEGATIVE (a docblock documenting a file's waivers disarmed the file). So every shape a consumer
- * actually writes gets a fixture, and the oxlint plugin's copy is pinned identically in
- * `configs/oxlint-plugin.test.ts`: the two halves of one contract must agree on what an annotation
- * IS, and may differ only on which rules each can judge.
+ * | axis | values |
+ * |-|-|
+ * | comment style | `//` · `/* *\/` · `/** *\/` · `{/* *\/}` · `{/** *\/}` · `<!-- -->` · JSON member |
+ * | token position | opener line · gutter line · trailing after code |
+ * | where the closer falls | the token's line · its own line · N lines below · n/a |
+ * | what follows | code · blank then code · comment then code · code on the closer's line |
+ *
+ * `configs/oxlint-plugin.test.ts` pins the same grid, under the same row names, for the subset the
+ * plugin can judge (TS/JSX — it never sees CSS, HTML or JSON). The two halves must agree on every
+ * shared cell; add a row to one and it goes in the other in the same commit.
+ *
+ * The unsupported cells are asserted too. "Unsupported" and "silently broken" read identically to a
+ * consumer, and the whole point of the grid is to make them different things.
  */
-describe('theme-allow comment shapes', () => {
-  const REASON = 'deliberate legacy value'
-  const waives = (relPath: string, src: string): boolean =>
-    checkSource(src, relPath, DEFAULT_GUARD_CONFIG).filter((f) => f.kind === 'raw-hex').length === 0
+/** Wraps JSX children in a component, so a `{/* … *\/}` child is legal source. */
+const jsxShape = (body: string): string =>
+  `export const C = () => (\n  <div>\n${body}\n  </div>\n)\n`
+
+/** Does the file waive its `raw-hex`? — the one question every grid row asks. */
+const shapeWaives = (relPath: string, src: string): boolean =>
+  checkSource(src, relPath, DEFAULT_GUARD_CONFIG).filter((f) => f.kind === 'raw-hex').length === 0
 
+describe('theme-allow shape grid', () => {
+  const REASON = 'deliberate legacy value'
+  const A = `theme-allow raw-hex — ${REASON}`
+  const AF = `theme-allow-file raw-hex — ${REASON}`
+  /** The statement the guard reports `raw-hex` on. */
+  const T = `const a = '#f00'`
+  /** The JSX child the guard reports `raw-hex` on. */
+  const JT = `<span style={{ color: '#f00' }} />`
+  const J = jsxShape
+  const waives = shapeWaives
+
+  // ── SUPPORTED — every cell of the grid that waives ────────────────────────
   it.each([
-    ['own line //', PATH, `// theme-allow raw-hex — ${REASON}\nconst a = '#f00'\n`],
+    // `//` — no closer to place.
+    ['// own line', PATH, `// ${A}\n${T}\n`],
+    ['// indented', PATH, `function f() {\n  // ${A}\n  ${T}\n}\n`],
+    ['// no space after the marker', PATH, `//${A}\n${T}\n`],
+    ['// trailing', PATH, `${T} // ${A}\n`],
+    ['// reason wrapped onto a second // comment', PATH, `// ${A},\n// continued here\n${T}\n`],
+    // `/* */` and `/** */` at statement level, closer in each of its three places.
+    ['/* */ own line', PATH, `/* ${A} */\n${T}\n`],
+    ['/* */ trailing', PATH, `${T} /* ${A} */\n`],
+    ['/** */ own line (docblock opener)', PATH, `/** ${A} */\n${T}\n`],
+    ['/* opener + token, closer on its own line', PATH, `/* ${A}\n*/\n${T}\n`],
+    ['/* gutter token, closer on the token line', PATH, `/*\n ${A} */\n${T}\n`],
+    ['/* gutter token, closer on its own line', PATH, `/*\n ${A}\n*/\n${T}\n`],
+    ['/** star gutter, closer on the token line', PATH, `/**\n * ${A} */\n${T}\n`],
+    ['/** star gutter, closer on its own line', PATH, `/**\n * ${A}\n */\n${T}\n`],
+    // Prose between the token and the closer — any amount of it.
+    ['/** token then 1 prose line', PATH, `/**\n * ${A}\n * more\n */\n${T}\n`],
+    ['/** token then 12 prose lines', PATH, `/**\n * ${A}\n${' * p\n'.repeat(12)} */\n${T}\n`],
     [
-      'indented //',
+      '/** prose first, token on a later gutter line',
       PATH,
-      `function f() {\n  // theme-allow raw-hex — ${REASON}\n  const a = '#f00'\n}\n`,
+      `/**\n * some prose\n * ${A}\n */\n${T}\n`,
     ],
-    ['trailing //', PATH, `const a = '#f00' // theme-allow raw-hex — ${REASON}\n`],
-    ['trailing block', PATH, `const a = '#f00' /* theme-allow raw-hex — ${REASON} */\n`],
+    // JSX expression containers — the family every disagreement so far has come from.
+    ['{/* */} own line', PATH, J(`    {/* ${A} */}\n    ${JT}`)],
+    ['{/* */} trailing on the target line', PATH, J(`    ${JT} {/* ${A} */}`)],
+    ['{/* opener + token, closer on its own line', PATH, J(`    {/* ${A}\n    */}\n    ${JT}`)],
+    ['{/* gutter token, closer on the token line', PATH, J(`    {/*\n      ${A} */}\n    ${JT}`)],
     [
-      'JSX expression comment',
+      '{/* gutter token, closer on its own line',
       PATH,
-      `export const C = () => (\n  <div>\n    {/* theme-allow raw-hex — ${REASON} */}\n    <span style={{ color: '#f00' }} />\n  </div>\n)\n`,
+      J(`    {/*\n      ${A}\n    */}\n    ${JT}`),
     ],
+    ['{/** star gutter, closer on the token line', PATH, J(`    {/**\n     * ${A} */}\n    ${JT}`)],
     [
-      'JSX expression comment, token on its own wrapped line',
+      '{/** star gutter, closer on its own line',
       PATH,
-      `export const C = () => (\n  <div>\n    {/*\n      theme-allow raw-hex — ${REASON} */}\n    <span style={{ color: '#f00' }} />\n  </div>\n)\n`,
+      J(`    {/**\n     * ${A}\n     */}\n    ${JT}`),
     ],
-    ['block gutter *', PATH, `/**\n * theme-allow raw-hex — ${REASON}\n */\nconst a = '#f00'\n`],
-    ['docblock opener /**', PATH, `/** theme-allow raw-hex — ${REASON} */\nconst a = '#f00'\n`],
-    ['css trailing', 'src/a.css', `a { color: #f00; /* theme-allow raw-hex — ${REASON} */ }\n`],
     [
-      'css reflowed onto continuation lines',
-      'src/a.css',
-      `a {\n  color: var(\n    --x,\n    #f00\n  ); /* theme-allow raw-hex — ${REASON} */\n}\n`,
+      '{/** token then 6 prose lines',
+      PATH,
+      J(`    {/**\n     * ${A}\n${'     * p\n'.repeat(6)}     */}\n    ${JT}`),
     ],
+    ['{/* target on the closer line', PATH, J(`    {/*\n      ${A}\n    */}${JT}`)],
+    ['{/* closer alone, tab indented', PATH, J(`\t{/*\n\t  ${A}\n\t*/}\n\t${JT}`)],
     [
-      'html comment',
-      'index.html',
-      `<!-- theme-allow raw-hex — ${REASON} -->\n<b style="color: #f00"></b>\n`,
+      '{/* closer alone, space between */ and }',
+      PATH,
+      J(`    {/*\n      ${A}\n    */ }\n    ${JT}`),
     ],
     [
-      'html trailing comment',
-      'index.html',
-      `<b style="color: #f00"></b> <!-- theme-allow raw-hex — ${REASON} -->\n`,
+      '{/* closer alone, two annotations in one block',
+      PATH,
+      J(`    {/*\n      ${A}\n      theme-allow raw-color-fn — ${REASON}\n    */}\n    ${JT}`),
+    ],
+    // A further comment between the annotation and the code is walked through; a blank line is not.
+    ['/** */ then an unrelated // note', PATH, `/** ${A} */\n// an unrelated note\n${T}\n`],
+    [
+      '{/* */} then an unrelated {/* */}',
+      PATH,
+      J(`    {/* ${A} */}\n    {/* unrelated */}\n    ${JT}`),
     ],
+    // The file-declaration form, which is position-independent — pinned in two placements anyway,
+    // because "position-independent" is a claim the parser has to keep making.
+    [
+      'theme-allow-file, {/* closer on its own line',
+      PATH,
+      J(`    {/*\n      ${AF}\n    */}\n    ${JT}`),
+    ],
+    ['theme-allow-file, /** star gutter', PATH, `/**\n * ${AF}\n */\n${T}\n`],
+    // Dialects the plugin never sees — CSS continuation lines, HTML, and the JSON member form.
+    ['css trailing', 'src/a.css', `a { color: #f00; /* ${A} */ }\n`],
+    [
+      'css reflowed onto continuation lines',
+      'src/a.css',
+      `a {\n  color: var(\n    --x,\n    #f00\n  ); /* ${A} */\n}\n`,
+    ],
+    ['html comment own line', 'index.html', `<!-- ${A} -->\n<b style="color: #f00"></b>\n`],
+    ['html trailing comment', 'index.html', `<b style="color: #f00"></b> <!-- ${A} -->\n`],
     [
       'JSON member form',
       'public/site.webmanifest',
@@ -2800,25 +2948,46 @@ describe('theme-allow comment shapes', () => {
     expect(waives(relPath as string, src as string)).toBe(true)
   })
 
-  // The false negative the prefix rule closed: a sentence that MENTIONS the token is not one.
+  // ── UNSUPPORTED — asserted, so a hole can never pass for a design decision ──
   it.each([
+    // A blank line is the separation people use for "this comment is not about the next statement".
+    ['blank line after a // annotation', PATH, `// ${A}\n\n${T}\n`],
+    ['blank line after a {/* */} annotation', PATH, J(`    {/* ${A} */}\n\n    ${JT}`)],
     [
-      'mid-sentence in a line comment',
-      `// we normally write a theme-allow raw-hex here\nconst a = '#f00'\n`,
+      'blank line after a {/* closer on its own line',
+      PATH,
+      J(`    {/*\n      ${A}\n    */}\n\n    ${JT}`),
     ],
+    // Prose that MENTIONS the token is not an annotation — the one false NEGATIVE in the set, and
+    // the reason the token has to START its comment.
+    ['mid-sentence in a line comment', PATH, `// we normally write a ${A} here\n${T}\n`],
     [
-      'mid-sentence in a docblock',
-      `/**\n * Each value below is escaped with a theme-allow raw-hex annotation.\n */\nconst a = '#f00'\n`,
+      'mid-sentence in a docblock gutter',
+      PATH,
+      `/**\n * Each value is escaped with a ${A} annotation.\n */\n${T}\n`,
+    ],
+    [
+      'mid-sentence in a JSX expression comment',
+      PATH,
+      J(`    {/* the shape here is a ${A} comment */}\n    ${JT}`),
+    ],
+    ['inside a string literal', PATH, `const doc = 'theme-allow raw-hex'\n${T}\n`],
+    // An annotation reaches the first line below its comment — not an arbitrary line further down.
+    // A multi-line opening tag therefore needs the annotation beside the attribute, not above the
+    // tag. Both halves agree, and both report rather than silently waiving the wrong node.
+    [
+      'above a multi-line opening tag',
+      PATH,
+      J(`    {/* ${A} */}\n    <span\n      style={{ color: '#f00' }}\n    />`),
     ],
-    ['inside a string literal', `const doc = 'theme-allow raw-hex'\nconst a = '#f00'\n`],
-  ])('%s does NOT waive', (_name, src) => {
-    expect(waives(PATH, src as string)).toBe(false)
+  ])('%s does NOT waive', (_name, relPath, src) => {
+    expect(waives(relPath as string, src as string)).toBe(false)
   })
 
   // The narrowness of the `*/}` exception: a `}` that is REAL code keeps its trailing
   // classification, so the annotation does not reach the statement below it.
   it('a trailing annotation on a real closing brace stays on its own line', () => {
-    const src = `function f() {\n  const a = 1\n} // theme-allow raw-hex — ${REASON}\nconst b = '#0f0'\n`
+    const src = `function f() {\n  const a = 1\n} // ${A}\nconst b = '#0f0'\n`
     expect(
       checkSource(src, PATH, DEFAULT_GUARD_CONFIG)
         .filter((f) => f.kind === 'raw-hex')
@@ -2829,7 +2998,7 @@ describe('theme-allow comment shapes', () => {
   // A trailing annotation is scoped to its OWN line — otherwise `const a = '#f00' // theme-allow`
   // would silently waive the statement below it too.
   it('a trailing annotation does not reach the line below', () => {
-    const src = `const a = '#f00' // theme-allow raw-hex — ${REASON}\nconst b = '#0f0'\n`
+    const src = `const a = '#f00' // ${A}\nconst b = '#0f0'\n`
     expect(
       checkSource(src, PATH, DEFAULT_GUARD_CONFIG).filter((f) => f.kind === 'raw-hex'),
     ).toHaveLength(1)

package/src/guard/index.ts

@@ -400,9 +400,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|Donut|DualPanel|Heatmap|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
@@ -771,8 +817,45 @@ function parseAllowAnnotation(rest: string, scope: AllowScope): AllowAnnotation
 /** How far back a trailing CSS annotation reaches for the declaration it terminates. */
 const MAX_CSS_CONTINUATION_LINES = 8
 
-/** How far a comment-only annotation reaches forward through the rest of its own comment block. */
-const MAX_COMMENT_BLOCK_LINES = 8
+/**
+ * The 0-based line the annotation's OWN comment closes on.
+ *
+ * A comment-only annotation waives the first line below its comment that is not itself comment, so
+ * the walk needs to know how far the annotation's own comment reaches. It used to substitute a
+ * budget — walk forward at most eight lines — which was wrong in two ways nothing could see:
+ *
+ * 1. **A comment block longer than the budget.** A docblock with ~12 lines of reason between the
+ *    token and its `*\/` ran the walk out before it reached the code, while the oxlint plugin
+ *    (which reads the comment NODE, so length is free) waived it. Nothing about the shape said so;
+ *    the annotation just stopped working past a line count nobody could count.
+ * 2. **A blank line inside the block.** Outside a comment a blank line SEPARATES — it is how people
+ *    say "this comment is not about the next statement" — but a blank gutter line in the middle of
+ *    a docblock is just prose, and ending the walk there dropped the waiver.
+ *
+ * Knowing where the comment ends settles both: inside it, keep going; past it, the ordinary
+ * comment-run rules apply (see the walk in {@link collectAllowAnnotations}, and
+ * {@link isCommentOnly} for the third hole this pass closed).
+ *
+ * An unterminated block comment reports its own line — the conservative answer for a file that does
+ * not parse anyway, and it keeps the walk from running to EOF.
+ */
+function commentBlockEnd(
+  lines: readonly string[],
+  index: number,
+  tokenAt: number,
+  syntax: GuardSyntax,
+): number {
+  const line = lines[index] ?? ''
+  // 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 (line.slice(tokenAt).includes(closer)) return index
+  for (let ahead = index + 1; ahead < lines.length; ahead++) {
+    if ((lines[ahead] ?? '').includes(closer)) return ahead
+  }
+  return index
+}
 
 /**
  * A comment opener sitting immediately before the annotation token.
@@ -805,6 +888,22 @@ const COMMENT_ONLY_LINE = /^\s*(?:\{\s*\/\*|\/\/|\/\*|\*|<!--)/
  */
 const JSX_COMMENT_CLOSE = /\*\/\s*\}\s*$/
 
+/**
+ * Is this line NOTHING but comment? — one definition, used both to classify the annotation's own
+ * line (own-line vs trailing) and to walk the lines under it.
+ *
+ * The two used to be written out separately, and the walk's copy was the one missing the
+ * {@link JSX_COMMENT_CLOSE} clause: a `*\/}` alone on its line read as the code `}`, so the walk
+ * stopped ON the closer and the annotation waived a brace. Two consumers isolated that
+ * independently — `{/* … *\/}` and `{/** … *\/}` — each with a probe pair differing by one newline,
+ * while the oxlint plugin (whose test is comment-node-based and never sees the brace) waived both.
+ * A shared predicate is what stops the two placements from drifting apart again.
+ */
+function isCommentOnly(raw: string, stripped: string): boolean {
+  const code = stripped.trim()
+  return code === '' || COMMENT_ONLY_LINE.test(raw) || (code === '}' && JSX_COMMENT_CLOSE.test(raw))
+}
+
 /**
  * Everything allowed between the comment opener (or the start of the line) and the annotation
  * token, for the token to count as an ANNOTATION rather than prose that mentions one.
@@ -933,7 +1032,12 @@ function collectAllowAnnotations(
   }
 
   /** Place one parsed annotation: file declarations reach everywhere, line ones the 3 placements. */
-  const record = (index: number, annotation: AllowAnnotation, trailing: boolean): void => {
+  const record = (
+    index: number,
+    annotation: AllowAnnotation,
+    trailing: boolean,
+    tokenAt: number,
+  ): void => {
     declared.push({ line: index + 1, annotation })
     if (annotation.scope === 'file') {
       fileScoped.push(annotation)
@@ -941,16 +1045,20 @@ function collectAllowAnnotations(
     }
     add(index, annotation)
     if (!trailing) {
-      // The first line below that is not itself comment. A docblock's `*/` (or the rest of a
-      // wrapped reason) sits between the annotation and the code it is about, so `index + 1` alone
-      // meant the natural multi-line shape silently waived nothing — argo hit it three times in one
-      // upgrade, each looking like a correct annotation. A BLANK line still ends the block: that is
-      // the separation people use to mean "this comment is not about the next statement".
-      for (let ahead = 1; ahead <= MAX_COMMENT_BLOCK_LINES; ahead++) {
-        const raw = lines[index + ahead] ?? ''
-        add(index + ahead, annotation)
-        if (raw.trim() !== '' && (codeLines[index + ahead] ?? '').trim() !== '') break
+      // The first CODE line below the comment. A docblock's `*/` (or the rest of a wrapped reason)
+      // sits between the annotation and the code it is about, so `index + 1` alone meant the
+      // natural multi-line shape silently waived nothing — argo hit it three times in one upgrade,
+      // each looking like a correct annotation. A BLANK line outside the comment still ends the
+      // block: that is the separation people use to mean "this comment is not about the next
+      // statement". Inside it, a blank gutter line is just prose.
+      const closesAt = commentBlockEnd(lines, index, tokenAt, syntax)
+      for (let ahead = 1; index + ahead < lines.length; ahead++) {
+        const at = index + ahead
+        add(at, annotation)
+        if (at <= closesAt) continue
+        const raw = lines[at] ?? ''
         if (raw.trim() === '') break
+        if (!isCommentOnly(raw, codeLines[at] ?? '')) break
       }
       return
     }
@@ -968,14 +1076,17 @@ function collectAllowAnnotations(
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i] ?? ''
     const stripped = codeLines[i] ?? ''
-    const code = stripped.trim()
-    const isCommentOnlyLine =
-      code === '' || COMMENT_ONLY_LINE.test(line) || (code === '}' && JSX_COMMENT_CLOSE.test(line))
+    const isCommentOnlyLine = isCommentOnly(line, stripped)
 
     // The JSON member form. Markup-only: in TS/CSS that string would be code, not an annotation.
     if (syntax === 'markup') {
       for (const m of line.matchAll(jsonKey)) {
-        record(i, parseAllowAnnotation(m[2] ?? '', m[1] === undefined ? 'line' : 'file'), false)
+        record(
+          i,
+          parseAllowAnnotation(m[2] ?? '', m[1] === undefined ? 'line' : 'file'),
+          false,
+          m.index,
+        )
       }
     }
 
@@ -993,6 +1104,7 @@ function collectAllowAnnotations(
         i,
         parseAllowAnnotation(rest, m[1] === undefined ? 'line' : 'file'),
         !isCommentOnlyLine,
+        at,
       )
     }
   }
@@ -1981,10 +2093,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={[')
@@ -1998,12 +2125,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)

package/src/vite.test.ts

@@ -234,6 +234,85 @@ describe('basaltAppPlugin — base handling', () => {
     const manifest = JSON.parse(runMiddleware(middleware, '/site.webmanifest') ?? '{}')
     expect(manifest.icons[0].src).toBe('/brand/web-app-manifest-192x192.png')
   })
+
+  // ── the consumer-named array form ─────────────────────────────────────────
+  //
+  // `{ dir }` can move basalt's six filenames but not rename one, so an app whose only icon is
+  // `favicon.svg` could pick between a manifest naming two PNGs it does not ship and a manifest
+  // with no icons at all. Both are wrong for an installable app, and the second is why rb still
+  // kept a hand-written manifest one release after `icons: false` was fixed.
+
+  // rb's REAL icon set, copied from apps/web/public/manifest.webmanifest — the manifest this
+  // option exists to let the plugin generate.
+  const RB_ICONS = [
+    { src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml', purpose: 'any' },
+  ] as const
+
+  test("generates rb's hand-written manifest icons member verbatim", () => {
+    const plugin = getPlugin({ name: 'rb', themeColor: THEME_COLOR, icons: RB_ICONS })
+    const middleware = getDevMiddleware(plugin, '/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/site.webmanifest') ?? '{}')
+
+    expect(manifest.icons).toEqual([
+      { src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml', purpose: 'any' },
+    ])
+    expect(JSON.stringify(manifest)).not.toContain('.png')
+    expect(manifest.name).toBe('rb')
+    expect(manifest.display).toBe('standalone')
+  })
+
+  test('a named icon reaches the head only when it asks for a rel', () => {
+    const iconLinks = (icons: NonNullable<BasaltAppOptions['icons']>): HtmlTagDescriptor[] => {
+      const plugin = getPlugin({ name: 'rb', themeColor: THEME_COLOR, icons })
+      resolveConfig(plugin, '/')
+      return transformHtml(plugin, HTML_NO_VIEWPORT).filter(
+        (tag) => tag.tag === 'link' && String(tag.attrs?.['rel']).includes('icon'),
+      )
+    }
+
+    // rb's index.html already links favicon.svg — the manifest gets fixed, the head is left alone.
+    expect(iconLinks(RB_ICONS)).toHaveLength(0)
+
+    const withRel = iconLinks([{ src: 'favicon.svg', type: 'image/svg+xml', rel: 'icon' }])
+    expect(withRel).toHaveLength(1)
+    expect(withRel[0]?.attrs).toEqual({
+      rel: 'icon',
+      type: 'image/svg+xml',
+      href: '/favicon.svg',
+    })
+  })
+
+  test('a named icon src is base-prefixed, with or without its leading slash', () => {
+    const plugin = getPlugin({
+      name: 'rb',
+      themeColor: THEME_COLOR,
+      icons: [
+        { src: 'favicon.svg', sizes: 'any' },
+        { src: '/icon-512.png', sizes: '512x512' },
+      ],
+    })
+    const middleware = getDevMiddleware(plugin, '/myapp/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/myapp/site.webmanifest') ?? '{}')
+
+    expect(manifest.icons.map((icon: { src: string }) => icon.src)).toEqual([
+      '/myapp/favicon.svg',
+      '/myapp/icon-512.png',
+    ])
+  })
+
+  test('an empty array reads as icons: false — no member, not an empty one', () => {
+    const plugin = getPlugin({ name: 'rb', themeColor: THEME_COLOR, icons: [] })
+    const middleware = getDevMiddleware(plugin, '/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/site.webmanifest') ?? '{}')
+    expect(manifest.icons).toBeUndefined()
+  })
+
+  test('the array form omits keys the consumer did not write', () => {
+    const plugin = getPlugin({ name: 'rb', themeColor: THEME_COLOR, icons: [{ src: '/a.svg' }] })
+    const middleware = getDevMiddleware(plugin, '/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/site.webmanifest') ?? '{}')
+    expect(manifest.icons).toEqual([{ src: '/a.svg' }])
+  })
 })
 
 describe('basaltAppPlugin — the anti-FOUC boot rule (V1)', () => {