rman 1.0.9 → 1.0.12

package/core/config.js

@@ -3,7 +3,9 @@ import * as yaml from 'js-yaml';
 import { createRequire } from 'module';
 import path from 'path';
 import merge from 'putil-merge';
+import semver from 'semver';
 import { pathToFileURL } from 'url';
+import vm from 'vm';
 /**
  * Identity helper for authoring a `.rmanrc.cjs`/`.mjs`/`.js` config with full type-checking and
  * autocomplete - the same `defineConfig` pattern Vite/Vitest use. Returns `config` completely
@@ -85,24 +87,93 @@ export async function readDirConfig(dirname) {
     return result;
 }
 /**
- * Resolves the effective config for `targetDir` by cascading from `rootDir`
- * down to `targetDir` (inclusive), the same way tsconfig's `extends` chain
- * works: each directory level overrides the ones above it. This lets a
- * package (or any intermediate directory) narrow or override the repository's
- * root configuration for itself and everything below it.
+ * Resolves the effective config for the package at `targetDir`, cascading from `rootDir` down to
+ * it (inclusive) - each directory level overrides the ones above it, the way tsconfig's `extends`
+ * chain does.
+ *
+ * Every level contributes in two ways, and the difference is the whole model:
+ *
+ * - **Unmarked keys configure the package of the directory that declares them.** The root's own
+ *   `.rmanrc` therefore configures the *root package* - which is where repo-wide settings
+ *   (`packageManager`, `allowBranch`, `version.*`, `githubRelease.*`) are read from anyway - and
+ *   not, silently, every package under it.
+ * - **A `"[selector]"` block configures the packages it names** (`"[*]"` for all of them,
+ *   `"[*-dialect]"` for a glob over package names). This is the only way a directory speaks about
+ *   anything but its own package.
+ *
+ * Splitting the two matters because the same key means different things to the two audiences. The
+ * clearest case is `run.<script>.postScript`: on a package it's that package's build hook, run in
+ * its own directory; on the root it's a repo-wide bookend run once at the repository root. A
+ * cascade that fed one declaration to both ran a package-relative command (`node
+ * ../../support/postbuild.cjs`) at the root, where it cannot resolve.
+ *
+ * `packageName` is what selectors match against; without it (resolving the root's own config, say)
+ * selector blocks contribute nothing at all.
  */
