@pyreon/compiler 0.18.0 → 0.20.0

package/src/tests/collapse-key-source-hygiene.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Compiler hardening — Round 1.
+ *
+ * Two locked invariants, one root cause.
+ *
+ * `rocketstyleCollapseKey` (jsx.ts) and its Vite-plugin twin used to embed
+ * RAW C0 control bytes (NUL 0x00 / SOH 0x01) directly inside source string
+ * literals as FNV-1a field separators. Three measured consequences:
+ *
+ *   1. BSD `file(1)` classifies the file as binary `data` (siblings with no
+ *      raw C0 are correctly "UTF-8 text").
+ *   2. Plain `grep`/`rg` silently skip the file (binary-skip) — the
+ *      compiler's primary source became un-greppable.
+ *   3. Silent-correctness fragility: a raw NUL/SOH in a `.ts` string literal
+ *      is mutable by formatters / editors / copy-paste / git text filters.
+ *      If the separator byte is altered, the cache key changes with ZERO
+ *      compile error — the "cache key from raw input" anti-pattern family.
+ *
+ * Fix: escape sequences (`U+0001` SOH / `U+0000` NUL) — byte-identical at runtime
+ * (`String.fromCharCode(1)` is identical to the raw byte), so every emitted key is unchanged, but
+ * the source is plain UTF-8 text again.
+ *
+ * Test A pins the ground-truth keys (proves the fix is byte-identical AND
+ * locks the algorithm against any future change). Test B is the
+ * self-discriminating repo-wide regression gate: before the fix three files
+ * carry raw C0 → it fails; after → it passes. Bisect-verified.
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { rocketstyleCollapseKey } from '../jsx'
+
+describe('rocketstyleCollapseKey — ground-truth key lock (escape fix is byte-identical)', () => {
+  // Captured from the ORIGINAL raw-byte implementation before the escape fix.
+  // The escape fix MUST reproduce these exactly (proves zero behavior change);
+  // any future algorithm change is also caught here.
+  it('emits the exact pre-fix keys', () => {
+    expect(rocketstyleCollapseKey('Button', { state: 'primary', size: 'lg' }, 'Click')).toBe('zfm01z')
+    expect(rocketstyleCollapseKey('Card', {}, '')).toBe('mzrimv')
+    expect(rocketstyleCollapseKey('Comp', { a: '1' }, '')).toBe('1l6zbih')
+    expect(rocketstyleCollapseKey('Comp', {}, 'a=1')).toBe('zteym7')
+    expect(rocketstyleCollapseKey('日本', { 'aria-label': 'café' }, 'arrow ok')).toBe('vnvy01')
+  })
+
+  it('is order-independent over props (sort) and shape-distinct (separators do their job)', () => {
+    expect(rocketstyleCollapseKey('Button', { state: 'primary', size: 'lg' }, 'Click')).toBe(
+      rocketstyleCollapseKey('Button', { size: 'lg', state: 'primary' }, 'Click'),
+    )
+    // Without NUL field separators, `{a:'1'},''` and `{},'a=1'` would collide.
+    expect(rocketstyleCollapseKey('Comp', { a: '1' }, '')).not.toBe(
+      rocketstyleCollapseKey('Comp', {}, 'a=1'),
+    )
+  })
+})
+
+function repoRoot(): string {
+  let d = resolve(__dirname)
+  while (!existsSync(join(d, '.git')) && dirname(d) !== d) d = dirname(d)
+  return d
+}
+
+describe('source hygiene — no raw C0/DEL control bytes in tracked source', () => {
+  it('every tracked .ts/.tsx/.js/.mjs/.rs file is plain text (no raw NUL/SOH/ESC/DEL)', () => {
+    const root = repoRoot()
+    const files = execFileSync(
+      'git',
+      ['ls-files', '*.ts', '*.tsx', '*.js', '*.mjs', '*.rs'],
+      { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 },
+    )
+      .split('\n')
+      .filter(Boolean)
+
+    const offenders: string[] = []
+    for (const rel of files) {
+      const buf = readFileSync(join(root, rel))
+      for (let i = 0; i < buf.length; i++) {
+        const b = buf[i]!
+        // Allow only tab (9), LF (10), CR (13); flag all other C0 + DEL (127).
+        if ((b < 32 && b !== 9 && b !== 10 && b !== 13) || b === 127) {
+          offenders.push(`${rel} (byte 0x${b.toString(16).padStart(2, '0')} at offset ${i})`)
+          break
+        }
+      }
+    }
+    expect(offenders, `raw control bytes in source — escape them (\\u00NN):\n${offenders.join('\n')}`).toEqual([])
+  })
+})

