@rozie/babel-plugin 0.1.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@rozie/babel-plugin",
+  "version": "0.1.0",
+  "description": "Babel plugin for Rozie.js — resolves .rozie imports and compiles them to idiomatic target-framework code.",
+  "type": "module",
+  "private": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts"
+  ],
+  "dependencies": {
+    "@babel/helper-plugin-utils": "^7.28.0",
+    "@rozie/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@babel/core": "^7.29.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.0",
+    "@babel/types": "^7.29.0",
+    "@types/babel__core": "^7.20.0",
+    "@types/babel__helper-plugin-utils": "^7.10.3",
+    "tsdown": "^0.21.10",
+    "vitest": "^4.1.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/One-Learning-Community/rozie.js.git",
+    "directory": "packages/babel-plugin"
+  },
+  "homepage": "https://github.com/One-Learning-Community/rozie.js#readme",
+  "bugs": {
+    "url": "https://github.com/One-Learning-Community/rozie.js/issues"
+  },
+  "author": "One Learning Community (https://github.com/One-Learning-Community)",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run --passWithNoTests",
+    "lint": "biome lint src",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/compileImport.ts

@@ -0,0 +1,22 @@
+// compileImport — thin indirection between the visitor in index.ts and
+// the fs-side writeSibling helper. Per CONTEXT.md recommended structure,
+// this layer exists so future cache strategies (content-hash sidecar v2,
+// in-memory LRU) can land without touching the visitor file or the
+// fs primitives. v1 is a one-liner.
+import { writeSiblingIfStale, type RozieBabelTarget } from './writeSibling.js';
+
+/**
+ * Read the .rozie at `roziePath`, compile it for `target`, and write the
+ * sibling `siblingPath` (plus React sidecars when applicable). Idempotent
+ * via mtime check. Errors are bubbled up unchanged for the visitor to
+ * re-shape into a Babel error via `path.buildCodeFrameError`.
+ */
+export function compileImport(
+  roziePath: string,
+  siblingPath: string,
+  target: RozieBabelTarget,
+  // Phase 23 — Angular CVA opt-out forwarded to writeSiblingIfStale → compile().
+  cva?: boolean,
+): void {
+  writeSiblingIfStale(roziePath, siblingPath, target, cva);
+}

package/src/index.ts

