Add plugins

.nvmrc

@@ -1 +1 @@
-v14.21.1
+v16

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Matt Fehskens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lib/index.js

@@ -19,10 +19,22 @@ const run = (command, ...args) => {
       return operators.update(args[0], args[1], config);
     /* istanbul ignore next */
     default:
-      return;
+      return runPlugins(config, command, args);
   }
 };
 
+const runPlugins = (config, command, args) => {
+  const plugin = config.plugins.find(
+    (plugin) => plugin.type === 'command' && plugin.commands.includes(command),
+  );
+
+  if (plugin) {
+    plugin.run(...args, config);
+  }
+
+  return;
+};
+
 /* istanbul ignore next */
 if (!module.parent) {
   run(...process.argv.slice(2));

lib/utils/config.util.js

@@ -11,12 +11,15 @@ const load = () => {
     dateFormat: getConfigValue('dateFormat', userConfig, 'yyyy-MM-dd HH:mm:ss'),
     drafts: getConfigValue('drafts', userConfig),
     pages: getConfigValue('pages', userConfig, { templates: [] }),
+    plugins: getConfigValue('plugins', userConfig, []),
     published: getConfigValue('published', userConfig),
     updating: getConfigValue('updating', userConfig),
   };
 
   checkTypes(config);
 
+  config.plugins = loadPlugins(config.plugins);
+
   return config;
 };
 
@@ -34,6 +37,7 @@ const checkTypes = (config) => {
   checkAssetsFormat(config.assets);
   checkDateFormat(config.dateFormat);
   checkPagesStructure(config.pages);
+  checkPlugins(config.plugins);
 };
 
 const checkAssetsFormat = (assets) => {
@@ -105,6 +109,43 @@ const checkSortType = (sortBy) => {
   }
 };
 
+const checkPlugins = (plugins) => {
+  if (!Array.isArray(plugins)) {
+    throw TypeError(
+      'The `plugins` attribute must be an array of package names',
+    );
+  }
+};
+
+const loadPlugins = (plugins) => {
+  const loaded = [];
+  const missing = [];
+
+  for (const plugin of plugins) {
+    files.loadModule(
+      plugin,
+      (_pluginName, pluginConfig) => {
+        loaded.push(pluginConfig);
+      },
+      () => {
+        missing.push(plugin);
+      },
+    );
+  }
+
+  if (missing.length) {
+    raiseMissingPlugins(missing);
+  }
+
+  return loaded;
+};
+
+const raiseMissingPlugins = (missing) => {
+  const list = missing.map((plugin) => `"${plugin}"`).join(', ');
+
+  throw ReferenceError(`The following plugins could not be found: ${list}`);
+};
+
 // This makes it so we can mock `load`
 // in tests
 module.exports = (...args) => module.exports.loadConfig(...args);

lib/utils/files.util.js

@@ -53,6 +53,17 @@ const getSystemRoot = () => {
   return systemRoot;
 };
 
