@emeryld/rrroutes-export

Export helpers and CLI for RRRoutes finalized leaves.

What this package provides

• Runtime API:
  • exportFinalizedLeaves
  • writeFinalizedLeavesExport
  • exportFinalizedLeavesChangelog
  • writeFinalizedLeavesChangelogExport
  • buildFinalizedLeavesViewerBundle
  • writeFinalizedLeavesViewerBundle
• CLI:
  • rrroutes-export-finalized-leaves
  • rrroutes-export-changelog
• Schema utilities:
  • serializeLeafContract
  • flattenLeafSchemas
  • introspectSchema

Depends on @emeryld/rrroutes-contract for contract types and schema parsing. This package is configured to install @emeryld/rrroutes-contract from npm (not from the local workspace) to ensure release-version parity.

Finalized leaves export CLI

Command:

rrroutes-export-finalized-leaves \
  --module ./path/to/leaves-module.cjs \
  --export leaves \
  --out ./finalized-leaves.export.json \
  --with-source \
  --tsconfig ./tsconfig.json

Settings:

• --module <path>: required. Path to the module that exports your leaves/registry.
• --export <name>: optional. Export name to load from the module. Default: leaves.
• --out <path>: optional. JSON output file path. Default: finalized-leaves.export.json.
• --with-source: optional flag. Enables AST source extraction (sourceByLeaf).
• --tsconfig <path>: optional. TS config used by source extraction.

Changelog export CLI

Command:

rrroutes-export-changelog \
  --module ./path/to/leaves-module.cjs \
  --export leaves \
  --from v1.4.0 \
  --to HEAD \
  --out ./finalized-leaves.changelog.json \
  --html ./finalized-leaves.changelog.viewer.html \
  --tsconfig ./tsconfig.json

Settings:

• --module <path>: required. Module path used for per-commit snapshots.
• --export <name>: optional. Export name in the module. Default: leaves.
• --from <rev>: optional. Baseline revision/tag. Default: last reachable semver tag.
• --to <rev>: optional. End revision/tag. Default: HEAD.
• --out <path>: optional. Changelog JSON output. Default: finalized-leaves.changelog.json.
• --html <path>: optional. Baked HTML viewer for changelog payload.
• --tsconfig <path>: optional. TS config used for source extraction in snapshots.
• --with-source: accepted for parity; changelog mode always enables source extraction.
• --cache-dir <path>: optional. Directory for per-commit compile cache artifacts.
• --no-cache: optional flag. Disable compile cache and force recompilation.

Behavior summary:

• Resolves commit path from from..to (chronological).
• Builds commit-aware module path candidates (current path + extension variants + rename history).
• Filters commits to those touching module tree/relevant config files.
• Ensures tip commit is always included.
• Creates a temp git worktree per selected commit.
• For TypeScript module entries, compiles the commit snapshot to JS and imports emitted output.
• For JavaScript module entries, imports directly from worktree.
• If module entrypoint cannot be resolved for a commit, changelog uses an empty snapshot for that commit (timeline continuity).
• If a commit snapshot fails to compile/load, changelog also uses an empty snapshot for that commit and continues.
• Exports snapshots, then computes adjacent diffs:
  • route events (route_added, route_removed, schema_changed, cfg_changed)
  • source-object events (source_object_added, source_object_removed, source_schema_changed)
  • metadata includes fallback details in _meta.unresolvedModuleCommits and _meta.snapshotFallbacks

Runtime progress logs:

• rrroutes-export-changelog now prints step-by-step progress (window resolution, commit filtering, per-commit snapshot progress, diff totals, output writing, cleanup).
• Changelog logs include compile lifecycle details: selected tsconfig, cache hit/miss, emitted entry path.
• Changelog logs include per-commit module resolution and unresolved-entry fallback messages.
• Changelog logs include snapshot compile/load fallback messages when a commit cannot be materialized.
• Bundle script prints stage logs for snapshot export + changelog export.

Troubleshooting historical TS imports:

• Changelog execution no longer relies on direct Node runtime loading of TS sources.
• Historical imports like ./x.js pointing to x.ts are handled by snapshot compilation.
• If tsconfig auto-discovery fails, pass --tsconfig.
• If entrypoint path moved across history, changelog resolves rename history automatically.

Recommended end-to-end script

Use this when you want one command to produce everything (snapshot + changelog + HTML + summary + timestamped storage).

Script command:

pnpm --filter @emeryld/rrroutes-export run export:bundle -- \
  --module ./src/contract/leaves.cjs \
  --export leaves \
  --tsconfig ./tsconfig.json \
  --from v1.4.0 \
  --to HEAD \
  --cache-dir ./.rroutes-exports/.cache \
  --dir ./.rrroutes-exports

Bundle script settings (scripts/export-release-bundle.ts):

• --module <path>: required.
• --export <name>: optional. Default: leaves.
• --tsconfig <path>: optional.
• --from <rev>: optional.
• --to <rev>: optional.
• --cache-dir <path>: optional.
• --no-cache: optional flag.
• --dir <path>: optional base directory for stored bundles. Default: .rrroutes-exports.

Per run, it writes a timestamped directory:

• finalized-leaves.export.json
• finalized-leaves.viewer.html
• finalized-leaves.changelog.json
• finalized-leaves.changelog.viewer.html
• finalized-leaves.bundle.json
• finalized-leaves.bundle.viewer.html
• summary.json

This is the recommended CI/release flow because outputs are immutable per run and easy to archive.

Runtime API (quick example)

import {
  buildFinalizedLeavesViewerBundle,
  exportFinalizedLeaves,
  exportFinalizedLeavesChangelog,
  writeFinalizedLeavesViewerBundle,
} from '@emeryld/rrroutes-export'

const snapshot = await exportFinalizedLeaves(leaves, {
  outFile: './finalized-leaves.export.json',
  htmlFile: './finalized-leaves.viewer.html',
  includeSource: true,
  sourceModulePath: './src/contract/leaves.cjs',
  sourceExportName: 'leaves',
})

const changelog = await exportFinalizedLeavesChangelog({
  modulePath: './src/contract/leaves.cjs',
  exportName: 'leaves',
  from: 'v1.4.0',
  to: 'HEAD',
  cacheDir: './.cache/rrroutes-export',
  noCache: false,
  outFile: './finalized-leaves.changelog.json',
  htmlFile: './finalized-leaves.changelog.viewer.html',
  log: (message) => console.log(message),
})

const unified = buildFinalizedLeavesViewerBundle({
  leavesPayload: snapshot,
  changelogPayload: changelog,
})

await writeFinalizedLeavesViewerBundle(unified, {
  outFile: './finalized-leaves.bundle.json',
  htmlFile: './finalized-leaves.bundle.viewer.html',
})