-export async function resolveConfig(rootDir, targetDir, cache = new Map()) {
+export async function resolveConfig(rootDir, targetDir, cache = new Map(), packageName) {
     const result = {};
+    const target = path.resolve(targetDir);
     for (const dir of dirChain(rootDir, targetDir)) {
         let local = cache.get(dir);
         if (!local) {
             local = await readDirConfig(dir);
             cache.set(dir, local);
         }
-        merge(result, local, { deep: true });
+        // Selectors first, so a directory's own unmarked config still wins over a selector declared
+        // alongside it - "this package" is a more specific statement than "packages matching a glob".
+        if (packageName) {
+            for (const block of matchingSelectors(local, packageName))
+                merge(result, block, { deep: true });
+        }
+        // A directory holding a package speaks for that package only - which is what keeps the root's
+        // own config off every package under it. A directory that holds none (an intermediate
+        // `packages/`, say) has no package to speak for, so its unmarked config can only mean
+        // "everything below" and still cascades.
+        const ownsAPackage = fs.existsSync(path.join(dir, 'package.json'));
+        if (!ownsAPackage || path.resolve(dir) === target)
+            merge(result, stripSelectors(local), { deep: true });
+    }
+    return result;
+}
+/** A config key naming packages rather than settings: `"[*]"`, `"[*-dialect]"`, `"[pkg-a]"`. The
+ *  brackets are what keep this space from colliding with real config keys - no setting starts with
+ *  one - and in YAML they also mean the key always needs quoting (`"[*]":`), since a bare `[*]`
+ *  parses as a flow sequence. */
+export function isSelectorKey(key) {
+    return key.length > 2 && key.startsWith('[') && key.endsWith(']');
+}
+/** The glob inside a selector key, as a `RegExp` anchored at both ends - so `"[*-dialect]"` matches
+ *  `mysql-dialect` but not `my-dialect-helper`. Glob rather than regex, to match every other
+ *  pattern in rman (`allowBranch`, `changelog.tagPattern`, `clean.include`). */
+export function selectorToRegExp(key) {
+    const glob = key.slice(1, -1);
+    const source = glob
+        .split('*')
+        .map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+        .join('.*');
+    return new RegExp(`^${source}$`);
+}
+/** Every selector block in `config` matching `packageName`, in increasing precedence: `"[*]"` first
+ *  and the rest in declaration order - so a specific glob overrides the catch-all, and two equally
+ *  specific ones resolve by the order they were written in. */
+function matchingSelectors(config, packageName) {
+    const matches = [];
+    for (const [key, value] of Object.entries(config)) {
+        if (!isSelectorKey(key) || !value || typeof value !== 'object')
+            continue;
+        if (selectorToRegExp(key).test(packageName))
+            matches.push([key, value]);
     }
+    return matches.sort((a, b) => Number(b[0] === CATCH_ALL) - Number(a[0] === CATCH_ALL)).map(([, block]) => block);
+}
+function stripSelectors(config) {
+    const result = {};
+    for (const [key, value] of Object.entries(config))
+        if (!isSelectorKey(key))
+            result[key] = value;
     return result;
 }
+const CATCH_ALL = '[*]';
 function dirChain(rootDir, targetDir) {
     const rel = path.relative(rootDir, targetDir);
     if (!rel || rel === '.' || rel.startsWith('..'))
@@ -115,3 +186,101 @@ function dirChain(rootDir, targetDir) {
     }
     return dirs;
 }
+/**
+ * Evaluates every `${{ ... }}` expression in **every** string value of a resolved config, against
+ * the package it was resolved for:
+ *
+ * ```yaml
+ * "[*]":
+ *   clean:
+ *     include: ["build", "../../coverage/${{ pkg.basename }}"]
+ *   publish:
+ *     docker:
+ *       image: "panates/${{ pkg.basename }}:${{ semver.major(pkg.version) }}"
+ * ```
+ *
+ * Every string, with no list of "interpolated keys" to memorize - a rule with exceptions is a rule
+ * nobody remembers.
+ *
+ * The contents are **real JavaScript**, not a template mini-language, so there is no growing list
+ * of substitutions to keep adding (`{{major}}`, `{{scope}}`, ...) - see `ConfigScope` for what is
+ * in scope.
+ *
+ * **`${{ }}`, deliberately not `{{ }}`.** A config value may legitimately carry `{{...}}` meant for
+ * something else entirely (`helm template --set tag={{.Values.tag}}`); with the plainer delimiter
+ * rman would try to evaluate it. To emit a literal, let an expression produce it, the way GitHub
+ * Actions does: `${{ '${{' }}`.
+ *
+ * A string that is *nothing but* one expression keeps the value's own type (`"${{ pkg.private }}"`
+ * -> a boolean), since otherwise this could only ever produce strings and settings like
+ * `run.<script>.skip` would be unreachable. Embedded in surrounding text it is stringified.
+ *
+ * Evaluation happens in a fresh V8 context holding only the scope's bindings. That is a clean
+ * scope, **not a sandbox** - `node:vm` is explicitly not a security mechanism, and no sandbox is
+ * called for here anyway: a `.rmanrc` that can say `exec: "..."` already runs arbitrary shell, so
+ * the expression evaluator adds no trust boundary that wasn't already wide open.
+ *
+ * A failing expression throws with the config path that holds it, rather than being left in place:
+ * silently passing through a mistake is how a config ends up quietly doing nothing.
+ */
+export function interpolateConfig(config, scope) {
+    const context = vm.createContext({ ...scope });
+    return walk(config, scope, context, []);
+}
+const EXPRESSION = /\$\{\{([\s\S]*?)\}\}/g;
+function walk(value, scope, context, at) {
+    if (typeof value === 'string')
+        return interpolateString(value, context, at);
+    if (Array.isArray(value))
+        return value.map((item, i) => walk(item, scope, context, [...at, i]));
+    if (value && typeof value === 'object') {
+        const result = {};
+        for (const [key, item] of Object.entries(value))
+            result[key] = walk(item, scope, context, [...at, key]);
+        return result;
+    }
+    return value;
+}
+function interpolateString(value, context, at) {
+    if (!value.includes('${{'))
+        return value;
+    const found = [...value.matchAll(EXPRESSION)];
+    if (!found.length)
+        return value;
+    /** Counted rather than matched with an anchored `^...$` regex: a lazy quantifier still backtracks
+     *  to satisfy an end anchor, so `"${{ a }} and ${{ b }}"` looked like *one* expression whose body
+     *  ran from `a` to `b`, brace-ends and all - invalid JavaScript. */
+    const soleExpression = found.length === 1 && found[0][0] === value.trim();
+    // Alone, a nullish result is just "this setting is unset" - a legitimate answer.
+    if (soleExpression)
+        return evaluate(found[0][1], value, context, at);
+    return value.replace(EXPRESSION, (_, expr) => {
+        const result = evaluate(expr, value, context, at);
+        /** Embedded in text, though, it never is: splicing in the word "undefined" produces a path or
+         *  tag like `app:undefined` that looks plausible and is wrong - the exact silent-mistake shape
+         *  this evaluator exists to avoid. `?? 'fallback'` says what was meant. */
+        if (result === undefined || result === null) {
+            const where = at.length ? formatPath(at) : 'the config root';
+            throw new Error(`Expression in "${where}" is ${result} inside a string: ${value.trim()}\n` +
+                `  \${{${expr}}} has no value here - give it a fallback (\${{${expr.trim()} ?? '...'}}).`);
+        }
+        return String(result);
+    });
+}
+/** Names the config path as well as the expression: an error saying only "x is not defined" sends
+ *  the reader hunting through a file that may hold dozens of them. */
+function evaluate(expr, source, context, at) {
+    try {
+        return vm.runInContext(expr, context, { timeout: EXPRESSION_TIMEOUT });
+    }
+    catch (e) {
+        const where = at.length ? formatPath(at) : 'the config root';
+        throw new Error(`Invalid expression in "${where}": ${source.trim()}\n  ${e?.message ?? e}`, { cause: e });
+    }
+}
+function formatPath(at) {
+    return at.reduce((acc, part) => (typeof part === 'number' ? `${acc}[${part}]` : acc ? `${acc}.${part}` : String(part)), '');
+}
+/** Guards against an expression that never returns (`while(true)`) taking the whole command with
+ *  it - a typo, not an attack, but the failure mode is identical. */
+const EXPRESSION_TIMEOUT = 1000;

package/core/repository.d.ts

@@ -37,9 +37,14 @@ export declare class Repository extends Package {
         hash?: string;
     }): Promise<Record<string, Repository.PackageStatus>>;
     /**
-     * Resolves the effective rman config for the repository root and every
-     * package, cascading root -> intermediate directories -> package directory,
-     * so a `.rmanrc` placed anywhere along that path overrides the levels above it.
+     * Resolves the effective rman config for the repository root and every package, cascading
+     * root -> intermediate directories -> package directory, so a `.rmanrc` placed anywhere along
+     * that path overrides the levels above it.
+     *
+     * Each package is resolved *by name* as well as by directory, since that is what a `"[selector]"`
+     * block matches against - see `resolveConfig`. The root package is resolved by name too: in a
+     * single-package repository it *is* the one package, so `"[*]"` has to reach it; in a monorepo
+     * nothing under `getPackages()` is the root, so only its own unmarked config applies.
      */
     protected _resolveConfigs(): Promise<void>;
     protected _updateDependencies(): void;

