Slides for my EmberConf 2021 presentation on writing crossfile codemods.

1. Crossfile Codemodding
with Joshua Lawrence

2. Joshua Lawrence
Sr. Software Engineer @LinkedIn
Developer Experience Team
Centralized Release Tool “CRT” - Internal CI/CD UI
Working with Ember for six years
Codemod n00b

3. Native
Classes
Engines
Angle
Brackets
Qunit
ES6
Modules
PODs

5. CHECKING
TYPE
ARGUMENT

6. Life Without Component Argument Type Checking
// ember-mascot usage
<EmberMascot @name={{this.name}} @likes={{this.likes}} />
Are there any other args
that I can/should provide?
Is this a number? Boolean?
An array of strings?
Probably a string

7. // ember-mascot.hbs
<p>{{this.name}}</p>
<p>{{this.likeCount}}</p>
<ul>
{{#each this.likes as |like|}}
<MascotLike @like={{like}} />
{{/each}}
</ul>
Life Without Component Argument Type Checking
Is this an argument with a default value
or a computed prop?
What is this an array of?

8. JSDoc Basic information for devs, but became
inaccurate over time
Verbose and lacks some features of argument
decorators
Uses modern patterns, is powerful and flexible,
doesn’t distract from component logic
ember-prop-types
ember-decorators/argument

9. Type Checking via “ember-decorators/argument”
// ember-mascot.hbs
<p>{{this.name}}</p>
<p>{{this.likeCount}}</p>
<ul>
{{#each this.likes as |like|}}
<MascotLike @like={{like}} />
{{/each}}
</ul>
// ember-mascot.js
export default class EmberMascot extends Component {
@argument(‘string’)
name = ‘’;
@argument(‘number’)
likeCount = 0;
@argument(shapeOf({
user: ‘string’,
date: Date
}))
likes;
}

11. Ditch type checking?
Brute force update?
Regex find and replace?
Stay on Ember 3.12 forever?
?

12. Ember.js Skill
GitHub Followers
Commits
Robert Jackson
@rwjblue
Chris Garrett
@pzuraq
Disclaimer: These stats are completely made up, but these guys are legit

13. ember-
argument-types
github.com/pzuraq/ember-
argument-types
// ember-mascot.hbs
{{arg-type @name (optional “string”)}}
{{arg-type @likeCount (optional “number”)}}
{{arg-type @likes (array-of
(shape-of
user=“string”
date=“date”
))
}}
<p>{{this.name}}</p>
<p>{{this.likeCount}}</p>
<ul>
{{#each this.likes as |like|}}
<MascotLike @like={{like}} />
{{/each}}
</ul>

14. ember-codemods
github.com/ember-codemods

16. jscodeshift
github.com/facebook/
jscodeshift
jscodeshift is a toolkit for running
codemods over multiple JavaScript or
TypeScript files.
…bring your own docs.

17. Input
source code
Mutate AST
Parse into
an AST
Convert to
source
and save
Lifecycle of a codemod

18. HTML DOM
JS AST

19. Can you codemod from
one file to another?
JS JS
HBS

20. codemod-cli project
Three transforms are better than one
Map
Decorators
to
JSON
Use JSON
to build
Template
Helpers
Remove
Argument
Decorators
JSON HBS JS

21. // argument-decorators.input.js
class Foo extends Component {
@argument(‘string’)
stringArg;
@argument(‘number’)
numberArg;
}
Transform 1 - Input/Output
// argument-decorators.map.json
{
“argument-decorators.input”: {
“path”: “path/to/file”,
“args”: {
“stringArg”: {
“type”: “StringLiteral”,
“value”: “string”
},
“numberArg”: {
“type”: “StringLiteral”,
“value”: “number”
},
}
}
}

22. // argument-types.input.hbs
<p>{{@stringArg}}</p>
<p>{{@numberArg}}</p>
Transform 2 - Input/Output
// argument-types.output.js
{{arg-type @stringArg “string”}}
{{arg-type @numberArg “number”}}
<p>{{@stringArg}}</p>
<p>{{@numberArg}}</p>

23. // argument-decorators.input.js
class Foo extends Component {
// This is a string arg
@argument(‘string’)
stringArg;
// This is a number arg
@argument(‘number’)
numberArg;
}
Transform 3 - Input/Output
// argument-decorators.output.js
class Foo extends Component {
// This is a string arg
stringArg;
// This is a number arg
numberArg;
}

24. Convert
Decorators
to
JSON
Use JSON

31. > codemod-cli new <project-name>
> codemod-cli generate codemod <codemod-name>
> codemod-cli generate fixture <codemod-name> <fixture-name>

32. // codemod-cli project transform
input.find(j.ClassBody).forEach((classBody) => {
classBody.value.body.filter((classProp) => {});B
});A
Transform 1: Decorators to JSON
// AST Explorer: Input
class Foo extends Component {
@argument(‘string’)
stringArg;
}
// AST Explorer: Parsed AST
class Foo extends Component {
@argument(‘string’)
stringArg;
}

33. // codemod-cli project transform
input.find(j.ClassBody).forEach((classBody) => {
classBody.value.body.filter((classProp) => {});B
});A
Transform 1: Decorators to JSON
// AST Explorer: Input
class Foo extends Component {
@argument(‘string’)
stringArg;
}
// AST Explorer: Parsed AST
class Foo extends Component {
@argument(‘string’)
stringArg;
}

34. // codemod-cli project transform
input.find(j.ClassBody).forEach((classBody) => {
classBody.value.body.filter((classProp) => {});B
});A
Transform 1: Decorators to JSON
// AST Explorer: Input
class Foo extends Component {
@argument(‘string’)
stringArg;
}
// AST Explorer: Parsed AST
class Foo extends Component {
@argument(‘string’)
stringArg;
}

35. // codemod-cli project transform
input.find(j.ClassBody).forEach((classBody) => {
classBody.value.body.filter((classProp) => {});B
});A
Transform 1: Decorators to JSON
// AST Explorer: Input
class Foo extends Component {
@argument(‘string’)
stringArg;
}
// AST Explorer: Parsed AST
class Foo extends Component {
@argument(‘string’)
stringArg;
}

36. // codemod-cli project transform
input.find(j.ClassBody).forEach((classBody) => {
classBody.value.body.filter((classProp) => {});B
});A
Transform 1: Decorators to JSON
// AST Explorer: Input
class Foo extends Component {
@argument(‘string’)
stringArg;
}
// AST Explorer: Parsed AST
class Foo extends Component {
@argument(‘string’)
stringArg;
}

37. // codemod-cli project transform
input.find(j.ClassBody).forEach((classBody) => {
classBody.value.body.filter((classProp) => {
return classProp.decorators.some((decorator) => {});C
});B
});A
Transform 1: Decorators to JSON
// AST Explorer: Input
class Foo extends Component {
@argument(‘string’)
stringArg;
}
// AST Explorer: Parsed AST
class Foo extends Component {
@argument(‘string’)
stringArg;
}

38. // codemod-cli project transform
input.find(j.ClassBody).forEach((classBody) => {
classBody.value.body.filter((classProp) => {
return classProp.decorators.some((decorator) => {
return (
decorator.expression.type === 'CallExpression' &&
(decorator.expression.callee.name === 'type' ||
decorator.expression.callee.name === 'argument')
);
});C
});B
});A
Transform 1: Decorators to JSON
// AST Explorer: Input
class Foo extends Component {
@argument(‘string’)
stringArg;
}
// AST Explorer: Parsed AST
class Foo extends Component {
@argument(‘string’)
stringArg;
}

39. // codemod-cli project transform
input.find(j.ClassBody).forEach((classBody) => {
classBody.value.body.filter((classProp) => {
return classProp.decorators.some((decorator) => {
return (
decorator.expression.type === 'CallExpression' &&
(decorator.expression.callee.name === 'type' ||
decorator.expression.callee.name === 'argument')
);
});C
}).forEach(parseDecoratorArgs);B
});A
Transform 1: Decorators to JSON
// AST Explorer: Input
class Foo extends Component {
@argument(‘string’)
stringArg;
}
// AST Explorer: Parsed AST
class Foo extends Component {
@argument(‘string’)
stringArg;
}

40. // codemod-cli project transform
input.find(j.ClassBody).forEach((classBody) => {
classBody.value.body.filter((classProp) => {
return classProp.decorators.some((decorator) => {
return (
decorator.expression.type === 'CallExpression' &&
(decorator.expression.callee.name === 'type' ||
decorator.expression.callee.name === 'argument')
);
});C
}).forEach(parseDecoratorArgs);B
});A
fs.writeFileSync(
‘map.json’,
JSON.stringify(parsedDecorators, null, 2),
{ encoding: ‘utf8' }
);
Transform 1: Decorators to JSON
// AST Explorer: Input
class Foo extends Component {
@argument(‘string’)
stringArg;
}
// AST Explorer: Parsed AST
class Foo extends Component {
@argument(‘string’)
stringArg;
}

41. Multiple codemod passes with increasing scope
Test Fixtures
One Component
Directory with a
few components
All components

42. Convert
Decorators
to build
Template
Helpers
Remove

52. Argument
Decorators
JSON HBS JS

53. import { argument } from '@ember-
decorators/argument';
class Foo extends Component {
// This is a string arg
@someUnrelatedDecorator
@argument(‘string’)
stringArg;
}
Remove Argument Decorators
class Foo extends Component {
// This is a string arg
@someUnrelatedDecorator
stringArg;
}

54. Putting them all together
Map
Decorators
to
JSON
Use JSON
to build
Template
Helpers
Remove
Argument
Decorators
JSON HBS JS

55. github.com/ember-decorators/
argument-codemod
ember-decorators/
argument-codemod
> npx @ember-decorators/argument-codemod decorators-to-json ./app/components
> npx @ember-decorators/argument-codemod json-to-template ./app/templates/components
> npx @ember-decorators/argument-codemod decorators-cleanup ./app/components

56. Almost there…

57. Ember 3.20 Octane

58. Takeaways
Your code(mod)
doesn’t need to
be perfect
Sometimes you
have to be the
one to fix it
Don’t stop
at one
Opportunities to
improve tooling

59. THANK YOU!
Resources
https://github.com/ember-decorators/argument-codemod
https://github.com/pzuraq/ember-argument-types
https://github.com/rwjblue/codemod-cli
https://github.com/facebook/jscodeshift
https://github.com/ember-codemods
jwlawrence joshlawrence jlaw