basalt-ui 1.21.0 → 1.23.0

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

@@ -13,10 +13,14 @@ import { SPACE_SCALE } from '../tokens/palette'
 import {
   checkSource,
   DEFAULT_GUARD_CONFIG,
+  findAllowAnnotations,
   GENERATED_HEADER_LINE,
   guardKindRemedy,
   guardWaiverHint,
   GUARD_RULES,
+  neutralizeAllowAnnotation,
+  NEUTRALIZED_ALLOW_TOKEN,
+  PLUGIN_RULE_IDS,
   TOKENS_ONLY_DISABLED_KINDS,
   unmatchedExemptPatterns,
 } from './index'
@@ -2733,3 +2737,292 @@ describe('inline-spacing — the style-object test', () => {
     expect(kinds(f)).toContain('inline-spacing')
   })
 })
+
+// ── theme-allow shape grid ───────────────────────────────────────────────────────────────────────
+
+/**
+ * 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:
+ *
+ * | 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.
+ */
+/** 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([
+    // `//` — 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`],
+    [
+      '/** prose first, token on a later gutter line',
+      PATH,
+      `/**\n * some prose\n * ${A}\n */\n${T}\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}`)],
+    [
+      '{/* gutter token, closer on its own line',
+      PATH,
+      J(`    {/*\n      ${A}\n    */}\n    ${JT}`),
+    ],
+    ['{/** star gutter, closer on the token line', PATH, J(`    {/**\n     * ${A} */}\n    ${JT}`)],
+    [
+      '{/** star gutter, closer on its own line',
+      PATH,
+      J(`    {/**\n     * ${A}\n     */}\n    ${JT}`),
+    ],
+    [
+      '{/** 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}`)],
+    [
+      '{/* closer alone, space between */ and }',
+      PATH,
+      J(`    {/*\n      ${A}\n    */ }\n    ${JT}`),
+    ],
+    [
+      '{/* 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',
+      `{\n  "basalt:theme-allow-file": "raw-hex — ${REASON}",\n  "theme_color": "#f00"\n}\n`,
+    ],
+  ])('%s waives', (_name, relPath, src) => {
+    expect(waives(relPath as string, src as string)).toBe(true)
+  })
+
+  // ── 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}`)],
+    [
+      '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 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    />`),
+    ],
+  ])('%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} // ${A}\nconst b = '#0f0'\n`
+    expect(
+      checkSource(src, PATH, DEFAULT_GUARD_CONFIG)
+        .filter((f) => f.kind === 'raw-hex')
+        .map((f) => f.line),
+    ).toEqual([4])
+  })
+
+  // 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' // ${A}\nconst b = '#0f0'\n`
+    expect(
+      checkSource(src, PATH, DEFAULT_GUARD_CONFIG).filter((f) => f.kind === 'raw-hex'),
+    ).toHaveLength(1)
+  })
+})
+
+// ── findAllowAnnotations / neutralizeAllowAnnotation ─────────────────────────────────────────────
+
+describe('findAllowAnnotations', () => {
+  const cfg = DEFAULT_GUARD_CONFIG
+
+  it('classifies each named id by whose reach it falls in', () => {
+    const src = [
+      `// theme-allow raw-hex — a guard kind`,
+      `const a = '#f00'`,
+      `// theme-allow hand-rolled-plot — a plugin rule, outside checkSource's reach`,
+      `const b = 1`,
+      `// theme-allow raw-hexx — a typo`,
+      `const c = 2`,
+      `// theme-allow`,
+      `const d = 3`,
+    ].join('\n')
+    const sites = findAllowAnnotations(src, PATH, cfg)
+
+    expect(sites.map((s) => s.line)).toEqual([1, 3, 5, 7])
+    expect(sites[0]).toMatchObject({ guardKinds: ['raw-hex'], pluginRules: [], bare: false })
+    expect(sites[1]).toMatchObject({ guardKinds: [], pluginRules: ['hand-rolled-plot'] })
+    expect(sites[2]).toMatchObject({ rules: [], unknownRules: ['raw-hexx'], bare: false })
+    expect(sites[3]).toMatchObject({ bare: true, hasReason: false })
+  })
+
+  it('records the file-declaration form once, at the line it is written on', () => {
+    const src = `// theme-allow-file raw-hex — the whole palette fixture\nconst a = '#f00'\n`
+    expect(findAllowAnnotations(src, PATH, cfg)).toMatchObject([
+      { line: 1, scope: 'file', guardKinds: ['raw-hex'] },
+    ])
+  })
+
+  it('carries the source line verbatim, and finds nothing in a file with no annotation', () => {
+    expect(findAllowAnnotations(`const a = '#f00'\n`, PATH, cfg)).toEqual([])
+    expect(
+      findAllowAnnotations(`  // theme-allow raw-hex — why not\nconst a = 1\n`, PATH, cfg)[0]?.text,
+    ).toBe('  // theme-allow raw-hex — why not')
+  })
+
+  // It shares `collectAllowAnnotations` with `checkSource`, so it cannot list a line the scan does
+  // not honour — the mirrored regex `--audit-allows` carried was already one alternation behind.
+  it('agrees with checkSource about what is prose and what is an annotation', () => {
+    expect(
+      findAllowAnnotations(`// a theme-allow raw-hex goes here\nconst a = 1\n`, PATH, cfg),
+    ).toEqual([])
+    expect(
+      findAllowAnnotations(`/** theme-allow raw-hex — deliberate */\nconst a = 1\n`, PATH, cfg),
+    ).toHaveLength(1)
+  })
+
+  it('finds the JSON member form in a manifest', () => {
+    const src = `{\n  "basalt:theme-allow-file": "raw-hex — brand color"\n}\n`
+    expect(findAllowAnnotations(src, 'public/site.webmanifest', cfg)).toMatchObject([
+      { line: 2, scope: 'file', guardKinds: ['raw-hex'] },
+    ])
+  })
+})
+
+describe('neutralizeAllowAnnotation', () => {
+  const cfg = DEFAULT_GUARD_CONFIG
+
+  it('neutralizes ONE annotation and reveals exactly what it suppressed', () => {
+    const src = [
+      `const a = '#f00' // theme-allow raw-hex — first`,
+      `const b = '#0f0' // theme-allow raw-hex — second`,
+    ].join('\n')
+    expect(checkSource(src, PATH, cfg).filter((f) => f.kind === 'raw-hex')).toEqual([])
+
+    const probe = neutralizeAllowAnnotation(src, 1, cfg)
+    expect(probe).toContain(NEUTRALIZED_ALLOW_TOKEN)
+    expect(
+      checkSource(probe, PATH, cfg)
+        .filter((f) => f.kind === 'raw-hex')
+        .map((f) => f.line),
+    ).toEqual([1])
+  })
+
+  it('leaves a line with no token, and an out-of-range line, untouched', () => {
+    const src = `const a = 1\nconst b = 2\n`
+    expect(neutralizeAllowAnnotation(src, 1, cfg)).toBe(src)
+    expect(neutralizeAllowAnnotation(src, 99, cfg)).toBe(src)
+  })
+
+  it('the neutralized token shares no substring with the annotation it replaces', () => {
+    expect(NEUTRALIZED_ALLOW_TOKEN).not.toContain(cfg.allowComment)
+    expect(NEUTRALIZED_ALLOW_TOKEN.includes('theme-allow')).toBe(false)
+  })
+})
+
+describe('PLUGIN_RULE_IDS', () => {
+  it('names no guard kind — the two registries are disjoint by construction', () => {
+    for (const id of PLUGIN_RULE_IDS) expect(Object.hasOwn(GUARD_RULES, id)).toBe(false)
+  })
+})

