@williamthorsen/toolbelt.packaging 0.0.0 → 0.2.0
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 +25 -0
- package/LICENSE +7 -0
- package/README.md +124 -1
- package/dist/esm/1-proposed/index.d.ts +1 -0
- package/dist/esm/1-proposed/index.js +1 -0
- package/dist/esm/2-draft/index.d.ts +1 -0
- package/dist/esm/2-draft/index.js +1 -0
- package/dist/esm/3-candidate/findPackageRoot.d.ts +1 -0
- package/dist/esm/3-candidate/findPackageRoot.js +4 -0
- package/dist/esm/3-candidate/getSelfVersion.d.ts +1 -0
- package/dist/esm/3-candidate/getSelfVersion.js +8 -0
- package/dist/esm/3-candidate/index.d.ts +2 -0
- package/dist/esm/3-candidate/index.js +2 -0
- package/dist/esm/4-release/findProjectRoot.d.ts +11 -0
- package/dist/esm/4-release/findProjectRoot.js +22 -0
- package/dist/esm/4-release/index.d.ts +1 -0
- package/dist/esm/4-release/index.js +1 -0
- package/dist/esm/internal/resolveOwningManifest.d.ts +10 -0
- package/dist/esm/internal/resolveOwningManifest.js +33 -0
- package/package.json +45 -2
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
## 0.2.0 — 2026-08-08
|
|
6
|
+
|
|
7
|
+
### Features
|
|
8
|
+
|
|
9
|
+
- Scaffold toolbelt.packaging for project-layout utilities (#99)
|
|
10
|
+
|
|
11
|
+
Adds `@williamthorsen/toolbelt.packaging`, a package scoped to package and project layout: where a package or project boundary begins, and what the manifest at that boundary declares. It exports nothing yet.
|
|
12
|
+
|
|
13
|
+
- 🚨 **Breaking:** Add findPackageRoot, getSelfVersion, and findProjectRoot to toolbelt.packaging (#107)
|
|
14
|
+
|
|
15
|
+
Adds a way for any module, whether it runs from a source tree or a compiled build, to identify the package that owns it and the version that package declares.
|
|
16
|
+
|
|
17
|
+
`findProjectRoot` moves from `@williamthorsen/toolbelt.filesystem` to `@williamthorsen/toolbelt.packaging`. Callers of `loadConfigCascade` must now state where its upward search stops, rather than relying on a project root the function found for them.
|
|
18
|
+
|
|
19
|
+
### Tooling
|
|
20
|
+
|
|
21
|
+
- Use identical compiler settings for all packages (#105)
|
|
22
|
+
|
|
23
|
+
All packages now have identical compiler settings, using the settings from the `@williamthorsen/tsconfig` base config without modification.
|
|
24
|
+
|
|
25
|
+
<!-- Generated by release-kit. Do not edit this file. Use .meta/changelog-overrides.json to override entries. -->
|
package/LICENSE
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 William Thorsen
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
|
|
6
|
+
|
|
7
|
+
The software is provided "as is" and the author disclaims all warranties with regard to this software including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, direct, indirect, or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.
|
package/README.md
CHANGED
|
@@ -1 +1,124 @@
|
|
|
1
|
-
|
|
1
|
+
# @williamthorsen/toolbelt.packaging
|
|
2
|
+
|
|
3
|
+
Package and project layout utilities for TypeScript and JavaScript: where a package or project boundary begins, and what the manifest at that boundary declares.
|
|
4
|
+
|
|
5
|
+
<!-- section:release-notes -->
|
|
6
|
+
## Release notes — v0.2.0 (2026-08-08)
|
|
7
|
+
|
|
8
|
+
### Features
|
|
9
|
+
|
|
10
|
+
- Scaffold toolbelt.packaging for project-layout utilities (#99)
|
|
11
|
+
|
|
12
|
+
Adds `@williamthorsen/toolbelt.packaging`, a package scoped to package and project layout: where a package or project boundary begins, and what the manifest at that boundary declares. It exports nothing yet.
|
|
13
|
+
|
|
14
|
+
- 🚨 **Breaking:** Add findPackageRoot, getSelfVersion, and findProjectRoot to toolbelt.packaging (#107)
|
|
15
|
+
|
|
16
|
+
Adds a way for any module, whether it runs from a source tree or a compiled build, to identify the package that owns it and the version that package declares.
|
|
17
|
+
|
|
18
|
+
`findProjectRoot` moves from `@williamthorsen/toolbelt.filesystem` to `@williamthorsen/toolbelt.packaging`. Callers of `loadConfigCascade` must now state where its upward search stops, rather than relying on a project root the function found for them.
|
|
19
|
+
<!-- /section:release-notes -->
|
|
20
|
+
|
|
21
|
+
## Installation
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
pnpm add @williamthorsen/toolbelt.packaging
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Runtime requirements
|
|
28
|
+
|
|
29
|
+
Every export reaches the filesystem through `node:` builtins, so they run under Node.js 24 or later, Bun, and Deno. They do not run in browsers, nor in edge runtimes that expose no filesystem.
|
|
30
|
+
|
|
31
|
+
## `findProjectRoot`
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
findProjectRoot(startDir: string, options?: { markers?: ReadonlyArray<string> }): ProjectRoot;
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Resolves `startDir` to an absolute path, ascends from it, and returns the first directory carrying a root marker, along with the evidence that identified it:
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
interface ProjectRoot {
|
|
41
|
+
marker: string | null; // the marker that matched, or null when a fallback answered
|
|
42
|
+
rootDir: string;
|
|
43
|
+
source: 'marker' | 'package-json' | 'start-dir';
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`DEFAULT_ROOT_MARKERS` is consulted in order, so the earliest entry wins when one directory carries several:
|
|
48
|
+
|
|
49
|
+
1. `.git`, matching either a directory (an ordinary clone) or a file (a worktree or submodule);
|
|
50
|
+
2. `pnpm-workspace.yaml`;
|
|
51
|
+
3. `pnpm-lock.yaml`;
|
|
52
|
+
4. `package-lock.json`;
|
|
53
|
+
5. `yarn.lock`;
|
|
54
|
+
6. `bun.lock`.
|
|
55
|
+
|
|
56
|
+
Passing `markers` replaces that list rather than extending it. Spread `DEFAULT_ROOT_MARKERS` to add to it:
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
import { DEFAULT_ROOT_MARKERS, findProjectRoot } from '@williamthorsen/toolbelt.packaging';
|
|
60
|
+
|
|
61
|
+
findProjectRoot(process.cwd(), { markers: [...DEFAULT_ROOT_MARKERS, 'deno.json'] });
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
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.
|
|
65
|
+
|
|
66
|
+
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:
|
|
67
|
+
|
|
68
|
+
1. the nearest ancestor holding a `package.json`, reported as `source: 'package-json'`;
|
|
69
|
+
2. `startDir` itself, reported as `source: 'start-dir'`.
|
|
70
|
+
|
|
71
|
+
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.
|
|
72
|
+
|
|
73
|
+
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.
|
|
74
|
+
|
|
75
|
+
## `findPackageRoot`
|
|
76
|
+
|
|
77
|
+
Candidate tier: imported from `@williamthorsen/toolbelt.packaging/candidate` rather than the package root, and subject to change.
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
findPackageRoot(fromUrl: string): string;
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Returns the directory of the package that owns a module, which is where assets shipped alongside that package resolve from.
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
import path from 'node:path';
|
|
87
|
+
|
|
88
|
+
import { findPackageRoot } from '@williamthorsen/toolbelt.packaging/candidate';
|
|
89
|
+
|
|
90
|
+
const templatesDir = path.join(findPackageRoot(import.meta.url), 'templates');
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
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.
|
|
94
|
+
|
|
95
|
+
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:
|
|
96
|
+
|
|
97
|
+
```jsonc
|
|
98
|
+
// dist/cjs/package.json -- a marker manifest, declaring no name
|
|
99
|
+
{ "type": "commonjs" }
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
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.
|
|
103
|
+
|
|
104
|
+
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.
|
|
105
|
+
|
|
106
|
+
## `getSelfVersion`
|
|
107
|
+
|
|
108
|
+
Candidate tier: imported from `@williamthorsen/toolbelt.packaging/candidate` rather than the package root, and subject to change.
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
getSelfVersion(fromUrl: string): string;
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Returns the version declared by the package that owns a module: the supported way for a CLI to report its own version without hand-rolling a manifest lookup.
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
import { getSelfVersion } from '@williamthorsen/toolbelt.packaging/candidate';
|
|
118
|
+
|
|
119
|
+
console.log(`my-cli ${getSelfVersion(import.meta.url)}`);
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Ownership is resolved exactly as [`findPackageRoot`](#findpackageroot) resolves it, so a marker manifest is passed over here too. Without that, a dual-format build would read its version as `undefined` rather than raising, since the marker manifest declares none.
|
|
123
|
+
|
|
124
|
+
A manifest that declares a `name` but no string `version` throws, naming the manifest. The ascent does not continue past it, so a versionless package never reports an ancestor's version as its own.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function findPackageRoot(fromUrl: string): string;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function getSelfVersion(fromUrl: string): string;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { resolveOwningManifest } from "../internal/resolveOwningManifest.js";
|
|
2
|
+
export function getSelfVersion(fromUrl) {
|
|
3
|
+
const { manifest, manifestPath } = resolveOwningManifest(fromUrl);
|
|
4
|
+
if (typeof manifest.version !== 'string') {
|
|
5
|
+
throw new TypeError(`Package manifest declares no string version: ${manifestPath}`);
|
|
6
|
+
}
|
|
7
|
+
return manifest.version;
|
|
8
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export declare const DEFAULT_ROOT_MARKERS: ReadonlyArray<string>;
|
|
2
|
+
export declare function findProjectRoot(startDir: string, options?: FindProjectRootOptions): ProjectRoot;
|
|
3
|
+
export interface FindProjectRootOptions {
|
|
4
|
+
markers?: ReadonlyArray<string> | undefined;
|
|
5
|
+
}
|
|
6
|
+
export interface ProjectRoot {
|
|
7
|
+
marker: string | null;
|
|
8
|
+
rootDir: string;
|
|
9
|
+
source: ProjectRootSource;
|
|
10
|
+
}
|
|
11
|
+
export type ProjectRootSource = 'marker' | 'package-json' | 'start-dir';
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import path from 'node:path';
|
|
2
|
+
import { findDirectoryChainMatch } from '@williamthorsen/toolbelt.filesystem';
|
|
3
|
+
export const DEFAULT_ROOT_MARKERS = [
|
|
4
|
+
'.git',
|
|
5
|
+
'pnpm-workspace.yaml',
|
|
6
|
+
'pnpm-lock.yaml',
|
|
7
|
+
'package-lock.json',
|
|
8
|
+
'yarn.lock',
|
|
9
|
+
'bun.lock',
|
|
10
|
+
];
|
|
11
|
+
export function findProjectRoot(startDir, options = {}) {
|
|
12
|
+
const { markers = DEFAULT_ROOT_MARKERS } = options;
|
|
13
|
+
const markerMatch = findDirectoryChainMatch(startDir, markers);
|
|
14
|
+
if (markerMatch !== undefined) {
|
|
15
|
+
return { marker: markerMatch.entryName, rootDir: markerMatch.dir, source: 'marker' };
|
|
16
|
+
}
|
|
17
|
+
const manifestMatch = findDirectoryChainMatch(startDir, ['package.json']);
|
|
18
|
+
if (manifestMatch !== undefined) {
|
|
19
|
+
return { marker: null, rootDir: manifestMatch.dir, source: 'package-json' };
|
|
20
|
+
}
|
|
21
|
+
return { marker: null, rootDir: path.resolve(startDir), source: 'start-dir' };
|
|
22
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { DEFAULT_ROOT_MARKERS, findProjectRoot, type FindProjectRootOptions, type ProjectRoot, type ProjectRootSource, } from './findProjectRoot.js';
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { DEFAULT_ROOT_MARKERS, findProjectRoot, } from "./findProjectRoot.js";
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
export declare function resolveOwningManifest(fromUrl: string): OwningManifest;
|
|
2
|
+
export interface OwningManifest {
|
|
3
|
+
manifest: PackageManifest;
|
|
4
|
+
manifestPath: string;
|
|
5
|
+
packageDir: string;
|
|
6
|
+
}
|
|
7
|
+
export interface PackageManifest {
|
|
8
|
+
name?: unknown;
|
|
9
|
+
version?: unknown;
|
|
10
|
+
}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import fs from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { fileURLToPath } from 'node:url';
|
|
4
|
+
import { listDirectoryChain } from '@williamthorsen/toolbelt.filesystem';
|
|
5
|
+
export function resolveOwningManifest(fromUrl) {
|
|
6
|
+
const startDir = path.dirname(fileURLToPath(fromUrl));
|
|
7
|
+
for (const dir of listDirectoryChain(startDir)) {
|
|
8
|
+
const manifestPath = path.join(dir, 'package.json');
|
|
9
|
+
if (!fs.existsSync(manifestPath))
|
|
10
|
+
continue;
|
|
11
|
+
const manifest = readManifest(manifestPath);
|
|
12
|
+
if (typeof manifest.name === 'string') {
|
|
13
|
+
return { manifest, manifestPath, packageDir: dir };
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
throw new Error(`No package.json declaring a name was found at or above: ${fromUrl}`);
|
|
17
|
+
}
|
|
18
|
+
function isPackageManifest(value) {
|
|
19
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
20
|
+
}
|
|
21
|
+
function readManifest(manifestPath) {
|
|
22
|
+
let parsed;
|
|
23
|
+
try {
|
|
24
|
+
parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
|
|
25
|
+
}
|
|
26
|
+
catch (error) {
|
|
27
|
+
throw new Error(`Package manifest is not readable as JSON: ${manifestPath}`, { cause: error });
|
|
28
|
+
}
|
|
29
|
+
if (!isPackageManifest(parsed)) {
|
|
30
|
+
throw new Error(`Package manifest is not a JSON object: ${manifestPath}`);
|
|
31
|
+
}
|
|
32
|
+
return parsed;
|
|
33
|
+
}
|
package/package.json
CHANGED
|
@@ -1,4 +1,47 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@williamthorsen/toolbelt.packaging",
|
|
3
|
-
"version": "0.
|
|
4
|
-
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Package and project layout utilities: where a package or project boundary begins, and what its manifest declares",
|
|
5
|
+
"keywords": [],
|
|
6
|
+
"homepage": "https://github.com/williamthorsen/toolbelt/tree/main/packages/packaging#readme",
|
|
7
|
+
"bugs": {
|
|
8
|
+
"url": "https://github.com/williamthorsen/toolbelt/issues"
|
|
9
|
+
},
|
|
10
|
+
"repository": {
|
|
11
|
+
"type": "git",
|
|
12
|
+
"url": "git+https://github.com/williamthorsen/toolbelt.git",
|
|
13
|
+
"directory": "packages/packaging"
|
|
14
|
+
},
|
|
15
|
+
"license": "ISC",
|
|
16
|
+
"author": "William Thorsen <william@thorsen.dev> (https://github.com/williamthorsen)",
|
|
17
|
+
"type": "module",
|
|
18
|
+
"exports": {
|
|
19
|
+
".": {
|
|
20
|
+
"import": "./dist/esm/4-release/index.js"
|
|
21
|
+
},
|
|
22
|
+
"./candidate": {
|
|
23
|
+
"import": "./dist/esm/3-candidate/index.js"
|
|
24
|
+
},
|
|
25
|
+
"./draft": {
|
|
26
|
+
"import": "./dist/esm/2-draft/index.js"
|
|
27
|
+
},
|
|
28
|
+
"./proposed": {
|
|
29
|
+
"import": "./dist/esm/1-proposed/index.js"
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
"files": [
|
|
33
|
+
"dist/*",
|
|
34
|
+
"CHANGELOG.md"
|
|
35
|
+
],
|
|
36
|
+
"dependencies": {
|
|
37
|
+
"@williamthorsen/toolbelt.filesystem": "0.3.0"
|
|
38
|
+
},
|
|
39
|
+
"engines": {
|
|
40
|
+
"node": ">=24.0.0"
|
|
41
|
+
},
|
|
42
|
+
"publishConfig": {
|
|
43
|
+
"access": "public",
|
|
44
|
+
"registry": "https://registry.npmjs.org"
|
|
45
|
+
},
|
|
46
|
+
"scripts": {}
|
|
47
|
+
}
|