- Notifications
You must be signed in to change notification settings - Fork5
A platform for running codemods based on runtime information
License
dyfactor/dyfactor
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Dyfactor is platform for writing and executing profile-guided codemods. By combining runtime information and static analysis, applications are able migrate codebases to new APIs at a much quicker pace.
See Dyfactor In Action
$ yarn global add dyfactor
$ yarn dyfactor --help Usage: dyfactor [options] [command] Options: -h, --help output usage information Commands: init Initializes dyfactorin your project run Runs a plugin against code list-plugins Lists the available pluginshelp [cmd] displayhelpfor [cmd]
Tools like JSCodeShift and Babel are excellent tools for migrating code from one API to another due to the fact they rely on static analysis. However, it is completely possible for parts of an application to be relying on runtime information to determine execution. In other cases you may have custom DSLs like template languages that don't have the same static analysis guarantees as JavaScript does. Migrating this type of code typically requires a great deal of developer intervention to sort out what is actually happening. Dyfactor's goal is to shorten this crevasse of understanding.
In Ember's template layer developers can invoke components with arguments. They also can look at local values on the backing class. A template for a component may look like the following.
<h1>{{firstName}}{{lastName}}</h1><h2>Info</h2><ul> <li>Posts:{{postCount}}</li> <li>Shares:{{shareCount}}</li></ul>
While this template is declarative, it's not obvious if any of theMustacheExpressions (curlies) were arguments to the component or if they are local values on the component class. The only way to know is to go look at the invocation of the component. In doing so, we find thatfirstName andlastName are passed in as arguments.
{{post-infofirstName=fNamelastName=lName}}
The Ember Core has recognized this is extremely problematic as an application grows, so they have allowed arguments to be pre-fixed with@ and locals to be prefixed withthis.. The issue is that migrating all the templates in a project would take too long because it requires developers to go separate these things out.
This is where Dyfactor comes in. By writing aDynamic Plugin, we can instrument the application in such a way that allows us to know how these symbols are being resolved at runtime. From there, we can use that information to go manually migrate the code or let Dyfactor attempt to do the migration for us.
At a high level, Dyfactor is a runner and plugin system. It currently supports two types of plugins: Static Plugins and Dynamic Plugins.
A Static Plugin is meant to be used to perform codemods that only require static analysis and is only single phased. These should be thought of as a light wrapper around a codemod you would write with jscodeshift or Babel.
interfaceStaticPlugin{/** * An array containing all recursive files and directories * under a given directory **/inputs:string[];/** * Hook called by the runner where codemod is implimented */modify():void;}
import{StaticPlugin}from'dyfactor';import*asfsfrom'fs';import*asrecastfrom'recast';functionfilesOnly(path){returnpath.charAt(path.length-1)!=='/';}exportdefaultclassextendsStaticPlugin{modify(){this.inputs.filter(filesOnly).forEach(input=>{letcontent=fs.readFileSync(input,'utf8');letast=recast.parse(content);letadd=ast.program.body[0];let{builders:b}=recast.types;ast.program.body[0]=b.variableDeclaration('var',[b.variableDeclarator(add.id,b.functionExpression(null,// Anonymize the function expression.add.params,add.body))]);add.params.push(add.params.shift());letoutput=recast.prettyPrint(ast,{tabWidth:2}).code;fs.writeFileSync(input,output);});}}
A Dynamic Plugin is two-phased. The first phase allows you to safely instrument an application to collect that runtime telemetry data. The instrumented application is then booted with Puppeteer to collect the data. The second phase is responsible for introspecting the runtime telemetry data and applying codemods based on that data. It's important to note that Dynamic Plugins can be run as single phased plugins just to produce the runtime telemetry and write it to disk.
interfaceDynamicPlugin{/** * An array containing all recursive files and directories * under a given directory **/inputs:string[];/** * Hook called by the runner to instrument the application */instrument():void;/** * Hook called by the runner to apply codemods based on the telemtry */modify(telemetry:Telemetry):void;}interfaceTelemetry{data:any;}
import{DynamicPlugin,TelemetryBuilder}from'dyfactor';import*asfsfrom'fs';import{preprocess,print}from'@glimmer/syntax';import{transform}from'babel-core';functionfilesOnly(path){returnpath.charAt(path.length-1)!=='/';}functioninstrumentCreate(babel){const{types:t}=babel;letident;lett=newTelemetryBuilder();lettemplate=babel.template(` IDENT.reopenClass({ create(injections) { let instance = this._super(injections);${t.preamble()}${t.conditionallyAdd('instance._debugContainerKey',()=>{return`Object.keys(injections.attrs).forEach((arg) => { if (!${t.path('instance._debugContainerKey')}.contains(arg)) {${t.path('instance._debugContainerKey')}.push(arg); } });`;},()=>{return`${t.path('instance._debugContainerKey')} = Object.keys(injections.attrs);`;})} return instance; } }); `);return{name:'instrument-create',visitor:{Program:{enter(p){ident=p.scope.generateUidIdentifier('refactor');},exit(p){letbody=p.node.body;letast=template({IDENT:ident});body.push(ast,t.exportDefaultDeclaration(ident));}},ExportDefaultDeclaration(p){letdeclaration=p.node.declaration;letdeclarator=t.variableDeclarator(ident,declaration);letvarDecl=t.variableDeclaration('const',[declarator]);p.replaceWith(varDecl);}}};}exportdefaultclassextendsDynamicPlugin{instrument(){this.inputs.filter(filesOnly).forEach(input=>{letcode=fs.readFileSync(input,'utf8');letcontent=transform(code,{plugins:[instrumentCreate]});fs.writeFileSync(input,content.code);});}modify(telemetry){telemetry.data.forEach(components=>{Object.keys(components).forEach(component=>{lettemplatePath=this.templateFor(component);lettemplate=fs.readFileSync(templatePath,'utf8');letast=preprocess(template,{plugins:{ast:[toArgs(components[component])]}});fs.writeFileSync(templatePath,print(ast));});});}templateFor(fullName:string){let[,name]=fullName.split(':');returnthis.inputs.find(input=>input.includes(`templates/components/${name}`));}}
About
A platform for running codemods based on runtime information