+/* istanbul ignore next */
+const loadModule = (moduleName, onLoad, onError) => {
+  try {
+    const modulePath = require.resolve(moduleName, { paths: [findRoot()] });
+
+    onLoad(moduleName, require(modulePath));
+  } catch (_) {
+    onError(moduleName);
+  }
+};
+
 /* istanbul ignore next */
 const requireFile = (dir, filename) => {
   let filepath = dir;
@@ -242,6 +253,7 @@ module.exports = {
   deleteFile,
   ensureExt,
   findRoot,
+  loadModule,
   readFile,
   readFiles,
   requireFile,

test/index.test.js

@@ -4,22 +4,36 @@ const sinon = require('sinon');
 const operators = require('../lib/operators');
 const loadConfig = require('../lib/utils/config.util');
 const run = require('../lib');
-const config = {
-  input: 'posts-md',
-  output: 'posts-html',
-};
 
 const setup = () => {
   const sandbox = sinon.createSandbox();
+  const config = {
+    input: 'posts-md',
+    output: 'posts-html',
+    plugins: [
+      {
+        commands: ['zap', 'z'],
+        name: 'zapper',
+        run: sinon.stub(),
+        type: 'command',
+      },
+      {
+        commands: ['tap', 't'],
+        name: 'taps',
+        run: sinon.stub(),
+        type: 'command',
+      },
+    ],
+  };
 
   sandbox.mock();
   sandbox.stub(loadConfig, 'loadConfig').returns(config);
 
-  return sandbox;
+  return { config, sandbox };
 };
 
 test('should delegate a "new" command to the generator', (t) => {
-  const sandbox = setup();
+  const { config, sandbox } = setup();
   const generate = sandbox.stub(operators, 'generateMarkdown');
 
   run('new', 'This is My Title');
@@ -30,7 +44,7 @@ test('should delegate a "new" command to the generator', (t) => {
 });
 
 test('should alias "new" with "n"', (t) => {
-  const sandbox = setup();
+  const { config, sandbox } = setup();
   const generate = sandbox.stub(operators, 'generateMarkdown');
 
   run('n', 'Aliased new');
@@ -41,7 +55,7 @@ test('should alias "new" with "n"', (t) => {
 });
 
 test('should delegate a "build" command to the convertor', (t) => {
-  const sandbox = setup();
+  const { config, sandbox } = setup();
   const convert = sandbox.stub(operators, 'convert');
 
   run('build');
@@ -52,7 +66,7 @@ test('should delegate a "build" command to the convertor', (t) => {
 });
 
 test('should alias "build" with "b"', (t) => {
-  const sandbox = setup();
+  const { config, sandbox } = setup();
   const convert = sandbox.stub(operators, 'convert');
 
   run('b');
@@ -63,7 +77,7 @@ test('should alias "build" with "b"', (t) => {
 });
 
 test('should delegate a "publish" command to the publish operator', (t) => {
-  const sandbox = setup();
+  const { config, sandbox } = setup();
   const publish = sandbox.stub(operators, 'publish');
 
   run('publish', 'my-file');
@@ -74,7 +88,7 @@ test('should delegate a "publish" command to the publish operator', (t) => {
 });
 
 test('should alias "publish" with "p"', (t) => {
-  const sandbox = setup();
+  const { config, sandbox } = setup();
   const publish = sandbox.stub(operators, 'publish');
 
   run('p', 'aliased');
@@ -85,7 +99,7 @@ test('should alias "publish" with "p"', (t) => {
 });
 
 test('should delegate an "update" command to the update operator', (t) => {
-  const sandbox = setup();
+  const { config, sandbox } = setup();
   const update = sandbox.stub(operators, 'update');
 
   run('update', 'start', 'my-file');
@@ -96,7 +110,7 @@ test('should delegate an "update" command to the update operator', (t) => {
 });
 
 test('should alias "update" with "u"', (t) => {
-  const sandbox = setup();
+  const { config, sandbox } = setup();
   const update = sandbox.stub(operators, 'update');
 
   run('u', 'finish', 'my-file');
@@ -105,3 +119,13 @@ test('should alias "update" with "u"', (t) => {
 
   sandbox.restore();
 });
+
+test('should run a plugin command', (t) => {
+  const { config, sandbox } = setup();
+
+  run('tap', true, 'blue', 12);
+
+  t.true(config.plugins[1].run.calledWith(true, 'blue', 12, config));
+
+  sandbox.restore();
+});

test/utils/config.util.test.js

@@ -11,6 +11,9 @@ test.before(() => {
   sandbox.stub(files, 'checkIsDir').returns(true);
   sandbox.stub(files, 'findRoot').returns('/root');
   sandbox.stub(files, 'requireFile').callsFake(() => userConfig);
+  sandbox.stub(files, 'loadModule').callsFake((_, onLoad) => {
+    onLoad({});
+  });
 });
 
 test.after(() => {
@@ -36,6 +39,7 @@ test('should look for a config file next to the nearest package.json', (t) => {
         },
       ],
     },
+    plugins: [],
     published: 'input',
     updating: 'rework',
   };
@@ -53,6 +57,7 @@ test('should use a default config if one is not present', (t) => {
     pages: {
       templates: [],
     },
+    plugins: [],
     published: 'published',
     updating: 'updating',
   });
@@ -72,11 +77,41 @@ test('should use a partial config', (t) => {
     pages: {
       templates: [],
     },
+    plugins: [],
     published: 'pizza',
     updating: 'updating',
   });
 });
 
+test('should load any plugins', (t) => {
+  const run = () => {};
+
+  userConfig = {
+    plugins: ['my-cool-plugin', 'found-plugin'],
+  };
+
+  files.loadModule.callsFake((moduleName, onLoad) => {
+    return onLoad(moduleName, {
+      name: moduleName,
+      run,
+      type: 'command',
+    });
+  });
+
+  t.deepEqual(load().plugins, [
+    {
+      name: 'my-cool-plugin',
+      run,
+      type: 'command',
+    },
+    {
+      name: 'found-plugin',
+      run,
+      type: 'command',
+    },
+  ]);
+});
+
 test('should throw an error if the `assets` value is not a string', (t) => {
   userConfig = { assets: 123 };
 
@@ -226,3 +261,42 @@ test("should throw an error if a `pages` template's `sortBy` attribute is NOT an
       'The `sortBy` attribute of a `templates` item in the `pages` configuration attribute must be an array of strings',
   });
 });
+
+test('should throw an error if plugins is not an array', (t) => {
+  userConfig = {
+    plugins: 'boop',
+  };
+
+  t.throws(() => load(), {
+    instanceOf: TypeError,
+    message: 'The `plugins` attribute must be an array of package names',
+  });
+});
+
+test('should throw an error if a plugin cannot be found', (t) => {
+  userConfig = {
+    plugins: [
+      'my-cool-plugin',
+      'missing-plugin',
+      'found-plugin',
+      'another-missing-plugin',
+    ],
+  };
+
+  files.loadModule.callsFake((moduleName, onLoad, onError) => {
+    if (
+      moduleName === 'missing-plugin' ||
+      moduleName === 'another-missing-plugin'
+    ) {
+      return onError(moduleName);
+    }
+
+    return onLoad(moduleName, {});
+  });
+
+  t.throws(() => load(), {
+    instanceOf: ReferenceError,
+    message:
+      'The following plugins could not be found: "missing-plugin", "another-missing-plugin"',
+  });
+});