@arc-e-tect/api-only-publisher 0.7.0 → 0.7.1

package/README.adoc

@@ -6,7 +6,7 @@
 :source-highlighter: rouge
 // The released version of this component: its snippets use it. The release
 // workflow updates it; do not change it by hand.
-:api-only-publisher-version: 0.7.0
+:api-only-publisher-version: 0.7.1
 
 image:https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/actions/workflows/nvd-cache-refresh.yml/badge.svg[Vulnerability Scan,link=https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/actions/workflows/nvd-cache-refresh.yml]
 image:https://img.shields.io/npm/v/@arc-e-tect/api-only-publisher[npm,link=https://www.npmjs.com/package/@arc-e-tect/api-only-publisher]
@@ -270,11 +270,41 @@ What it reports::
 [horizontal]
 `created`:: The file was not there, and is now.
 `identical`:: The file was there, and matches what `init` would write, ignoring line endings and final newlines.
+`updated`:: `apionly.yaml` was there, and lacked a kind's configuration; it does now.
+The message names every slot added -- see <<init-additive,Adding a kind to an existing library §>>.
 `differs`:: The file was there, and does not match: where the library has diverged from the scaffold, usually on purpose.
 It is left alone.
 `overwrote`:: The file differed, and `--force` replaced it.
 +
