Merge pull request #26 from rwjblue/add-project-readme

Add project readme

Author: rondale-sc

README.md

@@ -50,6 +50,12 @@ codemod-cli generate fixture <name of codemod> <name of fixture>
 This sets up two new files in `transforms/<name of codemod>/__testfixtures__/` using the fixture name
 you provided. These fixtures are used by the testing harness to verify that your codemod is working properly.
 
+Once you have things just how you like them with your new codemod (and your tests are passing :wink:) you
+can update your project's README and your transforms README via:
+
+```
+codemod-cli update-docs
+```
 
 Contributing
 ------------------------------------------------------------------------------

commands/global/new.js

@@ -16,14 +16,57 @@ module.exports.handler = function handler(options) {
   const { stripIndent } = require('common-tags');
   const pkg = require('../../package.json');
 
-  fs.outputFileSync(projectName + '/README.md', `# ${projectName}\n`, 'utf8');
+  fs.outputFileSync(
+    projectName + '/README.md',
+    stripIndent`
+      # ${projectName}\n
+
+      A collection of codemod's for ${projectName}.
+
+      ## Usage
+
+      To run a specific codemod from this project, you would run the following:
+
+      \`\`\`
+      npx ${projectName} <TRANSFORM NAME> path/of/files/ or/some**/*glob.js
+
+      # or
+
+      yarn global add ${projectName}
+      ${projectName} <TRANSFORM NAME> path/of/files/ or/some**/*glob.js
+      \`\`\`
+
+      ## Transforms
+
+      <!--TRANSFORMS_START-->
+      <!--TRANSFORMS_END-->
+
+      ## Contributing
+
+      ### Installation
+
+      * clone the repo
+      * change into the repo directory
+      * \`yarn\`
+
+      ### Running tests
+
+      * \`yarn test\`
+
+      ### Update Documentation
+
+      * \`yarn update-docs\`
+    `,
+    'utf8'
+  );
   fs.outputJsonSync(
     projectName + '/package.json',
     {
       name: projectName,
       version: '0.1.0',
       scripts: {
         test: 'codemod-cli test',
+        'update-docs': 'codemod-cli update-docs',
       },
       bin: './bin/cli.js',
       keywords: ['codemod-cli'],

commands/local/generate/codemod.js

@@ -10,9 +10,11 @@ module.exports.builder = function builder(yargs) {
 module.exports.handler = function handler(options) {
   const fs = require('fs-extra');
   const { stripIndent } = require('common-tags');
+  const importCwd = require('import-cwd');
   const generateFixture = require('./fixture').handler;
 
   let { codemodName } = options;
+  let projectName = importCwd('./package.json').name;
   let codemodDir = `${process.cwd()}/transforms/${codemodName}`;
 
   fs.outputFileSync(
@@ -48,7 +50,32 @@ module.exports.handler = function handler(options) {
     `,
     'utf8'
   );
-  fs.outputFileSync(`${codemodDir}/README.md`, `# ${codemodName}\n`, 'utf8');
+  fs.outputFileSync(
+    `${codemodDir}/README.md`,
+    stripIndent`
+      # ${codemodName}\n
+
+      ## Usage
+
+      \`\`\`
+      npx ${projectName} ${codemodName} path/of/files/ or/some**/*glob.js
+
+      # or
+
+      yarn global add ${projectName}
+      ${projectName} ${codemodName} path/of/files/ or/some**/*glob.js
+      \`\`\`
+
+      ## Input / Output
+
+      <!--FIXTURES_TOC_START-->
+      <!--FIXTURES_TOC_END-->
+
+      <!--FIXTURES_CONTENT_START-->
+      <!--FIXTURES_CONTENT_END-->
+    `,
+    'utf8'
+  );
 
   generateFixture({ codemodName, fixtureName: 'basic' });
 };

commands/local/update-docs.js

@@ -0,0 +1,93 @@
+module.exports.command = 'update-docs';
+module.exports.desc = 'Update the project README with current list of transforms';
+
+function updateProjectREADME() {
+  const fs = require('fs-extra');
+
+  let TRANSFORMS_PLACE_HOLDER = /<!--TRANSFORMS_START-->[\s\S]*<!--TRANSFORMS_END-->/;
+
+  let transforms = fs
+    .readdirSync('transforms')
+    .filter(file => fs.lstatSync(`transforms/${file}`).isDirectory());
+
+  let readmeContent = transforms
+    .map(name => `* [${name}](transforms/${name}/README.md)`)
+    .join('\n');
+
+  fs.writeFileSync(
+    'README.md',
+    fs
+      .readFileSync('README.md', 'utf8')
+      .replace(
+        TRANSFORMS_PLACE_HOLDER,
+        `<!--TRANSFORMS_START-->\n${readmeContent}\n<!--TRANSFORMS_END-->`
+      )
+  );
+}
+
+function updateTransformREADME(transformName) {
+  const fs = require('fs-extra');
+  const path = require('path');
+
+  let toc = [];
+  let details = [];
+
+  let fixtureDir = `transforms/${transformName}/__testfixtures__`;
+
+  if (!fs.existsSync(fixtureDir)) {
+    // project does not include fixtures (perhaps using different testing
+    // setup)
+    return;
+  }
+
+  fs.readdirSync(fixtureDir)
+    .filter(filename => /\.input$/.test(path.basename(filename, path.extname(filename))))
+    .forEach(filename => {
+      let extension = path.extname(filename);
+      let testName = filename.replace(`.input${extension}`, '');
+      let inputPath = path.join(fixtureDir, `${testName}.input${extension}`);
+      let outputPath = path.join(fixtureDir, `${testName}.output${extension}`);
+
+      toc.push(`* [${testName}](#${testName})`);
+      details.push(
+        '---',
+        `<a id="${testName}"></a>`,
+        `**Input** (<small>[${testName}.input${extension}](${inputPath})</small>):`,
+        fs.readFileSync(inputPath),
+        `**Output** (<small>[${testName}.input${extension}](${outputPath})</small>):`,
+        fs.readFileSync(outputPath)
+      );
+    });
+
+  let transformREADMEPath = `transforms/${transformName}/README.md`;
+
+  let FIXTURES_TOC_PLACE_HOLDER = /<!--FIXTURES_TOC_START-->[\s\S]*<!--FIXTURES_TOC_END-->/;
+  let FIXTURES_CONTENTS_PLACE_HOLDER = /<!--FIXTURES_CONTENT_START-->[\s\S]*<!--FIXTURES_CONTENT_END-->/;
+
+  fs.writeFileSync(
+    transformREADMEPath,
+    fs
+      .readFileSync(transformREADMEPath, 'utf8')
+      .replace(
+        FIXTURES_TOC_PLACE_HOLDER,
+        `<!--FIXTURES_TOC_START-->\n${toc.join('\n')}\n<!--FIXTURES_TOC_END-->`
+      )
+      .replace(
+        FIXTURES_CONTENTS_PLACE_HOLDER,
+        `<!--FIXTURES_CONTENTS_START-->\n${details.join('\n')}\n<!--FIXTURES_CONTENTS_END-->`
+      )
+  );
+}
+
+function updateTransformREADMEs() {
+  const fs = require('fs-extra');
+
+  fs.readdirSync('transforms')
+    .filter(file => fs.lstatSync(`transforms/${file}`).isDirectory())
+    .forEach(updateTransformREADME);
+}
+
+module.exports.handler = function handler() {
+  updateProjectREADME();
+  updateTransformREADMEs();
+};

tests/cli-test.js

@@ -74,6 +74,28 @@ QUnit.module('codemod-cli', function(hooks) {
     );
   });
 
+  QUnit.module('update-docs', function(hooks) {
+    setupProject(hooks);
+
+    QUnit.test(
+      'updates top-level README with links to transform READMEs',
+      wrap(function*(assert) {
+        codemodProject.write({
+          transforms: {
+            foo: { 'README.md': 'some content' },
+            bar: { 'README.md': 'some content' },
+          },
+        });
+
+        yield execa(EXECUTABLE_PATH, ['update-docs']);
+
+        let README = fs.readFileSync(codemodProject.path('README.md'), 'utf8');
+        assert.ok(README.includes('* [foo](transforms/foo/README.md'), 'foo link');
+        assert.ok(README.includes('* [bar](transforms/bar/README.md'), 'bar link');
+      })
+    );
+  });
+
   QUnit.module('generate', function(hooks) {
     setupProject(hooks);