@arc-e-tect/api-only-publisher 0.10.0 → 0.11.0

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.10.0
+:api-only-publisher-version: 0.11.0
 
 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]
@@ -169,7 +169,7 @@ A target whose closure is untouched needs no new version, however much else in t
 |`publish [--pre-release <ids>] [--target <t>]... [--channel <c>]... [--out <dir>]`
 |Pack once, then ship those same bytes to every configured channel, or to each `--channel`.
 
-|`split --out <dir> [--by kind\|target]`
+|`split [--out <dir>] [--by kind\|target]`
 |Make the library safe to break into separate repositories.
 |===
 
@@ -651,6 +651,16 @@ What happens when the destination already has the version:
 A NuGet feed that cannot return the package it has, so there is nothing to compare, fails as a different one would.
 |===
 
+[#channel-text]
+=== What a package says about itself
+
+The Maven POM, the npm `package.json`, the NuGet `.nuspec` and a GitHub release all describe the contract.
+By default each says `API description documents for <target>.`, and a GitHub release is titled `<target> <version>`.
+`channels.<channel>.description` replaces the description, and `channels.github-release.title` and `notes` the release's title and notes (notes default to the description); `{target}` and `{version}` are filled in, as in `tagFormat`.
+
+npm publishes a release under the dist-tag `latest` and a pre-release under `next`.
+`channels.npm.releaseTag` and `prereleaseTag` name others: publishing a patch to an older line under `releaseTag: v1` keeps `latest` on the newest line, which publishing it under `latest` would move back.
+
 Credentials are read from the environment, never from configuration.
 `channels.maven.tokenEnv` names the variable, `MAVEN_TOKEN` by default, and `channels.nuget.tokenEnv` the NuGet API key's, `NUGET_API_KEY` by default; a configuration file gets committed, and a credential in a committed file is a credential that has leaked.
 
@@ -671,6 +681,7 @@ channels:
     # tokenEnv: NUGET_API_KEY            # the variable holding the API key, for a URL
     # authors: Contoso API team          # default: idPrefix
     # license: MIT                       # an SPDX expression; default: UNLICENSED
+    # description: "{target} contract"   # default: API description documents for {target}.
 ----
 
 *The package id* is `<idPrefix>.<target in PascalCase>`: target `user-account` with `idPrefix: Contoso.Contracts` is `Contoso.Contracts.UserAccount`, the dotted PascalCase .NET uses for namespaces, from a kebab-case target.
@@ -775,6 +786,8 @@ defaults:
 build:
   staging: build/staging
   dist: build/dist
+  # packages: build/packages   # where pack and publish write archives; --out overrides
+  # split: build/split         # where split writes its parts; --out overrides
 reports:
   lint: build/reports/lint
 lint:
@@ -791,6 +804,14 @@ channels:
   file:
     directory: build/publish
     clean: true        # keep only the version being published
+  # Every channel that describes a package or a release takes `description`, with
+  # {target} and {version} filled in; default: API description documents for {target}.
+  # npm:
+  #   releaseTag: latest         # the dist-tag of a release; another keeps latest where it is
+  #   prereleaseTag: next        # the dist-tag of a pre-release
+  # github-release:
+  #   title: "{target} {version}"
+  #   notes: "..."               # default: description
 
 targets:
   orders:

package/package.json

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

package/src/channels.js

@@ -16,6 +16,14 @@ const { isPrerelease, npmDistTag } = require("./version-policy");
 const { ChannelError } = require("./channel-error");
 const { publishNuget } = require("./nuget");
 
+/** What every package and release says it is, unless `description` says otherwise. */
+const DEFAULT_DESCRIPTION = "API description documents for {target}.";
+
+/** `template` with {target} and {version} filled in, as tagFormat has always been. */
+function format(template, manifest) {
+    return String(template).replace(/\{target\}/g, manifest.target).replace(/\{version\}/g, manifest.version);
+}
+
 
 /**
  * `file` -- publish to a local directory.
@@ -44,7 +52,7 @@ function publishFile(archive, manifest, options, log) {
     return { location: archiveDest };
 }
 
-function pom(groupId, artifactId, version, packaging) {
+function pom(groupId, artifactId, version, packaging, description = `API description documents for ${artifactId}.`) {
     return `<?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -54,11 +62,16 @@ function pom(groupId, artifactId, version, packaging) {
   <artifactId>${artifactId}</artifactId>
   <version>${version}</version>
   <packaging>${packaging}</packaging>
-  <description>API description documents for ${artifactId}.</description>
+  <description>${description.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")}</description>
 </project>
 `;
 }
 
+/** The POM's description: configured, or the POM's own default. */
+function pomDescription(options, manifest) {
+    return options.description ? format(options.description, manifest) : undefined;
+}
+
 /**
  * `maven` -- publish into a Maven repository layout.
  *
@@ -91,7 +104,7 @@ function publishMaven(archive, manifest, options, log) {
     const base = `${artifactId}-${version}`;
     const artifactDest = path.join(dir, `${base}.${extension}`);
     fs.copyFileSync(archive, artifactDest);
-    fs.writeFileSync(path.join(dir, `${base}.pom`), pom(groupId, artifactId, version, extension));
+    fs.writeFileSync(path.join(dir, `${base}.pom`), pom(groupId, artifactId, version, extension, pomDescription(options, manifest)));
 
     // The manifest travels beside the artifact as well as inside it, so a
     // consumer can read provenance without unpacking anything.
@@ -115,7 +128,7 @@ function publishNpm(archive, manifest, options, log) {
     const scope = options.scope;
     const name = scope ? `${scope}/${manifest.target}` : (options.namePrefix || "") + manifest.target;
     const version = manifest.version;
-    const distTag = npmDistTag(version);
+    const distTag = npmDistTag(version, options);
 
     const workDir = fs.mkdtempSync(path.join(os.tmpdir(), "api-only-npm-"));
     try {
@@ -126,7 +139,7 @@ function publishNpm(archive, manifest, options, log) {
         fs.writeFileSync(path.join(workDir, "package.json"), JSON.stringify({
             name,
             version,
-            description: `API description documents for ${manifest.target}.`,
+            description: format(options.description || DEFAULT_DESCRIPTION, manifest),
             license: options.license || "UNLICENSED",
             files: fs.readdirSync(workDir).filter((f) => f !== "package.json").sort(),
             // npm defaults a scoped package to restricted. A contract exists to be
@@ -210,9 +223,7 @@ function publishGithubRelease(archive, manifest, options, log) {
     const repository = options.repository;
     if (!repository) throw new ChannelError("the github-release channel requires a repository");
 
-    const tag = (options.tagFormat || "{target}-v{version}")
-        .replace(/\{target\}/g, manifest.target)
-        .replace(/\{version\}/g, manifest.version);
+    const tag = format(options.tagFormat || "{target}-v{version}", manifest);
 
     const gh = (args) => execFileSync("gh", args, { encoding: "utf8", stdio: "pipe" });
 
@@ -225,8 +236,8 @@ function publishGithubRelease(archive, manifest, options, log) {
 
     if (!exists) {
         const args = ["release", "create", tag, "--repo", repository,
-                      "--title", `${manifest.target} ${manifest.version}`,
-                      "--notes", `API description documents for ${manifest.target}.`];
+                      "--title", format(options.title || "{target} {version}", manifest),
+                      "--notes", format(options.notes || options.description || DEFAULT_DESCRIPTION, manifest)];
         // A pre-release is marked as one, so that "latest release" never resolves
         // to a contract that is not finished.
         if (isPrerelease(manifest.version)) args.push("--prerelease");
@@ -333,7 +344,7 @@ function publishMavenRemote(archive, manifest, options, log) {
         }
         await putFile(`${base}.${extension}`, bytes, token, "application/octet-stream");
         await putFile(`${base}.pom`,
-            Buffer.from(pom(options.groupId, artifactId, version, extension), "utf8"),
+            Buffer.from(pom(options.groupId, artifactId, version, extension, pomDescription(options, manifest)), "utf8"),
             token, "application/xml");
         await putFile(`${base}-manifest.json`,
             Buffer.from(JSON.stringify(manifest, null, 2) + "\n", "utf8"),
@@ -368,4 +379,4 @@ function publish(archive, manifest, channel, options, log = () => {}) {
     return handler(archive, manifest, options || {}, log);
 }
 
-module.exports = { publish, CHANNELS, ChannelError, pom };
+module.exports = { publish, CHANNELS, ChannelError, pom, format, DEFAULT_DESCRIPTION };

package/src/cli.js

@@ -38,7 +38,7 @@ Usage:
   api-only-publisher changed --since <ref>
   api-only-publisher pack [--pre-release <ids>] [--target <name>]... [--out <dir>]
   api-only-publisher publish [--pre-release <ids>] [--target <name>]... [--channel <name>]... [--out <dir>]
-  api-only-publisher split --out <dir> [--by kind|target]
+  api-only-publisher split [--out <dir>] [--by kind|target]
 
 Options:
   --target <name>   Restrict to one target; repeat for several. Default: all.
@@ -60,7 +60,8 @@ Options:
   --portfolio-paths <target-prefix|none>, --portfolio-location <dir>
                     config only: the value of that question; a flag always wins.
   --since <ref>     changed only: the git ref to compare the working tree against.
-  --out <dir>       pack/publish/split: where to write.
+  --out <dir>       pack/publish/split: where to write, instead of build.packages
+                    or build.split in apionly.yaml.
   --channel <name>  publish only: repeat for several. Default: every configured channel.
   --by <kind|target>  split only: the boundary to split along. Default: kind.
   -C <dir>          Run as if started in <dir>.
@@ -407,7 +408,7 @@ async function main(argv, io = {}) {
             return 0;
         }
         case "pack": {
-            const outDir = path.resolve(options.dir, options.out || "build/packages");
+            const outDir = options.out ? path.resolve(options.dir, options.out) : config.packagesDir();
             const shipped = shippedTargets(config, targets);
             const versions = versionsOf(config, shipped, options.preRelease);
             const closures = forTargets(config, undefined, shipped);
@@ -430,7 +431,7 @@ async function main(argv, io = {}) {
             return 0;
         }
         case "publish": {
-            const outDir = path.resolve(options.dir, options.out || "build/packages");
+            const outDir = options.out ? path.resolve(options.dir, options.out) : config.packagesDir();
             const configured = config.channels || {};
             const names = options.channels || Object.keys(configured);
             if (names.length === 0) {
@@ -460,7 +461,7 @@ async function main(argv, io = {}) {
             return 0;
         }
         case "split": {
-            const outDir = path.resolve(options.dir, options.out || "build/split");
+            const outDir = options.out ? path.resolve(options.dir, options.out) : config.splitDir();
             prepare(config);
             const parts = split(config, { by: options.by, outDir, log });
             const duplicated = parts.reduce((n, p) => n + p.imported.length, 0);

package/src/config.js

@@ -25,7 +25,7 @@ const SOURCES_KEYS = ["root", "openapi", "asyncapi"];
 const DEFAULTS_KEYS = ["openapi", "asyncapi", "placeholders"];
 const DEFAULTS_KIND_KEYS = { openapi: ["lint", "outputName", "fragmentPaths"], asyncapi: ["lint", "outputName", "fragmentPaths"] };
 const PLACEHOLDERS_KEYS = ["strict"];
-const BUILD_KEYS = ["staging", "dist"];
+const BUILD_KEYS = ["staging", "dist", "packages", "split"];
 const REPORTS_KEYS = ["lint"];
 const LINT_KEYS = ["unreferenced", "examples"];
 const LINT_EXAMPLES_KEYS = ["openapi", "asyncapi"];
@@ -255,6 +255,14 @@ function load(configPath) {
         stagingDir(kind) {
             return path.join(this.stagingRoot(kind), requireString(this.sources[kind], `sources.${kind}`));
         },
+        // Where pack and publish write archives, and split its parts, unless --out says
+        // otherwise; relative to this configuration, as every other path here is.
+        packagesDir() {
+            return path.resolve(this.root, this.build.packages || "build/packages");
+        },
+        splitDir() {
+            return path.resolve(this.root, this.build.split || "build/split");
+        },
         distDir(target) {
             const dist = this.build.dist || "dist";
             return path.resolve(this.root, dist, target);

package/src/nuget.js

@@ -88,7 +88,8 @@ function nuspec(id, manifest, options) {
         `    <id>${escape(id)}</id>\n` +
         `    <version>${escape(manifest.version)}</version>\n` +
         `    <authors>${escape(options.authors || options.idPrefix || id)}</authors>\n` +
-        `    <description>API description documents for ${escape(manifest.target)}.</description>\n` +
+        `    <description>${escape((options.description || "API description documents for {target}.")
+            .replace(/\{target\}/g, manifest.target).replace(/\{version\}/g, manifest.version))}</description>\n` +
         `    <license type="expression">${escape(options.license || "UNLICENSED")}</license>\n` +
         repository +
         "  </metadata>\n" +

package/src/version-policy.js

@@ -44,10 +44,11 @@ function isPrerelease(version) {
  * The npm dist-tag a version should be published under.
  *
  * A pre-release goes to `next`, never `latest`, so that `npm install <pkg>`
- * cannot pick one up by accident.
+ * cannot pick one up by accident. Both can be named otherwise -- `releaseTag` for a
+ * patch to an older line that must not become `latest`, say.
  */
-function npmDistTag(version) {
-    return isPrerelease(version) ? "next" : "latest";
+function npmDistTag(version, { releaseTag = "latest", prereleaseTag = "next" } = {}) {
+    return isPrerelease(version) ? prereleaseTag : releaseTag;
 }
 
 /**