package/core/repository.js

@@ -1,8 +1,10 @@
+import { execFileSync } from 'node:child_process';
 import glob from 'fast-glob';
 import fs from 'fs';
 import path from 'path';
+import semver from 'semver';
 import { GitHelper } from '../utils/git.js';
-import { resolveConfig } from './config.js';
+import { interpolateConfig, resolveConfig } from './config.js';
 import { Package } from './package.js';
 export class Repository extends Package {
     dirname;
@@ -87,20 +89,55 @@ export class Repository extends Package {
         return result;
     }
     /**
-     * Resolves the effective rman config for the repository root and every
-     * package, cascading root -> intermediate directories -> package directory,
-     * so a `.rmanrc` placed anywhere along that path overrides the levels above it.
+     * Resolves the effective rman config for the repository root and every package, cascading
+     * root -> intermediate directories -> package directory, so a `.rmanrc` placed anywhere along
+     * that path overrides the levels above it.
+     *
+     * Each package is resolved *by name* as well as by directory, since that is what a `"[selector]"`
+     * block matches against - see `resolveConfig`. The root package is resolved by name too: in a
+     * single-package repository it *is* the one package, so `"[*]"` has to reach it; in a monorepo
+     * nothing under `getPackages()` is the root, so only its own unmarked config applies.
      */
     async _resolveConfigs() {
         const cache = new Map();
-        const rootConfig = await resolveConfig(this.dirname, this.dirname, cache);
-        this.config = rootConfig;
-        this.rootPackage.config = rootConfig;
+        const repoDir = this.dirname;
+        const scopeOf = (pkg) => {
+            // A package.json without a "name" is unusual but legal, and `info` prints such a package
+            // rather than refusing it - so the scope has to survive one too.
+            const name = pkg.name ?? '';
+            const at = name.lastIndexOf('/');
+            return {
+                name,
+                scope: at > 0 ? name.slice(0, at) : undefined,
+                unscopedName: at > 0 ? name.slice(at + 1) : name,
+                version: pkg.version ?? '',
+                basename: path.basename(pkg.dirname),
+                dirname: pkg.dirname,
+                relativeDir: path.relative(this.dirname, pkg.dirname),
+                // A copy: an expression has no business mutating the package rman is about to act on.
+                json: { ...pkg.json },
+            };
+        };
+        const packageScopes = this.packages.map(scopeOf);
+        let gitScope;
+        const repository = {
+            ...scopeOf(this.rootPackage),
+            monorepo: this.monorepo,
+            packages: packageScopes,
+            package: (name) => packageScopes.find(p => p.name === name),
+            // A getter, so a repository whose config never mentions git spawns no git at all - and every
+            // command resolves config, not just the ones that care.
+            get git() {
+                return (gitScope ??= readGitScope(repoDir));
+            },
+        };
+        const withVars = (pkg, config) => interpolateConfig(config, { pkg: scopeOf(pkg), repository, env: { ...process.env }, semver });
+        this.config = withVars(this.rootPackage, await resolveConfig(this.dirname, this.dirname, cache));
         for (const pkg of this.packages) {
-            if (pkg === this.rootPackage)
-                continue;
-            pkg.config = await resolveConfig(this.dirname, pkg.dirname, cache);
+            pkg.config = withVars(pkg, await resolveConfig(this.dirname, pkg.dirname, cache, pkg.name));
         }
+        if (this.monorepo)
+            this.rootPackage.config = this.config;
     }
     _updateDependencies() {
         const deps = {};
@@ -111,7 +148,7 @@ export class Repository extends Package {
                 ...pkg.json.peerDependencies,
                 ...pkg.json.optionalDependencies,
             };
-            const configDeps = pkg.config.packages?.[pkg.name]?.dependencies;
+            const configDeps = pkg.config.dependencies;
             if (configDeps) {
                 if (Array.isArray(configDeps))
                     configDeps.forEach(x => (o[x] = o[x] || '*'));
@@ -205,3 +242,30 @@ function topoSortPackages(packages) {
         return 0;
     });
 }
+/** `git` facts for a `${{ repository.git.* }}` expression. Synchronous on purpose: it backs a lazy
+ *  getter, and a getter cannot await. Everything is `undefined` outside a git checkout - not an
+ *  error, just a repository without one. */
+function readGitScope(dirname) {
+    const run = (args) => {
+        try {
+            return execFileSync('git', args, { cwd: dirname, stdio: ['ignore', 'pipe', 'ignore'] })
+                .toString()
+                .trim();
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const sha = run(['rev-parse', 'HEAD']);
+    if (sha === undefined)
+        return { branch: undefined, sha: undefined, shortSha: undefined, dirty: undefined };
+    const status = run(['status', '--porcelain']);
+    return {
+        // Empty on a detached HEAD, which is what a CI checkout often is - reported as undefined
+        // rather than an empty string, so `?? 'detached'` in an expression works.
+        branch: run(['branch', '--show-current']) || undefined,
+        sha,
+        shortSha: sha.slice(0, 7),
+        dirty: status === undefined ? undefined : status.length > 0,
+    };
+}

package/interfaces/rman-config.interface.d.ts

@@ -16,10 +16,45 @@ export interface RmanConfig {
     changelog?: RmanConfig.ChangelogOptions;
     clean?: RmanConfig.CleanOptions;
     publish?: RmanConfig.PublishOptions;
-    /** Keyed by npm script name (e.g. `"build"`, `"lint"`, `"test"`). */
-    run?: Record<string, RmanConfig.RunScriptOptions>;
-    /** Keyed by the in-repo package's own name. */
-    packages?: Record<string, RmanConfig.PackageOptions>;
+    githubRelease?: RmanConfig.GithubReleaseOptions;
+    /** Keyed by npm script name (e.g. `"build"`, `"lint"`, `"test"`). A bare string (or array of
+     *  them) is shorthand for `{ exec: ... }` - `test: "mocha"` and `test: { exec: "mocha" }` mean
+     *  exactly the same thing. */
+    run?: Record<string, string | string[] | RmanConfig.RunScriptOptions>;
+    /** In-repo packages this one depends on beyond what its real `package.json` declares - purely
+     *  for rman's own dependency graph (topo-sort, `--deps`/`--dependents`, `run`'s scheduling). An
+     *  array defaults each entry's range to `"*"`; an object gives an explicit name -> range map.
+     *  Declared from the root via a selector (`"[pkg-a]": { dependencies: [...] }`) or in the
+     *  package's own `.rmanrc`. */
+    dependencies?: string[] | Record<string, string>;
+    /**
+     * Config for **other** packages, keyed by a `"[selector]"` naming them - `"[*]"` for every
+     * package in the repository, `"[*-dialect]"` for a glob over package names, `"[pkg-a]"` for one.
+     * Everything else in this object configures the package of the directory declaring it, so this
+     * is the only way a `.rmanrc` speaks about anything but its own package - most usefully the
+     * repository root's, which otherwise configures the root package alone.
+     *
+     * ```yaml
+     * # the repository root's own .rmanrc.yml
+     * run:
+     *   build:
+     *     before: node support/generate.cjs   # a repo-wide bookend, run once at the root
+     * "[*]":
+     *   run:
+     *     build:
+     *       after: node ../../support/postbuild.cjs   # run in each package's own directory
+     * ```
+     *
+     * In YAML the quotes are **required**: a bare `[*]` parses as a flow sequence, and `*` as an
+     * alias indicator. Precedence, lowest first: `"[*]"`, then other selectors in declaration order,
+     * then the package's own unmarked config.
+     *
+     * Recursive, mirroring the schema's own `"$ref": "#"`: whatever a `.rmanrc` may say about its own
+     * package it may say here about the ones it names - nested selectors included. Typed as
+     * `RmanConfig` rather than `unknown` so the contents are actually checked; `unknown` let any
+     * shape through, which is the opposite of the point.
+     */
+    [selector: `[${string}]`]: RmanConfig;
 }
 export declare namespace RmanConfig {
     interface VersionOptions {
@@ -35,9 +70,29 @@ export declare namespace RmanConfig {
          *  any package's own `changelog.tagPattern`, or that package's changelog boundary will resolve
          *  to the repository release instead of its own last release. */
         releaseTagPattern?: string;
-        script?: string | string[];
-        preScript?: string | string[];
-        postScript?: string | string[];
+        /** Keep this package's Dockerfile `org.opencontainers.image.version` label in step with the
+         *  version being written. Per-package cascaded. Default `true` - the label's value is, by
+         *  specification, the version of the packaged software, so there is only ever one correct
+         *  value for it, and `version` is what knows it. Only ever *rewrites* a label the Dockerfile
+         *  already declares (never inserts one), and reads the same path `publish --target docker`
+         *  builds from (`publish.docker.dockerfile`), so a package without one is a no-op. */
+        stampDockerfile?: boolean;
+        /** Source files whose `version` constant is rewritten to the version being written, in the same
+         *  commit as the bump - paths relative to the package's own directory (e.g.
+         *  `["src/constants.ts"]`). Per-package cascaded; a listed file a package doesn't have is a
+         *  silent no-op, so one `"[*]"` declaration covers a repo where only some packages carry one.
+         *
+         *  Stamping the source, not the build output: a build-time rewrite leaves the checked-in file
+         *  claiming a placeholder, so anything running from source reports that placeholder, git never
+         *  records the released version, and the rewrite has to be redone on every build. */
+        stamp?: string | string[];
+        /** Command(s) run as this package's own `version` npm-lifecycle step, when its `package.json`
+         *  doesn't define one itself. An array runs them in sequence. */
+        exec?: string | string[];
+        /** Same, for `preversion`. */
+        before?: string | string[];
+        /** Same, for `postversion`. */
+        after?: string | string[];
     }
     interface ChangelogOptions {
         ignoreTypes?: string[];
@@ -59,26 +114,36 @@ export declare namespace RmanConfig {
         changedSince?: string;
         skip?: boolean;
         if?: string;
-        script?: string | string[];
-        preScript?: string | string[];
-        postScript?: string | string[];
+        /** Command(s) to run as this script itself, when the package's `package.json` doesn't define
+         *  it. An array runs them in sequence. */
+        exec?: string | string[];
+        /** Same, for this script's `pre<script>` hook. */
+        before?: string | string[];
+        /** Same, for its `post<script>` hook. */
+        after?: string | string[];
         override?: boolean;
     }
-    interface PackageOptions {
-        dependencies?: string[] | Record<string, string>;
-    }
     interface PublishOptions {
-        /** Where `publish` should release this package to - default `['npm']` (every existing repo
+        /** Which **registry** `publish` ships this package to - default `['npm']` (every existing repo
          *  keeps working unchanged). A package that only ever wants Docker images (typically also
-         *  `"private": true`, since it's not meant for npm at all) sets `['docker']`; a standalone app
-         *  shipped as GitHub Release assets - or deployed elsewhere entirely, with the release only
-         *  recording that it happened - sets `['github']`; any combination works (`['npm', 'github']`).
+         *  `"private": true`, since it's not meant for npm at all) sets `['docker']`; both works too.
          *  Each target answers "is this version already out there?" against its own registry, so a
-         *  package is never left without one: npm via `npm view`, docker via `docker manifest inspect`,
-         *  github via the release for that version's tag. */
+         *  package is never left without one: npm via `npm view`, docker via `docker manifest inspect`.
+         *
+         *  Note this is strictly about *package distribution*. The repository's GitHub Release is not
+         *  a target here - it isn't a place a package ships to, it's the repository's own record that
+         *  a release happened, and it is never opted into: see `githubRelease` and the
+         *  `github-release` command. */
         target?: PublishTarget | PublishTarget[];
+        /** Where this package's publishable output lives, relative to its own directory (e.g.
+         *  `"build"`). Per-package cascaded, so a root `"[*]"` block can say it once for the whole
+         *  repository instead of repeating `publishConfig.directory` in every `package.json` - which
+         *  still wins when a package declares it, being the more specific statement.
+         *
+         *  Publishing from such a directory means the manifest there is **generated by `publish`**,
+         *  from the package's own - see `PublishService`. There is nothing to configure about it. */
+        directory?: string;
         docker?: DockerPublishOptions;
-        github?: GithubPublishOptions;
         /** Excludes this package from `publish` entirely (every target), regardless of
          *  `target`/`"private"` - a single, explicit "never published" statement, e.g. for a package
          *  released through some separate, unrelated process. `changelog` also skips it by default
@@ -87,7 +152,7 @@ export declare namespace RmanConfig {
          *  package can still be meaningfully versioned without ever being published. */
         skip?: boolean;
     }
-    type PublishTarget = 'npm' | 'docker' | 'github';
+    type PublishTarget = 'npm' | 'docker';
     /** Required once `"docker"` is one of this package's `publish.target`s - `publish --target
      *  docker` errors clearly on a package that opts in here but leaves this out. */
     interface DockerPublishOptions {
@@ -112,19 +177,22 @@ export declare namespace RmanConfig {
          *  full description, if present. Default `"DOCKER_README.md"`. */
         readme?: string;
     }
-    /** Optional even when `"github"` is one of this package's `publish.target`s - unlike docker,
-     *  every required fact (which tag, which repository, what release notes) already has a sensible
-     *  source, so a bare `"target": ["github"]` is a complete configuration on its own. */
-    interface GithubPublishOptions {
+    /** Entirely optional - `github-release` needs no configuration at all, since every required fact
+     *  (which tag, which repository, what the notes say) already has a sensible source. Nothing here
+     *  decides *whether* a release is cut: a release records that the repository shipped, so it is
+     *  always cut, and these are only details about how. */
+    interface GithubReleaseOptions {
         /** Files to attach to the release, as glob patterns relative to the package's own directory
-         *  (e.g. `["dist/*.tar.gz"]`). A release with no assets is still perfectly valid - it records
-         *  that the version shipped, which is all a deploy-elsewhere package needs. */
+         *  (e.g. `["dist/*.tar.gz"]`). Read from **every** package, since one release covers the whole
+         *  source tree. A release with no assets at all is still perfectly valid - it records that the
+         *  version shipped, which is all a deploy-elsewhere package needs. */
         assets?: string[];
-        /** `owner/repo`. Default: parsed from the `origin` remote's URL. */
+        /** `owner/repo`. Default: parsed from the `origin` remote's URL. Root-level only. */
         repository?: string;
-        /** Create the release as an unpublished draft. Default `false`. */
+        /** Create the release as an unpublished draft. Default `false`. Root-level only. */
         draft?: boolean;
-        /** Default: whether the version being released is itself a semver prerelease (`1.3.0-beta.0`). */
+        /** Default: whether the version being released is itself a semver prerelease (`1.3.0-beta.0`).
+         *  Root-level only. */
         prerelease?: boolean;
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "1.0.9",
+  "version": "1.0.12",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {