gaffer-generator 1.2.5 → 2.0.0

package/README.md

@@ -6,7 +6,7 @@ My old Gaffer is tired of writing code, so he generates it instead! This is how
 
 ## Requirements
 
-Install the latest LTS of NodeJS. Or a version around v8.11.3. Or try whatever you've got installed already, maybe it will work!
+Install the latest LTS of NodeJS. Or a version around v24. Or try whatever you've got installed already, maybe it will work!
 https://nodejs.org/en/
 
 Also install `yarn`. Or don't, and use `npm` instead.
@@ -62,11 +62,11 @@ You should see output similar to the following:
 Let's break down the discrete steps that happened above:
 
 1. We search the current directory recursively for `.templateroot` directories.
-2. When one is found, we read in the `template.js` file (it should be a CommonJS module).
+2. When one is found, we read in the `template.cjs` (or `template.js`) file (it should be a CommonJS module).
 3. Call the `download` method of this file, which should return a promise that eventually resolves to any JSON describing what you want to generate.
-4. Using the exported `into` property from the `template.js`, we'll recursively look at all of the other files within the `.templateroot`.
+4. Using the exported `into` property from the `template.cjs` (or `template.js`), we'll recursively look at all of the other files within the `.templateroot`.
 5. When we find a directory, recurse in to it!