package/src/guard/index.ts

@@ -400,7 +400,7 @@ 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*=/
 
 // Raw lowercase form-control element — line-scoped, same shape as RAW_VISX_AXIS. `\b` after the
@@ -661,8 +661,12 @@ export function unmatchedExemptPatterns(
  * but they ARE valid ids in a `theme-allow`, so an annotation scoped to one of them must parse as
  * accountable rather than be reported as unscoped. Kept as a literal list because the plugin is a
  * standalone `.js` file this module must not import (see the plugin's own header).
+ *
+ * Exported for `check-theme --audit-allows`: an annotation naming one of these is outside the
+ * guard's reach, and judging it needs a `oxlint` run rather than a `checkSource` one. Keep in step
+ * with the plugin's own `KNOWN_RULE_IDS`; `configs/oxlint-plugin.test.ts` asserts the two agree.
  */
-const PLUGIN_RULE_IDS: ReadonlySet<string> = new Set([
+export const PLUGIN_RULE_IDS: ReadonlySet<string> = new Set([
   'no-raw-font-size',
   'raw-size-literal',
   'card-inset',
@@ -767,8 +771,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.
@@ -784,6 +825,39 @@ const COMMENT_OPENER_BEFORE = /(?:\/\/|\/\*|<!--)\s*$/
 /** A line that is NOTHING but a comment — the placement that waives the line below it. */
 const COMMENT_ONLY_LINE = /^\s*(?:\{\s*\/\*|\/\/|\/\*|\*|<!--)/
 
+/**
+ * A JSX expression container closing immediately after the comment that filled it — the `*\/}` of a
+ * `{/* … *\/}` whose annotation wrapped onto its own line.
+ *
+ * `stripComments` blanks the comment and leaves the bare `}` behind, so the line read as CODE and
+ * the annotation was classified TRAILING — scoped to a line that holds nothing but a brace, and
+ * therefore waiving nothing. That is the shape linewatch writes for every hand-composed chart axis
+ * (`{/*` on one line, the annotation and `*\/}` on the next), which worked only because the rules it
+ * names live in the oxlint plugin, whose own placement test is comment-node-based and never saw the
+ * brace. Any guard kind annotated this way was silently unwaivable.
+ *
+ * Deliberately narrow: the `}` must abut the comment CLOSE. A `}` that is real code (`} // theme-
+ * allow …` closing a block) keeps its trailing classification, so the annotation stays on its own
+ * line rather than reaching the statement below.
+ */
+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.
@@ -795,9 +869,14 @@ const COMMENT_ONLY_LINE = /^\s*(?:\{\s*\/\*|\/\/|\/\*|\*|<!--)/
  * own waivers in a docblock and thereby disarmed the file — the third hole found in this contract
  * in two rounds, and the only one that was a false NEGATIVE.
  *
- * So an annotation must START its comment, or start a line inside one: after `//`, `/*`, `<!--`, a
- * block-comment gutter `*`, or nothing but leading whitespace. Everything a consumer actually
- * writes qualifies; a sentence about the escape hatch does not.
+ * So an annotation must START its comment, or start a line inside one: after `//`, `/*` (or a
+ * docblock's `/**`), `<!--`, a block-comment gutter `*`, or nothing but leading whitespace.
+ * Everything a consumer actually writes qualifies; a sentence about the escape hatch does not.
+ *
+ * `/**` is in the alternation because the oxlint plugin's copy of this test always accepted it and
+ * this one did not: a one-line `/** theme-allow raw-hex — why *\/` waived under `oxlint` and
+ * reported under `check-theme`. The two halves of one contract must not disagree about what an
+ * annotation IS — only about which rules each can judge.
  *
  * What the annotation then WAIVES is a separate, fail-closed question — see
  * {@link parseAllowAnnotation}. A word in the id slot that names no rule waives nothing, so
@@ -809,7 +888,7 @@ const COMMENT_ONLY_LINE = /^\s*(?:\{\s*\/\*|\/\/|\/\*|\*|<!--)/
  * it anyway: the kind that fires is the UNSUPPRESSED one (`raw-hex`), not `theme-allow-unscoped`,
  * and downgrading `raw-hex` to waive-by-default is the hole this closed.
  */
-const ANNOTATION_PREFIX = /(?:^|\/\/|\/\*|<!--|^\s*\*)\s*$/
+const ANNOTATION_PREFIX = /(?:^|\/\/|\/\*\*?|<!--|^\s*\*)\s*$/
 
 /** Escape a config-supplied string for literal use inside a RegExp. */
 function escapeRegExp(value: string): string {
@@ -907,7 +986,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)
@@ -915,16 +999,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
     }
@@ -942,12 +1030,17 @@ function collectAllowAnnotations(
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i] ?? ''
     const stripped = codeLines[i] ?? ''
-    const isCommentOnlyLine = stripped.trim() === '' || COMMENT_ONLY_LINE.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,
+        )
       }
     }
 
@@ -965,6 +1058,7 @@ function collectAllowAnnotations(
         i,
         parseAllowAnnotation(rest, m[1] === undefined ? 'line' : 'file'),
         !isCommentOnlyLine,
+        at,
       )
     }
   }
@@ -2050,3 +2144,98 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
       severity: severityOf(f.kind, cfg),
     }))
 }
