aberlaas-readme 2.10.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Tim Carry (tim@pixelastic.com)
+
+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.

package/lib/main.js

@@ -0,0 +1,179 @@
+import path from 'path';
+import { _, dedent, pMap } from 'golgoth';
+import { absolute, exists, glob, read, readJson, write } from 'firost';
+import frontMatter from 'front-matter';
+import helper from 'aberlaas-helper';
+
+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);
+
+    const packageData = await this.getPackageData(cliArgs);
+    const docsData = await this.getDocsData(cliArgs);
+    const data = { package: packageData, ...docsData };
+
+    const output = await this.getReadmes(cliArgs);
+
+    const content = await this.convert(template, data);
+    // console.info({ template, data, docsData });
+
+    await pMap(output, async (filepath) => {
+      await write(content, filepath);
+    });
+  },
+  /**
+   * 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
+   */
+  async getTemplate(cliArgs = {}) {
+    if (cliArgs.template) {
+      const customTemplate = helper.hostPath(cliArgs.template);
+      if (await exists(customTemplate)) {
+        return await read(customTemplate);
+      }
+    }
+
+    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);
+  },
+  /**
+   * 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
+   */
+  async getPackageData(cliArgs = {}) {
+    const packagePath = await this.getPackagePath(cliArgs);
+    return await readJson(packagePath);
+  },
+  /**
+   * 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
+   */
+  async getPackagePath(cliArgs = {}) {
+    const libFolder = helper.hostPath(cliArgs.lib || './lib');
+    let packagePath = path.resolve(libFolder, 'package.json');
+
+    if (await exists(packagePath)) {
+      return packagePath;
+    }
+
+    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);
+    });
+    return docsData;
+  },
+  /**
+   * 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
+   */
+  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();
+    }
+
+    // README.md at the git root for GitHub
+    const hostReadmePath = helper.hostPath('README.md');
+
+    // 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 readmes = _.uniq([hostReadmePath, moduleReadmePath]);
+    return readmes;
+  },
+  /**
+   * 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
+   */
+  convert(source, data) {
+    const regexp = /{(?<key>.*?)}/gm;
+    const matches = Array.from(source.matchAll(regexp));
+
+    let convertedSource = dedent`
+    <!--
+      This page was automatically generated by aberlaas readme.
+      DO NOT EDIT IT MANUALLY.
+    -->
+
+    ${source}`;
+
+    _.each(matches, (match) => {
+      const key = match.groups.key;
+      convertedSource = convertedSource.replace(
+        `{${key}}`,
+        _.get(data, key, ''),
+      );
+    });
+    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
+   */
+  async read(filepath) {
+    const source = await this.__read(filepath);
+    const { body } = frontMatter(source);
+    return body;
+  },
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "aberlaas-readme",
+  "type": "module",
+  "description": "aberlaas readme helper: Write and synchronize README",
+  "version": "2.10.0",
+  "repository": "pixelastic/aberlaas",
+  "homepage": "https://projects.pixelastic.com/aberlaas/",
+  "author": "Tim Carry (@pixelastic)",
+  "license": "MIT",
+  "files": [
+    "lib/*.js",
+    "templates/"
+  ],
+  "exports": {
+    ".": "./lib/main.js"
+  },
+  "main": "./lib/main.js",
+  "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": "node ../../scripts/meta/update.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.10.0",
+    "firost": "4.3.0",
+    "front-matter": "4.0.2",
+    "golgoth": "2.4.0"
+  },
+  "gitHead": "bcdaf87c198a588e02b5539c222f611e356d3079"
+}

package/templates/README.md

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