---
robots: noindex, nofollow
tags: pitch
---

For instructions on shaping a project see here: [Shaping a Project](/kX02SXVbS6KzMOQd56i6Cg)

# CodeMods - May

### Problem
*From: [Problem guidance](https://basecamp.com/shapeup/1.5-chapter-06#ingredient-1-problem)*
*The best problem definition consists of a single specific story that shows why the status quo doesn’t work.*
A user wants to upgrade to the latest version of fluent-ui, but there are a few substantial breaking changes. While the user can go through and modify their code, it will be time consuming and tedious and will prevent adoption.

### Appetite
*From: [Appetite guidance](https://basecamp.com/shapeup/1.5-chapter-06#ingredient-2-appetite)*
3 weeks. This project encompases a group of fairly simple, yet significant changes. The combined work will likely take 3 weeks.

### Solution
A set of tools built with [ts-morph](https://ts-morph.com/) to solve the following:
1. Framework for testing codemods
2. Applying codemods to a group of files
1. Based on path/blob
2. Based on the ts.config file
* Example CLI to run codemods `npx migration.js <path to tsconfig>`
3. A way to choose which codemods should run
1. MVP: manually enter all codemod names in a json file
2. Codemods based on name
3. Codemods based on some function
5. Utilities that enable
1. Flagging pieces of code that are probablmatic, but cannot be fixed.
2. Finding of jsx elements
3. Replacing/renaming props of JSX elements (excluding edge cases)
4. Renaming JSX components
5. Repathing imports
6. Flagging bad imports
* "Flagging" should be accomplished by placing an easy to identify comment that owners can quickly search for
6. Document undocumented TS-morph functionality to make it easy for users to write their own mods.

Example codemod

    
import {
  SourceFile
} from "ts-morph";
import { utilities } from "../utilities/utilities";

const searchString=/^office\-ui\-fabric\-react/;
const newString = '@fluentui/react';

// This should replace ALL office-ui-fabric-react imports with @fluentui/react
export function RepathOfficeToFluentImports(file: SourceFile) {
  let imports = utilities.getImportsByPath(file, searchString);
  imports.forEach(val => {
    utilities.repathImport(val, newString, searchString);
  })
}

### Risks (Rabbit holes)
*From: [Rabbit hole guidance](https://basecamp.com/shapeup/1.5-chapter-06#ingredient-4-rabbit-holes)*
* Trying to solve all cases: There are no shortage of edge cases that the codemods will encounter. We should endevour to solve only the most common cases. If an edge case cannot be solved, flagging it agressively to help users find and fix the problems is an ideal compromise.
* Additionally, it is much more problematic for users to fix **badly modified** code than it is to manually deal with flagged areas of code. Prioritize identification over making risky changes.
* Abstracting too much. TS-morph already provides a large level of abstraction. Lean into it and provide documentation when necessary to enable users to write their own mods with it.

### Out of scope (No-gos)
*From: [No-gos guidance](https://basecamp.com/shapeup/1.5-chapter-06#ingredient-5-no-gos)*
Right now we don't need to worry about a complicated command line or visual user interface. Codemods should be easy to run and we can always tell users to `git revert` in the short term rather than providing a more robust CI option.