feat(#857): readme-automation

.github/workflows/readme-automation.yml

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: Copyright (c) 2022-2026 Objectionary.com
+# SPDX-License-Identifier: MIT
+---
+# yamllint disable rule:line-length
+name: readme-automation
+
+'on':
+  workflow_dispatch:
+  push:
+    paths:
+      - "src/eoc.js"
+concurrency:
+  group: readmeautomation-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v6
+      - name: Use Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: "18.x"
+          check-latest: false
+      - name: Clean install
+        run: npm ci
+      - name: Install global
+        run: npm install -g
+      - name: Run readme_automation script
+        run: |-
+          node scripts/readme_automation/readme_automation_run.js
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v8
+        with:
+          commit-message: "chore(readme): insert sections into README from CLI help"
+          branch: chore/readme-automation
+          title: "chore(readme): insert sections into README from CLI help"
+          body: |
+            This PR was automatically generated by GitHub Actions.
+
+            - Insert sections into README from CLI help output
+            - Keeps documentation in sync with the CLI

README.md

@@ -115,6 +115,7 @@ That's it.
 You can also do many other things with `eoc` commands
 (the flow is explained in [this blog post][blog]):
 
+<!-- BEGIN COMMANDS SECTION -->
 * `register` finds necessary `.eo` files and registers them in a JSON catalog
 * `assemble` parses `.eo` files into `.xmir`, optimizes them,
   and pulls foreign EO objects
@@ -151,6 +152,7 @@ There are also commands that help manipulate with XMIR and EO sources
 * ~~`dejump` removes `goto` objects~~
 * ~~`infer` suggests object names where it's possible to infer them~~
 * ~~`flatten` moves inner objects to upper level~~
+<!-- END COMMANDS SECTION -->
 
 This command line toolkit simply integrates other tools available in
 the [@objectionary](https://github.com/objectionary) GitHub organization.

scripts/readme_automation/help_to_markdown.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2022-2026 Objectionary.com
+ * SPDX-License-Identifier: MIT
+ */
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function updateSection(sectionName, newContent, readMeContent) {
+  const start = `<!-- BEGIN ${sectionName.toUpperCase()} SECTION -->`;
+  const end = `<!-- END ${sectionName.toUpperCase()} SECTION -->`;
+  const regex = new RegExp(
+    `(${escapeRegex(start)})([\\s\\S]*?)(${escapeRegex(end)})`,
+    "g"
+  );
+  return readMeContent.replace(regex, `$1\n${newContent}$3`);
+}
+
+function bulletListTemplate(rows) {
+  const list = rows.map(([cmd, desc]) => `* \`${cmd}\`  ${desc}`);
+  return `${list.join("\n")  }\n`;
+}
+
+function parseBlock(block_name,text) {
+  const lines = text.split("\n");
+  let inBlock = false;
+  const rows = [];
+  for (const line of lines) {
+    if (line.trim() === block_name) {
+      inBlock = true;
+    }
+    else if (inBlock) {
+      if (!line.trim()) {break;}
+      const parts = line.trim().split(/\s{2,}/);
+      const cmd = parts[0];
+      const desc = parts.slice(1).join(" ") || "";
+      rows.push([cmd, desc]);
+    }
+  }
+  if (!rows.length) {
+    throw new Error('no data something wrong');
+  }
+  return rows;
+}
+
+module.exports = {
+  parseBlock, bulletListTemplate, updateSection
+};
+

scripts/readme_automation/readme_automation_run.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2022-2026 Objectionary.com
+ * SPDX-License-Identifier: MIT
+ */
+
+const fs = require("fs");
+const assert = require('assert');
+const { parseBlock, bulletListTemplate, updateSection } = require("./help_to_markdown");
+const { getHelp } = require("../../src/eoc");
+
+function main () {
+  let help_text = getHelp();
+  help_text = help_text.replace(/\r\n/g, "\n");
+  assert.ok(["Options:","Commands:"].every(sub => help_text.includes(sub)),'"eoc --help" should includes Commands and Options');
+  const commands = parseBlock('Commands:',help_text);
+  assert.ok(commands.length > 0,'Commands should have rows')
+  const commandsMarkdown = bulletListTemplate(commands);
+  assert.ok(commandsMarkdown.length > 0,"commandsMarkdown result should have text")
+  let readMeContent = fs.readFileSync('README.md', "utf8");
+  assert.ok(readMeContent.length > 0,"readMeContent should have text")
+  readMeContent = updateSection('commands', commandsMarkdown, readMeContent);
+  assert.ok(readMeContent.length > 0,"readMeContent should sill have text after modification")
+  fs.writeFileSync('README.md',readMeContent);
+}
+
+if (require.main === module) {
+  main();
+};

src/eoc.js

@@ -394,12 +394,18 @@ program.command('fmt')
     });
   });
 
-try {
-  program.parse(process.argv);
-} catch (e) {
-  console.error(e.message);
-  console.debug(e.stack);
-  process.exit(1);
+if (require.main === module) {
+  try {
+    program.parse(process.argv);
+  } catch (e) {
+    console.error(e.message);
+    console.debug(e.stack);
+    process.exit(1);
+  }
+}
+
+module.exports.getHelp = function getHelp() {
+  return program.helpInformation();
 }
 
 /**

test/test_eoc.js

@@ -20,6 +20,13 @@ describe('eoc', () => {
     assert(stdout.includes(version.when));
     done();
   });
+  it('can get help from eoc as a module', (done) => {
+    const output = require('../src/eoc').getHelp();
+    assert(output.includes('Usage: eoc'));
+    assert(output.includes(version.what));
+    assert(output.includes(version.when));
+    done();
+  });
 });
 
 describe('eoc', () => {

test/test_readme_automation.js

@@ -0,0 +1,34 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2022-2026 Objectionary.com
+ * SPDX-License-Identifier: MIT
+ */
+
+const assert = require("assert");
+const path = require("path");
+const { parseBlock, updateSection, bulletListTemplate } = require(path.join(__dirname, "../scripts/readme_automation/help_to_markdown.js"));
+
+describe("readme_automation scripts", () => {
+  it("parseBlock builds a markdown table from a help block", () => {
+    const text = `\nUsage: eoc [options] [command]\nCommands:\n  foo   does foo\n  bar   does bar\n\nOptions:\n  -h, --help  output help`;
+    const res = parseBlock("Commands:", text);
+    assert.deepEqual(res,[['foo','does foo'],['bar','does bar']]);
+    const res2 = parseBlock("Options:", text);
+    assert.deepEqual(res2,[['-h, --help','output help']] );
+  });
+  it("parseBlock throws when no rows are found", () => {
+    assert.throws(
+      () => parseBlock("Commands:", ""),
+      /no data/
+    );
+  });
+  it("updateSection replaces only the requested section", () => {
+    const readme = `before\n<!-- BEGIN COMMANDS SECTION -->\nold\n<!-- END COMMANDS SECTION -->\n<!-- BEGIN OPTIONS SECTION -->\nkeep\n<!-- END OPTIONS SECTION -->\nafter`
+    const updated = updateSection("commands", "new content", readme);
+    assert.ok(!updated.includes("old"));
+    assert.ok(["new content","keep","after","before","<!-- BEGIN COMMANDS SECTION -->"].every(sub => updated.includes(sub)));
+  });
+  it("bulletListTemplate renders a list", async () => {
+    const output = bulletListTemplate([['one','a'],['two','b'],['three','c']]);
+    assert.strictEqual(output, "* `one`  a\n* `two`  b\n* `three`  c\n");
+  });
+});