@@ -0,0 +1,114 @@
+// @rozie/babel-plugin — Phase 6 Plan 04 / D-92 ImportDeclaration visitor.
+//
+// Replaces the Phase 1 placeholder with a thin Babel plugin that:
+//   1. Visits each `import Foo from './Foo.rozie'` declaration.
+//   2. Resolves the absolute .rozie path via the importer's `state.filename`.
+//   3. Calls compileImport() → writeSiblingIfStale() → @rozie/core.compile()
+//      to emit a sibling `Foo.{ext}` (and React sidecars when target='react').
+//   4. Rewrites the import source to the sibling extension so downstream
+//      Babel passes (preset-typescript / preset-react / preset-vue) and
+//      bundler resolution (Webpack / Metro) handle it as a normal module.
+//
+// Targets non-Vite distributions: Webpack/babel-loader, Metro, or any
+// Babel-driven pipeline. The Vite path remains @rozie/unplugin per D-48.
+//
+// Plugin order (Pitfall 3): plugins run BEFORE presets in default Babel
+// order, so this plugin's import-source rewrite lands before
+// preset-typescript / preset-react try to resolve `./Foo.rozie`. Document
+// the canonical config in README.md.
+//
+// Errors are surfaced as Babel errors via `path.buildCodeFrameError` per
+// D-97 — consumer sees a Babel-shaped error frame, not a raw Node throw.
+//
+// Source-LOC budget per D-92: ~50 LOC for this visitor file. Helpers
+// (writeSibling.ts, compileImport.ts) carry the fs + cache logic.
+import { declare } from '@babel/helper-plugin-utils';
+import type { PluginObj } from '@babel/core';
+import { resolve as pathResolve, dirname } from 'node:path';
+import { compileImport } from './compileImport.js';
+import type { RozieBabelTarget } from './writeSibling.js';
+
+export interface RozieBabelPluginOptions {
+  /** Required: target framework. Selects emit branch + sibling extension. */
+  target: RozieBabelTarget;
+  /**
+   * Phase 23 — per-target emit-semantics namespace (mirrors
+   * `CompileOptions.angular`). `angular.cva` (default ON) opts out of the auto
+   * `ControlValueAccessor` emit when `false`. Omitting it preserves the
+   * emitter default-ON path byte-identically to the other entrypoints.
+   * No-op for non-Angular targets.
+   */
+  angular?: { cva?: boolean };
+}
+
+/** D-92 sibling-extension dispatch table. */
+const TARGET_EXTENSIONS = {
+  vue: '.vue',
+  react: '.tsx',
+  svelte: '.svelte',
+  angular: '.ts',
+  solid: '.tsx',
+  lit: '.ts',
+} as const satisfies Record<RozieBabelTarget, string>;
+
+const ROZIE_EXT = '.rozie';
+
+export default declare((api, options: RozieBabelPluginOptions): PluginObj => {
+  api.assertVersion(7);
+
+  const { target } = options;
+  // Phase 23 — Angular CVA opt-out forwarded into the compile chain. Undefined
+  // when omitted → emitter default-ON (byte-identical to the other entrypoints).
+  const cva = options.angular?.cva;
+  if (!target || !(target in TARGET_EXTENSIONS)) {
+    // ROZ820 — invalid target option. Thrown at plugin instantiation so
+    // misconfigurations fail fast (before any visitor runs).
+    throw new Error(
+      `[ROZ820] @rozie/babel-plugin: 'target' option is required and must be one of vue|react|svelte|angular|solid|lit (got ${JSON.stringify(target)})`,
+    );
+  }
+  const ext = TARGET_EXTENSIONS[target];
+
+  return {
+    name: '@rozie/babel-plugin',
+    visitor: {
+      ImportDeclaration(path, state) {
+        const src = path.node.source.value;
+        // Phase 54 negative route: this guard is INTENTIONALLY `.rozie`-only.
+        // A `.rzts`/`.rzjs` script-partial import falls through here and is NOT
+        // intercepted — it has no standalone module surface to compile, so it
+        // must never trigger compileImport → writeSiblingIfStale (no `Foo.tsx`
+        // sibling for a partial). Partials vanish into the host's emitted module
+        // at lowerToIR inline time; the host's compiled sibling already carries
+        // the inlined declarations. Do NOT widen this guard to the partial exts.
+        if (!src.endsWith(ROZIE_EXT)) return;
+
+        // state.filename is the importer; needed to resolve the relative
+        // .rozie path. Babel always provides this when caller passes
+        // `filename` to transformAsync; if missing, surface ROZ821 with
+        // a code-frame so the consumer sees the offending import.
+        const importerFile = state.filename ?? state.file?.opts?.filename;
+        if (!importerFile) {
+          throw path.buildCodeFrameError(
+            `[ROZ821] @rozie/babel-plugin: cannot resolve relative .rozie import without state.filename`,
+          );
+        }
+        const roziePath = pathResolve(dirname(importerFile), src);
+        const siblingPath = roziePath.slice(0, -ROZIE_EXT.length) + ext;
+
+        try {
+          compileImport(roziePath, siblingPath, target, cva);
+        } catch (err) {
+          // Re-shape any error from compileImport (ROZ822 compile error
+          // or ROZ823 fs error) as a Babel error with code-frame per D-97.
+          throw path.buildCodeFrameError(`${(err as Error).message}`);
+        }
+
+        // Rewrite the import source so downstream Babel passes + the
+        // consumer's bundler resolve the sibling artifact naturally.
+        const newSrc = src.slice(0, -ROZIE_EXT.length) + ext;
+        path.node.source.value = newSrc;
+      },
+    },
+  };
+});

package/src/writeSibling.ts

