@arc-e-tect/api-only-publisher 0.1.0 → 0.2.0

package/README.adoc

@@ -138,6 +138,7 @@ stands. This is how the *conventions* become reusable, as opposed to the code.
 
 |`lint`
 |Lint what is already built, without rebuilding, for fast local feedback.
+Without `--target`, it also fails on a fragment no target reaches, as <<unreferenced,A fragment no target reaches fails the lint §>> describes.
 
 |`targets`
 |List the declared targets, what each one builds, and whether it is distributed.
@@ -420,6 +421,8 @@ build:
   dist: dist
 reports:
   lint: build/reports/lint
+lint:
+  unreferenced: error  # a fragment no target reaches: error, warn or off
 
 toolchain:
   redocly: "@redocly/cli@2.52.0"
@@ -473,6 +476,21 @@ from the directory it was told to use, so a snippet one level up was invisible
 and the workaround was to move the Markdown files. The search now starts at the
 staged source root.
 
+[[unreferenced]]
+=== A fragment no target reaches fails the lint
+
+A linter checks documents, and a fragment reaches a document only through a `$ref`.
+A fragment that no target references is therefore never linted, however wrong it is, until the day a target starts to use it.
+
+So `lint`, run without `--target`, also lists every YAML file under the source root that no target's closure reaches, in `build/reports/lint/unreferenced.txt`, and fails when there is one.
+Every target counts, `publish: false` ones included, because they are linted too.
+That reports a fragment that does not comply before anything uses it, and finds a definition left behind by a change that stopped using it.
+
+`lint.unreferenced` in `apionly.yaml` sets what happens: `error` by default, `warn` to report without failing, or `off` not to look.
+`lint --target` does not look, because an unreferenced fragment belongs to no target.
+
+`lint` lints every document even when one of them fails, and names every failure at the end, so a single run reports all of them.
+
 === Version stamping edits one scalar
 
 `info.version` is located structurally and that one scalar is spliced. It is

package/package.json

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

package/src/cli.js

@@ -15,6 +15,7 @@ const { split, SplitError } = require("./split");
 const { publish, ChannelError } = require("./channels");
 const { VersionError: PolicyError, describe } = require("./version-policy");
 const { versionOf, BundleVersionError } = require("./bundle-version");
