Skip to content
ContractSpec
Start here

Package manual · tools

·CLI, authoring and agent tooling

tools.contractspec-codemods

Codemods + import-graph scanner that mechanically migrate consumers of the rich-reference legacy surfaces (CodeBlock, DiffBlock, ObjectReferenceHandler, RichContentReference, rich-code-preferences) to the post-S-8 surface (RichBlock, RichRef, RichReference, rich-reference/preferences).

toolstoolv2.0.4experimentalservernode
@lssm-tech/tools.contractspec-codemods
bun add @lssm-tech/tools.contractspec-codemods
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Codemods + import-graph scan that mechanically migrate consumers of the pre-S-8 rich-reference legacy surface (CodeBlock, DiffBlock, ObjectReferenceHandler/Panel, RichContentReference, rich-code-preferences) to the post-S-8 surface (RichBlock, RichRef, PreviewPanel, RichReference, rich-reference/preferences).

See MIGRATION.md for the full migration guide, before/after examples, and human-follow-up cases.

Quick start

bash
# Discover legacy call sites (writes discovery-list.json)
bun run scripts/discover.ts --roots packages/ --out discovery-list.json

# Dry-run the codemods
bun run scripts/apply.ts --roots packages/ --dry

# Apply the codemods in place
bun run scripts/apply.ts --roots packages/

Codemods

  • codemod-code-block — CodeBlock → <RichBlock kind="code">.
  • codemod-diff-block — DiffBlock → <RichBlock kind="diff"> (incl. DiffBlock.web / DiffBlock.native platform splits).
  • codemod-object-reference — ObjectReferenceHandler → <RichRef> and ObjectReferencePanel → <PreviewPanel>.
  • codemod-rich-content-references — RichContentReference / RichCodeBlockModel / RichDiffBlockModel / redactRichCodeBlock / redactRichDiffBlock → new rich-reference + ui-kit-core equivalents.
  • codemod-personalization-imports — rich-code-preferences subpath → rich-reference/preferences.

Each codemod is pure (string → string) and idempotent. Run them in the canonical STANDARD_CODEMODS pipeline, or call them individually.

Safety

The codemods are regex/string-based with a brace-balanced JSX attribute parser. They use a context scanner that:

  • skips strings, template literals, and comments (so docs-page example template strings stay intact);
  • newline-terminates string scanning (defends against JSX-text apostrophes such as "What you'll build" — JS strings cannot contain raw newlines per spec, so this is correct in addition to defensive);
  • inserts new imports after the last REAL top-level import, never inside a template literal.

CI gate (AC-17)

  • Per-PR: bun run discover is informational; growth should be flagged.
  • Per-release: the migration regression test (__tests__/migration-regression.test.ts) asserts that every entry in discovery-list.json was migrated. Zero hits required to ship.

Files

text
src/
  legacy-symbols.ts        # canonical migration map
  parse-helpers.ts         # safe-span scanner + JSX tag parser
  codemod-runner.ts        # CodemodResult + pipeline helper
  codemod-code-block.ts
  codemod-diff-block.ts
  codemod-object-reference.ts
  codemod-rich-content-references.ts
  codemod-personalization-imports.ts
  import-graph-scan.ts     # AST-ish + string-literal scanner
  index.ts                 # public surface
scripts/
  discover.ts              # writes discovery-list.json
  apply.ts                 # writes codemod output in place
__tests__/                 # fixture tests + migration regression

Relationships

THIS PACKAGEtools.contractspec-codemods10 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

0 declarations

No Runtime dependencies are declared here.

Declared capabilities

This manifest does not declare a capability catalogue. Use the guide, import map and source to assess the package.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • cleanrimraf dist .turbo
  • lintbun run lint:fix
  • lint:fixnode ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../scripts/biome.cjs check .
  • testbun test
  • typechecktsgo --noEmit
  • prebuildcontractspec-bun-build prebuild
  • discoverbun run scripts/discover.ts
  • applybun run scripts/apply.ts
  • scanbun run scripts/scan.ts