@williamthorsen/toolbelt.packaging 0.5.5 → 0.6.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.
@@ -0,0 +1,409 @@
1
+ /** @noformat -- @generated. Do not edit. Compiled by rdy. */
2
+ /* eslint-disable */
3
+ export const __readyupVersion = "0.36.0";
4
+
5
+
6
+ // ../adoption/src/conventions/path-predicates.ts
7
+ var BIN_DIRECTORY = /(?:^|\/)bin\//;
8
+ var JS_TS_EXTENSION = /\.[cm]?[jt]sx?$/;
9
+ var TEST_DIRECTORY = /(?:^|\/)__tests__\//;
10
+ var TEST_SUFFIX = /\.(?:spec|test)\.[cm]?[jt]sx?$/;
11
+ function isAdoptableSource(path) {
12
+ return isJsTsSource(path) && !isBinWrapper(path) && !isTestFile(path) && !isInTestDirectory(path);
13
+ }
14
+ function isBinWrapper(path) {
15
+ return BIN_DIRECTORY.test(path);
16
+ }
17
+ function isInTestDirectory(path) {
18
+ return TEST_DIRECTORY.test(path);
19
+ }
20
+ function isJsTsSource(path) {
21
+ return JS_TS_EXTENSION.test(path);
22
+ }
23
+ function isTestFile(path) {
24
+ return TEST_SUFFIX.test(path);
25
+ }
26
+
27
+ // ../adoption/src/conventions/site-handoffs.ts
28
+ function isManifestSearch(names) {
29
+ return names.includes("package.json");
30
+ }
31
+
32
+ // ../adoption/src/kits/defineAdoptionKit.ts
33
+ import { defineRdyKit } from "readyup";
34
+ import {
35
+ buildFindingReport,
36
+ countPackageUsage,
37
+ readTrackedSources
38
+ } from "readyup/check-utils";
39
+ var NOT_A_REPO = "the project is not a git working tree, and these checks read the files that git tracks";
40
+ var NOTHING_TO_REPORT = { findings: [] };
41
+ function defineAdoptionKit(spec) {
42
+ assertCheckIdsAreUnique();
43
+ const cache = {};
44
+ const adoptedPackage = { exportNames: spec.exportNames, packageName: spec.packageName };
45
+ const kitScope = { noSourcesReason: spec.noSourcesReason, pathFilter: spec.pathFilter };
46
+ const pathFiltersByKind = mapPathFiltersByKind();
47
+ const sweptPathFilters = [
48
+ .../* @__PURE__ */ new Set([spec.pathFilter, ...spec.checks.map((check) => resolveScope(check).pathFilter)])
49
+ ];
50
+ return defineRdyKit({
51
+ description: spec.description,
52
+ defaultSeverity: "warn",
53
+ checklists: [
54
+ {
55
+ name: "adoption",
56
+ checks: spec.checks.map((check) => ({
57
+ name: check.name,
58
+ id: check.id,
59
+ ...check.severity !== void 0 && { severity: check.severity },
60
+ skip: () => skipUnlessProjectHoldsSources(resolveScope(check)),
61
+ check: () => reportKinds(check.kinds),
62
+ fix: check.fix
63
+ }))
64
+ }
65
+ ]
66
+ });
67
+ function assertCheckIdsAreUnique() {
68
+ const seen = /* @__PURE__ */ new Set();
69
+ const duplicated = /* @__PURE__ */ new Set();
70
+ for (const { id } of spec.checks) {
71
+ if (seen.has(id)) duplicated.add(id);
72
+ seen.add(id);
73
+ }
74
+ if (duplicated.size > 0) {
75
+ const ids = [...duplicated].toSorted().join(", ");
76
+ throw new Error(`${spec.packageName}'s kit gives one id to more than one check: ${ids}`);
77
+ }
78
+ }
79
+ function isSweptPath(path) {
80
+ return sweptPathFilters.some((pathFilter) => pathFilter(path));
81
+ }
82
+ function loadSummary() {
83
+ cache.summary ??= readProject();
84
+ return cache.summary;
85
+ }
86
+ function mapPathFiltersByKind() {
87
+ const pathFilters = /* @__PURE__ */ new Map();
88
+ const conflicted = /* @__PURE__ */ new Set();
89
+ for (const check of spec.checks) {
90
+ const { pathFilter } = resolveScope(check);
91
+ for (const kind of check.kinds) {
92
+ const assigned = pathFilters.get(kind);
93
+ if (assigned !== void 0 && assigned !== pathFilter) conflicted.add(kind);
94
+ pathFilters.set(kind, pathFilter);
95
+ }
96
+ }
97
+ if (conflicted.size > 0) {
98
+ const kinds = [...conflicted].toSorted().join(", ");
99
+ throw new Error(`${spec.packageName}'s kit reads one kind through more than one path filter: ${kinds}`);
100
+ }
101
+ return pathFilters;
102
+ }
103
+ async function readProject() {
104
+ const sources = await readTrackedSources(isSweptPath);
105
+ if (sources === void 0) return void 0;
106
+ return {
107
+ adoptedCount: countPackageUsage(sources, adoptedPackage),
108
+ findings: sources.flatMap(
109
+ (source) => spec.detect(source.text).filter((site) => (pathFiltersByKind.get(site.kind) ?? spec.pathFilter)(source.path)).map((site) => ({ ...site, path: source.path }))
110
+ ),
111
+ sources
112
+ };
113
+ }
114
+ async function reportKinds(kinds) {
115
+ const summary = await loadSummary();
116
+ if (summary === void 0) return NOTHING_TO_REPORT;
117
+ return buildFindingReport({
118
+ adoptedCount: summary.adoptedCount,
119
+ findings: summary.findings,
120
+ ownImplementation: { ...adoptedPackage, sources: summary.sources },
121
+ shouldReport: (finding) => kinds.includes(finding.kind)
122
+ });
123
+ }
124
+ function resolveScope(check) {
125
+ return check.pathFilter === void 0 ? kitScope : { noSourcesReason: check.noSourcesReason, pathFilter: check.pathFilter };
126
+ }
127
+ async function skipUnlessProjectHoldsSources(scope) {
128
+ const summary = await loadSummary();
129
+ if (summary === void 0) return NOT_A_REPO;
130
+ return summary.sources.some((source) => scope.pathFilter(source.path)) ? false : scope.noSourcesReason;
131
+ }
132
+ }
133
+
134
+ // ../adoption/src/portable/condenseWhitespace.ts
135
+ function condenseWhitespace(text) {
136
+ return text.replaceAll(/\s+/g, " ");
137
+ }
138
+
139
+ // ../adoption/src/portable/listDirectoryAscents.ts
140
+ import { getLineAtOffset } from "readyup/check-utils";
141
+
142
+ // ../adoption/src/portable/readAnchoredWindow.ts
143
+ function readAnchoredWindow(source, offset, lengths) {
144
+ return {
145
+ after: condenseWhitespace(source.slice(offset, offset + lengths.lookahead)),
146
+ before: condenseWhitespace(source.slice(Math.max(0, offset - lengths.lookbehind), offset))
147
+ };
148
+ }
149
+
150
+ // ../adoption/src/portable/readBalancedGroup.ts
151
+ var BRACES = { close: "}", open: "{" };
152
+ var PARENTHESES = { close: ")", open: "(" };
153
+ function readBalancedGroup(source, from, delimiters) {
154
+ const start = source.indexOf(delimiters.open, from);
155
+ if (start === -1) return void 0;
156
+ let depth = 0;
157
+ for (let index = start; index < source.length; index += 1) {
158
+ if (source[index] === delimiters.open) depth += 1;
159
+ else if (source[index] === delimiters.close) {
160
+ depth -= 1;
161
+ if (depth === 0) return { end: index + 1, start };
162
+ }
163
+ }
164
+ return void 0;
165
+ }
166
+
167
+ // ../adoption/src/portable/readLiteral.ts
168
+ function readLiteral(source, span) {
169
+ const start = span?.[0];
170
+ const end = span?.[1];
171
+ return start === void 0 || end === void 0 ? void 0 : source.slice(start + 1, end - 1);
172
+ }
173
+
174
+ // ../adoption/src/portable/listDirectoryAscents.ts
175
+ var ASSIGNED_TARGET = /(?<target>[A-Za-z_$][\w$]*) ?= ?$/;
176
+ var ASSIGNMENT_WINDOW = { lookahead: 0, lookbehind: 80 };
177
+ var BRACKET_CLOSERS = /* @__PURE__ */ new Set([")", "]", "}"]);
178
+ var BRACKET_OPENERS = /* @__PURE__ */ new Set(["(", "[", "{"]);
179
+ var DECLARATION = /\b(?:const|let|var)\s+(?<name>[A-Za-z_$][\w$]*)\s*(?::[^=;\n]*)?=(?![=>])/g;
180
+ var DECLARED_NAME = /\b(?:const|let|var)\s+(?<name>[A-Za-z_$][\w$]*)/g;
181
+ var DIRNAME_ASCENT = /(?:[A-Za-z_$][\w$]*\s*\.\s*)?\bdirname\s*\(\s*(?<subject>[A-Za-z_$][\w$]*)\s*\)/g;
182
+ var LEADING_SEPARATOR = /^[/\\]+/;
183
+ var LEVEL_PROBE = /\b(?:access|exists|lstat|readdir|readFile|stat)(?:Sync)?\s*\(/g;
184
+ var LOOP_KEYWORD = /\b(?<keyword>do|for|while)\b/g;
185
+ var PATH_TOKEN = /(?<quoted>(?<quote>['"])[^'"]*\k<quote>)|`|(?<![\w$.])(?<name>[A-Za-z_$][\w$]*)/g;
186
+ var REASSIGNMENT = /(?<![\w$.])(?<!\b(?:const|let|var)\s+)(?<name>[A-Za-z_$][\w$]*)\s*(?:\*\*|<<|>>>?|&&|\|\||\?\?|[-+*/%&|^])?=(?![=>])/g;
187
+ var SEPARATOR_RUN = /[/\\]+/g;
188
+ var SIMPLE_ASSIGNMENT = /(?<![\w$])(?<target>[A-Za-z_$][\w$]*)\s*=(?!=)\s*(?<value>[A-Za-z_$][\w$]*)(?![\w$.([])/g;
189
+ var STRING_CONSTANT = /\bconst\s+(?<name>[A-Za-z_$][\w$]*)\s*(?::\s*string\s*)?=\s*(?<literal>(?<quote>['"`])[^'"`$]*\k<quote>)\s*(?:as\s+const\s*)?(?=[;,)\n]|$)/dg;
190
+ var WHITESPACE = /\s/;
191
+ function listDirectoryAscents(code, source) {
192
+ const constants = listStringConstants(code, source);
193
+ const ascents = listLoops(code).flatMap((loop) => describeAscent(code, source, loop, constants) ?? []);
194
+ return ascents.filter((ascent) => ascents.every((other) => other === ascent || !isNested(other.loop, ascent.loop))).map((ascent) => ({ line: getLineAtOffset(code, ascent.loop.start), probedNames: ascent.probedNames }));
195
+ }
196
+ function countMatchesByName(text, pattern) {
197
+ const counts = /* @__PURE__ */ new Map();
198
+ for (const match of text.matchAll(pattern)) {
199
+ const name = match.groups?.["name"];
200
+ if (name !== void 0) counts.set(name, (counts.get(name) ?? 0) + 1);
201
+ }
202
+ return counts;
203
+ }
204
+ function describeAscent(code, source, loop, constants) {
205
+ const subject = findAscendedBinding(code.slice(loop.start, loop.end));
206
+ if (subject === void 0) return void 0;
207
+ const scope = { bindings: listLoopBindings(code, source, loop, subject, constants), constants };
208
+ return { loop, probedNames: listProbedNames(code, source, loop, subject, scope) };
209
+ }
210
+ function expandPathParts(parts, scope, subject) {
211
+ return parts.flatMap((part) => {
212
+ if (part.kind === "text" || part.name === subject) return [part];
213
+ const constant = scope.constants.find((candidate) => candidate.name === part.name);
214
+ if (constant !== void 0) return [{ kind: "text", text: constant.value }];
215
+ return scope.bindings.find((candidate) => candidate.name === part.name)?.parts ?? [part];
216
+ });
217
+ }
218
+ function findAscendedBinding(region) {
219
+ const assignments = listSimpleAssignments(region);
220
+ for (const match of region.matchAll(DIRNAME_ASCENT)) {
221
+ const subject = match.groups?.["subject"];
222
+ const target = readAssignedTarget(region, match.index);
223
+ if (subject === void 0 || target === void 0) continue;
224
+ if (target === subject) return subject;
225
+ const isCarriedBack = assignments.some(
226
+ (assignment) => assignment.target === subject && assignment.value === target
227
+ );
228
+ if (isCarriedBack) return subject;
229
+ }
230
+ return void 0;
231
+ }
232
+ function findBodyStart(code, afterKeyword, isDoLoop) {
233
+ let index = afterKeyword;
234
+ if (!isDoLoop) {
235
+ const head = readBalancedGroup(code, index, PARENTHESES);
236
+ if (head === void 0) return void 0;
237
+ index = head.end;
238
+ }
239
+ while (index < code.length && WHITESPACE.test(code.charAt(index))) index += 1;
240
+ return code.charAt(index) === "{" ? index : void 0;
241
+ }
242
+ function findExpressionEnd(code, from, limit) {
243
+ let depth = 0;
244
+ for (let index = from; index < limit; index += 1) {
245
+ const character = code.charAt(index);
246
+ if (BRACKET_OPENERS.has(character)) depth += 1;
247
+ else if (BRACKET_CLOSERS.has(character)) {
248
+ if (depth === 0) return index;
249
+ depth -= 1;
250
+ } else if ((character === "," || character === ";") && depth === 0) return index;
251
+ }
252
+ return limit;
253
+ }
254
+ function isNested(inner, outer) {
255
+ return outer.start <= inner.start && inner.end <= outer.end;
256
+ }
257
+ function listLoopBindings(code, source, loop, subject, constants) {
258
+ const region = code.slice(loop.start, loop.end);
259
+ const declarationCounts = countMatchesByName(region, DECLARED_NAME);
260
+ const reassignmentCounts = countMatchesByName(region, REASSIGNMENT);
261
+ const bindings = [];
262
+ for (const match of region.matchAll(DECLARATION)) {
263
+ const name = match.groups?.["name"];
264
+ if (name === void 0 || declarationCounts.get(name) !== 1 || reassignmentCounts.has(name)) continue;
265
+ const valueStart = loop.start + match.index + match[0].length;
266
+ const parts = readPathParts(code, source, valueStart, findExpressionEnd(code, valueStart, loop.end));
267
+ if (parts === void 0) continue;
268
+ bindings.push({ name, parts: expandPathParts(parts, { bindings, constants }, subject) });
269
+ }
270
+ return bindings;
271
+ }
272
+ function listLoops(code) {
273
+ const loops = [];
274
+ for (const match of code.matchAll(LOOP_KEYWORD)) {
275
+ const bodyStart = findBodyStart(code, match.index + match[0].length, match.groups?.["keyword"] === "do");
276
+ const body = bodyStart === void 0 ? void 0 : readBalancedGroup(code, bodyStart, BRACES);
277
+ if (body !== void 0) loops.push({ end: body.end, start: match.index });
278
+ }
279
+ return loops;
280
+ }
281
+ function listProbedNames(code, source, loop, subject, scope) {
282
+ const names = [];
283
+ let isProbing = false;
284
+ for (const match of code.slice(loop.start, loop.end).matchAll(LEVEL_PROBE)) {
285
+ const argumentList = readBalancedGroup(code, loop.start + match.index + match[0].length - 1, PARENTHESES);
286
+ if (argumentList === void 0) continue;
287
+ const pathStart = argumentList.start + 1;
288
+ const parts = readPathParts(code, source, pathStart, findExpressionEnd(code, pathStart, argumentList.end - 1));
289
+ const expanded = parts === void 0 ? [] : expandPathParts(parts, scope, subject);
290
+ const subjectIndex = expanded.findIndex((part) => part.kind === "read" && part.name === subject);
291
+ if (subjectIndex === -1) continue;
292
+ isProbing = true;
293
+ const name = readProbedName(expanded.slice(subjectIndex + 1));
294
+ if (name !== void 0) names.push(name);
295
+ }
296
+ return isProbing ? names : void 0;
297
+ }
298
+ function listSimpleAssignments(region) {
299
+ const assignments = [];
300
+ for (const match of region.matchAll(SIMPLE_ASSIGNMENT)) {
301
+ const target = match.groups?.["target"];
302
+ const value = match.groups?.["value"];
303
+ if (target !== void 0 && value !== void 0) assignments.push({ target, value });
304
+ }
305
+ return assignments;
306
+ }
307
+ function listStringConstants(code, source) {
308
+ const constants = [];
309
+ const declarationCounts = countMatchesByName(code, DECLARED_NAME);
310
+ for (const match of code.matchAll(STRING_CONSTANT)) {
311
+ const name = match.groups?.["name"];
312
+ const value = readLiteral(source, match.indices?.groups?.["literal"]);
313
+ if (name === void 0 || value === void 0) continue;
314
+ if (declarationCounts.get(name) === 1) constants.push({ name, value });
315
+ }
316
+ return constants;
317
+ }
318
+ function readAssignedTarget(region, offset) {
319
+ const { before } = readAnchoredWindow(region, offset, ASSIGNMENT_WINDOW);
320
+ return ASSIGNED_TARGET.exec(before)?.groups?.["target"];
321
+ }
322
+ function readPathParts(code, source, start, end) {
323
+ const parts = [];
324
+ let resumeAt = start;
325
+ for (const match of code.slice(start, end).matchAll(PATH_TOKEN)) {
326
+ const offset = start + match.index;
327
+ if (offset < resumeAt) continue;
328
+ const name = match.groups?.["name"];
329
+ const quoted = match.groups?.["quoted"];
330
+ if (name !== void 0) {
331
+ parts.push({ kind: "read", name });
332
+ } else if (quoted !== void 0) {
333
+ parts.push({ kind: "text", text: source.slice(offset + 1, offset + quoted.length - 1) });
334
+ } else {
335
+ const template = readTemplateParts(code, source, offset, end);
336
+ if (template === void 0) return void 0;
337
+ parts.push(...template.parts);
338
+ resumeAt = template.end;
339
+ }
340
+ }
341
+ return parts;
342
+ }
343
+ function readProbedName(parts) {
344
+ const segments = [];
345
+ for (const part of parts) {
346
+ if (part.kind === "read") return void 0;
347
+ if (part.text !== "") segments.push(part.text);
348
+ }
349
+ const name = segments.join("/").replaceAll(SEPARATOR_RUN, "/").replace(LEADING_SEPARATOR, "");
350
+ return name === "" ? void 0 : name;
351
+ }
352
+ function readTemplateParts(code, source, open, end) {
353
+ const parts = [];
354
+ let textStart = open + 1;
355
+ for (; ; ) {
356
+ const close = code.indexOf("`", textStart);
357
+ if (close === -1 || close >= end) return void 0;
358
+ const interpolation = code.indexOf("${", textStart);
359
+ if (interpolation === -1 || interpolation > close) {
360
+ parts.push({ kind: "text", text: source.slice(textStart, close) });
361
+ return { end: close + 1, parts };
362
+ }
363
+ parts.push({ kind: "text", text: source.slice(textStart, interpolation) });
364
+ const group = readBalancedGroup(code, interpolation + 1, BRACES);
365
+ if (group === void 0 || group.end > end) return void 0;
366
+ const interpolated = readPathParts(code, source, group.start + 1, group.end - 1);
367
+ if (interpolated === void 0) return void 0;
368
+ parts.push(...interpolated);
369
+ textStart = group.end;
370
+ }
371
+ }
372
+
373
+ // ../adoption/src/mod.ts
374
+ import { blankNonCode, getLineAtOffset as getLineAtOffset2 } from "readyup/check-utils";
375
+
376
+ // src/readiness/adoptedExports.ts
377
+ var ADOPTED_EXPORTS = ["findPackageRoot", "findProjectRoot", "resolveSelfVersion"];
378
+
379
+ // src/readiness/listManifestSearchSites.ts
380
+ function listManifestSearchSites(source) {
381
+ return listDirectoryAscents(blankNonCode(source), source).filter(({ probedNames }) => probedNames !== void 0 && isManifestSearch(probedNames)).map(({ line }) => ({ kind: "manifest-search", line }));
382
+ }
383
+
384
+ // .readyup/kits/default.ts
385
+ var FILESYSTEM_PACKAGE_NAME = "@williamthorsen/toolbelt.filesystem";
386
+ var PACKAGE_NAME = "@williamthorsen/toolbelt.packaging";
387
+ var README_URL = "https://github.com/williamthorsen/toolbelt/tree/main/packages/packaging#readme";
388
+ var default_default = defineAdoptionKit({
389
+ description: `Adoption checks for a project consuming ${PACKAGE_NAME}`,
390
+ detect: listManifestSearchSites,
391
+ exportNames: ADOPTED_EXPORTS,
392
+ noSourcesReason: "the project holds no JavaScript or TypeScript sources outside the exempt paths",
393
+ packageName: PACKAGE_NAME,
394
+ // A test writes this walk deliberately, and a bootstrap wrapper hand-rolls what it reaches for so that its
395
+ // build-first message survives an incomplete install.
396
+ pathFilter: isAdoptableSource,
397
+ checks: [
398
+ {
399
+ name: "No source searches the directory chain for package.json by hand",
400
+ id: "no-hand-rolled-manifest-search",
401
+ kinds: ["manifest-search"],
402
+ severity: "recommend",
403
+ fix: `Replace the loop named above with the function that matches what the loop looks for. Where it finds the package that owns the running module, call findPackageRoot(import.meta.url) from ${PACKAGE_NAME}/candidate, or resolveSelfVersion(import.meta.url) from the same subpath where the loop goes on to read the manifest's version. Both pass over a manifest that declares no name, such as the one that a dual-format build leaves in dist/, and both throw where no ancestor declares one. Where it finds the project that holds a directory, call findProjectRoot(dir) from ${PACKAGE_NAME}. It prefers .git and lockfiles to package.json, so in a monorepo it returns the repository root rather than the nearest package, and it returns the start directory rather than throwing where it finds neither. Where it needs the nearest manifest whatever that manifest declares, call findDirectoryChainMatch(dir, ['package.json']) from ${FILESYSTEM_PACKAGE_NAME}, since no function in this package returns it. Reference: ${README_URL}`
404
+ }
405
+ ]
406
+ });
407
+ export {
408
+ default_default as default
409
+ };
@@ -0,0 +1,90 @@
1
+ {
2
+ "version": 1,
3
+ "kits": [
4
+ {
5
+ "checklists": [
6
+ "adoption"
7
+ ],
8
+ "description": "Adoption checks for a project consuming @williamthorsen/toolbelt.packaging",
9
+ "esbuildVersion": "0.28.2",
10
+ "inputs": [
11
+ {
12
+ "hash": "1dc83619",
13
+ "kind": "module",
14
+ "path": "../../adoption/src/conventions/path-predicates.ts"
15
+ },
16
+ {
17
+ "hash": "0237a871",
18
+ "kind": "module",
19
+ "path": "../../adoption/src/conventions/site-handoffs.ts"
20
+ },
21
+ {
22
+ "hash": "8fb83c2d",
23
+ "kind": "module",
24
+ "path": "../../adoption/src/kits/defineAdoptionKit.ts"
25
+ },
26
+ {
27
+ "hash": "10596562",
28
+ "kind": "module",
29
+ "path": "../../adoption/src/mod.ts"
30
+ },
31
+ {
32
+ "hash": "6fdaacac",
33
+ "kind": "module",
34
+ "path": "../../adoption/src/portable/condenseWhitespace.ts"
35
+ },
36
+ {
37
+ "hash": "0661f0dd",
38
+ "kind": "module",
39
+ "path": "../../adoption/src/portable/listDirectoryAscents.ts"
40
+ },
41
+ {
42
+ "hash": "07c8358f",
43
+ "kind": "module",
44
+ "path": "../../adoption/src/portable/listFunctionBodies.ts"
45
+ },
46
+ {
47
+ "hash": "2d9f1edb",
48
+ "kind": "module",
49
+ "path": "../../adoption/src/portable/listTemplateLiterals.ts"
50
+ },
51
+ {
52
+ "hash": "b0751395",
53
+ "kind": "module",
54
+ "path": "../../adoption/src/portable/readAnchoredWindow.ts"
55
+ },
56
+ {
57
+ "hash": "0eb1daf1",
58
+ "kind": "module",
59
+ "path": "../../adoption/src/portable/readBalancedGroup.ts"
60
+ },
61
+ {
62
+ "hash": "e9427d50",
63
+ "kind": "module",
64
+ "path": "../../adoption/src/portable/readLiteral.ts"
65
+ },
66
+ {
67
+ "hash": "716f73e7",
68
+ "kind": "module",
69
+ "path": "kits/default.ts"
70
+ },
71
+ {
72
+ "hash": "6ddc3be2",
73
+ "kind": "module",
74
+ "path": "../src/readiness/adoptedExports.ts"
75
+ },
76
+ {
77
+ "hash": "33959e51",
78
+ "kind": "module",
79
+ "path": "../src/readiness/listManifestSearchSites.ts"
80
+ }
81
+ ],
82
+ "name": "default",
83
+ "path": "kits/default.js",
84
+ "readyupVersion": "0.36.0",
85
+ "source": "kits/default.ts",
86
+ "sourceHash": "716f73e7",
87
+ "targetHash": "40c1567e"
88
+ }
89
+ ]
90
+ }
package/CHANGELOG.md CHANGED
@@ -2,9 +2,56 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## 0.6.0 — 2026-09-15
6
+
7
+ ### 🎉 Features
8
+
9
+ - 🚨 **Breaking:** Move createTempTree from toolbelt.filesystem to toolbelt.testing (#313)
10
+
11
+ - Moves `CreateTempTreeOptions` and the `TempTree` handle to `@williamthorsen/toolbelt.testing/candidate` along with `createTempTree`.
12
+
13
+ Migration: Import `createTempTree`, `CreateTempTreeOptions`, and `TempTree` from `@williamthorsen/toolbelt.testing/candidate`, and declare `@williamthorsen/toolbelt.testing` in the manifest that declared `@williamthorsen/toolbelt.filesystem` for them.
14
+
15
+ - Add a ReadyUp adoption kit reporting hand-rolled package.json searches (#322)
16
+
17
+ - Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.packaging` that recommends `findPackageRoot`, `resolveSelfVersion`, or `findProjectRoot` in place of a hand-rolled loop checking each ancestor directory for `package.json`.
18
+
19
+ - Read a directory walk's probed name through a binding or constant (#324)
20
+
21
+ - Extends the ReadyUp adoption kit in `@williamthorsen/toolbelt.packaging` to recommend `findPackageRoot` or `resolveSelfVersion` for a hand-rolled `package.json` search that checks for the file through a variable declared once inside its loop and never reassigned there, or through a string constant declared once in the same file.
22
+ - Stops the kit in `@williamthorsen/toolbelt.filesystem` from reporting such a search, which it previously treated as a generic directory walk.
23
+
24
+ - Report hand-rolled dedents in the strings adoption kit (#330)
25
+
26
+ - Adds `no-joined-line-array`, which reports an array of string or template literals that spans several lines and is joined with a newline.
27
+ - Adds `no-layout-breaking-template`, which reports an untagged template literal whose later lines drop below the indentation of the line on which it opens.
28
+
29
+ ### 🧪 Tests
30
+
31
+ - Move the rdy run report reader into the adoption test utilities (#323)
32
+
33
+ - Replaces the `rdy run --json` report reader copied into each of the twelve `pragma-suppression.tool.test.ts` suites with `listKitCheckReports`, a helper added to `@williamthorsen/toolbelt.adoption/test-utils` that runs a package's compiled kit over a fixture repo and returns its check reports, so a change to the shape of readyup's report needs one edit rather than twelve.
34
+ - Fixes the error thrown for a kit that does not load: Each copy discarded the load error recorded by `rdy` on the kit's entry and threw "the run reported no adoption checks", and the helper throws with `rdy`'s own message instead.
35
+
36
+ ### ⚙️ Tooling
37
+
38
+ - Remove the stale repo-local cliff.toml and normalize changelog titles (#327)
39
+
40
+ - Stops `release-kit prepare` from printing a "skipped due to grouping error(s)" warning for each releasable workspace by letting it resolve the git-cliff template bundled with release-kit, previously overridden by the root `cliff.toml`.
41
+ - Excludes commits without a ticket prefix from future changelog entries.
42
+ - Renames the section titles in every `packages/*/.meta/changelog.json`, except `Dependency updates`, to the headings of release-kit's work-type taxonomy, such as "🎉 Features" and "🏗️ Internal features", and regenerates each `CHANGELOG.md` so that release-kit orders existing and new sections by the same rule.
43
+ - Causes the next `release-kit prepare` to plan patch releases of `dstructs`, `hof`, and `sets`, which had no other commits since their last release, because the changelog commit touches every workspace.
44
+
45
+ ### 📚 Documentation
46
+
47
+ - Align prose with plain-speech doctrine and writing conventions (#306)
48
+
49
+ - Copy-edits prose across the repo: comments, test names, package READMEs, and `AGENTS.md`.
50
+ - Rewrites a few user-facing strings as well, among them `configure-project`'s help text and the errors from `parseProjectSpec`, `securityCommands`, and `hashString`.
51
+
5
52
  ## 0.5.5 — 2026-09-06
6
53
 
7
- ### Documentation
54
+ ### 📚 Documentation
8
55
 
9
56
  - Repair reduced object relatives in passages recurring across files (#262)
10
57
 
@@ -44,7 +91,7 @@ All notable changes to this project will be documented in this file.
44
91
 
45
92
  ## 0.5.0 — 2026-08-16
46
93
 
47
- ### Features
94
+ ### 🎉 Features
48
95
 
49
96
  - Add `pointCwdAt`, a scope-bound cwd pointer (#178)
50
97
 
@@ -54,7 +101,7 @@ All notable changes to this project will be documented in this file.
54
101
 
55
102
  ## 0.4.0 — 2026-08-15
56
103
 
57
- ### Features
104
+ ### 🎉 Features
58
105
 
59
106
  - 🚨 **Breaking:** Promote createTempTree to the candidate tier with a caller-chosen prefix and binary entries (#148)
60
107
 
@@ -64,7 +111,7 @@ All notable changes to this project will be documented in this file.
64
111
 
65
112
  ## 0.3.1 — 2026-08-13
66
113
 
67
- ### Tooling
114
+ ### ⚙️ Tooling
68
115
 
69
116
  - Remove redundant .gitignore files
70
117
  - Populate manifest metadata and adopt a pnpm catalog (#140)
@@ -73,13 +120,13 @@ All notable changes to this project will be documented in this file.
73
120
 
74
121
  ## 0.3.0 — 2026-08-12
75
122
 
76
- ### Features
123
+ ### 🎉 Features
77
124
 
78
125
  - 🚨 **Breaking:** Rename get* functions by return kind and verb specificity (#119)
79
126
 
80
127
  Renames thirteen functions across various packages to align with a consistent naming pattern.
81
128
 
82
- ### Refactoring
129
+ ### ♻️ Refactoring
83
130
 
84
131
  - Align stray modules with layout and TypeScript conventions (#118)
85
132
 
@@ -87,7 +134,7 @@ All notable changes to this project will be documented in this file.
87
134
 
88
135
  ## 0.2.0 — 2026-08-08
89
136
 
90
- ### Features
137
+ ### 🎉 Features
91
138
 
92
139
  - Scaffold toolbelt.packaging for project-layout utilities (#99)
93
140
 
@@ -99,7 +146,7 @@ All notable changes to this project will be documented in this file.
99
146
 
100
147
  `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.
101
148
 
102
- ### Tooling
149
+ ### ⚙️ Tooling
103
150
 
104
151
  - Use identical compiler settings for all packages (#105)
105
152
 
package/README.md CHANGED
@@ -1,8 +1,34 @@
1
+ <!-- readme-type: library -->
2
+
1
3
  # @williamthorsen/toolbelt.packaging
2
4
 
3
5
  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
6
 
5
- <!-- section:release-notes --><!-- /section:release-notes -->
7
+ <!-- section:release-notes -->
8
+ ## Release notes — v0.6.0 (2026-09-15)
9
+
10
+ ### 🎉 Features
11
+
12
+ - 🚨 **Breaking:** Move createTempTree from toolbelt.filesystem to toolbelt.testing (#313)
13
+
14
+ - Moves `CreateTempTreeOptions` and the `TempTree` handle to `@williamthorsen/toolbelt.testing/candidate` along with `createTempTree`.
15
+
16
+ Migration: Import `createTempTree`, `CreateTempTreeOptions`, and `TempTree` from `@williamthorsen/toolbelt.testing/candidate`, and declare `@williamthorsen/toolbelt.testing` in the manifest that declared `@williamthorsen/toolbelt.filesystem` for them.
17
+
18
+ - Add a ReadyUp adoption kit reporting hand-rolled package.json searches (#322)
19
+
20
+ - Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.packaging` that recommends `findPackageRoot`, `resolveSelfVersion`, or `findProjectRoot` in place of a hand-rolled loop checking each ancestor directory for `package.json`.
21
+
22
+ - Read a directory walk's probed name through a binding or constant (#324)
23
+
24
+ - Extends the ReadyUp adoption kit in `@williamthorsen/toolbelt.packaging` to recommend `findPackageRoot` or `resolveSelfVersion` for a hand-rolled `package.json` search that checks for the file through a variable declared once inside its loop and never reassigned there, or through a string constant declared once in the same file.
25
+ - Stops the kit in `@williamthorsen/toolbelt.filesystem` from reporting such a search, which it previously treated as a generic directory walk.
26
+
27
+ - Report hand-rolled dedents in the strings adoption kit (#330)
28
+
29
+ - Adds `no-joined-line-array`, which reports an array of string or template literals that spans several lines and is joined with a newline.
30
+ - Adds `no-layout-breaking-template`, which reports an untagged template literal whose later lines drop below the indentation of the line on which it opens.
31
+ <!-- /section:release-notes -->
6
32
 
7
33
  ## Installation
8
34
 
@@ -20,7 +46,7 @@ Every export reaches the filesystem through `node:` builtins, so they run under
20
46
  findProjectRoot(startDir: string, options?: { markers?: ReadonlyArray<string> }): ProjectRoot;
21
47
  ```
22
48
 
23
- 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:
49
+ Resolves `startDir` to an absolute path, ascends from it, and returns the first directory that contains a root marker, along with the evidence that identified it:
24
50
 
25
51
  ```ts
26
52
  interface ProjectRoot {
@@ -30,7 +56,7 @@ interface ProjectRoot {
30
56
  }
31
57
  ```
32
58
 
33
- `DEFAULT_ROOT_MARKERS` is consulted in order, so the earliest entry wins when one directory carries several:
59
+ `DEFAULT_ROOT_MARKERS` is consulted in order, so the earliest entry wins when one directory contains several:
34
60
 
35
61
  1. `.git`, matching either a directory (an ordinary clone) or a file (a worktree or submodule);
36
62
  2. `pnpm-workspace.yaml`;
@@ -47,9 +73,9 @@ import { DEFAULT_ROOT_MARKERS, findProjectRoot } from '@williamthorsen/toolbelt.
47
73
  findProjectRoot(process.cwd(), { markers: [...DEFAULT_ROOT_MARKERS, 'deno.json'] });
48
74
  ```
49
75
 
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.
76
+ 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
77
 
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:
78
+ When no directory up to and including the filesystem root contains a marker, the result falls back in this order, reporting a `null` marker either way:
53
79
 
54
80
  1. the nearest ancestor holding a `package.json`, reported as `source: 'package-json'`;
55
81
  2. `startDir` itself, reported as `source: 'start-dir'`.
@@ -60,7 +86,7 @@ A project root is not a package root: This answers "which checkout am I in", whe
60
86
 
61
87
  ## `findPackageRoot`
62
88
 
63
- Candidate tier: imported from `@williamthorsen/toolbelt.packaging/candidate` rather than the package root, and subject to change.
89
+ Candidate tier: Imported from `@williamthorsen/toolbelt.packaging/candidate` rather than the package root, and subject to change.
64
90
 
65
91
  ```ts
66
92
  findPackageRoot(fromUrl: string): string;
@@ -78,7 +104,7 @@ const templatesDir = path.join(findPackageRoot(import.meta.url), 'templates');
78
104
 
79
105
  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
106
 
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:
107
+ The owning package is the nearest ancestor whose `package.json` declares a `name`. That rule distinguishes this from `findPackageJSON` in `node:module`, which answers the different question of which manifest _governs_ a file:
82
108
 
83
109
  ```jsonc
84
110
  // dist/cjs/package.json: a marker manifest, declaring no name
@@ -91,7 +117,7 @@ A module belonging to no named package throws, rather than falling back to a dir
91
117
 
92
118
  ## `resolveSelfVersion`
93
119
 
94
- Candidate tier: imported from `@williamthorsen/toolbelt.packaging/candidate` rather than the package root, and subject to change.
120
+ Candidate tier: Imported from `@williamthorsen/toolbelt.packaging/candidate` rather than the package root, and subject to change.
95
121
 
96
122
  ```ts
97
123
  resolveSelfVersion(fromUrl: string): string;
@@ -108,3 +134,38 @@ console.log(`my-cli ${resolveSelfVersion(import.meta.url)}`);
108
134
  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.
109
135
 
110
136
  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.
137
+
138
+ ## Adoption checks
139
+
140
+ The package ships a ReadyUp kit, so a project that installs it can ask how far its adoption got:
141
+
142
+ ```sh
143
+ rdy run --packages
144
+ ```
145
+
146
+ The kit reads the project's tracked sources and reports one idiom, counted against the calls that the project already makes into this package. It reports at `recommend`: A hand-rolled search is correct code that a published function expresses better, not a defect.
147
+
148
+ `no-hand-rolled-manifest-search` reports a loop that ascends by `dirname` and probes each level for `package.json`, naming the line on which the loop opens. The scan reads which names a loop probes, but not where the loop starts or what it does with the manifest, so the fix text sets out the choice by purpose. The package that owns the running module takes [`findPackageRoot`](#findpackageroot), or [`resolveSelfVersion`](#resolveselfversion) where the loop goes on to read the manifest's version; both pass over a manifest that declares no name. The project that holds a directory takes [`findProjectRoot`](#findprojectroot), which prefers `.git` and lockfiles to a manifest and so returns the repository root in a monorepo. The nearest manifest, whatever it declares, takes `findDirectoryChainMatch` from `@williamthorsen/toolbelt.filesystem`.
149
+
150
+ Every other walk up the directory chain belongs to [`@williamthorsen/toolbelt.filesystem`](https://github.com/williamthorsen/toolbelt/tree/main/packages/filesystem#adoption-checks), whose own kit reports it: a loop probing for root markers alone, such as `.git`; a loop probing for a manifest below the level, such as `node_modules/x/package.json`; and a loop that probes nothing. Reporting one here as well would show one loop twice under conflicting advice. A read of `package.json` outside any loop, and a loop over the directories listed by `listDirectoryChain`, ascend nothing by hand, and neither kit reports them.
151
+
152
+ The detector under-matches by design. A recursive walk-up function is no loop, an ascent written as `path.resolve(dir, '..')` carries a different anchor, and a loop whose body is a single unbraced statement goes unread, and neither kit reports any of the three. A probe for `package.json` made through a helper, through a constant imported from another module, or through a binding declared outside the loop names no manifest that the scan can read, and neither does a path holding another binding past the level, as `${dir}/${name}/package.json` does. `toolbelt.filesystem` reports each loop probing in one of these ways as a walk instead.
153
+
154
+ Bootstrap wrappers under `bin/` are exempt: Such a wrapper imports only builtins so its build-first message survives an incomplete install, and importing this package there would replace that message with a module-resolution failure. Tests are exempt too, since they write this walk deliberately. A source declared generated or vendored by the project in its own `.gitattributes`, under `linguist-generated` or `linguist-vendored`, is exempt as well: The sweep drops it before the kit sees it, so committed bundler output yields no advice that anyone could act on. The sweep is readyup's, so this holds on readyup 0.35.0 or later.
155
+
156
+ A reviewed site is silenced by an `rdy-ignore` pragma on its own line, or `rdy-ignore-next-line` on the line above. A pragma naming a check's id suppresses that check alone; with no id it covers every check on the line. A failed check prints its id ahead of its fraction, which is the form to write:
157
+
158
+ ```ts
159
+ // rdy-ignore-next-line toolbelt.packaging/no-hand-rolled-manifest-search -- runs before dependencies are installed
160
+ while (!fs.existsSync(path.join(dir, 'package.json'))) {
161
+ dir = path.dirname(dir);
162
+ }
163
+ ```
164
+
165
+ Add the package to `.config/readyup.config.ts` to include it in a routine sweep:
166
+
167
+ ```ts
168
+ export default defineRdyConfig({
169
+ packages: ['@williamthorsen/toolbelt.packaging'],
170
+ });
171
+ ```
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Names that identify a project root, in precedence order: When a directory carries more than one,
2
+ * Names that identify a project root, in precedence order: When a directory contains more than one,
3
3
  * the earliest in this list is the one reported.
4
4
  *
5
5
  * `.git` matches whether it is a directory (an ordinary clone) or a file (a worktree or submodule).
@@ -11,8 +11,8 @@ export declare const DEFAULT_ROOT_MARKERS: ReadonlyArray<string>;
11
11
  /**
12
12
  * Returns the project root at or above `startDir`, along with the evidence that identified it.
13
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
14
+ * Ascends from `startDir` (resolved to an absolute path) and returns the first directory that contains one of
15
+ * `markers`. If no directory up to and including the filesystem root contains one, falls back to the nearest
16
16
  * ancestor holding a `package.json`, then to `startDir` itself; both fallbacks report a `null` marker.
17
17
  *
18
18
  * @example
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@williamthorsen/toolbelt.packaging",
3
- "version": "0.5.5",
3
+ "version": "0.6.0",
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",
@@ -39,14 +39,19 @@
39
39
  }
40
40
  },
41
41
  "files": [
42
+ ".readyup/kits/*.js",
43
+ ".readyup/manifest.json",
42
44
  "dist/*",
43
45
  "CHANGELOG.md"
44
46
  ],
45
47
  "dependencies": {
46
- "@williamthorsen/toolbelt.filesystem": "0.8.3"
48
+ "@williamthorsen/toolbelt.filesystem": "0.9.0"
47
49
  },
48
50
  "devDependencies": {
49
- "@williamthorsen/toolbelt.testing": "0.5.1"
51
+ "@williamthorsen/toolbelt.adoption": "0.1.0",
52
+ "@williamthorsen/toolbelt.testing": "0.6.0",
53
+ "esbuild": "0.28.2",
54
+ "readyup": "0.36.0"
50
55
  },
51
56
  "engines": {
52
57
  "node": ">=24.0.0"