+const { unreferenced } = require("./unreferenced");
 
 const USAGE = `api-only-publisher -- build and distribute API description documents
 
@@ -162,26 +163,61 @@ async function main(argv) {
         }
         case "lint": {
             // Lint without rebuilding, for fast local feedback on what is already
-            // in dist/.
+            // in dist/. Every selected document is linted even when one fails, so
+            // one run reports every failure rather than only the first.
             const fs = require("fs");
             const { lint } = require("./pipeline");
+            const failures = [];
             let linted = 0;
             for (const kind of ["openapi", "asyncapi"]) {
                 for (const target of config.targetsFor(kind)) {
                     if (targets && !targets.includes(target)) continue;
                     const file = path.join(config.distDir(target), config.outputName(kind));
                     if (!fs.existsSync(file)) {
-                        throw new BuildError(`${file} does not exist; run 'build' first`);
+                        failures.push(`${target} (${kind}): ${file} does not exist; run 'build' first`);
+                        continue;
                     }
                     log(`=== ${target} (${kind}) ===`);
-                    lint(config, kind, file, log, {
-                        report: true,
-                        reportFile: config.lintReport(target, kind),
-                    });
+                    try {
+                        lint(config, kind, file, log, {
+                            report: true,
+                            reportFile: config.lintReport(target, kind),
+                        });
+                    } catch (error) {
+                        if (!(error instanceof BuildError)) throw error;
+                        console.error(error.message);
+                        failures.push(`${target} (${kind})`);
+                    }
                     linted += 1;
                 }
             }
             log(`\nLinted ${linted} document(s).`);
+
+            // A fragment no target reaches is never linted, so it is looked for
+            // here -- only when every target is linted, since it belongs to none.
+            const mode = config.lintUnreferenced();
+            let orphaned = null;
+            if (!targets && mode !== "off") {
+                prepare(config);
+                const orphans = unreferenced(config);
+                const reportFile = config.unreferencedReport();
+                fs.mkdirSync(path.dirname(reportFile), { recursive: true });
+                fs.writeFileSync(reportFile, orphans.map((file) => `${file}\n`).join(""));
+                if (orphans.length > 0) {
+                    orphaned =
+                        `${orphans.length} fragment(s) not reachable from any target, so nothing lints them:\n` +
+                        orphans.map((file) => `  ${file}`).join("\n") +
+                        "\nReference each one from a target's bundle, or delete it.";
+                    if (mode === "warn") log(orphaned);
+                }
+            }
+
+            const problems = [];
+            if (failures.length > 0) {
+                problems.push(`lint failed for ${failures.length} document(s): ${failures.join("; ")}`);
+            }
+            if (orphaned && mode === "error") problems.push(orphaned);
+            if (problems.length > 0) throw new BuildError(problems.join("\n\n"));
             return 0;
         }
         case "closure": {

package/src/config.js

@@ -93,6 +93,7 @@ function load(configPath) {
         toolchain: parsed.toolchain || {},
         build: parsed.build || {},
         reports: parsed.reports || {},
+        lint: parsed.lint || {},
         distribution: parsed.distribution || null,
         channels: parsed.channels || {},
         targets,
@@ -126,6 +127,21 @@ function load(configPath) {
             const reports = this.reports.lint || "build/reports/lint";
             return path.resolve(this.root, reports, target, `${kind}.txt`);
         },
+        // Where lint lists the fragments no target reaches.
+        unreferencedReport() {
+            const reports = this.reports.lint || "build/reports/lint";
+            return path.resolve(this.root, reports, "unreferenced.txt");
+        },
+        // What lint does about a fragment no target reaches: `error`, the default,
+        // fails the lint; `warn` reports it; `off` does not look.
+        lintUnreferenced() {
+            const configured = this.lint.unreferenced;
+            const mode = configured === undefined ? "error" : configured === false ? "off" : configured;
+            if (!["error", "warn", "off"].includes(mode)) {
+                throw new ConfigError(`lint.unreferenced must be error, warn or off, not ${JSON.stringify(configured)}`);
+            }
+            return mode;
+        },
         tool(name) {
             return requireString(this.toolchain[name], `toolchain.${name}`);
         },

package/src/index.js

@@ -14,6 +14,7 @@ module.exports = {
     ...require("./version-policy"),
     ...require("./bundle-version"),
     ...require("./closure"),
+    ...require("./unreferenced"),
     ...require("./aggregate"),
     ...require("./pipeline"),
     ...require("./pack"),

package/src/unreferenced.js

@@ -0,0 +1,53 @@
+"use strict";
+
+// Fragments no target reaches.
+//
+// A linter checks documents, and a fragment reaches a document only through a
+// $ref. A fragment that no target references is therefore never linted, however
+// wrong it is, until the day a target starts to use it. Looking for unreferenced
+// fragments is how that is caught before then -- and how a definition left behind
+// by a change that stopped using it is found at all.
+
+const fs = require("fs");
+const path = require("path");
+
+const { forTargets } = require("./closure");
+
+function yamlFiles(dir) {
+    const files = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) files.push(...yamlFiles(full));
+        else if (entry.isFile() && /\.ya?ml$/.test(entry.name)) files.push(full);
+    }
+    return files;
+}
+
+const portable = (file) => file.split(path.sep).join("/");
+
+/**
+ * Every YAML file under the source root that no target's closure reaches,
+ * relative to the source root and sorted.
+ *
+ * Every target counts, `publish: false` ones included: a documentation view is
+ * linted like any other target, so whatever it reaches is linted too. The staged
+ * tree must already exist, as for forTargets.
+ *
+ * @returns {string[]}
+ */
+function unreferenced(config) {
+    const reached = new Set();
+    for (const [, entry] of forTargets(config)) {
+        for (const [kind, files] of Object.entries(entry.byKind)) {
+            const stagingRoot = config.stagingRoot(kind);
+            for (const file of files) reached.add(portable(path.relative(stagingRoot, file)));
+        }
+    }
+    const sourceRoot = config.sourceRoot();
+    return yamlFiles(sourceRoot)
+        .map((file) => portable(path.relative(sourceRoot, file)))
+        .filter((file) => !reached.has(file))
+        .sort();
+}
+
+module.exports = { unreferenced };