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

package/src/init.js

@@ -322,17 +322,19 @@ const CONFIG_FILE = "apionly.yaml";
  * completion is measured against; without it, apionly.yaml is compared as every
  * other file is.
  *
+ * @param {{paths: string, location: string}} [portfolio] the portfolio section to
+ *     add when apionly.yaml lacks one; see addMissingConfig for what it does with it
  * @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, values) {
+function plan(targetDir, files, values, portfolio) {
     return Object.entries(files).map(([rel, content]) => {
         const file = path.join(targetDir, rel);
         if (!fs.existsSync(file)) return { rel, status: "missing" };
         const onDisk = fs.readFileSync(file, "utf8");
         if (rel === CONFIG_FILE && values) {
-            const completed = addMissingConfig(onDisk, { ...DEFAULTS, ...values });
+            const completed = addMissingConfig(onDisk, { ...DEFAULTS, ...values }, portfolio);
             if (completed.added.length > 0) {
                 const status = normalised(completed.text) === normalised(content) ? "identical" : "differs";
                 return { rel, status, added: completed.added, text: completed.text };
@@ -356,13 +358,17 @@ function plan(targetDir, files, values) {
  * 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.
+ *
+ * `portfolio`, given, is added the same way, as one more slot: whether the
+ * library is about to have more than one target -- and so whether this is worth
+ * asking about at all -- is decided before init is called, not here.
  */
-function init(targetDir, { values = DEFAULTS, force = false, log = () => {} } = {}) {
+function init(targetDir, { values = DEFAULTS, force = false, log = () => {}, portfolio = null } = {}) {
     const files = scaffold(values);
     const report = { created: [], overwritten: [], identical: [], differing: [], updated: [] };
     const updates = [];
 
-    for (const { rel, status, added, text } of plan(targetDir, files, values)) {
+    for (const { rel, status, added, text } of plan(targetDir, files, values, portfolio)) {
         if (added && !force) {
             fs.writeFileSync(path.join(targetDir, rel), text);
             report.updated.push(rel);

package/src/pipeline.js

@@ -9,8 +9,11 @@ const YAML = require("yaml");
 
 const { substituteFile } = require("./placeholders");
 const { stampFile } = require("./version");
-const { generateAsyncApi, isAggregate } = require("./aggregate");
+const { generateAsyncApi, generateOpenApi, openapiPushDown, isAggregate } = require("./aggregate");
 const { stampFiles, componentPaths, strayPaths, fragmentStamps, unresolvedStamps, FragmentPathError, KEY } = require("./fragment-paths");
+const {
+    asyncapiOperationsWithoutExamples, openapiOperationsWithoutExamples, asyncapiMessage, openapiMessage,
+} = require("./examples");
 
 class BuildError extends Error {}
 
@@ -85,7 +88,7 @@ function substituteTree(config, kind, log) {
 }
 
 function bundle(config, target, kind, outFile, log, { stagingRoot } = {}) {
-    const source = config.bundlePath(target, kind, stagingRoot);
+    const source = config.bundleRootPath(target, kind, stagingRoot);
     if (!fs.existsSync(source)) {
         throw new BuildError(`target '${target}': bundle root not found at ${source}`);
     }
@@ -130,7 +133,7 @@ function bundleWithFragmentPaths(config, target, kind, outFile, log) {
         return YAML.parse(fs.readFileSync(file, "utf8"));
     };
 
-    log(`-- Bundling ${path.basename(config.bundlePath(target, kind))} with ${KEY}`);
+    log(`-- Bundling ${path.basename(config.bundleRootPath(target, kind))} with ${KEY}`);
     const discovered = componentPaths(pass("discover", null));
     const fragments = new Set([...discovered.values()].filter(Boolean));
     const document = pass("stamp", fragments);
@@ -169,7 +172,7 @@ function bundleInlinedWithFragmentPaths(config, target, kind, outFile, log) {
     const root = path.join(scratch, "stamp");
     fs.cpSync(config.stagingRoot(kind), root, { recursive: true });
 
-    const bundleRoot = path.relative(root, config.bundlePath(target, kind, root)).split(path.sep).join("/");
+    const bundleRoot = path.relative(root, config.bundleRootPath(target, kind, root)).split(path.sep).join("/");
     try {
         stampFiles(root, { except: new Set([bundleRoot]) });
     } catch (error) {
@@ -177,7 +180,7 @@ function bundleInlinedWithFragmentPaths(config, target, kind, outFile, log) {
         throw error;
     }
 
-    log(`-- Bundling ${path.basename(config.bundlePath(target, kind))} with ${KEY}`);
+    log(`-- Bundling ${path.basename(config.bundleRootPath(target, kind))} with ${KEY}`);
     const file = path.join(scratch, "stamp.yaml");
     bundle(config, target, kind, file, () => {}, { stagingRoot: root });
     const document = YAML.parse(fs.readFileSync(file, "utf8"));
@@ -205,6 +208,33 @@ function lint(config, kind, file, log, { report = false, reportFile = null } = {
     if (report && output.trim()) log(output.trimEnd());
 }
 
+/**
+ * Reports operations of a built document whose example this kind's toolchain
+ * could use, and does not have -- separately from lint's own findings, since
+ * "your contract is wrong" and "your contract limits what you can do with it
+ * downstream" are different claims and read worse conflated.
+ *
+ * Governed by `lint.examples.<kind>`: `warn`, the default, logs each finding and
+ * continues; `error` logs them and fails the build; `off` does not look.
+ */
+function checkExamples(config, kind, file, log) {
+    const mode = config.lintExamples(kind);
+    if (mode === "off") return;
+
+    const document = YAML.parse(fs.readFileSync(file, "utf8"));
+    const findings = kind === "asyncapi"
+        ? asyncapiOperationsWithoutExamples(document).map(asyncapiMessage)
+        : openapiOperationsWithoutExamples(document).map(openapiMessage);
+    if (findings.length === 0) return;
+
+    for (const message of findings) log(`-- ${message}`);
+    if (mode === "error") {
+        throw new BuildError(
+            `${findings.length} operation(s) in ${path.basename(file)} have no example ` +
+            "(lint.examples." + kind + " is error):\n" + findings.map((m) => `  ${m}`).join("\n"));
+    }
+}
+
 /**
  * Copy a built document to the project that implements the target.
  *
@@ -240,8 +270,11 @@ function prepare(config, { kinds = ["openapi", "asyncapi"], log = () => {} } = {
         stage(config, kind, log);
         substituteTree(config, kind, log);
         for (const target of targets) {
-            if (isAggregate(config, target, kind) && kind === "asyncapi") {
+            if (!isAggregate(config, target, kind)) continue;
+            if (kind === "asyncapi") {
                 generateAsyncApi(config, target, { log });
+            } else {
+                generateOpenApi(config, target, { log });
             }
         }
     }
@@ -269,14 +302,13 @@ function build(config, { targets, versionOf = () => null, kinds = ["openapi", "a
             log(`\n=== ${target} (${kind}) ===`);
             // An aggregate has no hand-written bundle root; it is synthesised from
             // its members into the staged tree, so it can never fall behind them.
+            let openapiOwners = null;
             if (isAggregate(config, target, kind)) {
-                if (kind !== "asyncapi") {
-                    throw new BuildError(
-                        `target '${target}': aggregate is only supported for asyncapi; ` +
-                        `an OpenAPI portfolio is a hand-written table of contents of $refs`
-                    );
+                if (kind === "asyncapi") {
+                    generateAsyncApi(config, target, { log });
+                } else {
+                    openapiOwners = generateOpenApi(config, target, { log }).owners;
                 }
-                generateAsyncApi(config, target, { log });
             }
             const outFile = path.join(config.distDir(target), config.outputName(kind));
             if (config.fragmentPaths(kind)) {
@@ -284,12 +316,25 @@ function build(config, { targets, versionOf = () => null, kinds = ["openapi", "a
             } else {
                 bundle(config, target, kind, outFile, log);
             }
+            if (openapiOwners) {
+                // Pass 2: only once bundling has resolved every $ref does an
+                // operation's id, or whether it already sets its own security,
+                // become visible at all.
+                const { text, reconciled } = openapiPushDown(fs.readFileSync(outFile, "utf8"), openapiOwners, {
+                    operationIdStrategy: config.portfolioOperationIdStrategy(),
+                });
+                fs.writeFileSync(outFile, text);
+                for (const r of reconciled) {
+                    log(`-- Reconciled tag '${r.key}': two members describe it differently; kept the first's`);
+                }
+            }
             const version = versionOf(target);
             if (version) {
                 log(`-- Stamping version '${version}'`);
                 stampFile(outFile, version);
             }
             lint(config, kind, outFile, log);
+            checkExamples(config, kind, outFile, log);
 
             let distributed = null;
             if (config.isPublished(target)) {
@@ -303,4 +348,6 @@ function build(config, { targets, versionOf = () => null, kinds = ["openapi", "a
     return results;
 }
 
-module.exports = { build, prepare, stage, substituteTree, bundle, bundleWithFragmentPaths, lint, distribute, BuildError };
+module.exports = {
+    build, prepare, stage, substituteTree, bundle, bundleWithFragmentPaths, lint, checkExamples, distribute, BuildError,
+};

package/src/split.js

@@ -111,7 +111,7 @@ function split(config, { by = "kind", outDir, log = () => {} } = {}) {
         // Union of every member's closure.
         const files = new Set();
         for (const { target, kind } of members) {
-            const entry = config.bundlePath(target, kind);
+            const entry = config.bundleRootPath(target, kind);
             if (!fs.existsSync(entry)) {
                 throw new SplitError(
                     `target '${target}': ${kind} bundle root not found at ${entry}; build first so the tree is staged`