+
+// ── Allow-annotation enumeration (check-theme --audit-allows) ─────────────────────────────────────
+
+/**
+ * One `theme-allow` annotation as WRITTEN, classified by whose reach its ids fall in.
+ *
+ * `guardKinds` is what `checkSource` can judge by re-running itself with the annotation
+ * neutralized. `pluginRules` is what only an `oxlint` run can judge. `unknownRules` names no rule
+ * at all. All three empty with `bare: true` is the legacy blanket form.
+ */
+export type AllowAnnotationSite = {
+  /** 1-based line the annotation is written on. */
+  readonly line: number
+  /** `'file'` for the `theme-allow-file` declaration form, `'line'` otherwise. */
+  readonly scope: 'line' | 'file'
+  /** Every id the annotation names that resolves to a real rule, `basalt/` prefix stripped. */
+  readonly rules: readonly string[]
+  /** The subset of `rules` `checkSource` owns. */
+  readonly guardKinds: readonly GuardKind[]
+  /** The subset of `rules` the oxlint plugin owns — outside `checkSource`'s reach. */
+  readonly pluginRules: readonly string[]
+  /** Words that occupied the id slot but name no rule. Their presence makes the parse fail closed. */
+  readonly unknownRules: readonly string[]
+  /** A written reason follows the ids. */
+  readonly hasReason: boolean
+  /** The legacy blanket form — no ids at all, known or unknown. Only covers anything at line scope. */
+  readonly bare: boolean
+  /** The source line, verbatim. */
+  readonly text: string
+}
+
+/**
+ * Every allow annotation in one file, with the ids it names classified by reach.
+ *
+ * Pure, and it shares `collectAllowAnnotations` with {@link checkSource} — so a caller enumerating
+ * annotations sees exactly the set the scan honours, rather than a second regex that can drift from
+ * it. `--audit-allows` carried such a mirror and it was already one alternation behind.
+ *
+ * A file-scoped declaration appears once, at the line it is written on.
+ *
+ * @example
+ * for (const site of findAllowAnnotations(text, rel, cfg)) {
+ *   if (site.pluginRules.length > 0) probeWithOxlint(neutralizeAllowAnnotation(text, site.line, cfg))
+ * }
+ */
+export function findAllowAnnotations(
+  text: string,
+  relPath: string,
+  cfg: GuardConfig,
+): AllowAnnotationSite[] {
+  const lines = text.split('\n')
+  const syntax = guardSyntaxFor(relPath)
+  const codeText = syntax === 'markup' ? stripMarkupComments(text) : stripComments(text, syntax)
+  const { declared } = collectAllowAnnotations(
+    lines,
+    codeText.split('\n'),
+    cfg.allowComment,
+    syntax,
+  )
+  return declared.map(({ line, annotation }) => ({
+    line,
+    scope: annotation.scope,
+    rules: [...annotation.rules],
+    guardKinds: annotation.rules.filter((id): id is GuardKind => Object.hasOwn(GUARD_RULES, id)),
+    pluginRules: annotation.rules.filter(
+      (id) => !Object.hasOwn(GUARD_RULES, id) && PLUGIN_RULE_IDS.has(id),
+    ),
+    unknownRules: [...annotation.unknownRules],
+    hasReason: annotation.hasReason,
+    bare: annotation.rules.length === 0 && annotation.unknownRules.length === 0,
+    text: lines[line - 1] ?? '',
+  }))
+}
+
+/** The token a neutralized annotation is rewritten to. Shares no substring with `theme-allow`. */
+export const NEUTRALIZED_ALLOW_TOKEN = 'basalt-audit-neutralized'
+
+/**
+ * `text` with the allow token on ONE (1-based) line rewritten to {@link NEUTRALIZED_ALLOW_TOKEN},
+ * leaving every other annotation intact.
+ *
+ * The probe half of an audit: re-scan the result and the findings that appear are exactly what that
+ * one annotation suppresses. Shipped rather than left to each caller so the guard probe and the
+ * oxlint probe neutralize identically — a `--audit-allows` verdict that differs between the two
+ * halves by a substitution detail is worse than no verdict.
+ *
+ * A line with no token comes back unchanged.
+ */
+export function neutralizeAllowAnnotation(text: string, line: number, cfg: GuardConfig): string {
+  const lines = text.split('\n')
+  const target = lines[line - 1]
+  if (target === undefined) return text
+  lines[line - 1] = target.replaceAll(cfg.allowComment, NEUTRALIZED_ALLOW_TOKEN)
+  return lines.join('\n')
+}