tools.contractspec-codemods

@lssm-tech/tools.contractspec-codemods

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

# 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

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