package/src/tests/defer-inline.test.ts

@@ -121,22 +121,10 @@ export function App() {
 }
 `
     const result = transformDeferInline(input, 'app.tsx')
-    // No transform fires (multi-child shape doesn't match the inline-eligible
-    // single-component-child pattern). No warning either — v1 just leaves it
-    // alone; downstream Defer's runtime behaviour handles the malformed shape.
-    expect(result.changed).toBe(false)
-  })
-
-  test('skips Defer whose child has props (multi-prop closure capture)', () => {
-    const input = `
-import { Defer } from '@pyreon/core'
-import { Modal } from './Modal'
-export function App() {
-  return <Defer when={() => true}><Modal title="hi" /></Defer>
-}
-`
-    const result = transformDeferInline(input, 'app.tsx')
+    // v2 now emits a `multiple-children` warning so the author knows to use
+    // the explicit `chunk` form. v1 was silent — that was a footgun.
     expect(result.changed).toBe(false)
+    expect(result.warnings[0]?.code).toBe('defer-inline/multiple-children')
   })
 
   test('fast-path: no Defer in source returns unchanged', () => {
@@ -157,7 +145,74 @@ export const count = signal(0)
     expect(result.code).toBe(input)
   })
 
-  test('skips renamed imports — { Modal as M } not handled in v1', () => {
+  // v1 bailed on `{ Modal as M }`. v2 handles renamed imports — the
+  // local name in JSX is `M`, but the chunk extracts `__m.Modal` (the
+  // original exported name). See the positive test in the v2 section.
+})
+
+describe('transformDeferInline — v2 capabilities', () => {
+  test('preserves props on inline child', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import { Modal } from './Modal'
+export function App() {
+  return <Defer when={() => true}><Modal title="Confirm" size="md" /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    expect(result.code).not.toContain("import { Modal }")
+    // Props pass through verbatim. Only the component name is replaced.
+    expect(result.code).toContain('{(__C) => <__C title="Confirm" size="md" />}')
+  })
+
+  test('preserves nested children on inline child (non-self-closing)', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import { Modal } from './Modal'
+export function App() {
+  return (
+    <Defer when={() => true}>
+      <Modal title="Hello">
+        <p>nested content</p>
+      </Modal>
+    </Defer>
+  )
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    // Both opening AND closing tag names replaced with __C; nested JSX intact.
+    expect(result.code).toContain('<__C title="Hello">')
+    expect(result.code).toContain('</__C>')
+    expect(result.code).toContain('<p>nested content</p>')
+  })
+
+  test('captures closure variables via render-prop scope (signal in handler)', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import { signal } from '@pyreon/reactivity'
+import { Modal } from './Modal'
+
+export function App() {
+  const open = signal(false)
+  const count = signal(0)
+  return (
+    <Defer when={open}>
+      <Modal count={count} onClose={() => open.set(false)} />
+    </Defer>
+  )
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    // The render-prop arrow naturally captures `count` + `open.set` from
+    // the App function's scope — no closure-tracking pass needed, JS
+    // lexical scope just works.
+    expect(result.code).toContain('<__C count={count} onClose={() => open.set(false)} />')
+  })
+
+  test('handles renamed imports — { Modal as M }', () => {
     const input = `
 import { Defer } from '@pyreon/core'
 import { Modal as M } from './Modal'
