Skip to content

feat(gamut-codemods): add a color-roles preset - #53

Open
dreamwasp wants to merge 80 commits into
mainfrom
cass-gmt-1825-color-codemod
Open

dreamwasp wants to merge 80 commits into
mainfrom
cass-gmt-1825-color-codemod

Conversation

@dreamwasp

@dreamwasp dreamwasp commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Overview

Adds a color-roles preset that moves Gamut color names onto the generated system's roles, using design's migration map. Presets can now have their own manifest, pre-filter and leftovers report; scope-swap's behavior is unchanged.

Framework

  • lib/types.ts, lib/run-source.ts, presets/index.ts — Preset<M> and the migration types are generic over their manifest, defaulting to scope-swap's. A preset brings its own mentions pre-filter and an optional leftovers report.
  • cli.ts, transform.ts, presets/scope-swap — call those hooks; scope-swap passes the pre-filter and leftovers report the CLI used to call directly.
  • __tests__/manifest.test.ts, fixtures.test.ts — the export check covers manifests that promise exports; end-to-end fixtures for other presets live in __tests__/__testfixtures__/<preset>/.

color-roles

  • migrations/color-roles — one splice migration. Rename and merge rows are applied. Split, retired and pending names stay (they still fail the type check), with a /* color-roles: … */ comment carrying design's rule and a warning. Old palette names and runtime-built names (${variant}-hover) only warn.
  • Positions: the ten color props in JSX and style objects (ternaries, &&, responsive values), theme.colors.x / ['x'], themed('colors.x'). variant="primary" and other look-alike strings are left alone.
  • presets/color-roles — the manifest (32 aliases, 43 roles, 104 old palette names), a leftovers report of unresolved color-roles: comments, the checklist. aliases.ts is generated from gamut-styles colorSystem/migration.ts.

Tests and docs

  • Three fixture cases (JSX, style objects, manual kinds), each checked for idempotence, and color-roles-manifest.test.ts: every applied row names exactly one real role.
  • README.md — running color-roles, what it changes, its limits.

PR Checklist

  • Related to designs: gamut-sandbox PR #34 (migration map at c363244)
  • Related to JIRA ticket: GMT-1825
  • Changeset added (or empty changeset if no release)
  • I have run this code to verify it works
  • This PR includes unit tests for the code change
  • This PR includes testing instructions for the code change
  • Package previews from this PR are passing end-to-end tests in all relevant consuming repositories

Testing Instructions

  1. yarn nx test gamut-codemods → 136 tests pass.

  2. yarn nx build gamut-codemods, then node packages/gamut-codemods/dist/bin.js list → color-roles is listed.

  3. Dry run over gamut: node packages/gamut-codemods/dist/bin.js color-roles packages/gamut/src --dry. On feat(gamut-styles)!: brands, overrides and Original Codecademy on the color system #52's branch: 60 files, 171 warnings, 0 errors.

  4. For real, on a scratch copy: run it twice. The second run changes nothing. On feat(gamut-styles)!: brands, overrides and Original Codecademy on the color system #52's branch, gamut's type errors go from 284 to 145.

  5. Check out https://github.skillsoft.com/skillsoft-common/gamut-sandbox/pull/53 which combines all of the current PRs and runs this codemod

  6. Dry run over a real app with build output: node packages/gamut-codemods/dist/bin.js color-roles <app> --dry on cc/mono → no hits under .next/, and no errors.

Fixes from the mono dry run

A dry run of color-roles on cc/mono reported 7 errors, and its hits included build output. Before this commit, the source run skipped only node_modules, dist and build.

  • Build output. Six of the seven errors were parse failures on .next/ chunks, and the scan read minified bundles. The source run now uses the same skip list as the file walk (node_modules, dist, build, coverage, .next, .nx, tmp, .git). Result on mono: no hits under .next/; ok files 833 → 635.
  • The seventh error. apps/reverse-proxy-worker/worker-configuration.d.ts is a tracked, generated Cloudflare types file. Its quoted 'text' (a KV type argument) passed the pre-filter, and Babel rejects export { _EmailMessage as EmailMessage } inside declare module. Generated files are now skipped by name (GENERATED_FILES: worker-configuration.d.ts, next-env.d.ts) in the source run and the file walk. Result on mono: 0 errors, 635 ok.
  • tsconfig-dom warnings now fire only for a tsconfig whose directory imports gamut. Three of the five it reported (enterprise-data-worker, reverse-proxy-worker, le-container-scripts) import no gamut.
  • Left as they were: next-config (its four apps import gamut, so the flag is real); the four stylesheet hits under libs/le-shared (tracked source); and scope-swap (no-op on mono). No resolutions block is added: the README's preview step stays the user's job.
  • Not done: the [color-roles] warnings are still one per occurrence (1,738 on mono). Grouping them is a follow-up.

Known gap: aliases.ts is a generated copy of design's map, and the generator (gen-manifest.ts) still lives outside the repo, because this branch and #50 don't share gamut-styles yet. It should move in and read the workspace package once they do.

