@epilot/zenith-react 0.1.0-next.0

package/scripts/migration-diagnostics.mjs

@@ -0,0 +1,427 @@
+/**
+ * fs-bound migration-diagnostics ORCHESTRATION for a migrated (v1 -> Griffel) consumer tree —
+ * directory/file walking, symlink boundary checks, hashing, package identity resolution, and
+ * TypeScript resolution from the local filesystem. The actual rule logic (what counts as a
+ * defect) lives in the sibling `migration-diagnostics-core.mjs`, which this module delegates every
+ * read file to via `analyzeSource` — see that module for the rule catalogue and the
+ * supported-analysis-boundary documentation. This split exists so a future non-fs caller (e.g. a
+ * remote tool analyzing a submitted string) can reuse the identical rule implementation without
+ * pulling in any of this module's filesystem/process access (WP6B-2 extraction; no such
+ * caller is wired up yet).
+ *
+ * Used by the CLI wrapper (`migration-sweep.mjs`) and by tests. Importing this module has no
+ * side effects (no process.exit, no argv parsing, no eager TypeScript import — see below).
+ *
+ * TypeScript itself is resolved LAZILY from the consumer's own installation (see
+ * `resolveConsumerTypeScript`) — this package does not depend on or bundle `typescript` at
+ * runtime. If it cannot be resolved, rules `legacy-volt-class` and `hand-written-volt-css-var`
+ * (pure text, no TypeScript needed) still run; `unestablished-palette-install` is skipped with an
+ * explicit, actionable note rather than crashing the whole scan.
+ */
+import { createHash } from "node:crypto"
+import { createRequire } from "node:module"
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs"
+import { join, relative } from "node:path"
+import { pathToFileURL } from "node:url"
+
+import {
+  analyzeSource,
+  makeFinding,
+  RULES,
+  SCRIPT_EXT_RE,
+} from "./migration-diagnostics-core.mjs"
+
+// Re-exported so existing imports of `RULES` from this module keep working unchanged — the rule
+// catalogue itself now lives in the core (single source of truth), per WP6B-2.
+export { RULES }
+
+// ---------------------------------------------------------------------------
+// Package/token-family identity — derived from the built package, never hardcoded
+// ---------------------------------------------------------------------------
+
+function sha256(content) {
+  return createHash("sha256").update(content).digest("hex")
+}
+
+function readGeneratedFamilies(packageDir, file) {
+  const full = join(packageDir, "dist/tokens", file)
+  if (!existsSync(full)) {
+    throw new Error(
+      `Missing generated token file: dist/tokens/${file} under ${packageDir}. The package is not built — run \`bun run build\` there first.`
+    )
+  }
+  const content = readFileSync(full, "utf8")
+  const families = new Set(
+    [...content.matchAll(/--zenith-[a-z0-9]+-([a-z]+)-/g)].map((m) => m[1])
+  )
+  if (families.size === 0) {
+    throw new Error(
+      `Generated token file dist/tokens/${file} under ${packageDir} contains no recognizable family declarations. ` +
+        "It exists but is empty or malformed (does not match the expected --zenith-<hash>-<family>- pattern) — " +
+        "the package build is likely stale or broken. Re-run `bun run build` there, do not proceed with an empty family set."
+    )
+  }
+  return { families, content }
+}
+
+/**
+ * Resolves package name/version, its core/palette token family sets, and a deterministic hash of
+ * the generated-token inputs those sets were read from, from a built package directory. Throws
+ * (never silently falls back to empty sets) on a missing/unreadable package.json, missing
+ * generated token files, or generated files with no recognizable family declarations — "invalid
+ * package selection" is a hard error, not a quietly-disabled rule.
+ */
+export function resolvePackageIdentity(packageDir) {
+  const pkgJsonPath = join(packageDir, "package.json")
+  if (!existsSync(pkgJsonPath)) {
+    throw new Error(
+      `Invalid package selection: no package.json at ${packageDir}`
+    )
+  }
+  let pkgJson
+  try {
+    pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"))
+  } catch (err) {
+    throw new Error(
+      `Invalid package selection: could not parse ${pkgJsonPath}: ${err.message}`
+    )
+  }
+  if (!pkgJson.name || !pkgJson.version) {
+    throw new Error(
+      `Invalid package selection: ${pkgJsonPath} is missing "name" or "version"`
+    )
+  }
+
+  const coreRead = readGeneratedFamilies(packageDir, "core.generated.js")
+  const paletteRead = readGeneratedFamilies(packageDir, "palette.generated.js")
+  const core = coreRead.families
+  const palette = new Set([...paletteRead.families].filter((f) => !core.has(f)))
+  const generatedInputHash = sha256(
+    `${coreRead.content}\u0000${paletteRead.content}`
+  )
+
+  return {
+    packageDir,
+    packageName: pkgJson.name,
+    packageVersion: pkgJson.version,
+    core,
+    palette,
+    generatedInputHash,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// TypeScript — lazily resolved from the consumer's own installation, never bundled/depended-on
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolves `typescript` using Node's own module resolution, searching from each of `searchRoots`
+ * in order (first match wins). Never installs anything. Throws a clear, actionable error — never
+ * a cryptic MODULE_NOT_FOUND — naming exactly what to do, if none of the roots have it.
+ */
+export async function resolveConsumerTypeScript(searchRoots) {
+  const roots = searchRoots.filter(Boolean)
+  const req = createRequire(
+    join(roots[0] ?? process.cwd(), "noop-resolver.cjs")
+  )
+  let tsPath
+  for (const root of roots) {
+    try {
+      tsPath = req.resolve("typescript", { paths: [root] })
+      break
+    } catch {
+      // try the next root
+    }
+  }
+  if (!tsPath) {
+    throw new Error(
+      'Could not resolve a "typescript" installation from: ' +
+        roots.join(", ") +
+        '. The "unestablished-palette-install" rule parses source with your project\'s own TypeScript — ' +
+        "it is not bundled with this package. Install it as a devDependency in the project being scanned " +
+        "(`npm install -D typescript` or `bun add -d typescript`) and re-run. " +
+        "legacy-volt-class and hand-written-volt-css-var do not need TypeScript and are unaffected."
+    )
+  }
+  const mod = await import(pathToFileURL(tsPath).href)
+  return { ts: mod.default ?? mod, tsPath }
+}
+
+// ---------------------------------------------------------------------------
+// File walking
+// ---------------------------------------------------------------------------
+
+const SCAN_EXT_RE = /\.(tsx?|jsx?|s?css)$/
+/** `*.generated.*` build output — the generator's own emitted source of truth, never
+ * "hand-written" by a consumer. See §4 of the WP6A report. */
+const GENERATED_FILE_RE = /\.generated\.[a-z]+$/i
+/** A leading `/* GENERATED ... *\/` / `// GENERATED ...` marker — this repo's own convention
+ * (`packages/tokens/scripts/build.ts`), and common generally; catches generated files that don't
+ * follow the filename convention (e.g. tokens/index.ts). */
+const GENERATED_HEADER_RE = /^\s*(\/\*|\/\/|<!--)\s*generated\b/i
+
+function isExcluded(rel, excludes) {
+  return excludes.some((ex) => rel === ex || rel.startsWith(`${ex}/`))
+}
+
+function isGeneratedByHeader(filePath) {
+  try {
+    const fd = readFileSync(filePath, { encoding: "utf8", flag: "r" }).slice(
+      0,
+      200
+    )
+    return GENERATED_HEADER_RE.test(fd.split("\n")[0] ?? "")
+  } catch {
+    return false
+  }
+}
+
+function walk(dir, { excludes, root, skippedSymlinks, skippedGenerated }) {
+  const out = []
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch (err) {
+    throw new Error(`Cannot read directory ${dir}: ${err.message}`)
+  }
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name.startsWith(".")) continue
+    const full = join(dir, entry.name)
+    const rel = relative(root, full)
+    if (isExcluded(rel, excludes)) continue
+    if (entry.isSymbolicLink()) {
+      skippedSymlinks.push(rel)
+      continue
+    }
+    if (entry.isDirectory()) {
+      out.push(
+        ...walk(full, { excludes, root, skippedSymlinks, skippedGenerated })
+      )
+    } else if (SCAN_EXT_RE.test(entry.name)) {
+      if (GENERATED_FILE_RE.test(entry.name) || isGeneratedByHeader(full)) {
+        skippedGenerated.push(rel)
+        continue
+      }
+      out.push(full)
+    }
+  }
+  return out
+}
+
+/** Reads one file and delegates the actual analysis to the core's `analyzeSource` — this function
+ * is the ENTIRE fs-touching surface for per-file analysis; `analyzeSource` itself never reads a
+ * file. `relPath` doubles as `analyzeSource`'s `fileNameHint` (parse-mode detection + the `file`
+ * label on findings) — the same string was already used for both purposes before this split. */
+function analyzeFile(ts, identity, filePath, relPath) {
+  const raw = readFileSync(filePath, "utf8")
+  const findings = analyzeSource(raw, { identity, ts, fileNameHint: relPath })
+  return { findings, contentHash: sha256(raw) }
+}
+
+// ---------------------------------------------------------------------------
+// Public entrypoint
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolves `targetPath` into a boundary-checked root: rejects a target (or its auto-selected
+ * `src/`) that is itself a symlink, rather than silently following it (which could escape the
+ * requested scope entirely). Supports both a directory target and a single FILE target.
+ */
+function resolveScanRoot(targetPath) {
+  const targetLstat = lstatSync(targetPath)
+  if (targetLstat.isSymbolicLink()) {
+    return {
+      error: `Target path is a symlink (${targetPath} -> ${realpathSync(targetPath)}); point directly at the real path instead of a symlink.`,
+    }
+  }
+  if (targetLstat.isFile()) {
+    return { file: targetPath }
+  }
+  if (!targetLstat.isDirectory()) {
+    return {
+      error: `Target path is neither a file nor a directory: ${targetPath}`,
+    }
+  }
+  const srcDir = join(targetPath, "src")
+  if (existsSync(srcDir)) {
+    const srcLstat = lstatSync(srcDir)
+    if (srcLstat.isSymbolicLink()) {
+      return {
+        error: `The target's auto-selected src/ is a symlink (${srcDir} -> ${realpathSync(srcDir)}); this would scan outside the requested scope. Point the target directly at the real directory to scan, or pass it as the target itself.`,
+      }
+    }
+    if (srcLstat.isDirectory()) {
+      return { root: srcDir }
+    }
+  }
+  return { root: targetPath }
+}
+
+/**
+ * Scans one target (a repo root, whose `src/` is scanned if present; any directory directly; or a
+ * single file) and returns `{ target, filesScanned, targetInputHash, skippedSymlinks,
+ * skippedGenerated, toolingWarning?, findings }` on success, or `{ target, error }` for a
+ * missing/unreadable path, a symlinked target/src boundary, or an internal walk failure — never a
+ * silent "skipped" a caller could read as success by checking only `findings`.
+ */
+export async function analyzeTarget(
+  targetPath,
+  { identity, excludes = [], resolveTs } = {}
+) {
+  if (!identity) {
+    throw new Error(
+      "analyzeTarget requires a resolved package `identity` — see resolvePackageIdentity()"
+    )
+  }
+  if (!existsSync(targetPath)) {
+    return {
+      target: targetPath,
+      error: `Target path does not exist: ${targetPath}`,
+    }
+  }
+
+  let scanRoot
+  try {
+    scanRoot = resolveScanRoot(targetPath)
+  } catch (err) {
+    return {
+      target: targetPath,
+      error: `Target path is not readable: ${targetPath} (${err.message})`,
+    }
+  }
+  if (scanRoot.error) {
+    return { target: targetPath, error: scanRoot.error }
+  }
+
+  let files
+  const skippedSymlinks = []
+  const skippedGenerated = []
+  if (scanRoot.file) {
+    if (
+      GENERATED_FILE_RE.test(scanRoot.file) ||
+      isGeneratedByHeader(scanRoot.file)
+    ) {
+      skippedGenerated.push(
+        relative(targetPath, scanRoot.file) || scanRoot.file
+      )
+      files = []
+    } else if (SCAN_EXT_RE.test(scanRoot.file)) {
+      files = [scanRoot.file]
+    } else {
+      return {
+        target: targetPath,
+        error: `Target file has an unsupported extension for scanning: ${scanRoot.file}`,
+      }
+    }
+  } else {
+    try {
+      files = walk(scanRoot.root, {
+        excludes,
+        root: targetPath,
+        skippedSymlinks,
+        skippedGenerated,
+      })
+    } catch (err) {
+      return { target: targetPath, error: err.message }
+    }
+  }
+
+  // unestablished-palette-install only applies to script files — a CSS/SCSS-only target never
+  // needs TypeScript at all, and must not report a tooling problem for a rule that could not have
+  // run there anyway. Reuses the core's own SCRIPT_EXT_RE so this check can never drift from what
+  // analyzeSource itself treats as script-parseable.
+  const hasScriptFiles = files.some((f) => SCRIPT_EXT_RE.test(f))
+
+  let ts = null
+  let toolingWarning
+  let resolvedTypeScript
+  let analysisIncomplete = false
+  if (hasScriptFiles) {
+    // No explicit resolver from the caller does NOT mean "skip rule 3 silently" — the engine's
+    // own default path still attempts real resolution (cwd, the target, the package dir) so a
+    // caller of the public API who simply omits `resolveTs` gets the same honest
+    // toolingWarning/analysisIncomplete signal a CLI invocation would.
+    const resolver =
+      resolveTs ??
+      (() =>
+        resolveConsumerTypeScript([
+          process.cwd(),
+          targetPath,
+          identity.packageDir,
+        ]))
+    try {
+      const resolved = await resolver()
+      ts = resolved.ts
+      let tsVersion
+      try {
+        tsVersion = JSON.parse(
+          readFileSync(
+            join(resolved.tsPath, "..", "..", "package.json"),
+            "utf8"
+          )
+        ).version
+      } catch {
+        tsVersion = undefined
+      }
+      resolvedTypeScript = { path: resolved.tsPath, version: tsVersion }
+    } catch (err) {
+      toolingWarning = err.message
+      // A required rule could not run at all for this target — the scan is INCOMPLETE, not clean.
+      // A caller must not read `findings` alone (which may still be a truthful, non-empty result
+      // for the two textual rules) as proof "everything was checked."
+      analysisIncomplete = true
+    }
+  }
+
+  const findings = []
+  const perFileHashes = []
+  for (const file of files) {
+    const rel = relative(targetPath, file) || file.split("/").pop()
+    try {
+      const { findings: fileFindings, contentHash } = analyzeFile(
+        ts,
+        identity,
+        file,
+        rel
+      )
+      findings.push(...fileFindings)
+      perFileHashes.push(`${rel}:${contentHash}`)
+    } catch (err) {
+      findings.push(
+        makeFinding(identity, {
+          code: "analysis-error",
+          severity: "error",
+          confidence: "high",
+          file: rel,
+          line: 1,
+          column: 1,
+          evidence: String(err?.message ?? err),
+          explanation:
+            "The diagnostic engine could not parse or read this file.",
+          suggestion:
+            "Fix the underlying syntax/read error, or pass --exclude for this path if it is intentionally out of scope (e.g. generated code).",
+        })
+      )
+    }
+  }
+
+  const targetInputHash = sha256(perFileHashes.sort().join("\n"))
+
+  return {
+    target: targetPath,
+    filesScanned: files.length,
+    targetInputHash,
+    skippedSymlinks,
+    skippedGenerated,
+    ...(toolingWarning ? { toolingWarning } : {}),
+    ...(resolvedTypeScript ? { resolvedTypeScript } : {}),
+    ...(analysisIncomplete ? { analysisIncomplete: true } : {}),
+    findings,
+  }
+}

