rman 1.3.0 → 2.0.0-beta.3

package/core/config/config-file-scope.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The two members of the expression scope that answer questions about the filesystem: `file`, which
+ * says **where** something is, and `read`, which says what is **in** it.
+ *
+ * Both are built per directory - a package's own - so one `"[*]"` declaration asks each package
+ * about its own files. The parse cache is per *instance* and shared across those directories, so
+ * twenty packages reading one file parse it once.
+ *
+ * ```yaml
+ * "[*]":
+ *   run:
+ *     build:
+ *       exec: 'tsc -b ${{ file.resolveFirst("tsconfig-build.json", "tsconfig.json") }}'
+ *   version:
+ *     stamp: '${{ read("pom.xml").getElementsByTagName("version")[0].textContent }}'
+ * ```
+ *
+ * **Everything here is a query, and must stay one.** These run while a config resolves, which
+ * *every* command does - so anything that *did* something would do it on `rman list`, `rman info`
+ * and `rman config`, once per package, with nothing having asked.
+ */
+export declare class ConfigFileScope {
+    protected readonly cache: Map<string, ConfigFileScope.CachedFile>;
+    /**
+     * One parsed file per path, kept against the identity of the bytes it came from.
+     *
+     * Passed in to share one cache across several instances; left out, the instance owns its own.
+     */
+    constructor(cache?: Map<string, ConfigFileScope.CachedFile>);
+    /**
+     * The `file` member, resolving against `dirname`.
+     *
+     * @param dirname the package directory a relative path is resolved against
+     */
+    fileScope(dirname: string): ConfigFileScope.FileScope;
+    /**
+     * The `read` member, resolving against `dirname`.
+     *
+     * @param dirname the package directory a relative path is resolved against
+     */
+    readScope(dirname: string): ConfigFileScope.ReadFile;
+    /**
+     * Reads and parses one file, deeply frozen and memoized.
+     *
+     * Throws when the file is absent - `file.exists(p) ? read(p) : fallback` is the optional form, so
+     * there is no second function for it.
+     */
+    protected readStructured(file: string, format?: ConfigFileScope.FileFormat): unknown;
+    /**
+     * What format a file name says it is. An unrecognized name is an error naming the four, rather
+     * than a guess at JSON.
+     */
+    protected formatOf(file: string): ConfigFileScope.FileFormat;
+    /** Parses text in one of the four formats. Override to add another. */
+    protected parse(text: string, format: ConfigFileScope.FileFormat): unknown;
+    /**
+     * Parses XML into a **DOM**, not a plain object.
+     *
+     * ```yaml
+     * version: '${{ read("pom.xml").getElementsByTagName("version")[0].textContent }}'
+     * ```
+     */
+    protected parseXml(text: string): unknown;
+    /** Where a relative target lands, and whether anything is there. */
+    protected _locate(dirname: string, target: string): {
+        path: string;
+        found: boolean;
+    };
+}
+export declare namespace ConfigFileScope {
+    /**
+     * Where a file is - the `file` member of the expression scope.
+     *
+     * Three read-only members, and that is the whole of it; see the class doc for why nothing here
+     * changes anything.
+     */
+    interface FileScope {
+        /**
+         * The absolute path if it exists, **`''` if it does not** - so `a || b || c` picks the first one
+         * present, and so a miss never reaches the "nullish inside a string" guard that `undefined`
+         * would trip. Takes a relative path (against the package directory) or an absolute one.
+         */
+        exists(target: string): string;
+        /** The absolute path, or **throws** - for a file whose absence is a mistake rather than a case
+         *  to handle. The error names the config path holding the expression, like any other. */
+        resolve(target: string): string;
+        /**
+         * The first of several that exists, or **throws** naming every candidate it tried:
+         *
+         * ```yaml
+         * exec: 'tsc -b ${{ file.resolveFirst("tsconfig-build.json", "tsconfig.json") }}'
+         * ```
+         */
+        resolveFirst(...targets: string[]): string;
+    }
+    /** What `read` can parse. */
+    type FileFormat = 'json' | 'yaml' | 'ini' | 'xml';
+    /** `read(path)`, or `read(path, 'ini')` for a file whose name does not say what it is
+     *  (`.npmrc`). */
+    type ReadFile = (target: string, format?: FileFormat) => unknown;
+    /** One parsed file, kept against the identity of the bytes it came from. */
+    interface CachedFile {
+        /** `mtimeNs:size`. */
+        stamp: string;
+        value: unknown;
+    }
+}