@@ -166,11 +221,32 @@ export function App() {
 }
 `
     const result = transformDeferInline(input, 'app.tsx')
-    expect(result.changed).toBe(false)
-    // Renamed-import case is not yet supported — falls through to the
-    // import-not-found warning (no specifier whose `local.name === 'M'`
-    // AND `imported.name === local.name` matches).
-    expect(result.warnings[0]?.code).toBe('defer-inline/import-not-found')
+    expect(result.changed).toBe(true)
+    // Local name `M` is used at the JSX site, but the chunk extracts
+    // `__m.Modal` (the original exported name from './Modal').
+    expect(result.code).toContain(`chunk={() => import('./Modal').then((__m) => ({ default: __m.Modal }))}`)
+    expect(result.code).not.toContain("import { Modal as M }")
+    expect(result.code).toContain('{(__C) => <__C />}')
+  })
+
+  test('multi-specifier import: drops only the Defer-targeted binding', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import { Modal, OtherThing } from './shared'
+export function App() {
+  const use = OtherThing
+  return <Defer when={() => true}><Modal /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    // OtherThing is referenced elsewhere — its import must survive.
+    expect(result.code).toContain("OtherThing")
+    expect(result.code).toMatch(/import \{\s*OtherThing\s*\} from '\.\/shared'/)
+    // Modal binding is gone from the import declaration.
+    expect(result.code).not.toMatch(/import \{[^}]*\bModal\b[^}]*\}/)
+    // ...but the dynamic chunk pulls Modal from './shared' (same source).
+    expect(result.code).toContain(`chunk={() => import('./shared').then((__m) => ({ default: __m.Modal }))}`)
   })
 })
 
@@ -197,3 +273,115 @@ export function App() {
     expect(result.code).toContain(`chunk={() => import('./Comments').then((__m) => ({ default: __m.Comments }))}`)
   })
 })
+
+// Gap 4 from the v2 follow-up roadmap. Namespace imports were the last
+// inline-Defer shape that fell back to the explicit form — closing this
+// gap means EVERY common import shape is supported by the inline form.
+describe('transformDeferInline — namespace imports (v3)', () => {
+  test('rewrites <M.Modal /> with namespace import — chunk extracts __m.Modal', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import * as M from './Modal'
+export function App() {
+  return <Defer when={() => true}><M.Modal /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    expect(result.code).toContain(`chunk={() => import('./Modal').then((__m) => ({ default: __m.Modal }))}`)
+    // M.Modal in the JSX replaced with __C (the whole member expression
+    // is the "name" range that gets substituted).
+    expect(result.code).toContain('{(__C) => <__C />}')
+    expect(result.code).not.toContain('import * as M from')
+  })
+
+  test('rewrites with props on member-expression child', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import * as M from './Modal'
+export function App() {
+  return <Defer when={() => true}><M.Modal title="hi" /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    expect(result.code).toContain('{(__C) => <__C title="hi" />}')
+  })
+
+  test('non-self-closing member-expression child preserves opening + closing replacement', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import * as M from './Modal'
+export function App() {
+  return <Defer when={() => true}><M.Modal title="hi"><span>body</span></M.Modal></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    expect(result.code).toContain('{(__C) => <__C title="hi"><span>body</span></__C>}')
+  })
+
+  test('bails when namespace is referenced elsewhere in the file', () => {
+    // `M` is used for multiple components. Removing the static import
+    // would break the other usage AND the dynamic import becomes a
+    // no-op (Rolldown bundles the module statically when ANY part is
+    // referenced).
+    const input = `
+import { Defer } from '@pyreon/core'
+import * as M from './Modal'
+export function App() {
+  void M.Settings
+  return <Defer when={() => true}><M.Modal /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(false)
+    expect(result.warnings).toHaveLength(1)
+    expect(result.warnings[0]!.code).toBe('defer-inline/import-used-elsewhere')
+  })
+
+  test('bails on deeper member expression — <M.Sub.X /> not supported', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import * as M from './Modal'
+export function App() {
+  return <Defer when={() => true}><M.Sub.Modal /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    // analyzeChildElement returns null for non-depth-1 member
+    // expressions → no match in findDeferMatches → no warning. The
+    // Defer is left alone; runtime errors with "missing chunk".
+    expect(result.changed).toBe(false)
+  })
+
+  test('bails when member property is lowercase — <M.helper /> is not a component', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import * as M from './lib'
+export function App() {
+  return <Defer when={() => true}><M.helper /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(false)
+  })
+
+  test('bails when member expression but import is default (not namespace)', () => {
+    // `import M from './X'` (default) followed by `<M.Modal />` is a
+    // member access on the default-exported component itself, not a
+    // namespace lookup. Different semantics; out of scope. Compiler
+    // emits `unsupported-import-shape` so the author knows why.
+    const input = `
+import { Defer } from '@pyreon/core'
+import M from './Modal'
+export function App() {
+  return <Defer when={() => true}><M.Modal /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(false)
+    expect(result.warnings).toHaveLength(1)
+    expect(result.warnings[0]!.code).toBe('defer-inline/unsupported-import-shape')
+  })
+})

package/src/tests/detector-tag-consistency.test.ts

@@ -30,6 +30,7 @@ const COMPILER_CODES = [
   'for-missing-by',
   'for-with-key',
   'props-destructured',
+  'props-destructured-body',
   'process-dev-gate',
   'empty-theme',
   'raw-add-event-listener',
@@ -40,6 +41,7 @@ const COMPILER_CODES = [
   'static-return-null-conditional',
   'as-unknown-as-vnodechild',
   'island-never-with-registry-entry',
+  'query-options-as-function',
 ] as const
 type CompilerCode = (typeof COMPILER_CODES)[number]
 

package/src/tests/element-valued-const-child.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Compiler hardening — Round 9 (REAL bug, FIXED + bisect-verified).
+ *
+ *   const header = <h1>T</h1>
+ *   return <div>{header}<p>x</p></div>
+ *
+ * Pre-fix the compiler lowered the const to `_tpl(...)` (so it KNEW `header`
+ * was a `NativeItem` element) yet still emitted
+ * `document.createTextNode(header)` for the `{header}` child — `createTextNode`
+ * string-coerces the NativeItem → "[object Object]" instead of the `<h1>`.
+ * Only `props.children` / `own.children` reached the correct `_mountSlot`.
+ *
+ * Fix (jsx.ts): an `elementVars` set tracks `const`/`let` bindings whose
+ * initializer is a JSX element/fragment (optionally parenthesized); a bare
+ * `{el}` child of such a binding routes through `_mountSlot` — the same
+ * general child-insert `props.children` uses. Tight by construction: only a
+ * DIRECT JSX initializer reclassifies, so string/number/prop-derived/inline-
+ * hoisted children keep their existing (correct) paths. Routing is safe even
+ * under later same-name shadowing — `_mountSlot` renders strings/numbers
+ * correctly too; the only cost of imprecision is skipping the text fast path.
+ *
+ * NOT contradicted by `jsx.test.ts:777` `createTextNode(label)` — that pins
+ * the FREE undeclared identifier default (genuinely ambiguous); this fix only
+ * fires when the binding's initializer is provably JSX.
+ *
+ * Bisect: revert the `isElementValuedIdent` clause in `processOneChild`
+ * (jsx.ts) → the CONTRACT specs fail (emit reverts to `createTextNode(header)`)
+ * while every CONTROL spec stays green (proving the fix doesn't touch the
+ * text/reactive fast paths). Restore → all pass.
+ */
+import { describe, expect, it } from 'vitest'
+import { transformJSX_JS } from '../jsx'
+
+const emit = (c: string): string => transformJSX_JS(c, 'c.tsx').code ?? ''
+const ELEMENT_CONST = `function C(){ const header = <h1>T</h1>; return <div>{header}<p>x</p></div> }`
+
+describe('Round 9 — element-valued const used as a bare JSX child', () => {
+  it('CONTROL: string/number const child still uses the correct text fast path', () => {
+    expect(emit(`function C(){ const t = 'T'; return <div>{t}<p>x</p></div> }`)).toContain('createTextNode(t)')
+    expect(emit(`function C(){ const n = 5; return <div>{n}</div> }`)).toContain('textContent = n')
+  })
+
+  it('CONTROL: an INLINE element child is correctly hoisted (not text-coerced)', () => {
+    const out = emit(`function C(){ return <div>{<h1>T</h1>}<p>x</p></div> }`)
+    expect(out).toMatch(/const _\$h\d+ =/)
+    expect(out).not.toMatch(/createTextNode\(_\$h\d+\)/)
+  })
+
+  it('CONTRACT: element-valued const child is mounted via _mountSlot, not text-coerced', () => {
+    const out = emit(ELEMENT_CONST)
+    expect(out).toContain('const header = _tpl("<h1>T</h1>"')
+    expect(out).not.toContain('createTextNode(header)')
+    expect(out).toMatch(/_mountSlot\(\s*header\b/)
+  })
+
+  it('CONTRACT: single bare element-const child, parenthesized init, and let all mount', () => {
+    expect(emit(`function C(){ const el = <span>hi</span>; return <div>{el}</div> }`)).toMatch(/_mountSlot\(\s*el\b/)
+    expect(emit(`function C(){ const el = (<b>x</b>); return <div>{el}</div> }`)).toMatch(/_mountSlot\(\s*el\b/)
+    expect(emit(`function C(){ let el = <a/>; return <div>{el}</div> }`)).toMatch(/_mountSlot\(\s*el\b/)
+  })
+})

package/src/tests/falsy-child-characterization.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Compiler hardening — Round 3 (characterization, NOT a bug fix).
+ *
+ * Investigated: how the JSX transform emits falsy / boolean / null literal
+ * children vs the JSX rendering contract (`true`/`false`/`null`/`undefined`
+ * render nothing; `0` renders "0"; `''` renders empty).
+ *
+ * Finding: the patterns real code actually writes are CORRECT — a conditional
+ * (`{c ? x : null}`) or short-circuit (`{c && <X/>}`) child is wrapped in a
+ * `() =>` accessor and the null/boolean is filtered by runtime `mountChild`,
+ * so nothing renders (Pyreon's documented `VNodeChildAtom` `&&` contract
+ * holds). Only a CONTRIVED bare literal child (`<div>{false}</div>` — never
+ * written in practice) takes the static path and emits `textContent = false`
+ * → the DOM stringifies to "false". This is a spec divergence on input no one
+ * writes; fixing it would touch the hot child-emission path for zero
+ * real-world benefit, so the behavior is pinned here instead (any future
+ * change to it must be deliberate, and this test will flag it).
+ */
+import { describe, expect, it } from 'vitest'
+import { transformJSX_JS } from '../jsx'
+
+const emit = (c: string): string => transformJSX_JS(c, 'c.tsx').code ?? ''
+
+describe('Round 3 — conditional/short-circuit children are accessor-wrapped (the contract that matters)', () => {
+  it('ternary with a null branch is wrapped in an accessor (runtime filters null)', () => {
+    const out = emit(`function C(p){ return <div>{p.cond ? <a/> : null}</div> }`)
+    expect(out).toContain('() => p.cond ? <a/> : null')
+    expect(out).not.toContain('createTextNode(null)')
+  })
+
+  it('&& short-circuit is wrapped in an accessor (the documented && pattern)', () => {
+    const out = emit(`function C(p){ return <div>{p.show && <b/>}</div> }`)
+    expect(out).toContain('() => p.show && <b/>')
+    expect(out).not.toContain('createTextNode(false)')
+  })
+})
+
+describe('Round 3 — bare literal falsy children: pinned current behavior (contrived input)', () => {
+  it('numeric 0 child renders "0" (JSX-correct)', () => {
+    expect(emit(`function C(){ return <div>{0}</div> }`)).toContain('__root.textContent = 0')
+  })
+
+  // Pinned divergence: a bare `{false}` literal stringifies via textContent.
+  // Documented, not fixed — see file header for the rationale.
+  it('bare {false} literal takes the static textContent path (known, contrived)', () => {
+    expect(emit(`function C(){ return <div>{false}</div> }`)).toContain('__root.textContent = false')
+  })
+})

package/src/tests/malformed-input-resilience.test.ts

@@ -0,0 +1,50 @@
+/**
+ * Compiler hardening — Round 10 (resilience gate; no bug found).
+ *
+ * `transformJSX` runs per-file inside the Vite dev server; a throw on
+ * malformed input crashes the dev server (the documented contract is "a Rust
+ * panic / parse error must not crash Vite — fall back gracefully"). Probed 15
+ * adversarial inputs (unclosed/mismatched tags, stray brace, invalid attr,
+ * unterminated string, 500-deep nesting, BOM, raw control bytes, empty,
+ * comment-only, JSX in type position) through BOTH backends — all returned a
+ * `{ code: string }` result without throwing. This locks that resilience so a
+ * future change can't regress the compiler into throwing on bad input.
+ */
+import { describe, expect, it } from 'vitest'
+import { transformJSX, transformJSX_JS } from '../jsx'
+
+const INPUTS: Array<[string, string]> = [
+  ['unclosed-tag', `function C(){ return <div>oops }`],
+  ['mismatched-tags', `function C(){ return <div></span> }`],
+  ['invalid-attr', `function C(){ return <div class=></div> }`],
+  ['stray-brace', `function C(){ return <div>{</div> }`],
+  ['empty', ``],
+  ['whitespace-only', `   \n  `],
+  ['non-jsx-ts', `const x: number = 1; export function f(){ return x }`],
+  ['deeply-unbalanced', `function C(){ return <a><b><c></a> }`],
+  ['unterminated-string-attr', `function C(){ return <div title="abc>x</div> }`],
+  ['huge-nesting-500', `function C(){ return ${'<a>'.repeat(500)}x${'</a>'.repeat(500)} }`],
+  ['bom-prefixed', `function C(){ return <div>ok</div> }`],
+  ['comment-only', `// just a comment`],
+  ['fragment-unclosed', `function C(){ return <>x }`],
+  ['raw-control-garbage', String.fromCharCode(0, 1) + ' not code <div'],
+]
+
+describe('Round 10 — transform never throws on malformed input (Vite-dev-server resilience)', () => {
+  for (const [name, src] of INPUTS) {
+    it(`JS backend tolerates: ${name}`, () => {
+      let res: { code?: unknown } | undefined
+      expect(() => {
+        res = transformJSX_JS(src, 'c.tsx')
+      }).not.toThrow()
+      expect(typeof res?.code).toBe('string')
+    })
+    it(`native backend tolerates: ${name}`, () => {
+      let res: { code?: unknown } | undefined
+      expect(() => {
+        res = transformJSX(src, 'c.tsx')
+      }).not.toThrow()
+      expect(typeof res?.code).toBe('string')
+    })
+  }
+})

package/src/tests/manifest-snapshot.test.ts

@@ -0,0 +1,55 @@
+import {
+  renderApiReferenceEntries,
+  renderLlmsFullSection,
+  renderLlmsTxtLine,
+} from '@pyreon/manifest'
+import manifest from '../manifest'
+
+describe('gen-docs — compiler snapshot', () => {
+  it('renders a llms.txt bullet starting with the package prefix', () => {
+    const line = renderLlmsTxtLine(manifest)
+    expect(line.startsWith('- @pyreon/compiler —')).toBe(true)
+  })
+
+  it('renders a llms-full.txt section with the right header', () => {
+    const section = renderLlmsFullSection(manifest)
+    expect(section.startsWith('## @pyreon/compiler —')).toBe(true)
+    expect(section).toContain('```typescript')
+  })
+
+  it('renders MCP api-reference entries for every api[] item', () => {
+    const record = renderApiReferenceEntries(manifest)
+    expect(Object.keys(record).sort()).toEqual([
+      'compiler/analyzeReactivity',
+      'compiler/auditIslands',
+      'compiler/auditSsg',
+      'compiler/auditTestEnvironment',
+      'compiler/detectPyreonPatterns',
+      'compiler/detectReactPatterns',
+      'compiler/diagnoseError',
+      'compiler/formatIslandAudit',
+      'compiler/formatReactivityLens',
+      'compiler/formatSsgAudit',
+      'compiler/formatTestAudit',
+      'compiler/generateContext',
+      'compiler/hasPyreonPatterns',
+      'compiler/hasReactPatterns',
+      'compiler/migrateReactCode',
+      'compiler/transformDeferInline',
+      'compiler/transformJSX',
+      'compiler/transformJSX_JS',
+    ])
+  })
+
+  it('flags the experimental Reactivity-Lens entries', () => {
+    const r = renderApiReferenceEntries(manifest)
+    expect(r['compiler/analyzeReactivity']?.notes).toContain('[EXPERIMENTAL]')
+    expect(r['compiler/formatReactivityLens']?.notes).toContain('[EXPERIMENTAL]')
+  })
+
+  it('carries the foot-gun catalog into MCP mistakes for flagship APIs', () => {
+    const r = renderApiReferenceEntries(manifest)
+    expect(r['compiler/transformJSX']?.mistakes).toBeTruthy()
+    expect(r['compiler/detectPyreonPatterns']?.mistakes).toContain('fixable')
+  })
+})