package/scripts/migration-sweep.mjs

@@ -0,0 +1,205 @@
+/**
+ * CLI for the migration-diagnostics engine — checks a migrated consumer for the defects that
+ * survive every other gate (see migration-diagnostics.mjs for the rule catalogue and the
+ * analysis-boundary documentation; this file is argv parsing and output formatting only).
+ *
+ *   bun scripts/migration-sweep.mjs [--json] [--package <dir>] [--exclude <path>]... <path> [...]
+ *
+ * Exit code: 2 if any target has a hard input/argument error OR the requested analysis was
+ * INCOMPLETE (a script-file target whose TypeScript could not be resolved — a required rule did
+ * not run, which is not the same as "it ran and found nothing"); else 1 if any finding has
+ * severity "error" (legacy-volt-class / hand-written-volt-css-var — definite, unconditional textual
+ * defects); else 0. unestablished-palette-install never reports severity "error" — single-file
+ * analysis cannot prove a defect it might be wrong about (a bootstrap/provider elsewhere), so its
+ * findings are always "warning" and never independently produce a nonzero exit.
+ */
+import { resolve } from "node:path"
+import {
+  analyzeTarget,
+  resolveConsumerTypeScript,
+  resolvePackageIdentity,
+  RULES,
+} from "./migration-diagnostics.mjs"
+
+const DEFAULT_PACKAGE_DIR = resolve(import.meta.dirname, "..")
+const KNOWN_FLAGS = new Set(["--json", "--package", "--exclude"])
+
+function usage() {
+  return (
+    "usage: node migration-sweep.mjs [--json] [--package <dir>] [--exclude <path>]... <path> [...]\n" +
+    "  <path>            a repo root (scans its src/), a directory, or a single source file\n" +
+    "  --json            machine-readable JSON output instead of text (errors too)\n" +
+    "  --package <dir>   Griffel package to read token families from (default: this package)\n" +
+    "  --exclude <path>  path relative to the target to skip, repeatable\n" +
+    "  During a flag-gated migration, point it at the NEW tree:\n" +
+    "    node migration-sweep.mjs src/components/<name>-griffel src/surface"
+  )
+}
+
+/** Returns `{ targets, excludes, json, packageDir }` or `{ argError }` for a missing operand or
+ * an unrecognized `--flag` — never silently treats either as a target path. */
+function parseArgs(argv) {
+  const targets = []
+  const excludes = []
+  let json = false
+  let packageDir = DEFAULT_PACKAGE_DIR
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (!a.startsWith("--")) {
+      targets.push(a)
+      continue
+    }
+    if (!KNOWN_FLAGS.has(a)) {
+      return { argError: `Unknown flag: ${a}` }
+    }
+    if (a === "--json") {
+      json = true
+      continue
+    }
+    const operand = argv[i + 1]
+    if (operand === undefined || operand.startsWith("--")) {
+      return { argError: `Missing operand for ${a}` }
+    }
+    i++
+    if (a === "--package") packageDir = resolve(operand)
+    else if (a === "--exclude") excludes.push(operand)
+  }
+
+  return { targets, excludes, json, packageDir }
+}
+
+function emitError(json, message, extra = {}) {
+  if (json) {
+    console.log(
+      JSON.stringify({ schemaVersion: 1, error: message, ...extra }, null, 2)
+    )
+  } else {
+    console.error(message)
+    if (extra.usage) console.error(extra.usage)
+  }
+}
+
+export async function runCli(argv) {
+  const parsed = parseArgs(argv)
+  // Flag parsing errors can occur before we know whether --json was requested (e.g. an unknown
+  // flag before --json itself) — best-effort: honor --json if it appears anywhere in argv.
+  const jsonRequested = parsed.json ?? argv.includes("--json")
+
+  if (parsed.argError) {
+    emitError(jsonRequested, parsed.argError, { usage: usage() })
+    return 2
+  }
+
+  const { targets, excludes, json, packageDir } = parsed
+  if (!targets.length) {
+    emitError(json, "No target path(s) given.", { usage: usage() })
+    return 2
+  }
+
+  let identity
+  try {
+    identity = resolvePackageIdentity(packageDir)
+  } catch (err) {
+    emitError(json, String(err?.message ?? err))
+    return 2
+  }
+
+  const resolveTs = () =>
+    resolveConsumerTypeScript([
+      process.cwd(),
+      ...targets.map((t) => resolve(t)),
+      packageDir,
+    ])
+
+  const results = []
+  for (const t of targets) {
+    results.push(
+      await analyzeTarget(resolve(t), { identity, excludes, resolveTs })
+    )
+  }
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          package: {
+            name: identity.packageName,
+            version: identity.packageVersion,
+            generatedInputHash: identity.generatedInputHash,
+          },
+          rules: RULES,
+          results,
+        },
+        null,
+        2
+      )
+    )
+  } else {
+    for (const r of results) {
+      const name = r.target.split("/").pop()
+      if (r.error) {
+        console.log(`  ✗ ${name} — ${r.error}`)
+        continue
+      }
+      if (r.resolvedTypeScript) {
+        console.log(
+          `      typescript: ${r.resolvedTypeScript.version ?? "unknown version"} (${r.resolvedTypeScript.path})`
+        )
+      }
+      if (r.skippedGenerated?.length) {
+        console.log(
+          `      skipped as generated: ${r.skippedGenerated.join(", ")}`
+        )
+      }
+      if (r.skippedSymlinks?.length) {
+        console.log(`      skipped symlinks: ${r.skippedSymlinks.join(", ")}`)
+      }
+      if (r.toolingWarning) {
+        // Never a green check here, even if findings is empty — the required rule did not run,
+        // so "no findings" means "not fully checked", not "checked and clean".
+        console.log(
+          `  ! ${name} — INCOMPLETE ANALYSIS: ${r.toolingWarning}` +
+            (r.findings.length
+              ? ` (${r.findings.length} finding(s) from the rules that did run, below)`
+              : "")
+        )
+        for (const f of r.findings) {
+          console.log(
+            `      [${f.severity}] ${f.code.padEnd(28)} ${f.file}:${f.line}:${f.column}  ${f.evidence}`
+          )
+        }
+        continue
+      }
+      if (!r.findings.length) {
+        console.log(
+          `  ✓ ${name} (${r.filesScanned} file(s) scanned, targetInputHash ${r.targetInputHash.slice(0, 12)}…)`
+        )
+        continue
+      }
+      console.log(`  ✗ ${name} — ${r.findings.length} finding(s)`)
+      for (const f of r.findings) {
+        console.log(
+          `      [${f.severity}] ${f.code.padEnd(28)} ${f.file}:${f.line}:${f.column}  ${f.evidence}`
+        )
+      }
+    }
+    console.log("")
+  }
+
+  const hasIncompleteOrInputError = results.some(
+    (r) => r.error || r.analysisIncomplete
+  )
+  if (hasIncompleteOrInputError) return 2
+
+  const hasHardFailure = results.some((r) =>
+    r.findings?.some((f) => f.severity === "error")
+  )
+  return hasHardFailure ? 1 : 0
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const code = await runCli(process.argv.slice(2))
+  process.exit(code)
+}

