@williamthorsen/toolbelt.packaging 0.5.4 → 0.5.5

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.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,22 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## 0.5.5 — 2026-09-06
6
+
7
+ ### Documentation
8
+
9
+ - Repair reduced object relatives in passages recurring across files (#262)
10
+
11
+ Repairs the reduced object relative in the prose passages that recur across more than one file, in package READMEs, source comments, test titles, and the ReadyUp kits' check messages.
12
+
13
+ - Repair reduced object relatives in the READMEs and AGENTS.md (#263)
14
+
15
+ Repairs the reduced object relative in `AGENTS.md`, the root `README.md`, and the package READMEs.
16
+
17
+ - Repair the repository's prose and record every rejection's ground (#290)
18
+
19
+ Applies one repo-wide `revise-prose` sweep across the repository's READMEs, `AGENTS.md`, source comments, doc descriptions, and test names.
20
+
5
21
  ## 0.5.4 — 2026-08-30
6
22
 
7
23
  ### Dependency updates
package/README.md CHANGED
@@ -24,7 +24,7 @@ Resolves `startDir` to an absolute path, ascends from it, and returns the first
24
24
 
25
25
  ```ts
26
26
  interface ProjectRoot {
27
- marker: string | null; // the marker that matched, or null when a fallback answered
27
+ marker: string | null; // the marker that matched, or null when a fallback identified the root
28
28
  rootDir: string;
29
29
  source: 'marker' | 'package-json' | 'start-dir';
30
30
  }
@@ -47,7 +47,7 @@ import { DEFAULT_ROOT_MARKERS, findProjectRoot } from '@williamthorsen/toolbelt.
47
47
  findProjectRoot(process.cwd(), { markers: [...DEFAULT_ROOT_MARKERS, 'deno.json'] });
48
48
  ```
49
49
 
50
- Each marker is a path relative to the level it is probed against, on the terms [`listDirectoryChainMatches`](https://github.com/williamthorsen/toolbelt/tree/main/packages/filesystem#listdirectorychainmatches) sets out: one that is absolute, or whose `..` segments escape its level, is rejected before any directory is probed.
50
+ Each marker is a path relative to the level against which it is probed, on the terms set out by [`listDirectoryChainMatches`](https://github.com/williamthorsen/toolbelt/tree/main/packages/filesystem#listdirectorychainmatches): one that is absolute, or whose `..` segments escape its level, is rejected before any directory is probed.
51
51
 
52
52
  When no directory up to and including the filesystem root carries a marker, the result falls back in this order, reporting a `null` marker either way:
53
53
 
@@ -56,7 +56,7 @@ When no directory up to and including the filesystem root carries a marker, the
56
56
 
57
57
  The ascent terminates at the filesystem root on every platform, so a Windows drive root or UNC share is as safe a starting point as a POSIX path.
58
58
 
59
- A project root is not a package root: this answers "which checkout am I in", where [`findPackageRoot`](#findpackageroot) answers "which package declares me". A monorepo has one project root and many package roots.
59
+ A project root is not a package root: This answers "which checkout am I in", where [`findPackageRoot`](#findpackageroot) answers "which package declares me". A monorepo has one project root and many package roots.
60
60
 
61
61
  ## `findPackageRoot`
62
62
 
@@ -76,18 +76,18 @@ import { findPackageRoot } from '@williamthorsen/toolbelt.packaging/candidate';
76
76
  const templatesDir = path.join(findPackageRoot(import.meta.url), 'templates');
77
77
  ```
78
78
 
79
- Pass `import.meta.url`. A module's own URL is the only input that answers correctly from both a source tree and a compiled one, because the two sit at different depths and no fixed number of `..` hops suits both.
79
+ Pass `import.meta.url`. A module's own URL is the only input that resolves correctly from both a source tree and a compiled one, because the two sit at different depths and no fixed number of `..` hops suits both.
80
80
 
81
81
  The owning package is the nearest ancestor whose `package.json` declares a `name`. That rule is what distinguishes this from `findPackageJSON` in `node:module`, which answers the different question of which manifest _governs_ a file:
82
82
 
83
83
  ```jsonc
84
- // dist/cjs/package.json -- a marker manifest, declaring no name
84
+ // dist/cjs/package.json: a marker manifest, declaring no name
85
85
  { "type": "commonjs" }
86
86
  ```
87
87
 
88
88
  A dual-format build leaves that file so the runtime parses `dist/cjs/` as CommonJS. `findPackageJSON` stops there and reports it; `findPackageRoot` passes over it and keeps ascending to the manifest that declares the package's identity.
89
89
 
90
- A module belonging to no named package throws, rather than falling back to a directory that merely looks plausible, which is why the return is a bare string with no evidence to interpret. A manifest that is unreadable as JSON, or that parses to something other than an object, throws by name rather than being skipped: corruption is a defect, not an absence.
90
+ A module belonging to no named package throws, rather than falling back to a directory that merely looks plausible, which is why the return is a bare string with no evidence to interpret. A manifest that is unreadable as JSON, or that parses to something other than an object, throws by name rather than being skipped: Corruption is a defect, not an absence.
91
91
 
92
92
  ## `resolveSelfVersion`
93
93
 
@@ -1 +1,20 @@
1
+ /**
2
+ * Returns the directory of the package that owns the module at `fromUrl`, which is where assets shipped
3
+ * alongside that package resolve from.
4
+ *
5
+ * The owning package is the nearest ancestor whose `package.json` declares a `name`, so a marker manifest --
6
+ * the `{"type": "commonjs"}` file left in `dist/` by a dual-format build -- is passed over rather than
7
+ * returned. Pass `import.meta.url`: A module's own URL is the only input that resolves correctly from both a
8
+ * source tree and a compiled one, where the two sit at different depths.
9
+ *
10
+ * A module belonging to no package is an error rather than a fallback, so the return is a bare directory.
11
+ *
12
+ * @example
13
+ * findPackageRoot(import.meta.url); // '/home/dev/my-app/node_modules/some-package'
14
+ *
15
+ * @category Packaging
16
+ * @experimental
17
+ * @stage candidate
18
+ * @throws If no ancestor manifest declares a name, or if one is unreadable as JSON.
19
+ */
1
20
  export declare function findPackageRoot(fromUrl: string): string;
@@ -1 +1,17 @@
1
+ /**
2
+ * Returns the version declared by the package that owns the module at `fromUrl`.
3
+ *
4
+ * Pass `import.meta.url`, which reports the same version from a source tree and a compiled one even though
5
+ * the two sit at different depths. A manifest declaring a `name` but no string `version` raises rather than
6
+ * letting the ascent continue, so a versionless package never reports an ancestor's version as its own.
7
+ *
8
+ * @example
9
+ * resolveSelfVersion(import.meta.url); // '1.4.2'
10
+ *
11
+ * @category Packaging
12
+ * @experimental
13
+ * @stage candidate
14
+ * @throws If the owning manifest declares no string version, if no ancestor manifest declares a name, or if
15
+ * one is unreadable as JSON.
16
+ */
1
17
  export declare function resolveSelfVersion(fromUrl: string): string;
@@ -1,9 +1,34 @@
1
+ /**
2
+ * Names that identify a project root, in precedence order: When a directory carries more than one,
3
+ * the earliest in this list is the one reported.
4
+ *
5
+ * `.git` matches whether it is a directory (an ordinary clone) or a file (a worktree or submodule).
6
+ *
7
+ * @category Packaging
8
+ * @stage release
9
+ */
1
10
  export declare const DEFAULT_ROOT_MARKERS: ReadonlyArray<string>;
11
+ /**
12
+ * Returns the project root at or above `startDir`, along with the evidence that identified it.
13
+ *
14
+ * Ascends from `startDir` (resolved to an absolute path) and returns the first directory carrying one of
15
+ * `markers`. If no directory up to and including the filesystem root carries one, falls back to the nearest
16
+ * ancestor holding a `package.json`, then to `startDir` itself; both fallbacks report a `null` marker.
17
+ *
18
+ * @example
19
+ * findProjectRoot(import.meta.dirname); // { marker: '.git', rootDir: '/home/dev/my-app', source: 'marker' }
20
+ *
21
+ * @category Packaging
22
+ * @stage release
23
+ * @throws If a marker is absolute or escapes its directory level.
24
+ */
2
25
  export declare function findProjectRoot(startDir: string, options?: FindProjectRootOptions): ProjectRoot;
3
26
  export interface FindProjectRootOptions {
27
+ /** Replaces (does not extend) `DEFAULT_ROOT_MARKERS`. */
4
28
  markers?: ReadonlyArray<string> | undefined;
5
29
  }
6
30
  export interface ProjectRoot {
31
+ /** The marker that identified the root, or `null` when a fallback did. */
7
32
  marker: string | null;
8
33
  rootDir: string;
9
34
  source: ProjectRootSource;
@@ -1,9 +1,20 @@
1
+ /**
2
+ * Returns the manifest of the package that owns the module at `fromUrl`, together with where it was found.
3
+ *
4
+ * Ascends from the module's own directory and returns the first `package.json` declaring a `name`. One that
5
+ * declares none is a marker manifest, such as the `{"type": "commonjs"}` file left in `dist/` by a dual-format
6
+ * build, and the ascent passes over it. That is the whole difference from `node:module`'s `findPackageJSON`,
7
+ * which returns the nearest manifest whatever it holds.
8
+ *
9
+ * @internal
10
+ */
1
11
  export declare function resolveOwningManifest(fromUrl: string): OwningManifest;
2
12
  export interface OwningManifest {
3
13
  manifest: PackageManifest;
4
14
  manifestPath: string;
5
15
  packageDir: string;
6
16
  }
17
+ /** Only the fields read by this package are declared, and each as `unknown`, since a manifest is untrusted JSON. */
7
18
  export interface PackageManifest {
8
19
  name?: unknown;
9
20
  version?: unknown;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@williamthorsen/toolbelt.packaging",
3
- "version": "0.5.4",
3
+ "version": "0.5.5",
4
4
  "description": "Package and project layout utilities: where a package or project boundary begins, and what its manifest declares",
5
5
  "keywords": [
6
6
  "esm",
@@ -43,10 +43,10 @@
43
43
  "CHANGELOG.md"
44
44
  ],
45
45
  "dependencies": {
46
- "@williamthorsen/toolbelt.filesystem": "0.8.2"
46
+ "@williamthorsen/toolbelt.filesystem": "0.8.3"
47
47
  },
48
48
  "devDependencies": {
49
- "@williamthorsen/toolbelt.testing": "0.5.0"
49
+ "@williamthorsen/toolbelt.testing": "0.5.1"
50
50
  },
51
51
  "engines": {
52
52
  "node": ">=24.0.0"