package/core/config/config-file-scope.js

@@ -0,0 +1,226 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DOMParser } from '@xmldom/xmldom';
+import ini from 'ini';
+import * as yaml from 'js-yaml';
+/**
+ * The two members of the expression scope that answer questions about the filesystem: `file`, which
+ * says **where** something is, and `read`, which says what is **in** it.
+ *
+ * Both are built per directory - a package's own - so one `"[*]"` declaration asks each package
+ * about its own files. The parse cache is per *instance* and shared across those directories, so
+ * twenty packages reading one file parse it once.
+ *
+ * ```yaml
+ * "[*]":
+ *   run:
+ *     build:
+ *       exec: 'tsc -b ${{ file.resolveFirst("tsconfig-build.json", "tsconfig.json") }}'
+ *   version:
+ *     stamp: '${{ read("pom.xml").getElementsByTagName("version")[0].textContent }}'
+ * ```
+ *
+ * **Everything here is a query, and must stay one.** These run while a config resolves, which
+ * *every* command does - so anything that *did* something would do it on `rman list`, `rman info`
+ * and `rman config`, once per package, with nothing having asked.
+ */
+/* **Do not add `copy`, `write` or `mkdir`, however reasonable the request sounds.** It has already
+ * been tried, in the only way a function that does not exist can be: a shared config reaching for
+ * `file.copyMany(...)` made **every** rman command exit 1. The loud failure was the lucky outcome -
+ * had the member existed, `rman list` would have quietly copied files. Work goes in a step, which
+ * is the one thing rman runs on purpose, and a step can be a function too. */
+export class ConfigFileScope {
+    cache;
+    /**
+     * One parsed file per path, kept against the identity of the bytes it came from.
+     *
+     * Passed in to share one cache across several instances; left out, the instance owns its own.
+     */
+    /* **Per instance rather than per scope**, because the scope is built once *per package*: a cache
+     * living in one pass never helps across them, and twenty packages reading one shared file would
+     * parse it twenty times. */
+    constructor(cache = new Map()) {
+        this.cache = cache;
+    }
+    /**
+     * The `file` member, resolving against `dirname`.
+     *
+     * @param dirname the package directory a relative path is resolved against
+     */
+    fileScope(dirname) {
+        return {
+            exists: (target) => {
+                const { path: resolved, found } = this._locate(dirname, target);
+                return found ? resolved : '';
+            },
+            resolve: (target) => {
+                const { path: resolved, found } = this._locate(dirname, target);
+                if (!found) {
+                    throw new Error(`file.resolve("${target}") found nothing at ${resolved}\n` +
+                        `  Use file.exists() instead if its absence is a case to handle rather than a mistake.`);
+                }
+                return resolved;
+            },
+            resolveFirst: (...targets) => {
+                if (!targets.length)
+                    throw new Error('file.resolveFirst() needs at least one path');
+                for (const target of targets) {
+                    const { path: resolved, found } = this._locate(dirname, target);
+                    if (found)
+                        return resolved;
+                }
+                throw new Error(`file.resolveFirst() found none of: ${targets.map(t => `"${t}"`).join(', ')}\n  Looked in ${dirname}.`);
+            },
+        };
+    }
+    /**
+     * The `read` member, resolving against `dirname`.
+     *
+     * @param dirname the package directory a relative path is resolved against
+     */
+    readScope(dirname) {
+        return (target, format) => {
+            if (typeof target !== 'string' || !target.trim()) {
+                throw new Error('read() needs a path - it was given ' + JSON.stringify(target));
+            }
+            return this.readStructured(path.resolve(dirname, target), format);
+        };
+    }
+    /**
+     * Reads and parses one file, deeply frozen and memoized.
+     *
+     * Throws when the file is absent - `file.exists(p) ? read(p) : fallback` is the optional form, so
+     * there is no second function for it.
+     */
+    /* **Memoized against the identity of the contents, not the path**: the key is `mtimeNs:size`.
+     * Both halves were measured.
+     *
+     * A stat rather than a re-read: `statSync` is 1.3µs where `readFileSync` + `JSON.parse` is 16.1µs
+     * on a 2KB manifest, so the check costs a thirteenth of what it saves.
+     *
+     * Keyed on the stat rather than held for the run, because **rman writes files while it runs** -
+     * `version` rewrites every bumped manifest and then re-interpolates its deferred hooks, and a
+     * path-keyed cache would hand those back as they were before the write. `mtimeNs` is nanoseconds,
+     * so a same-millisecond rewrite does not slip through.
+     *
+     * **Frozen once on the way in and shared**, rather than copied per caller: every package gets the
+     * same object, so a mutation would quietly change what the next one sees. A copy costs 5.6µs on
+     * every call where freezing costs ~1µs once, and it turns the mistake into a `TypeError` rather
+     * than an effect at a distance. */
+    readStructured(file, format) {
+        let stat;
+        try {
+            stat = fs.statSync(file, { bigint: true });
+        }
+        catch {
+            throw new Error(`read("${path.basename(file)}") found nothing at ${file}\n` +
+                `  Use file.exists() first if its absence is a case to handle rather than a mistake.`);
+        }
+        if (stat.isDirectory())
+            throw new Error(`read() was given a directory, not a file: ${file}`);
+        const stamp = `${stat.mtimeNs}:${stat.size}`;
+        const cached = this.cache.get(file);
+        if (cached?.stamp === stamp)
+            return cached.value;
+        const resolved = format ?? this.formatOf(file);
+        const text = fs.readFileSync(file, 'utf-8');
+        let value;
+        try {
+            value = this.parse(text, resolved);
+        }
+        catch (e) {
+            /** The parser's own message says what is wrong with the syntax but never which file it was
+             *  reading - and an expression can name several. */
+            throw new Error(`read("${path.basename(file)}") could not parse ${file} as ${resolved}: ${e?.message}`, {
+                cause: e,
+            });
+        }
+        deepFreeze(value);
+        this.cache.set(file, { stamp, value });
+        return value;
+    }
+    /**
+     * What format a file name says it is. An unrecognized name is an error naming the four, rather
+     * than a guess at JSON.
+     */
+    /* The extension decides because the caller already wrote it - naming the parser as well would
+     * restate it and let the two disagree (`json("x.yml")`). A name that says nothing takes the
+     * explicit argument instead. */
+    formatOf(file) {
+        const ext = path.extname(file).toLowerCase();
+        if (ext === '.json')
+            return 'json';
+        if (ext === '.yml' || ext === '.yaml')
+            return 'yaml';
+        if (ext === '.ini')
+            return 'ini';
+        if (XML_EXTENSIONS.has(ext))
+            return 'xml';
+        throw new Error(`read() cannot tell what "${path.basename(file)}" is from its name.\n` +
+            `  Name the format: read("${path.basename(file)}", "json" | "yaml" | "ini" | "xml").`);
+    }
+    /** Parses text in one of the four formats. Override to add another. */
+    parse(text, format) {
+        if (format === 'json')
+            return JSON.parse(text);
+        /** `load`, not `loadAll`: a multi-document stream has no single value to be, and js-yaml says
+         *  so clearly enough ("expected a single document in the stream") to leave alone. */
+        if (format === 'yaml')
+            return yaml.load(text);
+        if (format === 'xml')
+            return this.parseXml(text);
+        return ini.parse(text);
+    }
+    /**
+     * Parses XML into a **DOM**, not a plain object.
+     *
+     * ```yaml
+     * version: '${{ read("pom.xml").getElementsByTagName("version")[0].textContent }}'
+     * ```
+     */
+    /* **The asymmetry with the other three formats is the honest shape rather than an omission.** XML
+     * has no lossless object form: an element can repeat, carry attributes and hold text at the same
+     * time, so any flattening has to pick a convention (`$`? `_text`? array-or-not?) and be wrong for
+     * somebody. A DOM is the shape XML actually has.
+     *
+     * **Freezing a DOM is safe** - measured, not assumed: a frozen `@xmldom/xmldom` document still
+     * answers `getElementsByTagName` for a tag first asked about *after* the freeze (the
+     * live-collection case that would have broken it), reads attributes, resolves namespaces, walks
+     * `childNodes` and serialises back.
+     *
+     * **A malformed file must throw.** xmldom reports problems through a handler and otherwise
+     * carries on with whatever it salvaged - so without the check a truncated file came back as a
+     * half-parsed DOM and the expression reading it simply found nothing. `read()` throws for a
+     * broken JSON file; it has to throw for this one too. */
+    parseXml(text) {
+        const problems = [];
+        const doc = new DOMParser({
+            onError: (level, message) => {
+                if (level !== 'warning')
+                    problems.push(message.split('\n')[0]);
+            },
+        }).parseFromString(text, 'text/xml');
+        if (problems.length)
+            throw new Error(problems[0]);
+        return doc;
+    }
+    /** Where a relative target lands, and whether anything is there. */
+    _locate(dirname, target) {
+        if (typeof target !== 'string' || !target.trim()) {
+            throw new Error('file.exists()/file.resolve() need a path - they were given ' + JSON.stringify(target));
+        }
+        const resolved = path.resolve(dirname, target);
+        return { path: resolved, found: fs.existsSync(resolved) };
+    }
+}
+/** The XML family worth recognizing by name: a project file is XML whatever its extension calls
+ *  itself, and `.csproj`/`.pom` are what a .NET or Maven repository actually holds. Anything else
+ *  still reads with an explicit `read(p, 'xml')`. */
+const XML_EXTENSIONS = new Set(['.xml', '.csproj', '.vbproj', '.fsproj', '.props', '.targets', '.nuspec', '.plist']);
+function deepFreeze(value) {
+    if (!value || typeof value !== 'object' || Object.isFrozen(value))
+        return;
+    Object.freeze(value);
+    for (const item of Object.values(value))
+        deepFreeze(item);
+}

