@arc-e-tect/api-only-publisher 0.0.0

package/src/closure.js

@@ -0,0 +1,128 @@
+"use strict";
+
+// The dependency closure of a target.
+//
+// Independent per-target versioning has one non-obvious consequence, and this is
+// the machinery that pays for it. A change under components/common/ affects every
+// target that reaches it; a change under one product's own context affects only
+// that one. Under repository-wide versioning that distinction is invisible,
+// because everything bumps together. Under per-target versioning the release job
+// has to work out which targets a commit actually changed.
+//
+// The closure is computed over the *staged, substituted* tree rather than the raw
+// source, so that a change to a Markdown snippet -- which genuinely changes the
+// published document -- is detected.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+class ClosureError extends Error {}
+
+// $ref values, in both the quoted and unquoted YAML forms the fragments use.
+const REF = /\$ref:\s*(?:'([^']+)'|"([^"]+)"|([^\s#'"][^\s]*))/g;
+
+/**
+ * Every file reachable from `entry` by following $refs transitively.
+ *
+ * A JSON-pointer-only reference ("#/channels/auditV1") points inside the file
+ * that contains it and adds nothing to the closure. A reference with a path
+ * before the "#" contributes that file.
+ *
+ * @returns {string[]} absolute paths, sorted, including the entry file
+ */
+function resolve(entry, { onMissing = "throw" } = {}) {
+    const seen = new Set();
+    const missing = [];
+    const queue = [path.resolve(entry)];
+
+    while (queue.length > 0) {
+        const file = queue.shift();
+        if (seen.has(file)) continue;
+
+        if (!fs.existsSync(file)) {
+            missing.push(file);
+            if (onMissing === "throw") {
+                throw new ClosureError(`$ref target does not exist: ${file}`);
+            }
+            continue;
+        }
+        seen.add(file);
+
+        let text;
+        try {
+            text = fs.readFileSync(file, "utf8");
+        } catch {
+            continue;
+        }
+
+        for (const match of text.matchAll(REF)) {
+            const ref = match[1] || match[2] || match[3];
+            if (!ref || ref.startsWith("#")) continue;
+            const [relPath] = ref.split("#");
+            if (!relPath) continue;
+            queue.push(path.resolve(path.dirname(file), relPath));
+        }
+    }
+
+    return { files: [...seen].sort(), missing };
+}
+
+/**
+ * A content hash over a target's closure.
+ *
+ * Content-addressed and order-stable: each file contributes its path relative to
+ * `root` and the SHA-256 of its bytes, in sorted order. Recording this alongside
+ * a released version is what lets a later commit decide whether the target
+ * actually changed, without re-reading the release.
+ */
+function hash(files, root) {
+    const digest = crypto.createHash("sha256");
+    for (const file of [...files].sort()) {
+        const rel = path.relative(root, file).split(path.sep).join("/");
+        digest.update(rel);
+        digest.update("\0");
+        digest.update(crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"));
+        digest.update("\n");
+    }
+    return digest.digest("hex");
+}
+
+/**
+ * Closures for every target that declares a bundle of the given kinds.
+ *
+ * The staged tree must already exist; callers stage first so that the closure
+ * covers substituted content.
+ *
+ * @returns {Map<string, {files: string[], sha256: string, byKind: object}>}
+ */
+function forTargets(config, kinds = ["openapi", "asyncapi"]) {
+    const result = new Map();
+
+    for (const kind of kinds) {
+        for (const target of config.targetsFor(kind)) {
+            const entry = config.bundlePath(target, kind);
+            if (!fs.existsSync(entry)) {
+                throw new ClosureError(
+                    `target '${target}': ${kind} bundle root not found at ${entry}; stage the tree first`
+                );
+            }
+            const { files } = resolve(entry);
+            const existing = result.get(target) || { files: [], byKind: {} };
+            existing.byKind[kind] = files;
+            existing.files = [...new Set(existing.files.concat(files))].sort();
+            result.set(target, existing);
+        }
+    }
+
+    // Hash against the staging root of whichever kind the files came from, so
+    // the recorded paths are stable across machines and checkouts.
+    for (const [target, entry] of result) {
+        const roots = Object.keys(entry.byKind).map((k) => config.stagingRoot(k));
+        entry.sha256 = hash(entry.files, roots[0]);
+        result.set(target, entry);
+    }
+    return result;
+}
+
+module.exports = { resolve, hash, forTargets, ClosureError, REF };

package/src/config.js

@@ -0,0 +1,157 @@
+"use strict";
+
+// Reading and validating apionly.yaml.
+//
+// The configuration is the single source of truth for what this library builds:
+// it replaced the per-script SERVICES arrays, and the `apis:` map that said an
+// overlapping thing under a different name.
+
+const fs = require("fs");
+const path = require("path");
+const YAML = require("yaml");
+
+const CONFIG_NAME = "apionly.yaml";
+const SUPPORTED_SCHEMA_VERSION = 1;
+
+class ConfigError extends Error {}
+
+// Walk up from `startDir` looking for apionly.yaml, so the CLI can be run from
+// anywhere inside the specification repository.
+function locate(startDir) {
+    let dir = path.resolve(startDir);
+    for (;;) {
+        const candidate = path.join(dir, CONFIG_NAME);
+        if (fs.existsSync(candidate)) return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            throw new ConfigError(
+                `no ${CONFIG_NAME} found in ${path.resolve(startDir)} or any parent directory`
+            );
+        }
+        dir = parent;
+    }
+}
+
+function requireString(value, what) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new ConfigError(`${what} must be a non-empty string`);
+    }
+    return value;
+}
+
+function load(configPath) {
+    const raw = fs.readFileSync(configPath, "utf8");
+    let parsed;
+    try {
+        parsed = YAML.parse(raw);
+    } catch (error) {
+        throw new ConfigError(`${configPath} is not valid YAML: ${error.message}`);
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        throw new ConfigError(`${configPath} is empty`);
+    }
+
+    if (parsed.schemaVersion !== SUPPORTED_SCHEMA_VERSION) {
+        throw new ConfigError(
+            `${configPath} declares schemaVersion ${JSON.stringify(parsed.schemaVersion)}; ` +
+            `this version of api-only-publisher understands ${SUPPORTED_SCHEMA_VERSION}`
+        );
+    }
+
+    const root = path.dirname(configPath);
+    const sources = parsed.sources || {};
+    requireString(sources.root, "sources.root");
+
+    const targets = parsed.targets;
+    if (!targets || typeof targets !== "object" || Object.keys(targets).length === 0) {
+        throw new ConfigError(`${configPath} declares no targets`);
+    }
+
+    // Declaration order is preserved deliberately: it is what makes one run's
+    // console output comparable with the next.
+    for (const [name, target] of Object.entries(targets)) {
+        if (!target || typeof target !== "object") {
+            throw new ConfigError(`target '${name}' is not a mapping`);
+        }
+        const kinds = ["openapi", "asyncapi"].filter((k) => target[k]);
+        if (kinds.length === 0) {
+            throw new ConfigError(
+                `target '${name}' declares neither an openapi nor an asyncapi bundle`
+            );
+        }
+        for (const kind of kinds) {
+            requireString(target[kind].bundle, `targets.${name}.${kind}.bundle`);
+        }
+    }
+
+    return {
+        path: configPath,
+        root,
+        schemaVersion: parsed.schemaVersion,
+        sources,
+        defaults: parsed.defaults || {},
+        toolchain: parsed.toolchain || {},
+        build: parsed.build || {},
+        distribution: parsed.distribution || null,
+        channels: parsed.channels || {},
+        targets,
+
+        // --- derived accessors, so callers never re-derive a path themselves ---
+
+        sourceRoot() {
+            return path.resolve(this.root, this.sources.root);
+        },
+        stagingRoot(kind) {
+            const staging = this.build.staging || "build/staging";
+            return path.resolve(this.root, staging, kind);
+        },
+        // The subtree of the staged mirror that holds one specification type.
+        stagingDir(kind) {
+            return path.join(this.stagingRoot(kind), requireString(this.sources[kind], `sources.${kind}`));
+        },
+        distDir(target) {
+            const dist = this.build.dist || "dist";
+            return path.resolve(this.root, dist, target);
+        },
+        outputName(kind) {
+            const name = (this.defaults[kind] || {}).outputName;
+            return requireString(name, `defaults.${kind}.outputName`);
+        },
+        lintConfig(kind) {
+            const lint = (this.defaults[kind] || {}).lint;
+            return lint ? path.resolve(this.root, lint) : null;
+        },
+        tool(name) {
+            return requireString(this.toolchain[name], `toolchain.${name}`);
+        },
+        // Targets declaring a bundle of this kind, in declaration order.
+        targetsFor(kind) {
+            return Object.keys(this.targets).filter((t) => this.targets[t][kind]);
+        },
+        // A target with `publish: false` is a documentation view rather than a
+        // contract any one project implements: built and linted, never shipped.
+        isPublished(target) {
+            return this.targets[target].publish !== false;
+        },
+        bundlePath(target, kind) {
+            return path.join(this.stagingDir(kind), this.targets[target][kind].bundle);
+        },
+        // Where a distributed document is copied to, from the transitional
+        // `distribution` block. Null once that block is gone.
+        destinationDir(target) {
+            if (!this.distribution) return null;
+            const layout = requireString(this.distribution.layout, "distribution.layout");
+            return path.resolve(
+                this.root,
+                this.distribution.root || ".",
+                layout.replace(/\{target\}/g, target)
+            );
+        },
+    };
+}
+
+function loadFrom(startDir) {
+    return load(locate(startDir));
+}
+
+module.exports = { load, loadFrom, locate, ConfigError, CONFIG_NAME, SUPPORTED_SCHEMA_VERSION };

package/src/index.js

@@ -0,0 +1,22 @@
+"use strict";
+
+// The programmatic surface.
+//
+// The CLI is the usual way in, but a release job that wants to decide something
+// for itself -- which targets changed, what a closure hashes to, whether a
+// version is a pre-release -- should not have to parse console output to find
+// out. Everything the CLI does is available here directly.
+
+module.exports = {
+    ...require("./config"),
+    ...require("./placeholders"),
+    ...require("./version"),
+    ...require("./version-policy"),
+    ...require("./closure"),
+    ...require("./aggregate"),
+    ...require("./pipeline"),
+    ...require("./pack"),
+    ...require("./changed"),
+    ...require("./split"),
+    ...require("./channels"),
+};

package/src/init.js

@@ -0,0 +1,183 @@
+"use strict";
+
+// `init` scaffolds a specification repository.
+//
+// This is how the *conventions* become reusable, as opposed to the code. The
+// layout below is the one the library documentation describes; a project that
+// starts from it inherits the common/<product> split, the shared info block with
+// placeholder snippets, and a configuration that already builds.
+
+const fs = require("fs");
+const path = require("path");
+
+const CONFIG = `# apionly.yaml
+#
+# Declares what this library builds, from where, and where each document goes.
+
+schemaVersion: 1
+
+sources:
+  root: specs
+  openapi: openapi
+  asyncapi: asyncapi
+
+defaults:
+  openapi:
+    lint: .redocly.yaml
+    outputName: openapi.yaml
+  asyncapi:
+    outputName: asyncapi.yaml
+  placeholders:
+    # Fail the build on a {{token}} with no matching Markdown file, rather than
+    # emitting a marker into a published contract.
+    strict: true
+
+build:
+  staging: build/staging
+  dist: dist
+
+toolchain:
+  redocly: "@redocly/cli@2.52.0"
+  asyncapi: "@asyncapi/cli@6.0.2"
+
+targets:
+  example-service:
+    openapi:
+      bundle: bundles/example-service_openapi_structure.yaml
+`;
+
+const INFO = `title: Example API
+version: 0.0.0
+description: |
+  What this API is for.
+
+  {{conventions}}
+contact:
+  name: Example Team
+  url: https://example.invalid
+license:
+  name: Apache-2.0
+  url: https://www.apache.org/licenses/LICENSE-2.0.html
+`;
+
+const CONVENTIONS = `## Conventions
+
+Prose shared by every document in this library lives in a Markdown snippet like
+this one, pulled into the specification by a placeholder token. Replace this file
+with whatever your own API consumers need to know up front -- pagination, status
+codes, error shapes.
+`;
+
+const SERVERS = `- url: https://api.example.invalid
+  description: Production.
+`;
+
+const BUNDLE = `openapi: 3.1.1
+info:
+  $ref: '../shared/info.yaml'
+servers:
+  $ref: '../shared/servers.yaml'
+security:
+  - bearerAuth: []
+tags: []
+paths:
+  /v1/examples:
+    $ref: '../paths/example/ExamplesV1.yaml'
+components:
+  securitySchemes:
+    bearerAuth:
+      $ref: '../components/common/security/BearerAuth.yaml'
+`;
+
+const SECURITY_SCHEME = `type: http
+scheme: bearer
+bearerFormat: JWT
+`;
+
+const PROBLEM = `description: The request was not valid.
+content:
+  application/problem+json:
+    schema:
+      # RFC 9457. A problem shape is product-wide infrastructure, so it lives
+      # under components/common/ however service-specific its meaning.
+      type: object
+      properties:
+        type:
+          type: string
+          format: uri
+        title:
+          type: string
+        status:
+          type: integer
+        detail:
+          type: string
+      required:
+        - type
+        - title
+        - status
+`;
+
+const PATH_FRAGMENT = `get:
+  operationId: listExamples
+  summary: List examples.
+  responses:
+    '200':
+      description: The examples.
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              type: string
+    '400':
+      $ref: '../../components/common/responses/errors/InvalidRequestProblemV1.yaml'
+`;
+
+const REDOCLY = `# Lint rules for this library.
+#
+# 'recommended' is Redocly's own baseline. Narrow or widen it as the library
+# grows -- these rules are the governance the library applies to itself, which is
+# why they live here rather than in any project that consumes the output.
+extends:
+  - recommended
+`;
+
+const GITIGNORE = `build/
+dist/
+node_modules/
+`;
+
+const FILES = {
+    "apionly.yaml": CONFIG,
+    ".redocly.yaml": REDOCLY,
+    ".gitignore": GITIGNORE,
+    "specs/openapi/shared/info.yaml": INFO,
+    "specs/openapi/shared/conventions.md": CONVENTIONS,
+    "specs/openapi/shared/servers.yaml": SERVERS,
+    "specs/openapi/bundles/example-service_openapi_structure.yaml": BUNDLE,
+    "specs/openapi/paths/example/ExamplesV1.yaml": PATH_FRAGMENT,
+    "specs/openapi/components/common/security/BearerAuth.yaml": SECURITY_SCHEME,
+    "specs/openapi/components/common/responses/errors/InvalidRequestProblemV1.yaml": PROBLEM,
+};
+
+function init(targetDir, { force = false, log = () => {} } = {}) {
+    const created = [];
+    const skipped = [];
+
+    for (const [rel, content] of Object.entries(FILES)) {
+        const file = path.join(targetDir, rel);
+        if (fs.existsSync(file) && !force) {
+            skipped.push(rel);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, content);
+        created.push(rel);
+    }
+
+    for (const rel of created) log(`  created  ${rel}`);
+    for (const rel of skipped) log(`  exists   ${rel} (left alone; --force overwrites)`);
+    return { created, skipped };
+}
+
+module.exports = { init, FILES };

package/src/pack.js

@@ -0,0 +1,125 @@
+"use strict";
+
+// Packing a built target into a distributable archive plus its manifest.
+//
+// The manifest is what makes provenance auditable, and it is the only thing the
+// Publisher and the Subscriber agree on. Treat its shape as expensive to change.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { execFileSync } = require("child_process");
+const YAML = require("yaml");
+
+const MANIFEST_NAME = "manifest.json";
+const MANIFEST_SCHEMA_VERSION = 1;
+
+class PackError extends Error {}
+
+function sha256(file) {
+    return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+function gitInfo(cwd) {
+    const git = (args) => {
+        try {
+            return execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+        } catch {
+            return null;
+        }
+    };
+    return {
+        repository: git(["config", "--get", "remote.origin.url"]),
+        commit: git(["rev-parse", "HEAD"]),
+    };
+}
+
+/**
+ * Build the manifest for one target.
+ *
+ * Computed once, before any channel fan-out, so that every channel ships the
+ * same bytes. Building it per channel invites the npm copy and the Maven copy of
+ * one version to differ by a line ending, which surfaces months later as an
+ * unexplainable verify failure.
+ */
+function manifest(config, target, { version, files, closureSha256, producedAt = new Date() }) {
+    if (!version) throw new PackError(`target '${target}': pack requires a version`);
+
+    const source = gitInfo(config.root);
+    return {
+        schemaVersion: MANIFEST_SCHEMA_VERSION,
+        target,
+        version,
+        producedAt: producedAt.toISOString().replace(/\.\d{3}Z$/, "Z"),
+        closureSha256,
+        source,
+        files: files
+            .map((file) => ({ path: path.basename(file), sha256: sha256(file) }))
+            .sort((a, b) => (a.path < b.path ? -1 : 1)),
+    };
+}
+
+/**
+ * Write the manifest into a target's dist directory and archive the whole thing.
+ *
+ * @returns {{archive: string, manifest: object, manifestPath: string}}
+ */
+function pack(config, target, { version, closureSha256, outDir, log = () => {} }) {
+    const distDir = config.distDir(target);
+    if (!fs.existsSync(distDir)) {
+        throw new PackError(`target '${target}': nothing built at ${distDir}; run 'build' first`);
+    }
+
+    const documents = fs
+        .readdirSync(distDir)
+        .filter((name) => /\.ya?ml$/.test(name))
+        .map((name) => path.join(distDir, name))
+        .sort();
+    if (documents.length === 0) {
+        throw new PackError(`target '${target}': no documents in ${distDir}`);
+    }
+
+    // A manifest that claims a version the documents were not stamped with is
+    // worse than no manifest: every downstream check would agree with it, and the
+    // mismatch would only surface as a consumer reading a contract whose
+    // info.version is not the version they asked for. Nothing else in the
+    // pipeline catches this, because `pack` is the first step that takes the
+    // version on trust from its caller rather than deriving it.
+    for (const document of documents) {
+        let declared;
+        try {
+            const parsed = YAML.parse(fs.readFileSync(document, "utf8"));
+            declared = parsed && parsed.info ? String(parsed.info.version) : null;
+        } catch (error) {
+            throw new PackError(`${document} is not valid YAML: ${error.message}`);
+        }
+        if (declared !== String(version)) {
+            throw new PackError(
+                `target '${target}': ${path.basename(document)} declares info.version '${declared}' ` +
+                `but is being packed as '${version}'. Build with --version ${version} first.`
+            );
+        }
+    }
+
+    const data = manifest(config, target, { version, files: documents, closureSha256 });
+    const manifestPath = path.join(distDir, MANIFEST_NAME);
+    fs.writeFileSync(manifestPath, JSON.stringify(data, null, 2) + "\n");
+
+    fs.mkdirSync(outDir, { recursive: true });
+    const archive = path.join(outDir, `${target}-${version}.tgz`);
+
+    // Deterministic archive: sorted entry names, and no mtime/owner noise, so the
+    // same inputs produce the same bytes on any machine.
+    const entries = documents.map((d) => path.basename(d)).concat([MANIFEST_NAME]).sort();
+    execFileSync("tar", [
+        "-czf", archive,
+        "-C", distDir,
+        "--numeric-owner",
+        ...entries,
+    ], { encoding: "utf8" });
+
+    log(`-- Packed ${path.basename(archive)} (${data.files.length} document(s))`);
+    return { archive, manifest: data, manifestPath };
+}
+
+module.exports = { pack, manifest, sha256, MANIFEST_NAME, MANIFEST_SCHEMA_VERSION, PackError };