-6. When we find a file, parse it as a [lodash template](https://lodash.com/docs/4.17.11#template). The context will be whatever was returned from the `download` promise above, plus any exported methods of our `template.js` will be exposed on the `utils` object.
+6. When we find a file, parse it as a [lodash template](https://lodash.com/docs/4.17.11#template). The context will be whatever was returned from the `download` promise above, plus any exported methods of our `template.cjs` (or `template.js`) will be exposed on the `utils` object.
 7. When we find a variable in the path, like `_fileName_.ts`, evaluate it based on our context from `download`.
 8. When we find a `_each` in the path, like `_eachEnum.fileName_.ts`, expand it out. This lets us generate many files from a single template.
 
@@ -90,6 +90,8 @@ There are several flags you can pass. To see them, run `gaffer-generator --help`
 
 ## Testing
 
+During development on Gaffer Generator itself, you can run various tests across the codebase. This will unit test and perform basic integration tests on the generated results.
+
 ```$bash
-yarn test
+npm run test
 ```

package/cli.js

@@ -1,38 +1,44 @@
 #!/usr/bin/env node
-require('yargs')
-  .command({
-    command: 'generate [directory]',
-    aliases: ['gen', 'g'],
-    desc: 'Recursively looks for .templateroots in the current directory, or supplied directory',
-    builder: yargs => yargs.default('directory', './'),
-    handler: argv => require('./src/generate/root').run(argv.directory),
-  })
-  .command({
-    command: 'create [directory] [--overwrite]',
-    aliases: ['c'],
-    desc: 'Create a starting .templateroot in to the current directory, or supplied directory',
-    builder: yargs => yargs.default('directory', './example.templateroot'),
-    handler: argv => require('./src/create').run(argv.directory),
-  })
-  .options({
-    'dry-run': {
-      boolean: true,
-      describe: 'Logs the changes that would be made without actually touching the file system.',
-    },
-    'into': {
-      string: true,
-      describe: 'Overrides the directory that .templateroots will target. Useful for targeting dynamic directories.',
-    },
-    'silent': {
-      boolean: true,
-      describe: 'Disables console logging.',
-    },
-    'no-colors': {
-      boolean: true,
-      describe: 'Turns off console coloring of text.',
-    },
-  })
-  .demandCommand()
-  .help()
-  .wrap(72)
-  .argv;
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { setArgv } from './lib/argv.js';
+
+setArgv(
+  yargs(hideBin(process.argv))
+    .command({
+      command: 'generate [directory]',
+      aliases: ['gen', 'g'],
+      desc: 'Recursively looks for .templateroots in the current directory, or supplied directory',
+      builder: yargs => yargs.default('directory', './'),
+      handler: async argv => (await import('./lib/generate/root.js')).run(argv.directory),
+    })
+    .command({
+      command: 'create [directory] [--overwrite]',
+      aliases: ['c'],
+      desc: 'Create a starting .templateroot in to the current directory, or supplied directory',
+      builder: yargs => yargs.default('directory', './example.templateroot'),
+      handler: async argv => (await import('./lib/create.js')).run(argv.directory),
+    })
+    .options({
+      'dry-run': {
+        boolean: true,
+        describe: 'Logs the changes that would be made without actually touching the file system.',
+      },
+      'into': {
+        string: true,
+        describe: 'Overrides the directory that .templateroots will target. Useful for targeting dynamic directories.',
+      },
+      'silent': {
+        boolean: true,
+        describe: 'Disables console logging.',
+      },
+      'no-colors': {
+        boolean: true,
+        describe: 'Turns off console coloring of text.',
+      },
+    })
+    .demandCommand()
+    .help()
+    .wrap(72)
+    .argv,
+);

package/lib/argv.js

@@ -0,0 +1,9 @@
+let argv;
+
+export function setArgv(newArgv) {
+  argv = newArgv;
+}
+
+export function getArgv() {
+  return argv;
+}

package/lib/create.js

@@ -0,0 +1,40 @@
+import colors from 'colors/safe.js';
+import path from 'path';
+import copy from 'recursive-copy';
+import { getArgv } from './argv.js';
+import * as utils from './utils.js';
+import { logChange } from './utils/logChange.js';
+import { logError } from './utils/logError.js';
+
+const dryRun = getArgv().dryRun || false;
+
+/*
+ Public API.
+ */
+export { run };
+
+/*
+ Implementation.
+ */
+function run(directory) {
+  const from = path.join(import.meta.dirname, '..', 'example', 'sample.templateroot');
+  const to = directory;
+  const options = {
+    overwrite: getArgv().overwrite,
+  };
+  logChange(to);
+  if (dryRun) {
+    return;
+  }
+  copy(from, to, options)
+    .on(copy.events.ERROR, (error, copyOperation) => {
+      logError(colors.red('Unable to copy to ') + colors.magenta(copyOperation.dest));
+    })
+    .then(results => {
+      utils.log(results.length + ' file(s) copied');
+    })
+    .catch(function(error) {
+      logError(colors.red(error));
+      process.exit(1);
+    });
+}

package/{src → lib}/generate/directory.js

@@ -1,21 +1,20 @@
-const _ = require('../lodash');
-const difference = _.difference;
-const uniq = _.uniq;
-const path = require('path');
-const fs = require('fs');
-const globule = require('globule');
-const argv = require('yargs').argv;
+import fs from 'fs';
+import globule from 'globule';
+import path from 'path';
+import { getArgv } from '../argv.js';
+import * as utils from '../utils.js';
+import { logRemoval } from '../utils/logRemoval.js';
+import * as node from './node.js';
+import difference from 'lodash.difference';
+import uniq from 'lodash.uniq';
 
-const utils = require('../utils');
-const dryRun = argv.dryRun || false;
-const node = require('./node');
-
-const reservedItems = ['template.js', 'template.ts', 'template', '.DS_Store'];
+const dryRun = getArgv().dryRun || false;
+const reservedItems = ['template.cjs', 'template.js', 'template.mjs', 'template.ts', 'template', '.DS_Store'];
 
 /*
  Public API.
  */
-exports.visit = visit;
+export { visit };
 
 /*
  Implementation.
@@ -48,7 +47,7 @@ function cleanDirectory(changedFiles) {
       }).map(utils.normalizePath);
       const obsoleteFiles = difference(allFiles, changedFiles.map(utils.normalizePath));
       for (let obsoleteFile of obsoleteFiles) {
-        utils.logRemoval(obsoleteFile);
+        logRemoval(obsoleteFile);
         !dryRun && fs.unlinkSync(obsoleteFile);
       }
     });

package/{src → lib}/generate/file.js

@@ -1,16 +1,16 @@
-require('colors');
-const _ = require('../lodash');
-const defaults = _.defaults;
-const template = _.template;
-const argv = require('yargs').argv;
+import colors from 'colors/safe.js';
+import defaults from 'lodash.defaults';
+import template from 'lodash.template';
+import { getArgv } from '../argv.js';
+import { templateArgs } from '../templateArgs.js';
+import * as utils from '../utils.js';
 
-const utils = require('../utils');
-const dryRun = argv.dryRun || false;
+const dryRun = getArgv().dryRun || false;
 
 /*
  Public API.
  */
-exports.visit = visit;
+export { visit };
 
 /*
  Implementation.
@@ -24,13 +24,13 @@ function visit(items, fromPath, toPath, templateSettings, changedFiles) {
       templateUtils.safeRead(fromPath),
       defaults({
         sourceURL: fromPath,
-      }, templateSettings.templateArgs || require('../templateArgs')),
+      }, templateSettings.templateArgs || templateArgs),
     );
   }
   catch (err) {
     templateUtils.logError(
-      'Hit error when compiling template:\n'.red
-      + String(fromPath).cyan,
+      colors.red('Hit error when compiling template:\n')
+      + colors.cyan(fromPath),
       err);
     return;
   }
@@ -53,8 +53,8 @@ function visit(items, fromPath, toPath, templateSettings, changedFiles) {
     }
     catch (err) {
       templateUtils.logError(
-        'Hit error when running template:\n'.red
-        + fromPath.cyan + ' => '.gray + item.path.cyan,
+        colors.red('Hit error when running template:\n')
+        + colors.cyan(fromPath) + colors.gray(' => ') + colors.cyan(item.path),
         err);
     }
   }

package/{src → lib}/generate/node.js

@@ -1,16 +1,13 @@
-require('colors');
-const _ = require('../lodash');
-const defaults = _.defaults;
-const fs = require('fs');
-
-const utils = require('../utils');
-const directory = require('./directory');
-const file = require('./file');
+import fs from 'fs';
+import defaults from 'lodash.defaults';
+import * as utils from '../utils.js';
+import * as directory from './directory.js';
+import * as file from './file.js';
 
 /*
  Public API.
  */
-exports.visit = visit;
+export { visit };
 
 /*
  Implementation.

package/lib/generate/root.js

@@ -0,0 +1,95 @@
+import colors from 'colors/safe.js';
+import fs from 'fs';
+import globule from 'globule';
+import { createRequire } from 'module';
+import path from 'path';
+import { getArgv } from '../argv.js';
+import * as utils from '../utils.js';
+import { logError } from '../utils/logError.js';
+import * as node from './node.js';
+
+// Create a CommonJS-compatible require that works from ESM context
+const requireCompat = createRequire(import.meta.url);
+
+/*
+ Public API.
+ */
+export { run, visit };
+
+/*
+ Implementation.
+ */
+async function run(directory) {
+  const matches = globule.find({
+    src: path.join(directory, '**/*.templateroot'),
+    filter: match => match.indexOf('node_modules') === -1,
+    dot: true,
+  });
+  for (const match of matches) {
+    await visit(path.resolve(match));
+  }
+}
+
+async function visit(rootPath) {
+  const templateSettingsPath = determineTemplateFile(rootPath);
+  if (!templateSettingsPath) {
+    logError(
+      colors.red('Found .templateroot without a template.cjs, template.mjs, template.js or template.ts file:\n')
+      + colors.cyan(rootPath));
+    return;
+  }
+  // TODO:
+  // const templateSettings = requireCompat(templateSettingsPath);
+  const templateSettings = await import(templateSettingsPath);
+  if (getArgv().into) {
+    templateSettings.into = getArgv().into;
+  }
+  if (!templateSettings.into) {
+    logError(
+      colors.red('Found .templateroot that does not have a "into" export in template file:\n')
+      + colors.cyan(templateSettingsPath));
+    return;
+  }
+  if (!templateSettings.download) {
+    logError(
+      colors.red('Found .templateroot that does not have a "download" export in template file:\n')
+      + colors.cyan(templateSettingsPath));
+    return;
+  }
+  const toPath = templateSettings.into[0] === '/' ? templateSettings.into : path.join(rootPath, templateSettings.into);
+  utils.log(colors.green('Running download from ') + colors.magenta(templateSettingsPath));
+  templateSettings.download(utils.fetch)
+    .catch(err => {
+      logError(
+        colors.red('Hit error when downloading for .templateroot:\n')
+        + colors.cyan(templateSettingsPath),
+        err);
+    })
+    .then(json => json && node.visit(json, rootPath, toPath, templateSettings));
+}
+
+function determineTemplateFile(rootPath) {
+  const cjsTemplate = path.join(rootPath, 'template.cjs');
+  const jsTemplate = path.join(rootPath, 'template.js');
+  const mjsTemplate = path.join(rootPath, 'template.mjs');
+  const tsTemplate = path.join(rootPath, 'template.ts');
+  if (fs.existsSync(cjsTemplate)) {
+    return cjsTemplate;
+  }
+  if (fs.existsSync(mjsTemplate)) {
+    return mjsTemplate;
+  }
+  if (fs.existsSync(jsTemplate)) {
+    return jsTemplate;
+  }
+  if (fs.existsSync(tsTemplate)) {
+    try {
+      requireCompat('ts-node').register();
+    }
+    catch (err) {
+      console.warn(colors.gray('Detected template.ts, but ts-node failed to register:'), err);
+    }
+    return tsTemplate;
+  }
+  return null;
+}

package/{src → lib}/templateArgs.js

@@ -1,4 +1,4 @@
-module.exports = {
+export const templateArgs = {
   evaluate: /<%([\s\S]+?)%>/g,
   escape: /<%-([\s\S]+?)%>/g,
   interpolate: /<%=([\s\S]+?)%>/g,

package/lib/utils/contentsDiffer.js

@@ -0,0 +1,20 @@
+import { normalizeLineEndings } from './normalizeLineEndings.js';
+
+/**
+ * Look at two strings to see if they contain the same content, ignoring line endings.
+ * @param a
+ * @param b
+ * @returns {boolean}
+ */
+export function contentsDiffer(a, b) {
+  // Are a and b both empty?
+  if (!a && !b) {
+    return false;
+  }
+  // Is only one of them empty?
+  if (!a || !b) {
+    return true;
+  }
+  // Otherwise, compare them while ignoring line endings to see if they're equivalent.
+  return normalizeLineEndings(a) !== normalizeLineEndings(b);
+}

package/lib/utils/log.js

@@ -0,0 +1,26 @@
+import colors from 'colors/safe.js';
+import { getArgv } from '../argv.js';
+
+/**
+ * Logs a message to the console with a nice prefix.
+ * @param text The text to write.
+ * @param [error] The optional error to log
+ * @param writeAsError If we should use console.error or console.log.
+ */
+export function log(text, error = null, writeAsError = false) {
+  if (getArgv().silent) {
+    return;
+  }
+  let prefix = colors.gray(`[${new Date().toTimeString().split(' ')[0]}] `);
+  if (writeAsError) {
+    if (error) {
+      console.error(prefix + text, error);
+    }
+    else {
+      console.error(prefix + text);
+    }
+  }
+  else {
+    console.log(prefix + text);
+  }
+}

package/lib/utils/logChange.js

@@ -0,0 +1,16 @@
+import colors from 'colors/safe.js';
+import fs from 'fs';
+import path from 'path';
+import { log } from './log.js';
+import { normalizePath } from './normalizePath.js';
+
+/**
+ * If the file doesn't exist, logs a message saying it is being created. Otherwise, it's being updated.
+ * @param file
+ */
+export function logChange(file) {
+  let url = normalizePath(typeof file === 'string'
+    ? file
+    : path.join(file.dirname, file.basename));
+  log(colors.cyan(`${fs.existsSync(url) ? 'updating' : 'creating'}: `) + colors.magenta(url));
+}

package/lib/utils/logError.js

@@ -0,0 +1,10 @@
+import { log } from './log.js';
+
+/**
+ * Logs an error.
+ * @param text
+ * @param [err]
+ */
+export function logError(text, err) {
+  log(text, err, true);
+}

package/lib/utils/logRemoval.js

@@ -0,0 +1,10 @@
+import colors from 'colors/safe.js';
+import { log } from './log.js';
+
+/**
+ * Logs a message saying the file is being removed.
+ * @param url
+ */
+export function logRemoval(url) {
+  log(colors.red(`removing: `) + colors.magenta(url));
+}

package/lib/utils/lowerCaseFirst.js

@@ -0,0 +1,11 @@
+/**
+ * Lowers the first letter of the provided string, leaving the rest of it alone.
+ * @param val
+ * @returns {string}
+ */
+export function lowerCaseFirst(val) {
+  if (!val || !val.toLowerCase) {
+    return val;
+  }
+  return val[0].toLowerCase() + val.slice(1);
+}

package/lib/utils/normalizeLineEndings.js

@@ -0,0 +1,8 @@
+/**
+ * Normalizes line endings for comparison purposes.
+ * @param contents
+ * @returns {string}
+ */
+export function normalizeLineEndings(contents) {
+  return contents.replace(/\r\n?/g, '\n');
+}

package/lib/utils/normalizePath.js

@@ -0,0 +1,10 @@
+import path from 'path';
+
+/**
+ * Normalizes a path across platforms. (Root / paths are assumed to be on C:\ on windows).
+ * @param ref
+ * @returns {string}
+ */
+export function normalizePath(ref) {
+  return ref && ref.startsWith('/') ? path.resolve(ref) : path.normalize(ref);
+}

package/lib/utils/parameterizeString.js

@@ -0,0 +1,19 @@
+import get from 'lodash.get';
+
+/**
+ * Given a string with _parameters_ within it, substitute them with the real values from the given context.
+ * @param str
+ * @param context
+ * @returns {string}
+ */
+export function parameterizeString(str, context) {
+  return str.replace(
+    /_[a-z]*\.?[a-z]+_/ig,
+    match => {
+      const variableName = match.slice(1, -1);
+      return get(context, variableName)
+        || get(context, variableName.toLowerCase())
+        || get(context, variableName.toUpperCase())
+        || match;
+    });
+}

package/lib/utils/safeRead.js

@@ -0,0 +1,17 @@
+import fs from 'fs';
+import path from 'path';
+import { normalizePath } from './normalizePath.js';
+
+/**
+ * Attempts to read in the provided file, returning the string contents if it exists, or null.
+ * @param file
+ * @returns {string}
+ */
+export function safeRead(file) {
+  let url = normalizePath(typeof file === 'string'
+    ? file
+    : path.join(file.dirname, file.basename));
+  return fs.existsSync(url)
+    ? fs.readFileSync(url, 'utf-8')
+    : null;
+}

package/lib/utils/safeWrite.js

@@ -0,0 +1,23 @@
+import fs from 'fs';
+import path from 'path';
+import { normalizePath } from './normalizePath.js';
+
+/**
+ * Writes the contents to the file, making sure the parent directories of the file exist.
+ * @param file
+ * @param contents
+ */
+export function safeWrite(file, contents) {
+  const url = normalizePath(typeof file === 'string'
+    ? file
+    : path.join(file.dirname, file.basename));
+  const dirs = url.split(path.sep).slice(0, -1);
+  // Note: we start at 1 to avoid trying to create the root directory.
+  for (let i = 1; i < dirs.length; i++) {
+    let collectivePath = dirs.slice(0, i + 1).join(path.sep);
+    if (!fs.existsSync(collectivePath)) {
+      fs.mkdirSync(collectivePath);
+    }
+  }
+  fs.writeFileSync(url, contents, 'utf-8');
+}

package/lib/utils.js

@@ -0,0 +1,16 @@
+import fetch from 'node-fetch';
+
+/*
+ Public API.
+ */
+export { contentsDiffer } from './utils/contentsDiffer.js';
+export { safeRead } from './utils/safeRead.js';
+export { safeWrite } from './utils/safeWrite.js';
+export { log } from './utils/log.js';
+export { logChange } from './utils/logChange.js';
+export { logRemoval } from './utils/logRemoval.js';
+export { logError } from './utils/logError.js';
+export { parameterizeString } from './utils/parameterizeString.js';
+export { lowerCaseFirst } from './utils/lowerCaseFirst.js';
+export { fetch };
+export { normalizePath } from './utils/normalizePath.js';