-At a terminal, `--force` first lists the files that differ and asks once whether to overwrite them; without a terminal, or with `--yes`, it overwrites them without asking.
+At a terminal, `--force` first lists the files that still differ -- after any additive update apionly.yaml already got -- and asks once whether to overwrite them; without a terminal, or with `--yes`, it overwrites them without asking.
+
+[#init-additive]
+=== Adding a kind to an existing library
+
+Running `init` again, with a kind the library did not have, is how a library grows: the fragments the new kind needs, and the configuration that makes the build see them.
+
+*Files* stay create-only, as everywhere else in `init`: a fragment not written before is written now; one already there, however it now reads, is left alone -- even where the new kind changes what the scaffold would write for it, such as `specs/openapi/paths/example/ExamplesV1.yaml` once an AsyncAPI event comes to share its schema.
+
+*Configuration* is additive: whichever of `sources.<kind>`, `defaults.<kind>`, the kind's pin in `toolchain`, and `targets.<target>.<kind>` `apionly.yaml` lacks is added to it, in the position a library scaffolded with both kinds from the start would have it in.
+Every value, key and comment already in the file survives untouched, and a slot that is already there, however it reads, is never touched either -- not even to add something missing from *inside* it: a `defaults.openapi` with no `lint` is a choice, and `init` leaves it that way.
+
+[source,console]
+----
+$ api-only-publisher init . --yes --openapi --target orders
+  created    apionly.yaml
+  created    specs/openapi/...
+
+$ api-only-publisher init . --yes --openapi --asyncapi --target orders
+  created    specs/asyncapi/...
+  updated    apionly.yaml (added sources.asyncapi, defaults.asyncapi, toolchain.asyncapi, targets.orders.asyncapi)
+  differs    specs/openapi/paths/example/ExamplesV1.yaml (left alone; --force overwrites)
+----
+
+Nothing is asked before completing `apionly.yaml`: unlike `--force`, an additive update never discards anything, so there is nothing to confirm.
+Run `init` again with the same kinds, and it reports nothing left to add.
+
+`--force` is the other tool for an apionly.yaml that differs, and it does the opposite of the additive update: it reinitialises the file wholesale, exactly as a first run with these values would write it -- any target or key it holds that these values would not produce is gone, additive or not.
+Use it to discard a customisation on purpose; use a plain `init` to add a kind without touching anything else.
 
 [#what-build-does]
 == What `build` does

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc-e-tect/api-only-publisher",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Builds, packs and publishes API description documents from a library of reusable fragments.",
   "license": "MIT",
   "author": "Arc-E-Tect",

package/src/cli.js

@@ -168,7 +168,7 @@ async function runInit(options, positional, io, log) {
         if (terminal && force) {
             // Asked, --force means "after showing me": it overwrites what differs only
             // once the list has been seen and agreed to.
-            const differing = plan(dir, scaffold(values)).filter((entry) => entry.status === "differs");
+            const differing = plan(dir, scaffold(values), values).filter((entry) => entry.status === "differs");
             if (differing.length > 0) {
                 output.write(`These files differ from the scaffold:\n${differing.map((d) => `  ${d.rel}\n`).join("")}`);
                 const answer = await terminal.question(`Overwrite these ${differing.length} file(s)? [y/N] `);

package/src/init-config.js

@@ -0,0 +1,115 @@
+"use strict";
+
+// Additively completing an apionly.yaml that already exists.
+//
+// `init` creates a file that is not there; this is the same rule applied to
+// configuration. When a kind's support is missing from an existing apionly.yaml --
+// in whole, because the library never had it, or in part, because a run was
+// interrupted between writing the fragments and writing the config for them -- the
+// slots it needs are added. What is already there, however it reads, is never
+// touched: a `defaults.openapi` block with no `lint` is a choice, not an absence.
+//
+// The unit added is a *slot*: one of the handful of places a kind's support in
+// apionly.yaml lives -- never a key inside one, which is why `slots()` below stops
+// at the map a kind occupies and goes no further into it.
+
+const YAML = require("yaml");
+
+/** Where a kind's tool is pinned in `toolchain`; the two kinds do not share a key name. */
+const TOOLCHAIN_KEY = { openapi: "redocly", asyncapi: "asyncapi" };
+const TOOLCHAIN_PIN = { openapi: "@redocly/cli@2.52.0", asyncapi: "@asyncapi/cli@6.0.2" };
+
+/**
+ * The slots scaffold(v) would fill for one kind, in the order config(v) declares them,
+ * each naming the sibling keys -- in the order to prefer -- a slot goes before when one
+ * of them is already there. `openapi` always precedes `asyncapi`, in every section that
+ * holds both; `asyncapi` precedes `placeholders`, the one section-closing key that is
+ * always there.
+ */
+function slotsFor(kind, v) {
+    const target = v.target;
+    if (kind === "openapi") {
+        return [
+            { path: ["sources"], key: "openapi", value: "openapi", before: ["asyncapi"] },
+            {
+                path: ["defaults"], key: "openapi", before: ["asyncapi", "placeholders"],
+                value: { lint: ".redocly.yaml", outputName: "openapi.yaml" },
+            },
+            { path: ["toolchain"], key: "redocly", value: TOOLCHAIN_PIN.openapi, before: ["asyncapi"] },
+            {
+                path: ["targets", target], key: "openapi", before: ["asyncapi"],
+                value: { bundle: `bundles/${target}_openapi_structure.yaml` },
+            },
+        ];
+    }
+    return [
+        { path: ["sources"], key: "asyncapi", value: "asyncapi", before: [] },
+        { path: ["defaults"], key: "asyncapi", value: { outputName: "asyncapi.yaml" }, before: ["placeholders"] },
+        { path: ["toolchain"], key: "asyncapi", value: TOOLCHAIN_PIN.asyncapi, before: [] },
+        {
+            path: ["targets", target], key: "asyncapi", before: [],
+            value: { bundle: `bundles/${target}_asyncapi_structure.yaml` },
+        },
+    ];
+}
+
+/** A slot's YAML path, dot-separated, as the report names it. */
+function slotName(slot) {
+    return [...slot.path, slot.key].join(".");
+}
+
+/**
+ * Sets `key: value` in the map at `parentPath`, before the first of `before` that is
+ * already a sibling there, or at the end when none is. Creates `parentPath` itself,
+ * as `Document#setIn` does, when it is not there yet -- there being nothing in a map
+ * that does not exist yet to come before.
+ */
+function place(doc, parentPath, key, value, before) {
+    const parent = doc.getIn(parentPath, true);
+    if (YAML.isMap(parent)) {
+        for (const candidate of before) {
+            const sibling = parent.items.find((pair) => String(pair.key) === candidate);
+            if (sibling) {
+                parent.items.splice(parent.items.indexOf(sibling), 0, doc.createPair(key, value));
+                return;
+            }
+        }
+    }
+    doc.setIn([...parentPath, key], value);
+}
+
+/**
+ * Adds to `text` -- an existing apionly.yaml -- whatever configuration slot
+ * scaffold(values) would write and this file lacks. Every value, key and comment
+ * already there survives unchanged; a slot already present, however it reads, is
+ * never touched, and neither is anything inside it.
+ *
+ * @param {string} text apionly.yaml, as it is on disk
+ * @param {object} v the values scaffold(values) was given, resolved: every value
+ *     DEFAULTS has, `values`' own where it gives one -- the shape scaffold() itself
+ *     works from, so a caller that already has that object need not rebuild it
+ * @returns {{text: string, added: string[]}} the edited text, and the slots added, in
+ *     the order scaffold() declares them; `added` is empty, and `text` is `text`
+ *     itself, when nothing was missing.
+ */
+function addMissingConfig(text, v) {
+    const doc = YAML.parseDocument(text);
+    const added = [];
+
+    // Not every file that differs is a library with a kind missing -- one that does not
+    // even declare sources.root is not an apionly.yaml this can complete, whatever it
+    // holds instead; force, or a person, is what that file needs.
+    if (!doc.hasIn(["sources", "root"])) return { text, added };
+
+    for (const kind of ["openapi", "asyncapi"].filter((k) => v.kinds.includes(k))) {
+        for (const slot of slotsFor(kind, v)) {
+            if (doc.hasIn([...slot.path, slot.key])) continue;
+            place(doc, slot.path, slot.key, slot.value, slot.before);
+            added.push(slotName(slot));
+        }
+    }
+
+    return added.length === 0 ? { text, added } : { text: doc.toString(), added };
+}
+
+module.exports = { addMissingConfig };

package/src/init.js

@@ -15,6 +15,7 @@
 const fs = require("fs");
 const path = require("path");
 const YAML = require("yaml");
+const { addMissingConfig } = require("./init-config");
 
 /** Every value the scaffold is written from, as it is when nobody chooses otherwise. */
 const DEFAULTS = Object.freeze({
@@ -307,17 +308,37 @@ function normalised(text) {
     return text.replace(/\r\n?/g, "\n").replace(/\n+$/, "");
 }
 
+const CONFIG_FILE = "apionly.yaml";
+
 /**
  * What writing these files would do to each: create it, leave it because it is
  * identical, or find it different from what would be written.
  *
- * @returns {{rel: string, status: "missing"|"identical"|"differs"}[]}
+ * apionly.yaml gets one more thing tried, ahead of "differs": whatever slot
+ * scaffold(values) would write and it lacks is added, in place, before the
+ * comparison that decides "identical" or "differs" -- so a file that is missing only
+ * a kind it never had is never reported as differing, and neither is one that is
+ * missing nothing at all. `values`, resolved as scaffold() resolves it, is what that
+ * completion is measured against; without it, apionly.yaml is compared as every
+ * other file is.
+ *
+ * @returns {{rel: string, status: "missing"|"identical"|"differs", added?: string[], text?: string}[]}
+ *     `added` and `text` -- the completed content -- are there only for apionly.yaml,
+ *     and only when something was missing from it.
  */
-function plan(targetDir, files) {
+function plan(targetDir, files, values) {
     return Object.entries(files).map(([rel, content]) => {
         const file = path.join(targetDir, rel);
         if (!fs.existsSync(file)) return { rel, status: "missing" };
-        const same = normalised(fs.readFileSync(file, "utf8")) === normalised(content);
+        const onDisk = fs.readFileSync(file, "utf8");
+        if (rel === CONFIG_FILE && values) {
+            const completed = addMissingConfig(onDisk, { ...DEFAULTS, ...values });
+            if (completed.added.length > 0) {
+                const status = normalised(completed.text) === normalised(content) ? "identical" : "differs";
+                return { rel, status, added: completed.added, text: completed.text };
+            }
+        }
+        const same = normalised(onDisk) === normalised(content);
         return { rel, status: same ? "identical" : "differs" };
     });
 }
@@ -327,13 +348,27 @@ function plan(targetDir, files) {
  *
  * A file that is not there is created. One that is there already is left alone,
  * reported as identical to what would have been written or as differing from it;
- * with `force`, one that differs is overwritten.
+ * with `force`, one that differs is overwritten, wholesale, as if this were the
+ * first time -- apionly.yaml included, whatever else it declares.
+ *
+ * Short of `force`, apionly.yaml gets one more chance: whatever configuration a
+ * missing kind needs and it lacks is added to it, leaving every value, key and
+ * comment already there exactly as it was. A kind already declared, however it
+ * reads, is never touched -- what is already there is not changed, only what is
+ * not there is added.
  */
 function init(targetDir, { values = DEFAULTS, force = false, log = () => {} } = {}) {
     const files = scaffold(values);
-    const report = { created: [], overwritten: [], identical: [], differing: [] };
-
-    for (const { rel, status } of plan(targetDir, files)) {
+    const report = { created: [], overwritten: [], identical: [], differing: [], updated: [] };
+    const updates = [];
+
+    for (const { rel, status, added, text } of plan(targetDir, files, values)) {
+        if (added && !force) {
+            fs.writeFileSync(path.join(targetDir, rel), text);
+            report.updated.push(rel);
+            updates.push({ rel, added });
+            continue;
+        }
         if (status === "identical") {
             report.identical.push(rel);
             continue;
@@ -350,6 +385,7 @@ function init(targetDir, { values = DEFAULTS, force = false, log = () => {} } =
 
     for (const rel of report.created) log(`  created    ${rel}`);
     for (const rel of report.overwritten) log(`  overwrote  ${rel}`);
+    for (const { rel, added } of updates) log(`  updated    ${rel} (added ${added.join(", ")})`);
     for (const rel of report.identical) log(`  identical  ${rel}`);
     for (const rel of report.differing) log(`  differs    ${rel} (left alone; --force overwrites)`);
     return { ...report, skipped: [...report.identical, ...report.differing] };