🤖 Generated with Claude Code

dreamwasp and others added 30 commits October 20, 2026 10:07
…eset

Adds @skillsoft/gamut-codemods: the CLI (clean-tree guard, --dry, --only,
--no-report, --force), the runner for ast, splice, and file migrations,
the shared helpers (module-string finder, leftovers report, version-range
checks, flat ESLint config detection), the preset registry, and the
fixture harness.

The scope-swap preset has its package map but no migrations yet, so a run
only reports the lines that still name an old package. Each breaking
change lands its migration in its own PR.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…swap

scope-rename swaps @Codecademy/gamut* and eslint-plugin-gamut for their
@SkillSoft names in every module position and in comments. package-json,
mdx-imports, and yarnrc cover dependencies, MDX ESM blocks, and
.yarnrc.yml lists.

@codecademy/gamut-kit has no replacement, so package-json and mf-shared
expand it into the packages it bundled. In Module Federation config that
makes Gamut a real singleton, which the checklist calls out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ides

moved-exports moves Video and VideoProps from the root to
@Codecademy/gamut/Video (scope-rename then swaps the scope).
markdown-video-overrides adds explicit iframeOverride/videoOverride to
each <Markdown>, since it no longer renders video through Video by
default, and drops the removed skipDefaultOverrides keys. tsconfig-dom
warns about tsconfigs without "dom", which Video used to supply.

On the Gamut side, a Video/package.json stub makes the subpath resolve
under node10, MarkdownVideo no longer passes NaN sizes, and a one-line
<video> is no longer wrapped in a <p>.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ectDropdown elements

Exports formFieldStyles, formFieldPaddingStyles, conditionalStyles,
ButtonBaseProps, HTMLToReactNode, MenuToolTipWrapper, and Menu's list
elements from the root. The list elements and SelectDropdown's option
component are renamed (MenuList*, MenuListButton, IconOptionComponent) so
they don't collide with the public List component and IconOption type.

The deep-imports codemod rewrites known /dist/ paths to the root, keeps
local names across renames, merges into existing imports, and warns on
paths with no public replacement.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
eslint-comments rewrites gamut/ directives to @skillsoft/gamut/, and
eslint-config updates the plugin name, plugin: extends, and rule keys in
legacy .eslintrc files. Under a flat config the prefix is the plugins key,
so eslint-comments skips itself and the checklist explains why.

Also types eslint-plugin-gamut's recommended severities as literals, so the
plugin fits ESLint's Plugin type in a typed flat config.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@skillsoft/gamut ships strict-ESM .mjs. With experimental.esmExternals
off, Next require()s server externals and default imports from
@emotion/styled and react-select break while it collects page data.
next-config is report-only: dropping the flag can take other config with
it, so it warns and adds a checklist item instead of rewriting.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ap-skill

# Conflicts:
#	packages/gamut-codemods/README.md
#	packages/gamut-codemods/src/presets/scope-swap/index.ts
# Conflicts:
#	packages/gamut-codemods/README.md
#	packages/gamut-codemods/src/__tests__/lib.test.ts
#	packages/gamut-codemods/src/presets/scope-swap/index.ts
…p-skill

# Conflicts:
#	packages/gamut-codemods/README.md
#	packages/gamut-codemods/src/__tests__/cli.test.ts
#	packages/gamut-codemods/src/presets/scope-swap/index.ts
The skill works alongside the scope-swap codemod: it reads the warnings,
leftovers, and next steps, and helps with what the codemod can't rewrite.
BREAKING_CHANGES.md lists every change in the move, and
NEXT_EMOTION_INTEROP.md covers the Next.js esmExternals fallback.

Also restores the end-to-end and MDX fixtures that run every migration
together, and fixes the cli.test merge between the sibling branches.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CodeQL read `migration.match(file)` in cli.ts as String.prototype.match
on a command-line argument and flagged js/regex-injection. Nothing builds
a regex from the path; the method just had the same name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…migrations

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…migrations

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…migrations

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…migrations

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The package-json warning already names each range that's newer than the
fork point, so the extra next step only repeated it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rkdown

# Conflicts:
#	packages/gamut-codemods/src/presets/scope-swap/index.ts
# Conflicts:
#	packages/gamut-codemods/src/presets/scope-swap/index.ts
# Conflicts:
#	packages/gamut-codemods/src/presets/scope-swap/index.ts
…swap-skill

# Conflicts:
#	packages/gamut-codemods/src/presets/scope-swap/index.ts
dreamwasp and others added 24 commits November 18, 2026 11:21
…fig-dom to gamut users

The source run skipped only node_modules, dist and build, so a color-roles
dry run in an app read its .next output: minified chunks that don't parse,
and 2,000+ warnings about bundle text. It now uses the same skip list as the
file walk (adds .next, .nx, coverage, tmp).

