rman 1.1.1 → 1.2.1

package/cli.js

@@ -24,6 +24,7 @@ import { assertNoBuiltinShadowing, loadCustomCommands } from './core/custom-comm
 import { Repository } from './core/repository.js';
 import { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';
 import { filterPackages, readPackageFilterOptions, readRootOption } from './utils/package-filter.js';
+import { printableConfig } from './utils/printable-config.js';
 import { runBin } from './utils/run-bin.js';
 export async function runCli(options) {
     try {
@@ -207,7 +208,7 @@ function printCommandConfig(repository, spec, args) {
     console.log(`command: ${name}`);
     const options = readOptions(args);
     console.log(Object.keys(options).length
-        ? `options:\n${indent(yaml.dump(options, { noRefs: true }).trimEnd())}`
+        ? `options:\n${indent(yaml.dump(printableConfig(options), { noRefs: true }).trimEnd())}`
         : `options: {}${comment('   # nothing but defaults')}`);
     const targets = commandTargets(repository, args);
     console.log(`packages: ${targets.length ? `[${targets.map(p => p.name).join(', ')}]` : '[]'}`);
@@ -225,7 +226,7 @@ function printCommandConfig(repository, spec, args) {
     const config = {};
     for (const pkg of shown)
         config[pkg.name] = keys?.length ? pick(pkg.config, keys) : pkg.config;
-    console.log(indent(yaml.dump(config, { noRefs: true, lineWidth: 100 }).trimEnd()));
+    console.log(indent(yaml.dump(printableConfig(config), { noRefs: true, lineWidth: 100 }).trimEnd()));
     if (!targets.includes(repository.rootPackage)) {
         console.log(comment(`# "${repository.rootPackage.name}" is the root - listed because repo-wide keys are read there.`));
     }

package/commands/config.command.js

@@ -3,6 +3,7 @@ import colors from 'ansi-colors';
 import * as yaml from 'js-yaml';
 import { DEFERRED_PATHS } from '../core/config.js';
 import { applyRootOption, readRootOption } from '../utils/package-filter.js';
+import { printableConfig } from '../utils/printable-config.js';
 export function initCli(repository, program) {
     program.command({
         command: 'config',
@@ -19,7 +20,7 @@ export function initCli(repository, program) {
         handler: args => {
             const target = (!readRootOption(args) && repository.currentPackage) || repository.rootPackage;
             if (args.json) {
-                console.log(JSON.stringify(target.config, undefined, 2));
+                console.log(JSON.stringify(printableConfig(target.config), undefined, 2));
                 return;
             }
             /**
@@ -38,7 +39,7 @@ export function initCli(repository, program) {
             /** `noRefs`: a value appearing twice in the config is the *same object* after merging, and
              *  js-yaml would otherwise emit the second as an `*anchor` reference - valid YAML that reads
              *  as a mistake in something meant to be looked at. */
-            console.log(yaml.dump(target.config, { noRefs: true, lineWidth: 100 }).trimEnd());
+            console.log(yaml.dump(printableConfig(target.config), { noRefs: true, lineWidth: 100 }).trimEnd());
         },
     });
 }

package/constants.js

@@ -1 +1 @@
-export const version = '1.1.1';
+export const version = '1.2.1';

package/core/config.d.ts

@@ -96,6 +96,17 @@ export declare function selectorToRegExp(key: string): RegExp;
  *       # first of these that exists, and an error naming the config path if none do
  *       exec: 'tsc -b ${{ file.exists("tsconfig-build.json") || file.resolve("tsconfig.json") }}'
  * ```
+ *
+ * **Every member asks a question, and none may ever change anything - no `copy`, no `write`, no
+ * `mkdir`.** Not a matter of taste: this is evaluated when the config *resolves*, which every
+ * command does, so a member that acted would act on `rman list`, `rman info` and `rman config`.
+ *
+ * That has been tried, in the only way a missing function can be: a shared config reaching for a
+ * `file.copyMany(...)` that does not exist made **every** rman command exit 1 - and had it existed,
+ * the quieter outcome would have been files copied by `rman list`. Work belongs in a step
+ * (`run.<script>`'s slots, `version`'s hooks), which is the one place rman runs anything, and a
+ * step can now be a function - so there is nothing this would enable that is not already possible
+ * at the right moment.
  */
 export interface FileScope {
     /**
@@ -175,10 +186,6 @@ export interface RepositoryScope extends PackageScope {
     packages: PackageScope[];
     /** One package by name, or `undefined` - for reaching a sibling's directory. */
     package(name: string): PackageScope | undefined;
-    /** Read from git only if an expression actually asks for it, then remembered: a repository that
-     *  never mentions these pays nothing, and every command resolves config. All `undefined` outside
-     *  a git checkout, which is a legitimate state rather than an error. */
-    git: GitScope;
 }
 export interface GitScope {
     branch: string | undefined;
@@ -208,6 +215,23 @@ export interface ConfigScope {
     repository: RepositoryScope;
     /** Paths, resolved against the package the config was resolved for. */
     file: FileScope;
+    /**
+     * The **contents** of a structured file - `${{ read('tsconfig.json').compilerOptions.outDir }}` -
+     * where `file` answers only where one is. Resolved against `pkg.dirname` like `file`, so a
+     * `"[*]"` block asks each package about its own; a repository-level file is reached through
+     * `read(path.join(repository.dirname, ...))`.
+     *
+     * `.json`, `.yml`/`.yaml` and `.ini` by extension, or name it for a file that does not say
+     * (`read('.npmrc', 'ini')`). **Throws** when the file is absent, as `file.resolve` does - compose
+     * with `file.exists` when its absence is a case to handle.
+     *
+     * **A manifest is `pkg.manifest`, not this.** `read('package.json')` works and is the wrong
+     * answer: which file a package's identity lives in belongs to the ecosystem, so that expression
+     * is already wrong in a Cargo package sitting beside a Node one.
+     *
+     * The result is **deeply frozen and shared** - see `readStructuredFile`. Spread it to change it.
+     */
+    read: ReadFile;
     env: Record<string, string | undefined>;
     /** rman's own `semver`, for the arithmetic every release config eventually wants
      *  (`semver.major(pkg.version)`). */
@@ -221,6 +245,23 @@ export interface ConfigScope {
      * genuinely needs one of them (a Docker image path, say, which is always posix).
      */
     path: typeof path;
+    /**
+     * The checkout: branch, sha, whether the tree is dirty.
+     *
+     * **Top level, not `repository.git`** - which is where it used to be, and the move is the point.
+     * `repository` shares its shape with `pkg` because the repository root *is* a package, and its
+     * only other members (`monorepo`, `packages`, `package()`) say something about the repository as
+     * a container of packages. A branch name says nothing about any package; it describes the
+     * working tree every one of them happens to be sitting in - the same kind of ambient fact as
+     * `env`, and it belongs beside it.
+     *
+     * **Read from git only if an expression actually asks**, then remembered for the whole run: every
+     * command resolves config, and a repository that never mentions git must not pay for one. See
+     * `Repository.configScope` for the getter, and `interpolateConfig` for why the context is built
+     * from property descriptors rather than a spread - a spread would fire this getter on every
+     * command, which is exactly what moving it up here risked.
+     */
+    git: GitScope;
 }
 /**
  * Evaluates every `${{ ... }}` expression in **every** string value of a resolved config, against
@@ -264,9 +305,13 @@ export interface ConfigScope {
  * 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 declare function interpolateConfig<T>(config: T, scope: ConfigScope, options?: {
+export interface InterpolateOptions {
+    /** Config paths to leave entirely untouched - `DEFERRED_PATHS`, when the whole config is walked. */
     skip?: string[];
-}): T;
+    /** Where `config` sits in the whole config, for a caller interpolating a fragment. */
+    at?: string[];
+}
+export declare function interpolateConfig<T>(config: T, scope: ConfigScope, options?: InterpolateOptions): T;
 /**
  * Config paths left untouched when a repository's config is first resolved, and evaluated only by
  * the command that runs them.
@@ -277,5 +322,79 @@ export declare function interpolateConfig<T>(config: T, scope: ConfigScope, opti
  * command at all would fail on a config that mentions it.
  */
 export declare const DEFERRED_PATHS: string[];
+/**
+ * Paths whose value is a **step** - something to run later - rather than a setting to compute now.
+ * `*` matches one path segment (`run.<script>.exec`).
+ *
+ * This is what tells a step function from a value function, and the two live side by side in one
+ * config:
+ *
+ * ```js
+ * '[ws:*]': {
+ *   clean: { include: ({ vars, value }) => [...value, vars.buildDir] },   // a value: called here
+ *   run: { build: { after: ({ pkg }) => copyDocs(pkg) } },                // a step: called by `run`
+ * }
+ * ```
+ *
+ * **The key decides, and it already did.** `run.build.exec: 'tsc -b'` is a shell command and
+ * `publish.directory: 'build'` is a path - not because of anything about the strings, but because of
+ * where they sit. A function inherits the same rule, so nothing new has to be learned and no marker
+ * has to be remembered. The alternative was inspecting the function (arity, parameter names), which
+ * is the kind of guess `loadPlugins` refuses to make about a module's export for the same reason:
+ * guessing wrong here means running build-time code while merely loading the repository, or
+ * silently never running it.
+ *
+ * A **string** at one of these paths is still interpolated - `exec: 'tsc -b ${{ file.resolve(...) }}'`
+ * has to keep working - so this is narrower than `DEFERRED_PATHS`, which skips its paths entirely.
+ */
+export declare const STEP_PATHS: string[];
+/**
+ * Keys whose **whole subtree** is code rather than config, so no function under them is a value to
+ * compute. `plugins` is the only one, and it has to be here: an entry may be the plugin *object*
+ * itself, and an `RmanPlugin` is almost entirely functions - `manifest.read`, `workspace.resolve`,
+ * `versionPlanner`, `binPaths`, and every command's `builder` and `handler`.
+ *
+ * Measured, and it is why this exists: with `plugins` walked like any other key, resolving the
+ * config of a repository that named a plugin called that plugin's yargs builder with the config
+ * scope - `Config function in "plugins[0].commands[0].builder" failed: cmd.option is not a
+ * function`. A `plugins` entry is loaded by `loadPlugins`, never read as a setting.
+ */
+export declare const CODE_SUBTREES: string[];
 /** The `file` namespace for one package's directory - see `FileScope`. */
+/**
+ * `read` in a `${{ ... }}` expression (and in a value function): a structured file's **contents**,
+ * parsed - where `file` answers only where a path is.
+ *
+ * ```yaml
+ * "[*]":
+ *   run:
+ *     build:
+ *       exec: 'tsc --outDir ${{ read("tsconfig.json").compilerOptions.outDir }}'
+ * ```
+ *
+ * `cache` is shared across every package (see `Repository.configScope`) and keyed by what the file
+ * *is*, not merely where - so the same file read by twenty packages is parsed once, and a file rman
+ * itself rewrites mid-run is re-read rather than remembered. See `readStructuredFile`.
+ */
+export declare function createReadScope(dirname: string, cache: Map<string, CachedFile>): ReadFile;
+/**
+ * What `read` can parse.
+ *
+ * **`.env` is deliberately absent, and that is the durable part of this list**: `env` is already in
+ * scope, and a `.env` file exists to be loaded *into* an environment by something else - a config
+ * reading one as data would mean two different things called the environment.
+ *
+ * Nothing else is excluded on principle. `xml` arrived because a `pom.xml` or a `.csproj` holds a
+ * version exactly the way a `package.json` does, and rman is language-agnostic; the earlier line
+ * ("no new parsers") did not survive it, since xmldom *is* a new one.
+ */
+export type FileFormat = 'json' | 'yaml' | 'ini' | 'xml';
+/** `read(path)`, or `read(path, 'ini')` for a file whose name does not say what it is (`.npmrc`). */
+export type ReadFile = (target: string, format?: FileFormat) => unknown;
+/** One parsed file, kept against the identity of the bytes it came from - see `readStructuredFile`. */
+export interface CachedFile {
+    /** `mtimeNs:size`. */
+    stamp: string;
+    value: unknown;
+}
 export declare function createFileScope(dirname: string): FileScope;