@@ -0,0 +1,122 @@
+// writeSibling — fs-side effects for @rozie/babel-plugin (Plan 06-04 D-92).
+//
+// Idempotency strategy: mtime comparison with a 100ms tolerance window.
+// Per RESEARCH Pitfall 1 (atomic-save editor jitter on APFS/NFS), if the
+// sibling's mtime is within 100ms BEHIND the .rozie's mtime, treat the
+// sibling as up-to-date. False negatives (an unnecessary recompile) are
+// preferred over false positives (silent stale output).
+//
+// Recovery: consumers can `rm Foo.{ext}` to force a fresh compile. The v2
+// path is a content-hash sidecar (deferred per CONTEXT.md).
+//
+// All writes go through a single try/catch so any fs error becomes a
+// stable ROZ823 diagnostic carrying the offending path.
+//
+// React-only sidecars: when target='react' and compile() populated
+// result.types/css/globalCss, write Foo.d.ts / Foo.css / Foo.global.css
+// alongside the primary Foo.tsx (Phase 25 — the scoped-CSS sibling is a plain
+// stylesheet, not a CSS-Modules sidecar; React no longer routes scoped <style>
+// through CSS Modules). Other targets only receive the primary artifact
+// (D-84 inline-typed).
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+// WR-03 — import compile() via RELATIVE path into the sibling workspace package,
+// matching every other compile() entrypoint (compile.ts, unplugin/transform.ts,
+// cli/commands/*, dist-parity). The package-name form (`@rozie/core`) can
+// resolve to a stale built dist/ while the others resolve to live source —
+// under which the Phase 23 dist-parity byte-equality contract
+// (FIXTURE_ANGULAR_CVA_OFF across all four entrypoints) could pass in CI yet
+// drift in a real babel consumer build. tsdown inlines the workspace sibling
+// when bundling (the strategy proven by @rozie/unplugin — see compile.ts:30-37).
+import { compile } from '../../core/src/compile.js';
+
+/** Editor atomic-save jitter window per RESEARCH Pitfall 1. */
+const MTIME_TOLERANCE_MS = 100;
+
+export type RozieBabelTarget = 'vue' | 'react' | 'svelte' | 'angular' | 'solid' | 'lit';
+
+/**
+ * Compile the .rozie at `roziePath` and write its sibling `siblingPath`,
+ * skipping the work entirely when the sibling appears up-to-date.
+ *
+ * @param roziePath  Absolute path to the source .rozie file on disk.
+ * @param siblingPath Absolute path to the target sibling (e.g. Foo.tsx).
+ * @param target Target framework — selects emit branch and sidecar layout.
+ *
+ * @throws Error with `[ROZ822]` prefix when compile() reports any error
+ *         severity diagnostic. The message embeds each [ROZxxx] code so the
+ *         babel-plugin caller can buildCodeFrameError around it.
+ * @throws Error with `[ROZ823]` prefix when fs writeFileSync fails.
+ */
+export function writeSiblingIfStale(
+  roziePath: string,
+  siblingPath: string,
+  target: RozieBabelTarget,
+  // Phase 23 — Angular CVA opt-out. Undefined → emitter default-ON path,
+  // byte-identical to compile()/CLI/unplugin when omitted.
+  cva?: boolean,
+): void {
+  // Idempotency check — if sibling is fresher than .rozie (or within the
+  // 100ms tolerance window), skip. Saves the compile() cost on hot paths
+  // (HMR, rebuild after unrelated edit, etc).
+  const rozieStat = statSync(roziePath);
+  if (existsSync(siblingPath)) {
+    const sibStat = statSync(siblingPath);
+    if (sibStat.mtimeMs >= rozieStat.mtimeMs - MTIME_TOLERANCE_MS) {
+      return; // up-to-date within tolerance
+    }
+  }
+
+  // Compile via the @rozie/core single source of truth (D-93 byte-identical).
+  const source = readFileSync(roziePath, 'utf8');
+  const result = compile(source, {
+    target,
+    filename: roziePath,
+    // Phase 23 — attach the `angular` namespace only on opt-out so the
+    // default-ON path stays byte-identical to the other entrypoints.
+    ...(cva === false ? { angular: { cva: false } } : {}),
+  });
+  const errors = result.diagnostics.filter((d) => d.severity === 'error');
+  if (errors.length > 0) {
+    const detail = errors.map((d) => `[${d.code}] ${d.message}`).join('; ');
+    throw new Error(`[ROZ822] @rozie/babel-plugin: compile failed: ${detail}`);
+  }
+
+  // Write phase — primary artifact + react sidecars in a single try/catch.
+  try {
+    writeFileSync(siblingPath, result.code, 'utf8');
+    if (target === 'react') {
+      // WR-03: assert the canonical .tsx invariant before deriving sidecar
+      // paths. `String.prototype.replace(/\.tsx$/, …)` is a no-op on a path
+      // that doesn't end in `.tsx`, which would silently overwrite the
+      // primary `.tsx` with the .d.ts/.css text. The visitor in `index.ts`
+      // is the only known caller and feeds canonical extensions via
+      // TARGET_EXTENSIONS, so this is defense-in-depth — bailing loudly is
+      // safer than silent corruption if a future caller drifts.
+      if (!siblingPath.endsWith('.tsx')) {
+        throw new Error(
+          `[ROZ823] @rozie/babel-plugin: react sibling path must end with .tsx, got ${siblingPath}`,
+        );
+      }
+      const stem = siblingPath.slice(0, -'.tsx'.length);
+      if (result.types) {
+        writeFileSync(`${stem}.d.ts`, result.types, 'utf8');
+      }
+      if (result.css) {
+        // Phase 25 — plain `.css` sidecar (no longer a CSS-Modules sidecar).
+        // React no longer routes scoped `<style>` through CSS Modules; the
+        // emitted `.tsx` body imports it for side effect via `import './Foo.css'`,
+        // and class isolation is the `[data-rozie-s-HASH]` attribute selector
+        // inside the CSS. The bundler treats the plain `.css` as a global
+        // stylesheet.
+        writeFileSync(`${stem}.css`, result.css, 'utf8');
+      }
+      if (result.globalCss) {
+        writeFileSync(`${stem}.global.css`, result.globalCss, 'utf8');
+      }
+    }
+  } catch (err) {
+    throw new Error(
+      `[ROZ823] @rozie/babel-plugin: failed to write sibling ${siblingPath}: ${(err as Error).message}`,
+    );
+  }
+}