tsconfig-dom warned about every tsconfig that set lib without dom, including
workers that never imported gamut. It now warns only where the directory
imports gamut. The file migration context gets usesGamut() for that.

Tests: the fake runner honors ignorePattern, and cli tests cover build output
and the tsconfig scoping. Fixtures pass usesGamut.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
worker-configuration.d.ts (wrangler types) is rejected by Babel: its
declare module block exports a let. It matched the color pre-filter on a
KV 'text' type argument, so it was the last error in a mono dry run. Files
a tool rebuilds are now skipped in the source run and the file walk, by
name (GENERATED_FILES: worker-configuration.d.ts, next-env.d.ts).

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
The skill triaged scope-swap only. Add a color-roles section: the dry-run and
real-run steps, what the warnings and color-roles: comments mean and what to
do for each, the checks before calling it done, and what not to do. The
description names the preset so the skill triggers on color-name work.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 6f0e3de)
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
…on and cover every preset

The skill covered scope-swap only. It's now gamut-migration: a presets table,
one workflow for all presets, a section per preset (scope-swap, color-roles),
and a section on documenting a new preset. Renames the changeset to match.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit f5bf30b)
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 15c7699)
…section

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 80522ce)
- scope-swap manifest gains requiredPeers: @vidstack/react and react-player for @skillsoft/gamut, stylis for @skillsoft/gamut-styles. package-json adds any that an app needs and doesn't list, at the range the package declares. manifest.test checks each range against the source package.json.
- The CoreTheme comment and warning no longer tell every app to use SkillsoftTheme. It is the type for brand themes; the theme stays a per-app choice because it changes the spacing scale.
- Changeset notes the peers and the spacing-scale difference between themes.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
…re used

- Old palette names get a color-roles: comment in front of the site, not only a terminal warning, so the review queue is in the code and the leftovers report lists it. Stylesheet hits and runtime-built names follow the same rule.
- The message names the context: the prop, the style key, a theme.colors or themed() lookup, or a CSS variable. The same palette name is a fill in one place and text in another.
- The comment uses the plain name, not --color-<name>, so a second run doesn't match the marker's own text as an old variable.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
…ion skill

- next-config: removing esmExternals: false is necessary but not always enough. Build each app and fix the routes that still fail at prerender.
- CI: the job that runs sync-gamut-deps fails too, so change it with the script.
- resolutions: yarn why can list two lock locators after a pin, with one copy installed. Check node_modules.
- tsconfig-dom: the codemod warns only where gamut is imported.
- Missing peers: @vidstack/react, react-player and stylis, with the range to add by hand.
- color-roles: a palette name can map to different roles by slot, so use the context in the comment. Keep each app's theme, since the choice changes the spacing scale.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit a0f18dc)
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
…lette names

- decisions.ts holds the defaults, outside the generated alias table: red becomes an error role and green a success role by use (fill, text, border); white becomes surface-raised, text-inverse or border-subtle; navy takes the nearest role by brightness in each family. Dark navy fills stay warnings for design.
- A default is applied only in a color prop, where the use is known. Theme lookups and CSS variables are still warned.
- Bare white joins the palette list, since it's the most common white use.
- Tests: each default names a role the system has, and unknown uses fall back to a warning.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
…gration skill

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit bb684b9)
…igration skill

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit b35dc09)
Hyper is the old primary, so fills, text and borders take action-primary. Yellow stays a warning, since its role depends on the brand.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
blue-500 is admin's light-mode primary. Its text is links and focus, so it takes action-primary. Fills and borders mix interactive and decorative uses, so they stay warnings.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
… skill

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 552d148)
…ser in the gamut-migration skill

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 7d92c95)
The greys are neutral, so a brightness match would make mid-grey text light ink. Fills follow lightness, grey text is text-subtle, and borders follow weight. Light grey text stays a warning.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
…ate-stylis symptom

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 0dc47cf)
@emotion/cache brings its own stylis. The root copy the codemod added can sit at a different version from emotion's, and a duplicate is suspected to break style inserts (reading 'push'). The codemod now adds only @vidstack/react and react-player.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
…t import Video

Those two peers only load for Video, so package-json adds them when the source imports Video from gamut (through the Video subpath, or a Video name from the root). Apps that don't use Video don't get them. The context is memoized per directory, like usesGamut.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 53cce61)
Moved tests follow main's colocated layout. The codemod suite passes (151 tests).

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
dreamwasp added a commit that referenced this pull request Nov 20, 2026
Replaces this branch's tree with the color stack as it now stands: the
site branch (#67, which includes #63, #59, #54, #66, #58, #52 and #50,
each merged with main through 45586df), plus the codemod branch (#53).
Static styles (#69) is still out, as before.

The preview's earlier head is the parent. This commit only moves the
tree forward, so nothing is rewritten.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
dreamwasp and others added 3 commits November 20, 2026 11:34
The deep-import checks build a TypeScript program over the built packages.
They take about 1s alone, but ran past the 15s limit in CI, where nx runs the
package tests in parallel on a cold cache.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant