chore: update README.md (#32)

Author: valerybugakov

src/cli.ts

@@ -18,18 +18,20 @@ program
     .addOption(
         new Option('-t, --transform <transform>', 'Transform name').choices(transformNames).makeOptionMandatory()
     )
+    // TODO: make it `true` by default after switching to bulk format.
+    .option('-f, --format [format]', 'Format Typescript source files with ESLint', false)
     .option('-w, --write [write]', 'Persist codemod changes to the filesystem', false)
     .argument('<fileGlob>', 'File glob or globs to change files based on')
     .action(async (fileGlob: string, options: CodemodCliOptions) => {
-        const { write: shouldWriteFiles, transform } = options
+        const { write: shouldWriteFiles, format: shouldFormat, transform } = options
         const projectGlob = path.isAbsolute(fileGlob) ? fileGlob : path.join(process.cwd(), fileGlob)
 
         signale.start(`Starting codemod "${transform}" with project glob "${projectGlob}"`)
 
         const project = new Project()
         project.addSourceFilesAtPaths(projectGlob)
 
-        const results = await transforms[transform]({ project, shouldWriteFiles })
+        const results = await transforms[transform]({ project, shouldWriteFiles, shouldFormat })
 
         if (results) {
             if (shouldWriteFiles) {

src/transforms/globalCssToCssModule/README.md

@@ -12,6 +12,36 @@ Convert globally scoped stylesheet tied to the React component into a CSS Module
 
 ## Usage
 
+See available commands and options:
+
+```sh
+yarn transform --help
+```
+
+Apply codemod:
+
 ```sh
 yarn transform -t globalCssToCssModule --write true "/client/web/src/search/**/*.tsx"
 ```
+
+To automatically fix formatting in the updated React components use the `--format true` flag.
+
+```sh
+yarn transform -t globalCssToCssModule --write true --format true "/client/web/src/search/**/*.tsx"
+```
+
+Currently, it's quite slow because a new ESLint instance is initialized for each file. Consider running `eslint --fix` after the codemod if you're changing a lot of files in one command.
+
+## Post codemod steps in the Sourcegraph repo
+
+1. Remove global styles import from the codebase: `@import 'DeletedGlobalStylesFile';`.
+2. Check "Unused CSS classes" reported in the CLI output. These are classes that exist in the CSS module but were not found in the adjacent React component.
+   1. Remove redundant CSS classes from the CSS module.
+   2. Fix classes used outside of the component by using CSS module there or convert them to props to eliminate the implicit dependency.
+3. Double-check the usage of the deleted global CSS classes in integration tests or other stylesheets.
+   1. If global CSS class is used in the integration test — add `data-testid="some-name-here"` to the relevant JSX element and use `[data-testid="some-name-here"]` selector in the integration test.
+4. Fix usage of the global SCSS variables in the CSS module:`color: $success; -> color: var(--success);`
+   1. If CSS variable doesn't exist — add it next to the SCSS variable: `$spacer: 1px; -> $spacer: 1px; :root { --spacer: #{$spacer}; }`
+5. Double-check that the `:global(...)` selector usage in the created CSS module is correct.
+6. Run `yarn test -u` to update Jest snapshots.
+7. Run `eslint --fix` to update the Typescript source files formatting if `--format` flag was not used in the codemod command.

src/transforms/globalCssToCssModule/__tests__/globalCssToCssModule.test.ts

@@ -10,7 +10,7 @@ describe('globalCssToCssModule', () => {
     it('transforms correctly', async () => {
         const project = new Project()
         project.addSourceFilesAtPaths(TARGET_FILE)
-        const codemodResults = await globalCssToCssModule({ project })
+        const codemodResults = await globalCssToCssModule({ project, shouldFormat: true })
 
         expect(codemodResults).toBeTruthy()
 

src/transforms/globalCssToCssModule/globalCssToCssModule.ts

@@ -25,7 +25,7 @@ import { transformComponentFile } from './ts/transformComponentFile'
  *
  */
 export async function globalCssToCssModule(options: CodemodOptions): CodemodResult {
-    const { project, shouldWriteFiles } = options
+    const { project, shouldWriteFiles, shouldFormat } = options
     /**
      * Find `.tsx` files with co-located `.scss` file.
      * For example `RepoHeader.tsx` should have matching `RepoHeader.scss` in the same folder.
@@ -75,7 +75,9 @@ export async function globalCssToCssModule(options: CodemodOptions): CodemodResu
             moduleSpecifier: `./${path.parse(cssModuleFileName).base}`,
         })
 
-        formatWithPrettierEslint(tsSourceFile)
+        if (shouldFormat) {
+            formatWithPrettierEslint(tsSourceFile)
+        }
         const formattedCssModuleSource = await formatWithStylelint(cssModuleSource, cssFilePath)
 
         /**

src/transforms/globalCssToCssModule/ts/getClassNameNodeReplacement.ts

@@ -92,12 +92,14 @@ export function getClassNameNodeReplacement(
     if (
         parentKind === SyntaxKind.ConditionalExpression ||
         parentKind === SyntaxKind.CallExpression ||
-        parentKind === SyntaxKind.BinaryExpression
+        parentKind === SyntaxKind.BinaryExpression ||
+        parentKind === SyntaxKind.VariableDeclaration
     ) {
         // Replace one class string inside of `ConditionalExpression` with the `exportName`.
         // className={classNames('d-flex', isActive ? 'kek' : 'pek')} -> className={classNames('d-flex', isActive ? styles.kek : 'pek')}
         return { isParentTransformed: false, replacement: replacementWithoutBraces }
     }
+
     if (parentKind === SyntaxKind.JsxAttribute) {
         const replacement = ts.factory.createJsxExpression(undefined, replacementWithoutBraces)
 

src/types/index.ts

@@ -18,4 +18,6 @@ export interface CodemodOptions {
     project: Project
     /** If `true` persist changes made by the codemod to the filesystem. */
     shouldWriteFiles?: boolean
+    /** If `true` format Typescript source files with `prettier-eslint`. */
+    shouldFormat?: boolean
 }