# @lssm-tech/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). ## Source and release context - Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498` - Repository: `lssm-tech/contractspec` - Declared package version: `2.0.4` - Package path: `packages/tools/contractspec-codemods` - Manifest path: `packages/tools/contractspec-codemods/package.json` - Manifest Git blob: `a63624329b99f5fb76b2821c6d074d31a34db160` - Manifest origin: pinned GitHub manifest fetch - Manual: [@lssm-tech/tools.contractspec-codemods](https://lssm.co/docs/packages/tools.contractspec-codemods/) - Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/) This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review. Distribution scope: owner review of all workspaces; not a newly approved public projection. - [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods) - [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/package.json) - [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/README.md) - [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/tools.contractspec-codemods.txt) ## Package metadata ```json { "layer": "tools", "physicalArea": null, "primaryArea": "tooling-and-agent-delivery", "classification": { "privateDeclared": null, "catalogFamily": "contracts", "catalogKind": "tool", "catalogStatus": "active", "adoptionMode": "operator-only", "stability": "experimental" }, "descriptionOrigin": "package.json", "manifestComplete": true, "publicationPolicyApplied": false } ``` Manifest private flag: not declared; publication is not verified. Primary area: [CLI, authoring and agent tooling](https://lssm.co/docs/areas/tooling-and-agent-delivery/) ## Package guide ```json { "status": "available", "sourcePath": "packages/tools/contractspec-codemods/README.md", "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/README.md", "blobSha": "d99418ce7f8c08d13c2579ca71d60c59954f6710", "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498", "origin": "README recovered byte-for-byte from pinned aggregate guide", "integrity": "exact Git blob match", "executionStatus": "not executed" } ``` The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations. # `@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`](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/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` → ``. - `codemod-diff-block` — `DiffBlock` → `` (incl. `DiffBlock.web` / `DiffBlock.native` platform splits). - `codemod-object-reference` — `ObjectReferenceHandler` → `` and `ObjectReferencePanel` → ``. - `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 ``` ## Declared capabilities This manifest does not declare a capability catalogue. Assess the package using its guide, import map and source. ## Catalogue metadata ```json { "family": "contracts", "kind": "tool", "status": "active", "adoptionMode": "operator-only", "stability": "experimental", "platforms": [ "server" ], "runtimes": [ "node" ], "entrypoints": [ ".", "./codemod-code-block", "./codemod-diff-block", "./codemod-object-reference", "./codemod-personalization-imports", "./codemod-rich-content-references", "./codemod-runner", "./import-graph-scan", "./legacy-symbols", "./parse-helpers" ], "examples": [], "replacements": [], "nonAdoptableRationale": "This tool is published for execution by operators, not as a reusable library dependency." } ``` ## Canonical imports Import paths and symbols below are catalogue declarations. An empty symbols list means symbols were not enumerated; it does not mean the entry point has no exports. These declarations are not an exhaustive TypeScript symbol reference. ```json [] ``` ## Declared export entry points Scope: manifest-declared export entrypoints and catalog-declared imports. Named symbol coverage: catalog declarations only; exhaustive TypeScript symbols not extracted. Installation status: not verified. - `@lssm-tech/tools.contractspec-codemods` — subpath `.` - `unconditional`: `./src/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/src/index.ts); verified source file. - `@lssm-tech/tools.contractspec-codemods/codemod-code-block` — subpath `./codemod-code-block` - `unconditional`: `./src/codemod-code-block.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/src/codemod-code-block.ts); verified source file. - `@lssm-tech/tools.contractspec-codemods/codemod-diff-block` — subpath `./codemod-diff-block` - `unconditional`: `./src/codemod-diff-block.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/src/codemod-diff-block.ts); verified source file. - `@lssm-tech/tools.contractspec-codemods/codemod-object-reference` — subpath `./codemod-object-reference` - `unconditional`: `./src/codemod-object-reference.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/src/codemod-object-reference.ts); verified source file. - `@lssm-tech/tools.contractspec-codemods/codemod-personalization-imports` — subpath `./codemod-personalization-imports` - `unconditional`: `./src/codemod-personalization-imports.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/src/codemod-personalization-imports.ts); verified source file. - `@lssm-tech/tools.contractspec-codemods/codemod-rich-content-references` — subpath `./codemod-rich-content-references` - `unconditional`: `./src/codemod-rich-content-references.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/src/codemod-rich-content-references.ts); verified source file. - `@lssm-tech/tools.contractspec-codemods/codemod-runner` — subpath `./codemod-runner` - `unconditional`: `./src/codemod-runner.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/src/codemod-runner.ts); verified source file. - `@lssm-tech/tools.contractspec-codemods/import-graph-scan` — subpath `./import-graph-scan` - `unconditional`: `./src/import-graph-scan.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/src/import-graph-scan.ts); verified source file. - `@lssm-tech/tools.contractspec-codemods/legacy-symbols` — subpath `./legacy-symbols` - `unconditional`: `./src/legacy-symbols.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/src/legacy-symbols.ts); verified source file. - `@lssm-tech/tools.contractspec-codemods/parse-helpers` — subpath `./parse-helpers` - `unconditional`: `./src/parse-helpers.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/tools/contractspec-codemods/src/parse-helpers.ts); verified source file. ## Package publication metadata These are source-manifest declarations, not a registry installation check. ```json { "types": "./dist/index.d.ts", "files": [ "dist", "README.md", "MIGRATION.md" ], "publishExports": { ".": { "types": "./dist/index.d.ts", "bun": "./dist/index.js", "node": "./dist/node/index.js", "default": "./dist/index.js" }, "./codemod-code-block": { "types": "./dist/codemod-code-block.d.ts", "bun": "./dist/codemod-code-block.js", "node": "./dist/node/codemod-code-block.js", "default": "./dist/codemod-code-block.js" }, "./codemod-diff-block": { "types": "./dist/codemod-diff-block.d.ts", "bun": "./dist/codemod-diff-block.js", "node": "./dist/node/codemod-diff-block.js", "default": "./dist/codemod-diff-block.js" }, "./codemod-object-reference": { "types": "./dist/codemod-object-reference.d.ts", "bun": "./dist/codemod-object-reference.js", "node": "./dist/node/codemod-object-reference.js", "default": "./dist/codemod-object-reference.js" }, "./codemod-personalization-imports": { "types": "./dist/codemod-personalization-imports.d.ts", "bun": "./dist/codemod-personalization-imports.js", "node": "./dist/node/codemod-personalization-imports.js", "default": "./dist/codemod-personalization-imports.js" }, "./codemod-rich-content-references": { "types": "./dist/codemod-rich-content-references.d.ts", "bun": "./dist/codemod-rich-content-references.js", "node": "./dist/node/codemod-rich-content-references.js", "default": "./dist/codemod-rich-content-references.js" }, "./codemod-runner": { "types": "./dist/codemod-runner.d.ts", "bun": "./dist/codemod-runner.js", "node": "./dist/node/codemod-runner.js", "default": "./dist/codemod-runner.js" }, "./import-graph-scan": { "types": "./dist/import-graph-scan.d.ts", "bun": "./dist/import-graph-scan.js", "node": "./dist/node/import-graph-scan.js", "default": "./dist/import-graph-scan.js" }, "./legacy-symbols": { "types": "./dist/legacy-symbols.d.ts", "bun": "./dist/legacy-symbols.js", "node": "./dist/node/legacy-symbols.js", "default": "./dist/legacy-symbols.js" }, "./parse-helpers": { "types": "./dist/parse-helpers.d.ts", "bun": "./dist/parse-helpers.js", "node": "./dist/node/parse-helpers.js", "default": "./dist/parse-helpers.js" } } } ``` ## Dependencies Metadata status: complete pinned manifest. ### Runtime dependencies No declarations in the inspected manifest. ### Peer dependencies No declarations in the inspected manifest. ### Optional dependencies No declarations in the inspected manifest. ### Development dependencies - [@lssm-tech/tool.bun](https://lssm.co/docs/packages/tool.bun/): `workspace:*` - [@lssm-tech/tool.typescript](https://lssm.co/docs/packages/tool.typescript/): `workspace:*` - `typescript`: `catalog:` ### Peer dependency metadata ```json {} ``` ### Bundled dependencies ```json null ``` ## Package scripts Commands are exact manifest declarations and were not executed in this review. Script metadata status: complete pinned manifest. ```json { "build": "contractspec-bun-build build", "build:bundle": "contractspec-bun-build transpile", "build:types": "contractspec-bun-build types", "clean": "rimraf dist .turbo", "lint": "bun run lint:fix", "lint:fix": "node ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .", "lint:check": "node ../../../scripts/biome.cjs check .", "test": "bun test", "typecheck": "tsgo --noEmit", "prebuild": "contractspec-bun-build prebuild", "discover": "bun run scripts/discover.ts", "apply": "bun run scripts/apply.ts", "scan": "bun run scripts/scan.ts" } ``` ## Declared documentation links - [Tools Contractspec Codemods documentation](https://www.npmjs.com/package/%40lssm-tech%2Ftools.contractspec-codemods) — declared link; destination not verified. ```json { "url": "https://www.npmjs.com/package/%40lssm-tech%2Ftools.contractspec-codemods", "kind": "readme" } ``` ## Existing agent-guide projection ```json { "path": "packages/apps/web-landing/public/llms-packages/tools.contractspec-codemods.txt", "route": "/llms/tools.contractspec-codemods", "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/tools.contractspec-codemods.txt", "blobSha": "d99418ce7f8c08d13c2579ca71d60c59954f6710", "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498", "bodyEqualsReadme": true, "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt", "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf" } ```