aberlaas-readme 2.18.1 → 2.20.1

package/lib/main.js

@@ -1,180 +1,194 @@
-import path from 'node:path';
 import { _, pMap } from 'golgoth';
+import { consoleWarn, exists, firostError, read, write } from 'firost';
+import { hostGitPath, hostGitRoot } from 'aberlaas-helper';
 import dedent from 'dedent';
-import { absolute, exists, glob, read, readJson, write } from 'firost';
 import frontMatter from 'front-matter';
-import helper from 'aberlaas-helper';
+import Gilmore from 'gilmore';
 
-export default {
-  /**
-   * Update the main README.md based on the template and the documentation
-   * @param {object} cliArgs CLI Argument object, as created by minimist
-   * @param {string} cliArgs.template Path to the template (default to
-   * .github/README.template.md
-   * @param {string} cliArgs.docs Path to the documentation folder
-   * @param {string} cliArgs.lib Path to the library folder
-   * @param {string} cliArgs.output List of files to output. Default to
-   * README at the root, and next to package.json
-   */
-  async run(cliArgs) {
-    const template = await this.getTemplate(cliArgs);
+export let __;
 
-    const packageData = await this.getPackageData(cliArgs);
-    const docsData = await this.getDocsData(cliArgs);
-    const data = { package: packageData, ...docsData };
+const TEMPLATE_PATH = '.README.template.md';
 
-    const output = await this.getReadmes(cliArgs);
+/**
+ * Update the various README.md files based on the template
+ * @param {object} cliArgs CLI Argument object, as created by minimist
+ * @param {string} cliArgs.template Path to the template (default to .README.template.md)
+ * @param {Array} cliArgs._ List of files that changed (passed by lint-staged)
+ * @param {boolean} cliArgs.addToGit Whether to add generated files to git staging area
+ */
+export async function run(cliArgs = {}) {
+  await __.warnIfDeprecatedTemplate();
+  await __.ensureTemplateExists();
 
-    const content = await this.convert(template, data);
-    // console.info({ template, data, docsData });
+  // Get all template data (inputs, outputs, body)
+  const templateData = await __.getTemplateData();
 
-    await pMap(output, async (filepath) => {
-      await write(content, filepath);
-    });
-  },
+  // Stop if the passed args do not require a regeneration
+  if (!__.shouldContinue(cliArgs?._, templateData)) {
+    return;
+  }
+
+  // Regenerate the READMEs
+  await __.generateAndWrite(templateData);
+
+  // Add generated files to git staging area if requested
+  if (cliArgs['add-to-git']) {
+    await __.addToGit(templateData);
+  }
+}
+
+__ = {
   /**
-   * Returns the content of the template
-   * @param {object} cliArgs CLI Argument object, as created by minimist
-   * @param {string} cliArgs.template Path to the template
-   * Will default to .github/README.template.md in the host, or fallback to
-   * a default value in aberllas
-   * @returns {string} Template content
+   * Warns the user if they are using the deprecated README template location.
    */
-  async getTemplate(cliArgs = {}) {
-    if (cliArgs.template) {
-      const customTemplate = helper.hostPath(cliArgs.template);
-      if (await exists(customTemplate)) {
-        return await read(customTemplate);
-      }
+  async warnIfDeprecatedTemplate() {
+    const oldTemplate = hostGitPath('.github/README.template.md');
+    if (!(await exists(oldTemplate))) {
+      return;
     }
 
-    const hostDefaultTemplate = helper.hostPath('.github/README.template.md');
-    if (await exists(hostDefaultTemplate)) {
-      return await read(hostDefaultTemplate);
-    }
-
-    const aberlaasDefaultTemplate = absolute('../templates/README.md');
-    return await read(aberlaasDefaultTemplate);
+    __.consoleWarn('aberlaas: Readme template location has changed.');
+    __.consoleWarn(
+      'Please move ./.github/README.template.md to ./.README.template.md',
+    );
   },
+
   /**
-   * Returns the content of the library package.json
-   * @param {object} cliArgs CLI Argument object, as created by minimist
-   * Will default search in cliArgs.lib, ./lib, or the root
-   * @returns {object} package.json content
+   * Ensures that the template file exists at the expected location.
    */
-  async getPackageData(cliArgs = {}) {
-    const packagePath = await this.getPackagePath(cliArgs);
-    return await readJson(packagePath);
+  async ensureTemplateExists() {
+    const templatePath = hostGitPath(TEMPLATE_PATH);
+    if (await exists(templatePath)) {
+      return;
+    }
+    throw firostError(
+      'ABERLAAS_README_MISSING_TEMPLATE',
+      `README template not found at ${TEMPLATE_PATH}`,
+    );
   },
+
   /**
-   * Returns the path to the package.json
-   * @param {object} cliArgs CLI Argument object, as created by minimist
-   * Will default search in cliArgs.lib, ./lib, or the root
-   * @returns {object} package.json content
+   * Extracts and processes template data including inputs, outputs, and body content.
+   * Uses the static TEMPLATE_PATH constant.
+   * @returns {object} Object containing processed inputs array, outputs array, and template body content
    */
-  async getPackagePath(cliArgs = {}) {
-    const libFolder = helper.hostPath(cliArgs.lib || './lib');
-    let packagePath = path.resolve(libFolder, 'package.json');
-
-    if (await exists(packagePath)) {
-      return packagePath;
+  async getTemplateData() {
+    const templatePath = hostGitPath(TEMPLATE_PATH);
+    const rawContent = await read(templatePath);
+    const parsed = frontMatter(rawContent);
+
+    // Template content
+    const body = parsed.body;
+
+    // Outputs from frontmatter
+    const outputs = _.map(parsed.attributes.outputs, hostGitPath);
+
+    // Ensure outputs are defined
+    if (_.isEmpty(outputs)) {
+      throw firostError(
+        'ABERLAAS_README_MISSING_OUTPUTS',
+        `File ${TEMPLATE_PATH} is missing an outputs: key in its frontmatter`,
+      );
     }
 
-    return helper.hostPath('package.json');
-  },
-  /**
-   * Returns all documentation as an object
-   * @param {object} cliArgs CLI Argument object, as created by minimist
-   * @param {string} cliArgs.docs Path to the documentation directory
-   * Will default to ./docs/src
-   * @returns {object} Documentation content
-   */
-  async getDocsData(cliArgs = {}) {
-    const docsPath = helper.hostPath(cliArgs.docs || './docs/src');
-    const mdFiles = await glob(`${docsPath}/**/*.md`);
-    const docsData = {};
-    await pMap(mdFiles, async (filepath) => {
-      // Convert filepath to a (nested) dot key
-      const key = _.chain(path.relative(docsPath, filepath))
-        .replace(/\.md$/, '')
-        .replace(/\//g, '.')
-        .value();
-
-      // Grab the content, excluding front-matter
-      const rawContent = await read(filepath);
-      const { body } = frontMatter(rawContent);
-      _.set(docsData, key, body);
+    // Inputs
+    const fileRegexp = /{file:(?<filepath>[^}]+)}/gm;
+    const matches = Array.from(body.matchAll(fileRegexp));
+    const inputs = _.chain(matches)
+      .map((match) => match.groups.filepath)
+      .map((filepath) => {
+        return {
+          match: filepath,
+          filepath: hostGitPath(filepath),
+        };
+      })
+      .value();
+
+    // Ensure all inputs actually exist
+    await pMap(inputs, async (input) => {
+      const { match, filepath } = input;
+      if (await exists(filepath)) {
+        return;
+      }
+      throw firostError(
+        'ABERLAAS_README_MISSING_INPUT',
+        `Unable to find file to include for {file:${match}} in ${TEMPLATE_PATH}`,
+      );
     });
-    return docsData;
+
+    return {
+      inputs,
+      outputs,
+      body,
+    };
   },
+
   /**
-   * Returns path to all README.md to write
-   * @param {object} cliArgs CLI Argument object, as created by minimist
-   * @param {string} cliArgs.output Comma-separated list of output path
-   * Will default to a README.md at the git root, and one in the module code
-   * (./lib by default)
-   * @returns {Array} List of paths to write the READMEs
+   * Determines if the README generation should continue based on changed files.
+   * If none of the changed files are used as inputs, or outputs of the readme,
+   * we should stop
+   * @param {Array} cliFiles List of passed files
+   * @param {object} templateData Template data containing inputs, outputs, and body
+   * @returns {boolean} True if generation should continue, false otherwise
    */
-  async getReadmes(cliArgs = {}) {
-    // Custom --output passed as a comma-separated list
-    if (cliArgs.output) {
-      return _.chain(cliArgs.output)
-        .split(',')
-        .map((filepath) => {
-          return helper.hostPath(filepath);
-        })
-        .sort()
-        .value();
+  shouldContinue(cliFiles, templateData) {
+    // If no files passed, always continue
+    if (_.isEmpty(cliFiles)) {
+      return true;
     }
 
-    // README.md at the git root for GitHub
-    const hostReadmePath = helper.hostPath('README.md');
+    // Build list of files that would trigger a README regeneration
+    const templatePath = hostGitPath(TEMPLATE_PATH);
+    const filesTriggeringChange = [
+      ..._.map(templateData.inputs, 'filepath'),
+      templatePath,
+    ];
 
-    // README.md in the module folder for npm/yarn
-    const packagePath = await this.getPackagePath(cliArgs);
-    const moduleReadmePath = path.resolve(
-      path.dirname(packagePath),
-      'README.md',
-    );
+    const changedFiles = _.map(cliFiles, (filepath) => hostGitPath(filepath));
 
-    const readmes = _.uniq([hostReadmePath, moduleReadmePath]);
-    return readmes;
+    // Stop if no relevant files changed
+    const intersection = _.intersection(changedFiles, filesTriggeringChange);
+    return !_.isEmpty(intersection);
   },
+
   /**
-   * Convert a source string by replace {key} with the matching keys of data
-   * @param {string} source The source string
-   * @param {object} data The data object to use to compile
-   * @returns {string} The converted string
+   * Generates the README content and writes it to all output files.
+   * @param {object} templateData Template data containing inputs, outputs, and body
    */
-  convert(source, data) {
-    const regexp = /{(?<key>.*?)}/gm;
-    const matches = Array.from(source.matchAll(regexp));
+  async generateAndWrite(templateData) {
+    const { inputs, outputs, body } = templateData;
 
-    let convertedSource = dedent`
+    // Generate content by wrapping template and replacing placeholders
+    let content = dedent`
     <!--
-      This page was automatically generated by aberlaas readme.
-      DO NOT EDIT IT MANUALLY.
+      This file was automatically generated by 'aberlaas readme' from ${TEMPLATE_PATH}
+      DO NOT EDIT MANUALLY
     -->
+    ${body}
+    `;
 
-    ${source}`;
+    await pMap(inputs, async (input) => {
+      const { match, filepath } = input;
+      const includedContent = await read(filepath);
+      content = _.replace(content, `{file:${match}}`, includedContent);
+    });
 
-    _.each(matches, (match) => {
-      const key = match.groups.key;
-      convertedSource = convertedSource.replace(
-        `{${key}}`,
-        _.get(data, key, ''),
-      );
+    // Write to all output files
+    await pMap(outputs, async (outputPath) => {
+      await write(content, outputPath);
     });
-    return convertedSource;
   },
+
   /**
-   * Read a file from disk, removing its front-matter if it has one
-   * @param {string} filepath Path to the file
-   * @returns {string} File content, stripped of front-matter
+   * Adds generated README files to git staging area
+   * @param {object} templateData Template data containing outputs
    */
-  async read(filepath) {
-    const source = await this.__read(filepath);
-    const { body } = frontMatter(source);
-    return body;
+  async addToGit(templateData) {
+    const { outputs } = templateData;
+    const repo = new Gilmore(hostGitRoot());
+    await repo.add(outputs);
   },
+  consoleWarn,
 };
+
+export default { run };

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "aberlaas-readme",
   "type": "module",
+  "sideEffects": false,
   "description": "aberlaas readme helper: Write and synchronize README",
-  "version": "2.18.1",
+  "version": "2.20.1",
   "repository": "pixelastic/aberlaas",
   "homepage": "https://projects.pixelastic.com/aberlaas/",
   "author": "Tim Carry (@pixelastic)",
   "license": "MIT",
   "files": [
-    "lib/*.js",
-    "templates/"
+    "lib/*.js"
   ],
   "exports": {
     ".": "./lib/main.js"
@@ -18,27 +18,25 @@
   "engines": {
     "node": ">=18.18.0"
   },
-  "scripts": {
-    "build": "../../scripts/local/build",
-    "build:prod": "../../scripts/local/build-prod",
-    "cms": "../../scripts/local/cms",
-    "serve": "../../scripts/local/serve",
-    "ci": "../../scripts/local/ci",
-    "release": "../../scripts/local/release",
-    "update-dependencies": "node ../../scripts/meta/update-dependencies.js",
-    "test:meta": "../../scripts/local/test-meta",
-    "test": "../../scripts/local/test",
-    "test:watch": "../../scripts/local/test-watch",
-    "compress": "../../scripts/local/compress",
-    "lint": "../../scripts/local/lint",
-    "lint:fix": "../../scripts/local/lint-fix"
-  },
   "dependencies": {
-    "aberlaas-helper": "^2.18.1",
-    "dedent": "1.5.3",
-    "firost": "5.2.1",
+    "aberlaas-helper": "workspace:*",
+    "dedent": "1.7.1",
+    "firost": "5.5.1",
     "front-matter": "4.0.2",
+    "gilmore": "1.2.0",
     "golgoth": "3.0.0"
   },
-  "gitHead": "00b60dcf9aebab442a809ccc81942005d87d1b5c"
+  "scripts": {
+    "build": "cd ../docs && yarn run build",
+    "build:prod": "cd ../docs && yarn run build:prod",
+    "cms": "cd ../docs && yarn run cms",
+    "serve": "cd ../docs && yarn run serve",
+    "release": "cd ../.. && ./scripts/release",
+    "test:meta": "cd ../.. && ./scripts/test-meta",
+    "test": "cd ../.. && ./scripts/test",
+    "test:watch": "cd ../.. && ./scripts/test-watch",
+    "compress": "cd ../.. && ./scripts/compress",
+    "lint": "cd ../.. && ./scripts/lint",
+    "lint:fix": "cd ../.. && ./scripts/lint-fix"
+  }
 }

package/templates/README.md

@@ -1 +0,0 @@
-aberlaas template