package/testing/jest-preset.cjs

@@ -0,0 +1,64 @@
+/**
+ * Jest/Vitest configuration for consumers of this package.
+ *
+ * WHY THIS EXISTS. The package is ESM-only. Jest 26 and 27 ignore the `exports` field, so before
+ * 0.2.2 a bare `@epilot/zenith-react` resolved to nothing and every suite that
+ * rendered a component died with "Cannot find module". Both pilot MFEs hit it; one hand-wrote
+ * `moduleNameMapper: { '^@epilot/…$': '<rootDir>/../../../node_modules/@epilot/…/dist/index.js' }`,
+ * a path that breaks the moment hoisting changes.
+ *
+ * 0.2.2 adds a `main` field, so those resolvers now find `dist/index.js` on their own and no
+ * mapping is needed. What is still needed is a TRANSFORM: the file they resolve is ESM, and Jest's
+ * default `transformIgnorePatterns` skips everything in `node_modules`. That is what this file
+ * supplies.
+ *
+ * There is deliberately no CommonJS build. The runtime keeps module-level state — `sheet.ts` holds
+ * the `installed` Set that dedups token sheets, and one shared renderer — and a dual ESM/CJS build
+ * would give a consumer two copies of it. That breaks the single-insertion-point and single-renderer
+ * guarantees `gate:isolation` and `gate:griffel-contract` assert. One format is a correctness
+ * requirement here, not an oversight. See DECISIONS D13.
+ *
+ * USAGE — spread it into your own config:
+ *
+ *   const griffel = require("@epilot/zenith-react/testing/jest-preset.cjs")
+ *
+ *   module.exports = griffel.withGriffel({
+ *     preset: "ts-jest",
+ *     // …your config…
+ *   }, { alsoTransform: ["@xyflow"] })
+ *
+ * Requires `babel-jest` and `@babel/preset-env` as devDependencies. If you already transform JS in
+ * `node_modules` with something else, take `transformIgnorePatterns` from here and keep your own
+ * `transform`.
+ */
+const PACKAGE_NAME = "@epilot/zenith-react"
+
+/** Transform for the ESM this package ships. Keyed on `.js`/`.mjs`, which is all it emits. */
+const transform = {
+  "^.+\\.m?js$": [
+    "babel-jest",
+    { presets: [["@babel/preset-env", { targets: { node: "current" } }]] },
+  ],
+}
+
+/**
+ * Jest ignores a file if ANY pattern matches, so an extra pattern cannot un-ignore what the
+ * default `/node_modules/` already caught — the array has to be replaced, not appended to. Hence
+ * the explicit `alsoTransform` list rather than a merge.
+ */
+const transformIgnorePatterns = (alsoTransform = []) => [
+  `node_modules/(?!(${[PACKAGE_NAME, ...alsoTransform].join("|")})/)`,
+]
+
+const withGriffel = (config = {}, { alsoTransform = [] } = {}) => ({
+  ...config,
+  transform: { ...transform, ...config.transform },
+  transformIgnorePatterns: transformIgnorePatterns(alsoTransform),
+})
+
+module.exports = {
+  PACKAGE_NAME,
+  transform,
+  transformIgnorePatterns: transformIgnorePatterns(),
+  withGriffel,
+}

package/tokens.d.ts

@@ -0,0 +1,3 @@
+// Types for the `./tokens` resolution stub. See tokens.js for why this path exists.
+// Written without a file extension so resolvers that predate `exports` can follow it.
+export * from "./dist/tokens/index"