@williamthorsen/nmr-core 0.10.3 → 0.10.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,16 +1,55 @@
1
+ /** Names the cache directory a tool's entries live in: `{home}/node_modules/.cache/{tool}/`. */
1
2
  export interface CacheDirRef {
3
+ /** The tool the cache belongs to, e.g. `nmr-compile`. Becomes the directory name. */
2
4
  tool: string;
5
+ /** The directory the cache serves; its nearest `node_modules` ancestor hosts the cache. */
3
6
  scopeDir: string;
4
7
  }
8
+ /** Locates a single entry within a tool's cache directory. */
5
9
  export interface CacheEntryRef extends CacheDirRef {
10
+ /** Readable filename prefix, e.g. the package name. */
6
11
  slug: string;
12
+ /** Filename extension, including the leading dot. */
7
13
  extension: string;
14
+ /**
15
+ * Strings folded into the filename digest alongside the absolute scope directory, so that one scope can hold
16
+ * several entries. Two refs differing only in `slug` would collide were the slug all that separated them.
17
+ */
8
18
  discriminators?: string[];
9
19
  }
20
+ /**
21
+ * Reads an entry's raw text, or `undefined` when it is absent or unreadable. A cache that cannot be read is a
22
+ * miss, never an error: the caller's fallback is to do the work again, which is always correct.
23
+ */
10
24
  export declare function readCacheEntry(entryPath: string): Promise<string | undefined>;
25
+ /**
26
+ * Reads a JSON entry and narrows it with `isValidEntry`, returning `undefined` when the entry is missing,
27
+ * unparseable, or of the wrong shape. Content written by an older format therefore reads as a miss rather than
28
+ * reaching the caller as a value it cannot trust.
29
+ */
11
30
  export declare function readJsonCacheEntry<T>(entryPath: string, isValidEntry: (value: unknown) => value is T): Promise<T | undefined>;
31
+ /** Removes a tool's entire cache directory. Idempotent: an absent directory is a silent no-op. */
12
32
  export declare function removeCacheDir(ref: CacheDirRef): Promise<void>;
33
+ /** Removes a single entry. Idempotent: an absent entry is a silent no-op, as is an absent cache directory. */
13
34
  export declare function removeCacheEntry(entryPath: string): Promise<void>;
35
+ /**
36
+ * Resolves the absolute path of a tool's cache directory. The conventional `node_modules/.cache/{tool}/` home is
37
+ * git-ignored and outside any `files` convention, so an entry never reaches a published tarball. The home is the
38
+ * nearest enclosing directory that already has a `node_modules`: the scope's own when it has one, otherwise a
39
+ * hoisted ancestor, such as the workspace root for a zero-dependency package. No `node_modules` is ever
40
+ * materialized solely to hold the cache.
41
+ */
14
42
  export declare function resolveCacheDir(ref: CacheDirRef): string;
43
+ /**
44
+ * Resolves the absolute path of a single cache entry. The file name folds a digest of the absolute scope
45
+ * directory (and any discriminators) into a readable base name, so scopes sharing a hoisted `node_modules`
46
+ * never collide while the path stays stable across runs for the same scope.
47
+ */
15
48
  export declare function resolveCacheEntryPath(ref: CacheEntryRef): string;
49
+ /**
50
+ * Writes an entry, creating the cache directory as needed. The write lands in a uniquely named temporary file
51
+ * and is renamed into place, so a concurrent reader sees either the previous entry or the new one and never a
52
+ * half-written file. Throws when the write cannot be completed; a caller for whom a failed cache write is not
53
+ * worth failing over catches it.
54
+ */
16
55
  export declare function writeCacheEntry(entryPath: string, content: string): Promise<void>;
@@ -1 +1,8 @@
1
+ /**
2
+ * Find the nearest ancestor directory containing `package.json`, starting from
3
+ * the directory of the given `import.meta.url`.
4
+ *
5
+ * Useful for resolving bundled assets (presets, templates) relative to the
6
+ * package root, regardless of the calling module's depth in the source or dist tree.
7
+ */
1
8
  export declare function findPackageRoot(fromUrl: string): string;
@@ -1 +1,10 @@
1
+ /**
2
+ * The `maxBuffer` every git invocation that pipes stdout should declare, raised well above Node's 1 MiB default
3
+ * so a tree with thousands of untracked files still reports a status and a long-lived repo still lists its tags.
4
+ *
5
+ * Node enforces the cap on the parent side: it kills the child and reports `ENOBUFS` once the pipe accumulates
6
+ * past the limit, so the child never learns why it died and the error names the spawned program rather than the
7
+ * output that overflowed. A call site that omits the option inherits the default silently and fails only once
8
+ * the repo it runs against has grown enough, which is why the value is shared rather than chosen per site.
9
+ */
1
10
  export declare const GIT_OUTPUT_LIMIT: number;
