feat(260602-dv1): add ROZ123 refsPreMountValidator ($refs read before mount)

- Register REFS_READ_BEFORE_MOUNT: 'ROZ123' with doc-quality registry comment
- New refsPreMountValidator: flags $refs reads in $computed bodies, $watch
  getters, and template binding/interpolation/r-if/r-show/r-for-iterable exprs
- $watch-getter verdict EAGER (flagged): solid lowers the getter into
  createEffect(on(...)) whose deps-fn runs at setup before the ref is assigned
- Do-not-flag: lifecycle bodies, $watch callbacks, @event handlers, listeners,
  r-model targets, plain functions, top-level reads; nested defer via path.skip
- Wire into analyzeAST after runEmitNameValidator; never throws (D-08)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: serpentblade

packages/core/src/diagnostics/codes.ts

@@ -164,6 +164,38 @@ export const RozieErrorCode = {
   // SCOPE — no false positive. ROZ122 is the next free code after ROZ121 in the
   // 100 semantic-binding cluster.
   EMIT_EMPTY_EVENT_NAME: 'ROZ122', // $emit('') / $emit('   ') — empty/whitespace-only string-literal event name
+  // Quick 260602-dv1 — a `$refs.<member>` read in a PRE-MOUNT evaluation position.
+  // `$refs` are only populated AFTER the component mounts, so reading one in a
+  // position that is evaluated during setup/render is a silent cross-target
+  // divergence: on solid the eager memo / `$watch` effect reads `$refs` at setup
+  // (before the ref callback assigns the element) → TDZ crash / null; on lit and
+  // the other targets it simply yields null. This exact shape — `$computed(() =>
+  // [rangePlugin({ input: $refs.rangeEnd })])` — was falsified in debug session
+  // lit-rangeplugin-shadow-dom (the $computed crashed solid and silently no-op'd
+  // lit), and Dan blessed turning the divergence into a LOUD compile error.
+  //
+  // FLAGGED (the two pre-mount eval contexts), emitted by refsPreMountValidator:
+  //   - inside a `$computed(...)` argument body in <script>;
+  //   - inside the `$watch(getter, cb)` GETTER (argument[0]) in <script> — the
+  //     getter is EAGER on solid: it lowers to `createEffect(on(() => getter(),
+  //     …))`, whose deps-fn runs at setup BEFORE the `let elRef = null` ref
+  //     binding is assigned (empirically confirmed, 260602-dv1 probe), the same
+  //     hazard as a `$computed` body;
+  //   - inside a <template> binding (`:plugins="…"`), a `{{ }}` interpolation,
+  //     or an `r-if` / `r-show` / `r-for`-iterable expression (all render-time).
+  // DO-NOT-FLAG (all run post-mount when invoked): `$onMount`/`$onUnmount`/
+  // `$onUpdate` bodies; the `$watch` CALLBACK (argument[1]); `@event` handler
+  // expressions (`@click="$refs.x.focus()"`); `<listeners>` handlers; r-model
+  // targets; r-for LHS aliases (not a JS expr); and plain function/method bodies
+  // (and a `$refs` read at <script> Program top level — a separate concern, not
+  // this validator's).
+  // OUT OF SCOPE: computed `$refs['x']` is ROZ106's concern (detectMagicAccess
+  // returns null for it); non-`$refs` magic accessors are unaffected.
+  // Error severity; fires once per offending `$refs` read, code-framed at the
+  // read, naming the member. Never throws (D-08): all template re-parses are
+  // try/catch-wrapped. ROZ123 is the next free code after ROZ122 in the 100
+  // semantic-binding cluster.
+  REFS_READ_BEFORE_MOUNT: 'ROZ123', // $refs.x read in a $computed body / $watch getter / template binding|interpolation|r-if|r-show|r-for-iterable — evaluated before mount
 
   // ---- Compile-time correctness errors (Phase 2 Plan 02) — ROZ200..ROZ299 ----
   WRITE_TO_NON_MODEL_PROP: 'ROZ200', // SEM-02: $props.foo = … where foo lacks model: true (Phase 2 success criterion 2)

packages/core/src/semantic/analyze.ts

@@ -37,6 +37,7 @@ import { runReservedIdentifierValidator } from './validators/reservedIdentifierV
 import { runListenerElementValidator } from './validators/listenerElementValidator.js';
 import { runExposeValidator } from './validators/exposeValidator.js';
 import { runEmitNameValidator } from './validators/emitNameValidator.js';
+import { runRefsPreMountValidator } from './validators/refsPreMountValidator.js';
 
 export interface AnalyzeResult {
   bindings: BindingsTable;
@@ -65,6 +66,8 @@ export function analyzeAST(ast: RozieAST): AnalyzeResult {
   runExposeValidator(ast, bindings, diagnostics);
   // Quick 260601-l2u — ROZ122: reject empty/whitespace-only $emit event names (script + template + listeners). No binding dependency.
   runEmitNameValidator(ast, diagnostics);
+  // Quick 260602-dv1 — ROZ123: $refs read in a pre-mount eval position ($computed body / $watch getter / template binding/interpolation/r-if/r-show/r-for-iterable expr). No binding dependency.
+  runRefsPreMountValidator(ast, diagnostics);
   // Phase 19 (D-08) — final pass: a <listener> placed inside <template> is a
   // misplaced element (ROZ206). No binding dependency.
   runListenerElementValidator(ast, diagnostics);

packages/core/src/semantic/validators/refsPreMountValidator.ts

@@ -0,0 +1,325 @@
+/**
+ * SEM (Quick 260602-dv1) — `$refs`-read-before-mount validator (ROZ123).
+ *
+ * `$refs` are only populated AFTER the component mounts. Reading a `$refs.<x>`
+ * in a position that is evaluated DURING setup/render is a silent cross-target
+ * divergence — on solid the eager memo / `$watch` effect reads `$refs` at setup
+ * (before the ref callback assigns the element) → TDZ crash / null; on lit and
+ * the other targets it simply yields null. The debug session
+ * lit-rangeplugin-shadow-dom falsified the exact shape
+ * `$computed(() => [rangePlugin({ input: $refs.rangeEnd })])` (it crashed solid
+ * and silently no-op'd lit) and Dan blessed turning the divergence into a LOUD
+ * compile error.
+ *
+ * ── FLAGGED (the two pre-mount evaluation contexts) ──────────────────────────
+ *   <script>:
+ *     - inside a `$computed(...)` argument body;
+ *     - inside the `$watch(getter, cb)` GETTER (argument[0]).
+ *   <template>:
+ *     - kind === 'binding'   (`:plugins="…"`, `:disabled="…"`);
+ *     - kind === 'directive' for `if` / `show` / `text` / `html`;
+ *     - the ITERABLE (right-hand side) of an `r-for` (render-time);
+ *     - a `{{ ... }}` TemplateInterpolation.
+ *
+ * ── DO-NOT-FLAG (all run post-mount when invoked) ────────────────────────────
+ *     - `$onMount` / `$onUnmount` / `$onUpdate` callback bodies;
+ *     - the `$watch` CALLBACK (argument[1]);
+ *     - `@event` handler expressions (`@click="$refs.x.focus()"`);
+ *     - `<listeners>` handlers (this validator never walks <listeners>);
+ *     - `r-model` targets;
+ *     - the `r-for` LHS alias clause (`item in …` — not a JS expression);
+ *     - plain function / method bodies (called later, post-mount);
+ *     - a `$refs` read at <script> Program top level (a separate concern).
+ *
+ * ── $watch-GETTER VERDICT: EAGER → FLAGGED ───────────────────────────────────
+ * Empirically confirmed (260602-dv1 probe, compile(..., { target: 'solid' })):
+ * `$watch(() => $refs.el?.offsetWidth, cb)` lowers to
+ *   `createEffect(on(() => (() => elRef?.offsetWidth)(), …, { defer: true }));`
+ *   `let elRef: HTMLElement | null = null;`            // declared AFTER the effect
+ * `on`'s deps-function runs the getter at the effect's first run (setup time),
+ * BEFORE the ref callback assigns `elRef` — the same eager-read hazard as a
+ * `$computed` body (and a literal read-before-declaration of `elRef`). So the
+ * getter is FLAGGED. The CALLBACK (argument[1]) fires in response to a change
+ * (post-mount) and is ALWAYS do-not-flag.
+ *
+ * ── OUT OF SCOPE ─────────────────────────────────────────────────────────────
+ * Computed `$refs['x']` is ROZ106's concern (detectMagicAccess returns null for
+ * computed access). Non-`$refs` magic accessors are unaffected.
+ *
+ * ── Re-parse / byte-offset discipline ────────────────────────────────────────
+ * Template expression text is re-parsed via @babel/parser.parseExpression inside
+ * a try/catch (D-08: never throws — the parser layer already diagnosed malformed
+ * mustache/expression text). Every emitted diagnostic carries an absolute
+ * byte-offset loc: re-parsed fragments add the fragment's base offset (the
+ * attribute valueLoc.start, the interpolation loc.start + 2 to skip `{{`, or the
+ * r-for value offset + the iterable's position within the LHS string).
+ *
+ * This validator has NO bindings dependency.
+ *
+ * @experimental — shape may change before v1.0
+ */
+import * as t from '@babel/types';
+import _traverse from '@babel/traverse';
+import type { NodePath } from '@babel/traverse';
+import { parseExpression } from '@babel/parser';
+import type { RozieAST, SourceLoc } from '../../ast/types.js';
+import type { ScriptAST } from '../../ast/blocks/ScriptAST.js';
+import type {
+  TemplateAST,
+  TemplateNode,
+  TemplateElement,
+  TemplateAttr,
+} from '../../ast/blocks/TemplateAST.js';
+import type { Diagnostic } from '../../diagnostics/Diagnostic.js';
+import { RozieErrorCode } from '../../diagnostics/codes.js';
+import { detectMagicAccess } from '../visitors.js';
+
+// Default-export interop: see unknownRefValidator.ts for the same pattern.
+type TraverseFn = typeof import('@babel/traverse').default;
+const traverse: TraverseFn =
+  typeof _traverse === 'function'
+    ? _traverse
+    : (_traverse as unknown as { default: TraverseFn }).default;
+
+/** Callees whose callback argument runs post-mount — a `$refs` read inside one
+ *  is deferred and must NOT be flagged, even when nested inside a flagged
+ *  region (e.g. `$computed(() => { $onMount(() => use($refs.el)); … })`). */
+const DEFER_CALLEES = new Set(['$onMount', '$onUnmount', '$onUpdate']);
+
+interface ValidatorContext {
+  diagnostics: Diagnostic[];
+}
+
+/**
+ * Shift Babel-relative offsets (computed against the parsed expression
+ * fragment) into absolute offsets in the .rozie file by adding `baseOffset`.
+ */
+function locFromNodeOffset(node: t.Node, baseOffset: number): SourceLoc {
+  return {
+    start: (node.start ?? 0) + baseOffset,
+    end: (node.end ?? 0) + baseOffset,
+  };
+}
+
+/** A `$refs.<member>` static read (computed `$refs['x']` returns null → ROZ106). */
+function refsMember(node: t.Node): string | null {
+  if (!t.isMemberExpression(node)) return null;
+  const access = detectMagicAccess(node);
+  return access && access.scope === 'refs' ? access.member : null;
+}
+
+/** Emit ROZ123 for a `$refs.<refName>` read at `loc`. */
+function pushRefsPreMount(
+  ctx: ValidatorContext,
+  refName: string,
+  loc: SourceLoc,
+): void {
+  ctx.diagnostics.push({
+    code: RozieErrorCode.REFS_READ_BEFORE_MOUNT,
+    severity: 'error',
+    message: `$refs.${refName} is read before mount — $refs are only populated after the component mounts, but this position is evaluated during setup/render.`,
+    loc,
+    hint: 'Read $refs only inside $onMount (or another callback that runs after mount). $computed bodies, $watch getters, and template/binding expressions evaluate too early.',
+  });
+}
+
+// ── <script> walk ────────────────────────────────────────────────────────────
+
+/**
+ * Traverse a FLAGGED region (a `$computed` body or a `$watch` getter), pushing
+ * ROZ123 for every `$refs.<x>` read. Nested do-not-flag callbacks re-defer: when
+ * we hit a `$onMount`/`$onUnmount`/`$onUpdate(...)` call OR a `$watch(...)`
+ * callback (argument[1]), we `path.skip()` so its subtree is not flagged (a
+ * `$refs` read in there runs post-mount). Nested `$computed`/`$watch`-getter
+ * regions remain flagged (they re-enter via the same eager-eval contract). The
+ * base offset is 0 — `<script>` nodes carry absolute .rozie offsets.
+ */
+function flagRefsInRegion(region: t.Node, ctx: ValidatorContext): void {
+  const wrapped = t.file(
+    t.program([t.expressionStatement(region as t.Expression)]),
+  );
+  traverse(wrapped, {
+    CallExpression(path) {
+      const callee = path.node.callee;
+      if (!t.isIdentifier(callee)) return;
+      if (DEFER_CALLEES.has(callee.name)) {
+        // The whole call (its callback body) is deferred — do not flag inside.
+        path.skip();
+      } else if (callee.name === '$watch') {
+        // A nested $watch: its CALLBACK (arg[1]) is deferred, but its GETTER
+        // (arg[0]) is still eager and must remain flagged. Descend into the
+        // getter explicitly, then skip the rest of this call subtree.
+        const getter = path.node.arguments[0];
+        if (
+          getter &&
+          (t.isArrowFunctionExpression(getter) || t.isFunctionExpression(getter))
+        ) {
+          flagRefsInRegion(getter, ctx);
+        }
+        path.skip();
+      }
+    },
+    MemberExpression(path) {
+      const refName = refsMember(path.node);
+      if (refName !== null) {
+        pushRefsPreMount(ctx, refName, locFromNodeOffset(path.node, 0));
+      }
+    },
+  });
+}
+
+/**
+ * Walk the `<script>` Program for the pre-mount eval contexts. We scope the flag
+ * precisely with a CallExpression visitor: for each `$computed(fn)` descend into
+ * `fn` (arg[0]); for each `$watch(getterFn, cb)` descend into `getterFn`
+ * (arg[0]) ONLY (the getter is eager on solid — see the $watch-getter verdict
+ * above; the callback is deferred). Anything outside these regions — top-level
+ * reads, plain functions, lifecycle bodies — is never flagged.
+ */
+function validateScript(script: ScriptAST, ctx: ValidatorContext): void {
+  traverse(script.program, {
+    CallExpression(path) {
+      const callee = path.node.callee;
+      if (!t.isIdentifier(callee)) return;
+      if (callee.name === '$computed') {
+        const body = path.node.arguments[0];
+        if (
+          body &&
+          (t.isArrowFunctionExpression(body) || t.isFunctionExpression(body))
+        ) {
+          flagRefsInRegion(body, ctx);
+        }
+      } else if (callee.name === '$watch') {
+        const getter = path.node.arguments[0];
+        if (
+          getter &&
+          (t.isArrowFunctionExpression(getter) || t.isFunctionExpression(getter))
+        ) {
+          flagRefsInRegion(getter, ctx);
+        }
+      }
+    },
+  });
+}
+
+// ── <template> walk ──────────────────────────────────────────────────────────
+
+/**
+ * Re-parse a template-expression fragment and flag `$refs` reads. Returns
+ * silently on parse failure (parser layer already diagnosed it). NEVER throws.
+ */
+function parseAndFlag(text: string, baseOffset: number, ctx: ValidatorContext): void {
+  let expr: t.Expression;
+  try {
+    expr = parseExpression(text, { sourceType: 'module' });
+  } catch {
+    return; // malformed — parser-layer diagnostics cover it; stay silent (D-08).
+  }
+  const wrapped = t.file(t.program([t.expressionStatement(expr)]));
+  traverse(wrapped, {
+    MemberExpression(path) {
+      const refName = refsMember(path.node);
+      if (refName !== null) {
+        pushRefsPreMount(ctx, refName, locFromNodeOffset(path.node, baseOffset));
+      }
+    },
+  });
+}
+
+// `(item, idx) in iterable` / `item of iterable` — find the keyword split so we
+// can re-parse ONLY the iterable RHS (render-time) and skip the alias LHS (not a
+// JS expression). Linear-time, bounded; mirrors extractRForAliases's posture.
+const R_FOR_KEYWORD = /\s+(?:in|of)\s+/;
+
+/**
+ * Flag `$refs` reads inside an `r-for` ITERABLE (the RHS of `… in iterable`).
+ * The LHS alias clause is intentionally NOT parsed (it is `item` / `(item, idx)`
+ * binding syntax, not a JS expression). baseOffset is the attribute
+ * valueLoc.start plus the byte offset of the iterable within the raw value.
+ */
+function validateRForIterable(attr: TemplateAttr, ctx: ValidatorContext): void {
+  if (attr.value === null || attr.valueLoc === null) return;
+  const m = R_FOR_KEYWORD.exec(attr.value);
+  if (!m || m.index === undefined) return; // malformed r-for — rForKeyValidator owns it.
+  const iterableStart = m.index + m[0].length;
+  const iterable = attr.value.slice(iterableStart);
+  parseAndFlag(iterable, attr.valueLoc.start + iterableStart, ctx);
+}
+
+/**
+ * Walk a TemplateAttr's expression value for the render-time positions only.
+ * SKIP `event` (handlers run on user action, post-mount), `r-model` (binding
+ * target), and `static`. FLAG `binding` and `directive` `if`/`show`/`text`/
+ * `html`; the `r-for` iterable RHS is flagged via validateRForIterable.
+ */
+function validateTemplateAttr(attr: TemplateAttr, ctx: ValidatorContext): void {
+  if (attr.value === null || attr.valueLoc === null) return;
+  if (attr.kind === 'event') return; // @click etc. — post-mount.
+  if (attr.kind === 'binding') {
+    parseAndFlag(attr.value, attr.valueLoc.start, ctx);
+    return;
+  }
+  if (attr.kind === 'directive') {
+    if (attr.name === 'for') {
+      validateRForIterable(attr, ctx);
+      return;
+    }
+    if (attr.name === 'model') return; // r-model target — do-not-flag.
+    if (
+      attr.name === 'if' ||
+      attr.name === 'show' ||
+      attr.name === 'text' ||
+      attr.name === 'html'
+    ) {
+      parseAndFlag(attr.value, attr.valueLoc.start, ctx);
+    }
+    // Other directives (e.g. r-key) are not pre-mount eval positions for $refs.
+  }
+}
+
+function isElement(node: TemplateNode): node is TemplateElement {
+  return node.type === 'TemplateElement';
+}
+
+function isInterpolation(
+  node: TemplateNode,
+): node is { type: 'TemplateInterpolation'; rawExpr: string; loc: SourceLoc } {
+  return node.type === 'TemplateInterpolation';
+}
+
+function visitTemplateNode(node: TemplateNode, ctx: ValidatorContext): void {
+  if (isInterpolation(node)) {
+    // {{ ... }} — baseOffset = loc.start + 2 (skipping `{{`).
+    parseAndFlag(node.rawExpr, node.loc.start + 2, ctx);
+    return;
+  }
+  if (!isElement(node)) return;
+  for (const attr of node.attributes) {
+    validateTemplateAttr(attr, ctx);
+  }
+  for (const child of node.children) {
+    visitTemplateNode(child, ctx);
+  }
+}
+
+function validateTemplate(template: TemplateAST, ctx: ValidatorContext): void {
+  for (const child of template.children) {
+    visitTemplateNode(child, ctx);
+  }
+}
+
+/**
+ * Run the `$refs`-read-before-mount validator over the given AST. Emits ROZ123
+ * into `diagnostics`. NEVER throws (D-08). No bindings dependency.
+ *
+ * Note: <listeners> is intentionally NOT walked — listener handlers run
+ * post-mount (do-not-flag).
+ */
+export function runRefsPreMountValidator(
+  ast: RozieAST,
+  diagnostics: Diagnostic[],
+): void {
+  const ctx: ValidatorContext = { diagnostics };
+  if (ast.script) validateScript(ast.script, ctx);
+  if (ast.template) validateTemplate(ast.template, ctx);
+}