package/core/config/config-interpolator.d.ts

@@ -0,0 +1,164 @@
+import vm from 'node:vm';
+import type { ConfigScope } from '../../interfaces/config-scope.interface.js';
+import type { Resolved } from '../../interfaces/rman-config.interface.js';
+import { type PreviousValue } from './merge-config.js';
+/**
+ * Resolves a config's values - every `${{ ... }}` expression and every value function - against a
+ * scope.
+ *
+ * Where `ConfigReader` answers *what the files say*, this answers *what those words evaluate to*.
+ * It takes a `ConfigScope` rather than a package, so whoever holds the repository builds the scope;
+ * `Repository.configScope` is that today.
+ *
+ * Two passes: {@link interpolate} resolves everything the scope can answer now, and
+ * {@link resolveDeferred} resolves what `defer(...)` left for later.
+ */
+export declare class ConfigInterpolator {
+    /** How long one expression may run, in milliseconds. Raise it for a repository with genuinely
+     *  slow `read()` calls. */
+    protected readonly expressionTimeout: number;
+    /** The file the key being walked was written in, for an error message to name. */
+    protected currentOrigin: string | undefined;
+    /** How many `defer(...)` calls have been rewritten so far. */
+    protected deferCount: number;
+    /**
+     * Pass one: resolves everything the scope can answer now, and leaves `defer(...)` for
+     * {@link resolveDeferred}.
+     *
+     * A string that is *nothing but* one expression keeps that value's own type -
+     * `"${{ pkg.private }}"` is a boolean, not the word `true`. Embedded in surrounding text it is
+     * stringified, and a nullish result there is an error rather than the word `undefined`.
+     *
+     * Returns `Resolved<T>`: every value function has been called, so they are gone from the type.
+     */
+    interpolate<T>(args: ConfigInterpolator.InterpolateArgs<T>): Resolved<T>;
+    /**
+     * Pass two: resolves what pass one deferred, against a scope that can now answer it.
+     *
+     * `version` is the case it exists for - `${{ defer(pkg.targetVersion) }}` in a `version` hook
+     * names a version that does not exist while the config is being read.
+     *
+     * Only the keys pass one marked are walked; a `${{` that arrived any other way is left exactly as
+     * it is. A string handed over on its own has no containing object to carry a mark, so it is
+     * interpolated outright - the caller passing one has already decided.
+     */
+    resolveDeferred<T>(args: ConfigInterpolator.ResolveDeferredArgs<T>): T;
+    /** Whether anything under `config` is waiting for {@link resolveDeferred} - `false` for every
+     *  config that never writes `defer(...)`, so the second pass can be skipped. */
+    hasDeferred(config: unknown): boolean;
+    /** The V8 context an expression is evaluated in - a clean scope holding only `scope`'s bindings. */
+    protected _createContext(scope: ConfigScope): vm.Context;
+    protected _walk(value: unknown, scope: ConfigScope, context: vm.Context, at: Path, skip: string[]): any;
+    /**
+     * Runs `body` with `vars` scoped to this node: a fresh copy at every level, with the node's own
+     * `vars` block - if it declares one - merged **per key** over what the level above resolved to,
+     * so redeclaring one var keeps the rest.
+     *
+     * The node's own block is resolved against the outer scope before being installed, so
+     * `vars: { out: '${{ vars.x }}/dist' }` refines the `x` it inherits rather than reading itself.
+     */
+    protected _withScopedVars<T>(node: Record<string, unknown>, scope: ConfigScope, context: vm.Context, at: Path, skip: string[], body: () => T): T;
+    /**
+     * Walks one key with `value` bound to what the layers underneath resolved to.
+     *
+     * Always bound, even with nothing underneath - see {@link _previousValue} for what it is then.
+     * The chain resolves bottom-up, so a layer deriving from a layer that itself derived from
+     * something is handed the finished value rather than a half-resolved expression.
+     */
+    protected _walkWithPrevious(item: unknown, previous: PreviousValue | undefined, scope: ConfigScope, context: vm.Context, at: Path, skip: string[]): unknown;
+    /**
+     * Whether a function at `at` is **code** - a step to run later, or part of a plugin - rather than
+     * a value to compute now.
+     *
+     * Array indices are dropped before matching, so a function inside a *list* of steps is still a
+     * step; `*` in a `STEP_PATHS` entry matches any one segment (`run.<script>.exec`).
+     */
+    protected _isCodePath(at: Path): boolean;
+    /**
+     * Calls a **value** function: the JS spelling of a `${{ }}` expression, answering the same
+     * question at the same moment.
+     *
+     * It is handed one object carrying everything an expression can name, plus `value` - what this
+     * key resolved to in the layers underneath.
+     *
+     * A value function **computes and returns; it must never act.** This runs while the config
+     * resolves, which *every* command does - so one that writes a file writes it on `rman list`,
+     * `rman info` and `rman config` too, once per package, with nothing having asked. Work goes in a
+     * step.
+     */
+    protected _callValueFn(fn: (arg: unknown) => unknown, context: vm.Context, at: Path): unknown;
+    protected _interpolateString(value: string, context: vm.Context, at: Path): unknown;
+    /** Evaluates one expression, rewriting any `defer(...)` in it first. A failure names the config
+     *  path and the expression. */
+    protected _evaluate(expr: string, source: string, context: vm.Context, at: Path): unknown;
+    /**
+     * Turns `defer(<inner>)` into a string literal holding `${{ <inner> }}`, so the expression around
+     * it resolves now and the deferred part survives as an expression for pass two.
+     *
+     * ```
+     * '_' + defer(pkg.targetVersion) + '-' + pkg.name
+     * '_' + "${{ pkg.targetVersion }}" + '-' + pkg.name     // rewritten
+     * _${{ pkg.targetVersion }}-mypackage                   // evaluated
+     * ```
+     *
+     * `defer` is a marker the source is rewritten around, not a function in scope - so
+     * `defer(() => x)` is not a thing to write. A nested `defer` is refused.
+     */
+    protected _rewriteDefer(expr: string, source: string, at: Path): string;
+    /** The text between `defer(` and the parenthesis that closes it. */
+    protected _findDeferArgument(expr: string, open: number, source: string, at: Path): string;
+    /** Records which of `node`'s keys deferred, invisibly to anything but pass two. */
+    protected _markDeferred(node: Record<string, unknown>, keys: Record<string, true>): void;
+    /** Pass two's walk: only the keys pass one marked, so a `${{` that arrived from anywhere else is
+     *  left exactly as it is. */
+    protected _walkDeferred(value: unknown, context: vm.Context, at: Path): unknown;
+    protected _withOrigin<T>(origin: string | undefined, body: () => T): T;
+    /** `"version.commitMessage" (.rmanrc.yml)`, or just the path when nothing recorded a file. The
+     *  file is relative to the working directory when it sits inside it. */
+    protected _describeAt(at: Path): string;
+    /**
+     * What a layer deriving from the one below it reads as `value`.
+     *
+     * Spreads as empty when nothing below set the key, so `[...value, 'x']` needs no guard. Used as a
+     * string or a number it throws, naming the key and what to write instead.
+     */
+    protected _previousValue(raw: unknown, at: Path): unknown;
+    /** The one sentence both `value` refusals share: what was asked for, why it cannot be done, what
+     *  to write instead. */
+    protected _unusable(at: Path, because: string, instead: string): Error;
+}
+/** Where a value sits in the config, as the walk builds it up - a string key or an array index.
+ *  A module-level type rather than a member of the namespace below, so the class's own signatures
+ *  can name it without shadowing the namespace's copy of the name. */
+type Path = (string | number)[];
+export declare namespace ConfigInterpolator {
+    interface InterpolateArgs<T = unknown> {
+        /** The config, or a fragment of it. */
+        config: T;
+        /** Everything an expression can name: `pkg`, `repository`, `file`, `env`, `semver`, `path`,
+         *  `git`. Built by whoever holds the repository - see the class doc for why it is not a
+         *  `Package`. */
+        scope: ConfigScope;
+        /**
+         * Where `config` sits in the whole config, for a caller handing over a **fragment**.
+         *
+         * Optional in the type and required in practice for a fragment: the path is what decides
+         * whether a function is a value to compute or a step to leave alone (`STEP_PATHS`). Without it
+         * a fragment starts at the root and matches nothing, so a function in a `version` hook was
+         * called while the hook was being *prepared* - it failed inside the user's own code with
+         * `path.join` receiving undefined.
+         */
+        at?: Path;
+        /** Config paths to leave entirely untouched, subtree and all. */
+        skip?: string[];
+    }
+    interface ResolveDeferredArgs<T = unknown> {
+        /** What `interpolate` returned - the marks it left are what this walks. */
+        config: T;
+        /** The scope with whatever pass one could not bind, `pkg.targetVersion` being the case this
+         *  exists for. */
+        scope: ConfigScope;
+        at?: Path;
+    }
+}
+export {};