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).
@lssm-tech/tools.contractspec-codemodsbun add @lssm-tech/tools.contractspec-codemodsManifest 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
# 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.nativeplatform splits).codemod-object-reference—ObjectReferenceHandler→<RichRef>andObjectReferencePanel→<PreviewPanel>.codemod-rich-content-references—RichContentReference/RichCodeBlockModel/RichDiffBlockModel/redactRichCodeBlock/redactRichDiffBlock→ new rich-reference + ui-kit-core equivalents.codemod-personalization-imports—rich-code-preferencessubpath →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 discoveris informational; growth should be flagged. - Per-release: the migration regression test (
__tests__/migration-regression.test.ts) asserts that every entry indiscovery-list.jsonwas 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 regressionRelationships
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 buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typescleanrimraf dist .turbolintbun run lint:fixlint:fixnode ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .lint:checknode ../../../scripts/biome.cjs check .testbun testtypechecktsgo --noEmitprebuildcontractspec-bun-build prebuilddiscoverbun run scripts/discover.tsapplybun run scripts/apply.tsscanbun run scripts/scan.ts