@@ -1,3 +1,8 @@
1
+ /**
2
+ * Narrows a thrown value to an `Error` carrying the given Node errno code.
3
+ *
4
+ * `isError` recognizes an `Error` crossing a realm boundary, which a bare `instanceof` test reports as false.
5
+ */
1
6
  export declare function hasErrnoCode(error: unknown, code: string): error is Error & {
2
7
  code: string;
3
8
  };
@@ -1,3 +1,8 @@
1
+ /**
2
+ * A whole-repo content hash, or the reason one could not be produced. Every degraded condition (no repository,
3
+ * no commit, a git failure, a tree this hash cannot describe) reports `ok: false` rather than a hash a caller
4
+ * might act on. A caller that gates work on the hash therefore does the work whenever the hash is unavailable.
5
+ */
1
6
  export type WorkingTreeHashResult = {
2
7
  ok: true;
3
8
  hash: string;
@@ -7,5 +12,23 @@ export type WorkingTreeHashResult = {
7
12
  ok: false;
8
13
  reason: string;
9
14
  };
15
+ /**
16
+ * Produces a content hash of the entire working tree at `cwd`: the commit's tree object folded with the current
17
+ * content of every path git reports as changed or untracked. Two trees holding the same content hash alike, so
18
+ * a `touch` that changes no bytes leaves the hash where it was, while any edit, addition, or deletion moves it.
19
+ *
20
+ * The hash is taken from git's own status rather than by walking the filesystem, which keeps it proportional to
21
+ * what has changed rather than to the size of the repository, and inherits git's ignore rules for free. Nothing
22
+ * here writes to the object database or the index: a hash is an observation, and a repository must look exactly
23
+ * the same after taking one.
24
+ *
25
+ * Because the commit's tree object is the base of the fold, committing an already-hashed tree moves the hash
26
+ * even though no content changed. The reverse holds too, and usefully: a rebase or an amended message that
27
+ * preserves content leaves the hash alone, as does checking out a branch whose tree is identical.
28
+ */
10
29
  export declare function hashWorkingTree(cwd: string): WorkingTreeHashResult;
30
+ /**
31
+ * Returns the commit `HEAD` names, or `undefined` when git cannot say. Cheap next to a full hash, so a caller
32
+ * holding an observation of a tree can ask whether the commit still stands where it did without retaking it.
33
+ */
11
34
  export declare function readHeadSha(cwd: string): string | undefined;
@@ -1,24 +1,51 @@
1
+ /** Schema entry describing a single CLI flag. */
1
2
  export interface FlagDefinition {
2
3
  long: string;
3
4
  type: 'boolean' | 'string';
4
5
  short?: string;
5
6
  }
7
+ /** Map of camelCase property names to their flag definitions. */
6
8
  export type FlagSchema = Record<string, FlagDefinition>;
9
+ /** Infer the result type from a flag schema: booleans become `boolean`, strings become `string | undefined`. */
7
10
  export type ParsedFlags<S extends FlagSchema> = {
8
11
  [K in keyof S]: S[K]['type'] extends 'boolean' ? boolean : string | undefined;
9
12
  };
13
+ /** Return type of `parseArgs`: typed flags plus collected positionals. */
10
14
  export interface ParsedArgs<S extends FlagSchema> {
11
15
  flags: ParsedFlags<S>;
12
16
  positionals: string[];
13
17
  }
18
+ /** Options controlling how `parseArgs` handles input beyond the flag schema. */
14
19
  export interface ParseArgsOptions {
20
+ /** When true, positionals are collected; otherwise an unexpected positional throws. Defaults to false. */
15
21
  allowPositionals?: boolean;
16
22
  }
23
+ /** Discriminates the failure modes `parseArgs` reports. */
17
24
  export type ParseErrorKind = 'unknown-flag' | 'missing-value' | 'unexpected-value' | 'unexpected-positional';
25
+ /**
26
+ * Error thrown by `parseArgs` on invalid input.
27
+ *
28
+ * Carries the failure `kind` and the offending token in `flag` — a flag as the user typed it, or the
29
+ * positional value for `'unexpected-positional'`. Its `message` is composed from those fields, so error
30
+ * wording is uniform across every kind.
31
+ */
18
32
  export declare class ParseError extends Error {
19
33
  readonly kind: ParseErrorKind;
20
34
  readonly flag: string;
21
35
  constructor(kind: ParseErrorKind, flag: string);
22
36
  }
37
+ /**
38
+ * Parse a pre-sliced argv array against a flag schema.
39
+ *
40
+ * Delegates tokenizing to `node:util.parseArgs` (non-strict, with tokens) and validates the token
41
+ * stream against the schema. Throws `ParseError` on an unknown flag, a missing string-flag value, a
42
+ * value supplied to a boolean flag, or — unless `options.allowPositionals` is set — an unexpected
43
+ * positional argument. Does not write output or exit.
44
+ */
23
45
  export declare function parseArgs<S extends FlagSchema>(argv: string[], schema: S, options?: ParseArgsOptions): ParsedArgs<S>;
46
+ /**
47
+ * Parse argv, or print a usage error to stderr and exit non-zero.
48
+ *
49
+ * The canonical "parse or die" entry point for CLI commands that terminate on invalid input.
50
+ */
24
51
  export declare function parseArgsOrExit<S extends FlagSchema>(argv: string[], schema: S, options?: ParseArgsOptions): ParsedArgs<S>;
@@ -1 +1,14 @@
1
+ /**
2
+ * Read the `version` field from the nearest ancestor `package.json`, starting
3
+ * from the directory of the given `import.meta.url`.
4
+ *
5
+ * Composes `findPackageRoot` with a `package.json` read so callers get a
6
+ * depth-agnostic version lookup that works in source layouts (`src/...`),
7
+ * compiled layouts (`dist/esm/...`), and consumer layouts (npm-installed,
8
+ * `npx`).
9
+ *
10
+ * Throws if the located `package.json` lacks a string `version` field.
11
+ * Propagates `findPackageRoot`'s own error when no ancestor `package.json`
12
+ * exists.
13
+ */
1
14
  export declare function readPackageVersion(fromUrl: string): string;
@@ -1,9 +1,24 @@
1
1
  import type { Writable } from 'node:stream';
2
2
  import type { WriteResult } from './writeFileWithCheck.js';
3
+ /**
4
+ * Renders the canonical `Error: <message>` line (without a trailing newline) — the single
5
+ * definition of this shape. Use it where the line is a value rather than a write target,
6
+ * e.g. a command that returns its message for the caller to print.
7
+ */
3
8
  export declare function formatErrorLine(message: string): string;
9
+ /** Prints an error message to stderr. */
4
10
  export declare function printError(message: string): void;
11
+ /** Prints a skip/warning message to stdout. */
5
12
  export declare function printSkip(message: string): void;
13
+ /** Prints a step label with a right-arrow prefix. */
6
14
  export declare function printStep(message: string): void;
15
+ /** Prints a success message with a checkmark emoji prefix. */
7
16
  export declare function printSuccess(message: string): void;
17
+ /**
18
+ * Writes the canonical `Error: <message>` line to a stream (stderr by default) — the single
19
+ * sanctioned door for this output shape. Pass an injected stream for in-process CLIs that
20
+ * route output through a `Writable` rather than touching `process.stderr` directly.
21
+ */
8
22
  export declare function reportError(message: string, stream?: Writable): void;
23
+ /** Prints a terminal message for a write result based on its outcome. */
9
24
  export declare function reportWriteResult(result: WriteResult, dryRun: boolean): void;
@@ -1,9 +1,19 @@
1
+ /** Outcome of a `writeFileWithCheck` call. */
1
2
  export type WriteOutcome = 'created' | 'overwritten' | 'up-to-date' | 'skipped' | 'failed';
3
+ /** Result returned by `writeFileWithCheck`. */
2
4
  export interface WriteResult {
3
5
  filePath: string;
4
6
  outcome: WriteOutcome;
5
7
  error?: string;
6
8
  }
9
+ /**
10
+ * Write a file with existence and content checks.
11
+ *
12
+ * Creates parent directories as needed. Compares content using whitespace-normalized comparison
13
+ * to determine whether an existing file is up to date. In dry-run mode, returns the outcome
14
+ * that would happen without performing writes. Filesystem errors are caught and returned as
15
+ * `{ outcome: 'failed' }` rather than thrown.
16
+ */
7
17
  export declare function writeFileWithCheck(filePath: string, content: string, options: {
8
18
  dryRun: boolean;
9
19
  overwrite: boolean;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@williamthorsen/nmr-core",
3
- "version": "0.10.3",
3
+ "version": "0.10.4",
4
4
  "private": false,
5
5
  "description": "Shared utilities for node-monorepo-tools packages",
6
6
  "keywords": [
@@ -32,12 +32,12 @@
32
32
  "dist"
33
33
  ],
34
34
  "dependencies": {
35
- "@williamthorsen/toolbelt.errors": "0.6.1"
35
+ "@williamthorsen/toolbelt.errors": "0.6.3"
36
36
  },
37
37
  "devDependencies": {
38
- "@williamthorsen/toolbelt.filesystem": "0.8.0",
39
- "@williamthorsen/toolbelt.testing": "0.4.0",
40
- "@williamthorsen/toolbelt.vitest": "0.6.0"
38
+ "@williamthorsen/toolbelt.filesystem": "0.8.2",
39
+ "@williamthorsen/toolbelt.testing": "0.5.0",
40
+ "@williamthorsen/toolbelt.vitest": "0.8.0"
41
41
  },
42
42
  "engines": {
43
43
  "node": ">=24"