@orkestrel/scaffold 0.0.134 → 0.0.136
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/dist/agents/skills/orkestrel-parallel/scripts/lane.js +777 -83
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +327 -21
- package/dist/bin/main.js +254 -36
- package/dist/bin/main.js.map +1 -1
- package/dist/host/AGENTS.md +2 -2
- package/dist/host/agents/orchestration.md +2 -2
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +983 -123
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -5
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +403 -32
- package/dist/host/claude/agents/orkestrel.md +17 -17
- package/dist/host/claude/agents/reviewer.md +1 -1
- package/dist/host/claude/rules/architecture.md +1 -1
- package/dist/host/claude/rules/documentation.md +1 -1
- package/dist/host/claude/rules/patterns.md +4 -2
- package/dist/host/claude/rules/workspace.md +73 -67
- package/dist/host/configs/helpers.ts +109 -73
- package/dist/host/dotfiles/oxlintrc.json +1 -57
- package/dist/host/guides/agent.md +989 -395
- package/dist/host/guides/contract.md +198 -163
- package/dist/host/guides/database.md +978 -503
- package/dist/host/guides/indexeddb.md +80 -66
- package/dist/host/guides/middleware.md +5 -5
- package/dist/host/guides/ollama.md +41 -42
- package/dist/host/guides/relation.md +56 -32
- package/dist/host/guides/scaffold.md +185 -107
- package/dist/host/guides/sqlite.md +44 -23
- package/dist/host/guides/study.md +12 -12
- package/dist/host/guides/test.md +163 -47
- package/dist/host/guides/toolbox.md +127 -81
- package/dist/host/guides/workspace.md +21 -14
- package/dist/host/manifest.json +30 -30
- package/dist/host/scripts/browsers.sh +0 -0
- package/dist/host/scripts/codex.sh +0 -0
- package/dist/host/scripts/cursor.sh +0 -0
- package/dist/host/scripts/deps.sh +0 -0
- package/dist/host/scripts/npm.sh +0 -0
- package/dist/host/scripts/ollama.sh +0 -0
- package/dist/host/tests/config.test.ts +237 -115
- package/dist/src/core/index.cjs +591 -218
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +248 -29
- package/dist/src/core/index.d.ts +248 -29
- package/dist/src/core/index.js +581 -216
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +18 -8
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +4 -3
- package/dist/src/server/index.d.ts +4 -3
- package/dist/src/server/index.js +19 -9
- package/dist/src/server/index.js.map +1 -1
- package/package.json +3 -3
|
@@ -29,6 +29,7 @@ When a consumer needs a dependency's unpublished source, to meet a defect that l
|
|
|
29
29
|
- A runtime `dependencies` bump reaches every consumer: each package downstream re-pins, re-runs its gates, bumps, and republishes in layer order.
|
|
30
30
|
- A development `devDependencies` bump reaches nobody: re-pin, prove the gates green, commit to `main`; do not bump or publish.
|
|
31
31
|
- A development bump that moves the published artifact is a runtime bump. Prove the direction with the build: rebuild after the re-pin and run `node .agents/skills/orkestrel-publish/scripts/compare.ts`, which compares `dist/` against the published tarball on material content only. Exit 3 bumps and publishes that package, and its dependents follow the runtime rule.
|
|
32
|
+
- A change that moves only comments, TSDoc, or a guide owes no release of its own, even when `compare.ts` exits 3. It ships with the package's next release that another change owes. Scaffold's vendored files follow § The scaffold surface instead.
|
|
32
33
|
- A `0.0.x` caret pins one exact release, so the fleet publishes in topological layer order derived from runtime `dependencies` and `peerDependencies` edges, never from a development edge.
|
|
33
34
|
- Read each package's version and layer from the catalog table in `.claude/agents/orkestrel.md`, refreshed per [wave.md](wave.md) § Prepare a layer before sequencing a cascade. Never write a second order elsewhere.
|
|
34
35
|
|
|
@@ -16,22 +16,39 @@ overwrite receipts are written only where the work tree ignores `tmp/`.
|
|
|
16
16
|
1. Re-pin every `dependencies` and `devDependencies` range the audit's release readings name to
|
|
17
17
|
the caret of its returned release, and install before the overwrite. Keep a published
|
|
18
18
|
`peerDependencies` range at the floor the release needs: raise it only when its floor fails the
|
|
19
|
-
release.
|
|
20
|
-
|
|
19
|
+
release. The floor fails when the declared range excludes the version the registry serves. Raise
|
|
20
|
+
it to the caret of that version, and leave a range the served version satisfies as declared. Read an
|
|
21
|
+
exact version, a caret, a tilde, and `||` arms of those; leave any other form as declared. Name
|
|
22
|
+
each peer raised or kept in the rewrite row, with the reason it was kept. Read the audit
|
|
23
|
+
population as the declared `@orkestrel`
|
|
21
24
|
dependencies in `dependencies` and `devDependencies`, plus declared foreign tools that the
|
|
22
25
|
blueprint plans in those sections; exclude the fixed showcase tool pair from ordinary release lookups.
|
|
23
26
|
Look up fleet releases with `*`; look up foreign tools with
|
|
24
27
|
a caret over the declared major when one can be extracted, otherwise with the declared range.
|
|
25
28
|
Do not treat a declared minor or patch bound as the lookup bound. A lookup skips a deprecated
|
|
26
|
-
version, and skips a version above `latest` when the range is `*` or sits in `latest`'s major.
|
|
29
|
+
version, and skips a version above `latest` when the range is `*` or sits in `latest`'s major.
|
|
30
|
+
A peer declared also as a dependency takes that dependency's reading. Peer-only dependencies
|
|
31
|
+
produce no audit reading, so the visit looks each one up with `npm view` under the same bounds:
|
|
32
|
+
a fleet package with `*`, and a foreign tool with a caret over its declared major, or with its
|
|
33
|
+
declared range when its arms span several majors. A peer-only reading moves `peerDependencies`
|
|
34
|
+
ranges alone and never a dependency range the audit did not read. When a lookup exits non-zero,
|
|
35
|
+
stop the step before the rewrite and the install. When a lookup exits 0 and serves no eligible
|
|
36
|
+
release, keep the peer and name it `no eligible release`. Offline, look up nothing and keep each
|
|
37
|
+
peer-only dependency as `no release reading`. When more than one arm of a peer range sits in the
|
|
38
|
+
release's major, keep the peer and name it `several arms in the major of` the release. A peer
|
|
39
|
+
whose arms span several majors and that no dependency reading names never rises, because its
|
|
40
|
+
own range bounds its lookup and admits every release the lookup serves.
|
|
27
41
|
For example, with a peer `vite: ^8.3.7` and a development `vite: ^8.3.7` whose registry serves
|
|
28
|
-
`8.3.8`, apply `vite: ^8.3.7 -> ^8.3.8` to the development range and leave the peer at `^8.3.7
|
|
42
|
+
`8.3.8`, apply `vite: ^8.3.7 -> ^8.3.8` to the development range and leave the peer at `^8.3.7`,
|
|
43
|
+
which admits `8.3.8`; with a peer `@orkestrel/database: ^0.0.23` whose registry serves `0.0.24`,
|
|
44
|
+
apply `^0.0.23 -> ^0.0.24` to the peer, because a `0.0.x` caret admits one release;
|
|
29
45
|
with a planned tool whose registry serves `8.3.4`, apply `vite: ~8.2.0 -> ^8.3.4` even though
|
|
30
46
|
the tilde excludes `8.3.4`.
|
|
31
47
|
Keep this pin step within each declared major; step 5 states the overwrite's lift.
|
|
32
48
|
A range joined by `||` names one supported major per
|
|
33
49
|
arm, so move only the arm in the release's major and keep every other arm: with
|
|
34
|
-
`vitest: ^4.1.11 || ^5.0.5` and a registry serving `4.1.12`, apply `^4.1.12 || ^5.0.5
|
|
50
|
+
`vitest: ^4.1.11 || ^5.0.5` and a registry serving `4.1.12`, apply `^4.1.12 || ^5.0.5` to a
|
|
51
|
+
dependency range; a peer `~4.1.11 || ^5.0.5` against `4.2.0` rises to `^4.2.0 || ^5.0.5`.
|
|
35
52
|
For a workspace whose selected framework activates a
|
|
36
53
|
`TOOLCHAIN_HOLDS` row, keep the tool within that range's major; read the audit question for its reason. Prove
|
|
37
54
|
that framework on the later major before lifting its hold.
|
|
@@ -3,10 +3,14 @@
|
|
|
3
3
|
// node .agents/skills/orkestrel-publish/scripts/wave.ts --plan [--catalog PATH] [--json]
|
|
4
4
|
// --visit runs the visit `wave.md` § Visit a repository fixes, in order, stopping at the first step
|
|
5
5
|
// that fails: pin (read `scaffold audit --json`, whose drift exit is the reading the pin closes, then
|
|
6
|
-
// re-pin every `dependencies` and `devDependencies` range the audit release readings name to the registry caret
|
|
7
|
-
//
|
|
8
|
-
//
|
|
9
|
-
//
|
|
6
|
+
// re-pin every `dependencies` and `devDependencies` range the audit release readings name to the registry caret,
|
|
7
|
+
// look up each peer-only dependency with `npm view` as the audit bounds a dependency, stopping when a lookup
|
|
8
|
+
// exits non-zero, raise a `peerDependencies` range from its reading, never a dependency range from a peer-only
|
|
9
|
+
// reading, to the caret of its served version only when the declared exact, caret, tilde, or `||` range excludes
|
|
10
|
+
// that version, moving the one arm in the release's major, keep every other peer as declared, including one with
|
|
11
|
+
// several arms in that major, no eligible release, or no reading offline, and one spanning several majors whose
|
|
12
|
+
// lookup bound is its own range and never rises, name each peer raised or kept in the rewrite row, and install),
|
|
13
|
+
// commit (`git commit --only` of
|
|
10
14
|
// the manifest and lockfile as the preparation commit), overwrite (`scaffold overwrite --json`, then
|
|
11
15
|
// `scaffold audit` exiting 0; offline, an exit of 1 whose note names the skipped catalog step is
|
|
12
16
|
// accepted; on @orkestrel/scaffold itself both are skipped with a note, because the vendored host
|
|
@@ -226,12 +230,38 @@ export interface RangeMove {
|
|
|
226
230
|
readonly moved: readonly string[]
|
|
227
231
|
}
|
|
228
232
|
|
|
229
|
-
/** Describes a manifest re-pin: the ranges it moved and the
|
|
233
|
+
/** Describes a manifest re-pin: the ranges it moved, raised peers included, and the peers it kept. */
|
|
230
234
|
export interface Rewrite {
|
|
231
235
|
readonly moved: readonly string[]
|
|
232
236
|
readonly kept: readonly string[]
|
|
233
237
|
}
|
|
234
238
|
|
|
239
|
+
/** Describes one manifest field after a re-pin: its moves and the peer messages it kept. */
|
|
240
|
+
export interface FieldMove {
|
|
241
|
+
readonly field: string
|
|
242
|
+
readonly moves: RangeMove
|
|
243
|
+
readonly kept: readonly string[]
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
/** Describes the versions one `||` arm of a range admits, from `floor` up to but excluding `ceiling`. */
|
|
247
|
+
export interface RangeArm {
|
|
248
|
+
readonly floor: readonly [number, number, number]
|
|
249
|
+
readonly ceiling: readonly [number, number, number]
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/** Describes the decision on one peer range: the range after it, its rewrite message, and whether it rose. */
|
|
253
|
+
export interface PeerMove {
|
|
254
|
+
readonly range: string
|
|
255
|
+
readonly message: string
|
|
256
|
+
readonly raised: boolean
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
/** Describes the registry lookup a peer-only dependency needs: its name and the lookup bound. */
|
|
260
|
+
export interface PeerLookup {
|
|
261
|
+
readonly name: string
|
|
262
|
+
readonly bound: string
|
|
263
|
+
}
|
|
264
|
+
|
|
235
265
|
/** Describes the bump ruling a visit reaches. */
|
|
236
266
|
export interface Ruling {
|
|
237
267
|
readonly distMoved: boolean | undefined
|
|
@@ -958,7 +988,8 @@ export function refuseLocalSpecs(runner: Runner, step: string): boolean {
|
|
|
958
988
|
*
|
|
959
989
|
* @param runner - The visit's state.
|
|
960
990
|
* @returns The first refusal, or undefined when the lock is tracked and clean, the manifest holds no
|
|
961
|
-
* local spec or workspace, `tmp
|
|
991
|
+
* local spec or workspace, `tmp/units/wave` crosses no link inside the target, `tmp/` is ignored,
|
|
992
|
+
* and the target is its work tree's root.
|
|
962
993
|
*/
|
|
963
994
|
export function readRegenerationRefusal(runner: Runner): string | undefined {
|
|
964
995
|
if (
|
|
@@ -985,6 +1016,12 @@ export function readRegenerationRefusal(runner: Runner): string | undefined {
|
|
|
985
1016
|
if (specs.length > 0)
|
|
986
1017
|
return `local dependency specs: ${specs.map(([path, spec]) => `${path}: ${spec}`).join(', ')}`
|
|
987
1018
|
if (manifest !== undefined && 'workspaces' in manifest) return 'the manifest declares workspaces'
|
|
1019
|
+
// Git refuses a pathspec beyond a link with exit 128, which reads as an unignored `tmp/`.
|
|
1020
|
+
try {
|
|
1021
|
+
validateWavePath(runner.target, join(runner.target, 'tmp', 'units', 'wave'))
|
|
1022
|
+
} catch (error) {
|
|
1023
|
+
return error instanceof Error ? error.message : String(error)
|
|
1024
|
+
}
|
|
988
1025
|
if (
|
|
989
1026
|
runStep(
|
|
990
1027
|
runner,
|
|
@@ -1535,6 +1572,246 @@ export function runFormat(runner: Runner): FormatReceipt | undefined {
|
|
|
1535
1572
|
}
|
|
1536
1573
|
}
|
|
1537
1574
|
|
|
1575
|
+
/**
|
|
1576
|
+
* Parses a whole text as one JSON object or a list of JSON objects.
|
|
1577
|
+
*
|
|
1578
|
+
* @param text - A JSON document, such as `npm view NAME@RANGE FIELD --json` output, which prints one
|
|
1579
|
+
* record for one match and a list for several.
|
|
1580
|
+
* @returns Each object the document carries, or none when the text is not JSON.
|
|
1581
|
+
*/
|
|
1582
|
+
export function parseJsonRecords(text: string): ReadonlyArray<Record<string, unknown>> {
|
|
1583
|
+
try {
|
|
1584
|
+
const parsed: unknown = JSON.parse(text)
|
|
1585
|
+
return (Array.isArray(parsed) ? parsed : [parsed])
|
|
1586
|
+
.filter(isRecord)
|
|
1587
|
+
.map((entry) => Object.fromEntries(Object.entries(entry)))
|
|
1588
|
+
} catch {
|
|
1589
|
+
return []
|
|
1590
|
+
}
|
|
1591
|
+
}
|
|
1592
|
+
|
|
1593
|
+
/**
|
|
1594
|
+
* Parses the major, minor, and patch numbers of a plain `major.minor.patch` version.
|
|
1595
|
+
*
|
|
1596
|
+
* @param text - The version text.
|
|
1597
|
+
* @returns The three numbers, or undefined when the text carries a prefix, a prerelease, or any
|
|
1598
|
+
* other form.
|
|
1599
|
+
* @example
|
|
1600
|
+
* ```ts
|
|
1601
|
+
* parseVersion('8.3.8') // [8, 3, 8]
|
|
1602
|
+
* parseVersion('8.3.8-beta.1') // undefined
|
|
1603
|
+
* ```
|
|
1604
|
+
*/
|
|
1605
|
+
export function parseVersion(text: string): readonly [number, number, number] | undefined {
|
|
1606
|
+
const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u.exec(text)
|
|
1607
|
+
if (match === null) return undefined
|
|
1608
|
+
return [Number(match[1]), Number(match[2]), Number(match[3])]
|
|
1609
|
+
}
|
|
1610
|
+
|
|
1611
|
+
/**
|
|
1612
|
+
* Compares two plain versions by their major, minor, and patch numbers.
|
|
1613
|
+
*
|
|
1614
|
+
* @param left - The version ordered first when it compares lower.
|
|
1615
|
+
* @param right - The version it is compared with.
|
|
1616
|
+
* @returns A negative number when `left` is lower, zero when equal, and a positive number when higher.
|
|
1617
|
+
* @example
|
|
1618
|
+
* ```ts
|
|
1619
|
+
* compareVersions([0, 0, 23], [0, 0, 24]) // -1
|
|
1620
|
+
* ```
|
|
1621
|
+
*/
|
|
1622
|
+
export function compareVersions(
|
|
1623
|
+
left: readonly [number, number, number],
|
|
1624
|
+
right: readonly [number, number, number],
|
|
1625
|
+
): number {
|
|
1626
|
+
return left[0] - right[0] || left[1] - right[1] || left[2] - right[2]
|
|
1627
|
+
}
|
|
1628
|
+
|
|
1629
|
+
/**
|
|
1630
|
+
* Parses a declared range as the half-open version intervals its `||` arms admit.
|
|
1631
|
+
*
|
|
1632
|
+
* @remarks
|
|
1633
|
+
* An arm is an exact `major.minor.patch` version, a caret, or a tilde over one. A caret admits up to
|
|
1634
|
+
* the next major, the next minor under major 0, and the next patch under `0.0`; a tilde admits up to
|
|
1635
|
+
* the next minor. Any other form, an empty arm included, makes the whole range unreadable.
|
|
1636
|
+
*
|
|
1637
|
+
* @param range - The declared range.
|
|
1638
|
+
* @returns One interval per arm, with an inclusive `floor` and an exclusive `ceiling`, or undefined
|
|
1639
|
+
* when an arm is outside those forms.
|
|
1640
|
+
* @example
|
|
1641
|
+
* ```ts
|
|
1642
|
+
* parseRange('^0.0.23') // [{ floor: [0, 0, 23], ceiling: [0, 0, 24] }]
|
|
1643
|
+
* parseRange('>=8') // undefined
|
|
1644
|
+
* ```
|
|
1645
|
+
*/
|
|
1646
|
+
export function parseRange(range: string): readonly RangeArm[] | undefined {
|
|
1647
|
+
const arms = range.trim().split(/\s*\|\|\s*/u)
|
|
1648
|
+
const parsed = arms.flatMap((arm): readonly RangeArm[] => {
|
|
1649
|
+
const match = /^([\^~]?)(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u.exec(arm)
|
|
1650
|
+
if (match === null) return []
|
|
1651
|
+
const major = Number(match[2])
|
|
1652
|
+
const minor = Number(match[3])
|
|
1653
|
+
const patch = Number(match[4])
|
|
1654
|
+
const ceiling: readonly [number, number, number] =
|
|
1655
|
+
match[1] === '~'
|
|
1656
|
+
? [major, minor + 1, 0]
|
|
1657
|
+
: match[1] === ''
|
|
1658
|
+
? [major, minor, patch + 1]
|
|
1659
|
+
: major > 0
|
|
1660
|
+
? [major + 1, 0, 0]
|
|
1661
|
+
: minor > 0
|
|
1662
|
+
? [0, minor + 1, 0]
|
|
1663
|
+
: [0, 0, patch + 1]
|
|
1664
|
+
return [{ floor: [major, minor, patch], ceiling }]
|
|
1665
|
+
})
|
|
1666
|
+
return parsed.length === arms.length ? parsed : undefined
|
|
1667
|
+
}
|
|
1668
|
+
|
|
1669
|
+
/**
|
|
1670
|
+
* Computes whether a declared range admits a plain version.
|
|
1671
|
+
*
|
|
1672
|
+
* @param range - The declared range, in a form {@link parseRange} reads.
|
|
1673
|
+
* @param version - The plain version.
|
|
1674
|
+
* @returns True if an arm admits the version, false if none does, and undefined when the range or
|
|
1675
|
+
* the version is unreadable.
|
|
1676
|
+
* @example
|
|
1677
|
+
* ```ts
|
|
1678
|
+
* computeSatisfaction('^8.3.7', '8.3.8') // true
|
|
1679
|
+
* computeSatisfaction('^0.0.23', '0.0.24') // false
|
|
1680
|
+
* computeSatisfaction('*', '1.0.0') // undefined
|
|
1681
|
+
* ```
|
|
1682
|
+
*/
|
|
1683
|
+
export function computeSatisfaction(range: string, version: string): boolean | undefined {
|
|
1684
|
+
const arms = parseRange(range)
|
|
1685
|
+
const parsed = parseVersion(version)
|
|
1686
|
+
if (arms === undefined || parsed === undefined) return undefined
|
|
1687
|
+
return arms.some(
|
|
1688
|
+
(arm) => compareVersions(arm.floor, parsed) <= 0 && compareVersions(parsed, arm.ceiling) < 0,
|
|
1689
|
+
)
|
|
1690
|
+
}
|
|
1691
|
+
|
|
1692
|
+
/**
|
|
1693
|
+
* Raises one declared peer range whose floor fails the served release, and words the decision.
|
|
1694
|
+
*
|
|
1695
|
+
* @remarks
|
|
1696
|
+
* A range the served version satisfies stays as declared. A failing range moves per
|
|
1697
|
+
* {@link moveRange}: the one arm in the release's major becomes the caret of the release. A range
|
|
1698
|
+
* that is unreadable, carries no arm or several arms in that major, or whose arm in that major opens
|
|
1699
|
+
* above the release stays as declared, and the message names why. A reading that names the peer and
|
|
1700
|
+
* carries no release keeps it as `no eligible release`; no reading keeps it as `no release reading`.
|
|
1701
|
+
*
|
|
1702
|
+
* @param name - The peer's package name.
|
|
1703
|
+
* @param range - The declared peer range.
|
|
1704
|
+
* @param reading - The release reading that names the peer, or undefined when none does.
|
|
1705
|
+
* @returns The range after the decision and the rewrite row message: `peer NAME OLD -> NEW` when it
|
|
1706
|
+
* rose, `peer NAME OLD kept, REASON` otherwise.
|
|
1707
|
+
* @example
|
|
1708
|
+
* ```ts
|
|
1709
|
+
* raisePeer('@orkestrel/database', '^0.0.23', { name: '@orkestrel/database', range: '*', latest: '0.0.24' })
|
|
1710
|
+
* // { range: '^0.0.24', message: 'peer @orkestrel/database ^0.0.23 -> ^0.0.24', raised: true }
|
|
1711
|
+
* ```
|
|
1712
|
+
*/
|
|
1713
|
+
export function raisePeer(name: string, range: string, reading: Release | undefined): PeerMove {
|
|
1714
|
+
const arms = parseRange(range)
|
|
1715
|
+
const latest = reading?.latest
|
|
1716
|
+
const version = latest === undefined ? undefined : parseVersion(latest)
|
|
1717
|
+
const matched =
|
|
1718
|
+
version === undefined ? [] : (arms ?? []).filter((entry) => entry.floor[0] === version[0])
|
|
1719
|
+
const reason =
|
|
1720
|
+
arms === undefined
|
|
1721
|
+
? 'unreadable range'
|
|
1722
|
+
: reading === undefined
|
|
1723
|
+
? 'no release reading'
|
|
1724
|
+
: latest === undefined
|
|
1725
|
+
? 'no eligible release'
|
|
1726
|
+
: version === undefined
|
|
1727
|
+
? `unreadable release ${latest}`
|
|
1728
|
+
: computeSatisfaction(range, latest) === true
|
|
1729
|
+
? `admits ${latest}`
|
|
1730
|
+
: matched.length === 0
|
|
1731
|
+
? `no arm in the major of ${latest}`
|
|
1732
|
+
: matched.length > 1
|
|
1733
|
+
? `several arms in the major of ${latest}`
|
|
1734
|
+
: matched.some((arm) => compareVersions(arm.floor, version) > 0)
|
|
1735
|
+
? `its floor is above ${latest}`
|
|
1736
|
+
: undefined
|
|
1737
|
+
if (reason !== undefined || latest === undefined)
|
|
1738
|
+
return { range, message: `peer ${name} ${range} kept, ${String(reason)}`, raised: false }
|
|
1739
|
+
const next = String(moveRange(range, latest))
|
|
1740
|
+
return { range: next, message: `peer ${name} ${range} -> ${next}`, raised: true }
|
|
1741
|
+
}
|
|
1742
|
+
|
|
1743
|
+
/**
|
|
1744
|
+
* Collects the registry lookup each peer-only dependency needs for its release reading.
|
|
1745
|
+
*
|
|
1746
|
+
* @remarks
|
|
1747
|
+
* A peer a release reading already names, such as one also declared under `devDependencies`, takes
|
|
1748
|
+
* that reading. A peer whose range {@link parseRange} cannot read needs no reading. A fleet package
|
|
1749
|
+
* is looked up with `*`, and a foreign tool with a caret over its declared major, or with the
|
|
1750
|
+
* declared range when its arms span several majors, as the audit bounds a dependency. A range bound
|
|
1751
|
+
* by itself admits every release its lookup serves, so such a peer never rises.
|
|
1752
|
+
*
|
|
1753
|
+
* @param manifest - The manifest record.
|
|
1754
|
+
* @param releases - The audit's release readings.
|
|
1755
|
+
* @returns One lookup per peer-only dependency, in declaration order.
|
|
1756
|
+
* @example
|
|
1757
|
+
* ```ts
|
|
1758
|
+
* collectPeerLookups({ peerDependencies: { vite: '^8.3.7' } }, [])
|
|
1759
|
+
* // [{ name: 'vite', bound: '^8' }]
|
|
1760
|
+
* ```
|
|
1761
|
+
*/
|
|
1762
|
+
export function collectPeerLookups(
|
|
1763
|
+
manifest: Record<string, unknown>,
|
|
1764
|
+
releases: readonly Release[],
|
|
1765
|
+
): readonly PeerLookup[] {
|
|
1766
|
+
const named = new Set(releases.map((release) => release.name))
|
|
1767
|
+
const block = manifest.peerDependencies
|
|
1768
|
+
if (typeof block !== 'object' || block === null) return []
|
|
1769
|
+
return Object.entries(block).flatMap(([name, range]): readonly PeerLookup[] => {
|
|
1770
|
+
if (typeof range !== 'string' || named.has(name)) return []
|
|
1771
|
+
const majors = [...new Set(parseRange(range)?.map((arm) => arm.floor[0]))]
|
|
1772
|
+
if (majors.length === 0) return []
|
|
1773
|
+
const bound = name.startsWith('@orkestrel/')
|
|
1774
|
+
? '*'
|
|
1775
|
+
: majors.length === 1
|
|
1776
|
+
? `^${String(majors[0])}`
|
|
1777
|
+
: range
|
|
1778
|
+
return [{ name, bound }]
|
|
1779
|
+
})
|
|
1780
|
+
}
|
|
1781
|
+
|
|
1782
|
+
/**
|
|
1783
|
+
* Reads the release a registry lookup serves out of the output of
|
|
1784
|
+
* `npm view NAME@BOUND version deprecated dist-tags.latest --json`.
|
|
1785
|
+
*
|
|
1786
|
+
* @remarks
|
|
1787
|
+
* The reading skips a deprecated version, a version outside the plain `major.minor.patch` form, and
|
|
1788
|
+
* a version above `latest` when the bound is `*` or the caret of `latest`'s major, then takes the
|
|
1789
|
+
* highest, as the audit's lookup does.
|
|
1790
|
+
*
|
|
1791
|
+
* @param text - The command's standard output.
|
|
1792
|
+
* @param bound - The lookup bound.
|
|
1793
|
+
* @returns The served version, or undefined when no version is eligible or the output is unreadable.
|
|
1794
|
+
* @example
|
|
1795
|
+
* ```ts
|
|
1796
|
+
* readServedVersion('{"version":"0.0.24","dist-tags.latest":"0.0.24"}', '*') // '0.0.24'
|
|
1797
|
+
* ```
|
|
1798
|
+
*/
|
|
1799
|
+
export function readServedVersion(text: string, bound: string): string | undefined {
|
|
1800
|
+
const eligible = parseJsonRecords(text).flatMap((entry) => {
|
|
1801
|
+
const version = readString(entry, 'version') ?? ''
|
|
1802
|
+
const plain = parseVersion(version)
|
|
1803
|
+
const deprecated = readString(entry, 'deprecated') ?? ''
|
|
1804
|
+
const latest = parseVersion(readString(entry, 'dist-tags.latest') ?? '')
|
|
1805
|
+
if (plain === undefined || deprecated.length > 0) return []
|
|
1806
|
+
const capped =
|
|
1807
|
+
latest !== undefined && (bound === '*' || bound === `^${String(latest[0])}`)
|
|
1808
|
+
? compareVersions(plain, latest) <= 0
|
|
1809
|
+
: true
|
|
1810
|
+
return capped ? [{ version, plain }] : []
|
|
1811
|
+
})
|
|
1812
|
+
return eligible.toSorted((left, right) => compareVersions(right.plain, left.plain))[0]?.version
|
|
1813
|
+
}
|
|
1814
|
+
|
|
1538
1815
|
/**
|
|
1539
1816
|
* Moves one declared range to the registry caret of a release, keeping every other major a
|
|
1540
1817
|
* disjunctive range admits.
|
|
@@ -1597,56 +1874,107 @@ export function computeRanges(
|
|
|
1597
1874
|
}
|
|
1598
1875
|
|
|
1599
1876
|
/**
|
|
1600
|
-
* Writes the re-pinned ranges into the target's manifest,
|
|
1877
|
+
* Writes the re-pinned ranges into the target's manifest, raising each peer range whose floor fails
|
|
1878
|
+
* its release.
|
|
1601
1879
|
*
|
|
1602
1880
|
* @remarks
|
|
1603
|
-
* A `
|
|
1604
|
-
*
|
|
1605
|
-
*
|
|
1881
|
+
* A `dependencies` or `devDependencies` range moves per {@link computeRanges} over the audit's
|
|
1882
|
+
* readings alone. A `peerDependencies` range takes the last audit reading that names it with a
|
|
1883
|
+
* release, else its peer-only reading, and moves per {@link raisePeer}: it rises to the caret of the
|
|
1884
|
+
* served version only when the declared range excludes that version, and otherwise stays as
|
|
1885
|
+
* declared. Every raised peer joins the moved list and every other peer is reported as kept.
|
|
1606
1886
|
*
|
|
1607
1887
|
* @param target - The target directory.
|
|
1608
1888
|
* @param releases - The audit's release readings.
|
|
1889
|
+
* @param peers - The peer-only readings, which move `peerDependencies` ranges alone. Default: none.
|
|
1609
1890
|
* @returns One message per range moved and one per peer range kept; the manifest is rewritten only
|
|
1610
1891
|
* when a range moved.
|
|
1611
1892
|
* @example
|
|
1612
1893
|
* ```ts
|
|
1613
1894
|
* writeRanges('.', [{ name: 'vite', range: '^8', latest: '8.3.8' }])
|
|
1614
|
-
* // { moved: ['vite ^8.3.7 -> ^8.3.8'], kept: ['peer vite ^8.3.7
|
|
1895
|
+
* // { moved: ['vite ^8.3.7 -> ^8.3.8'], kept: ['peer vite ^8.3.7 kept, admits 8.3.8'] }
|
|
1615
1896
|
* ```
|
|
1616
1897
|
*/
|
|
1617
|
-
export function writeRanges(
|
|
1898
|
+
export function writeRanges(
|
|
1899
|
+
target: string,
|
|
1900
|
+
releases: readonly Release[],
|
|
1901
|
+
peers: readonly Release[] = [],
|
|
1902
|
+
): Rewrite {
|
|
1618
1903
|
const manifest = readManifest(target)
|
|
1619
1904
|
if (manifest === undefined) return { moved: [], kept: [] }
|
|
1620
|
-
const fields = RANGE_FIELDS.flatMap((field) => {
|
|
1905
|
+
const fields = RANGE_FIELDS.flatMap((field): readonly FieldMove[] => {
|
|
1621
1906
|
const block = manifest[field]
|
|
1622
1907
|
if (typeof block !== 'object' || block === null) return []
|
|
1623
1908
|
const ranges = Object.fromEntries(Object.entries(block))
|
|
1624
|
-
|
|
1909
|
+
if (field !== 'peerDependencies')
|
|
1910
|
+
return [{ field, moves: computeRanges(ranges, releases), kept: [] }]
|
|
1911
|
+
const decisions = Object.entries(ranges).flatMap(([name, range]) =>
|
|
1912
|
+
typeof range === 'string'
|
|
1913
|
+
? [
|
|
1914
|
+
[
|
|
1915
|
+
name,
|
|
1916
|
+
raisePeer(
|
|
1917
|
+
name,
|
|
1918
|
+
range,
|
|
1919
|
+
releases.findLast(
|
|
1920
|
+
(release) => release.name === name && release.latest !== undefined,
|
|
1921
|
+
) ?? peers.findLast((release) => release.name === name),
|
|
1922
|
+
),
|
|
1923
|
+
] as const,
|
|
1924
|
+
]
|
|
1925
|
+
: [],
|
|
1926
|
+
)
|
|
1927
|
+
return [
|
|
1928
|
+
{
|
|
1929
|
+
field,
|
|
1930
|
+
moves: {
|
|
1931
|
+
ranges: {
|
|
1932
|
+
...ranges,
|
|
1933
|
+
...Object.fromEntries(decisions.map(([name, peer]) => [name, peer.range])),
|
|
1934
|
+
},
|
|
1935
|
+
moved: decisions.flatMap(([, peer]) => (peer.raised ? [peer.message] : [])),
|
|
1936
|
+
},
|
|
1937
|
+
kept: decisions.flatMap(([, peer]) => (peer.raised ? [] : [peer.message])),
|
|
1938
|
+
},
|
|
1939
|
+
]
|
|
1625
1940
|
})
|
|
1626
|
-
const
|
|
1627
|
-
const kept = peers.flatMap((entry) =>
|
|
1628
|
-
Object.entries(entry.ranges)
|
|
1629
|
-
.filter(([name, range]) => entry.moves.ranges[name] !== range)
|
|
1630
|
-
.map(
|
|
1631
|
-
([name, range]) =>
|
|
1632
|
-
`peer ${name} ${String(range)} left alone, not ${String(entry.moves.ranges[name])}`,
|
|
1633
|
-
),
|
|
1634
|
-
)
|
|
1635
|
-
const pinned = fields.filter((entry) => entry.field !== 'peerDependencies')
|
|
1636
|
-
const moved = pinned.flatMap((entry) => entry.moves.moved)
|
|
1941
|
+
const moved = fields.flatMap((entry) => entry.moves.moved)
|
|
1637
1942
|
if (moved.length > 0) {
|
|
1638
1943
|
const written = {
|
|
1639
1944
|
...manifest,
|
|
1640
|
-
...Object.fromEntries(
|
|
1945
|
+
...Object.fromEntries(fields.map((entry) => [entry.field, entry.moves.ranges])),
|
|
1641
1946
|
}
|
|
1642
1947
|
writeFileSync(join(target, 'package.json'), `${JSON.stringify(written, null, '\t')}\n`)
|
|
1643
1948
|
}
|
|
1644
|
-
return { moved, kept }
|
|
1949
|
+
return { moved, kept: fields.flatMap((entry) => entry.kept) }
|
|
1950
|
+
}
|
|
1951
|
+
|
|
1952
|
+
/**
|
|
1953
|
+
* Judges one peer-only release lookup.
|
|
1954
|
+
*
|
|
1955
|
+
* @param result - The `npm view NAME@BOUND version deprecated dist-tags.latest --json` command.
|
|
1956
|
+
* @param bound - The lookup bound.
|
|
1957
|
+
* @returns Exit 0 naming the served version, or naming that no release within the bound is
|
|
1958
|
+
* eligible, when the lookup exited 0; else the lookup's failing exit and its reason.
|
|
1959
|
+
*/
|
|
1960
|
+
export function judgeLookup(result: SpawnSyncReturns<string>, bound: string): Verdict {
|
|
1961
|
+
if (result.status !== 0) return readVerdict(result)
|
|
1962
|
+
const served = readServedVersion(result.stdout, bound)
|
|
1963
|
+
return {
|
|
1964
|
+
exit: 0,
|
|
1965
|
+
note: served === undefined ? `no eligible release within ${bound}` : `serves ${served}`,
|
|
1966
|
+
}
|
|
1645
1967
|
}
|
|
1646
1968
|
|
|
1647
1969
|
/**
|
|
1648
1970
|
* Runs the pin step.
|
|
1649
1971
|
*
|
|
1972
|
+
* @remarks
|
|
1973
|
+
* A peer-only dependency produces no audit release reading, so the step looks each one up with
|
|
1974
|
+
* `npm view`, per {@link collectPeerLookups}, before the rewrite, and stops before the rewrite and
|
|
1975
|
+
* the install when a lookup exits non-zero. A lookup that exits 0 with no eligible release keeps
|
|
1976
|
+
* its peer. Offline, it looks up none and the rewrite keeps those peers as declared.
|
|
1977
|
+
*
|
|
1650
1978
|
* @param runner - The visit's state.
|
|
1651
1979
|
* @param scaffoldFile - The scaffold executable.
|
|
1652
1980
|
* @param scaffoldPrefix - The arguments that precede scaffold's own.
|
|
@@ -1670,7 +1998,38 @@ export function runPin(
|
|
|
1670
1998
|
if (audit !== undefined) {
|
|
1671
1999
|
const releases = readReleases(audit.stdout)
|
|
1672
2000
|
if (releases === undefined || (audit.status !== 0 && audit.status !== 1)) return
|
|
1673
|
-
const
|
|
2001
|
+
const lookups = collectPeerLookups(readManifest(runner.target) ?? {}, releases)
|
|
2002
|
+
if (runner.offline && lookups.length > 0)
|
|
2003
|
+
appendStep(
|
|
2004
|
+
runner,
|
|
2005
|
+
'pin',
|
|
2006
|
+
'npm view',
|
|
2007
|
+
`offline: no peer-only lookup for ${lookups.map((lookup) => lookup.name).join(', ')}`,
|
|
2008
|
+
)
|
|
2009
|
+
const readings = (runner.offline ? [] : lookups).map((lookup): Release | undefined => {
|
|
2010
|
+
const view = runNpmStep(
|
|
2011
|
+
runner,
|
|
2012
|
+
'pin',
|
|
2013
|
+
[
|
|
2014
|
+
'view',
|
|
2015
|
+
`${lookup.name}@${lookup.bound}`,
|
|
2016
|
+
'version',
|
|
2017
|
+
'deprecated',
|
|
2018
|
+
'dist-tags.latest',
|
|
2019
|
+
'--json',
|
|
2020
|
+
],
|
|
2021
|
+
(result) => judgeLookup(result, lookup.bound),
|
|
2022
|
+
)
|
|
2023
|
+
if (view?.status !== 0) return undefined
|
|
2024
|
+
const latest = readServedVersion(view.stdout, lookup.bound)
|
|
2025
|
+
return { name: lookup.name, range: lookup.bound, latest }
|
|
2026
|
+
})
|
|
2027
|
+
if (readings.includes(undefined)) return
|
|
2028
|
+
const { moved, kept } = writeRanges(
|
|
2029
|
+
runner.target,
|
|
2030
|
+
releases,
|
|
2031
|
+
readings.filter((reading) => reading !== undefined),
|
|
2032
|
+
)
|
|
1674
2033
|
appendStep(
|
|
1675
2034
|
runner,
|
|
1676
2035
|
'pin',
|
|
@@ -2099,7 +2458,8 @@ export function runVisit(values: Arguments['values']): Visit | undefined {
|
|
|
2099
2458
|
*
|
|
2100
2459
|
* @param target - The target directory.
|
|
2101
2460
|
* @returns A new stamped directory under the target's `tmp/units/wave/` when the target is inside a
|
|
2102
|
-
* work tree that ignores `tmp/`,
|
|
2461
|
+
* work tree that ignores `tmp/`, or when that path crosses a link, which the caller's link check
|
|
2462
|
+
* refuses; else undefined.
|
|
2103
2463
|
*/
|
|
2104
2464
|
export function readJournalDirectory(target: string): string | undefined {
|
|
2105
2465
|
const inside = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
|
|
@@ -2108,14 +2468,25 @@ export function readJournalDirectory(target: string): string | undefined {
|
|
|
2108
2468
|
windowsHide: true,
|
|
2109
2469
|
})
|
|
2110
2470
|
if (inside.status !== 0 || inside.stdout.trim() !== 'true') return undefined
|
|
2471
|
+
const directory = join(
|
|
2472
|
+
target,
|
|
2473
|
+
'tmp',
|
|
2474
|
+
'units',
|
|
2475
|
+
'wave',
|
|
2476
|
+
new Date().toISOString().replace(/[:.]/gu, '-'),
|
|
2477
|
+
)
|
|
2478
|
+
// Git refuses a pathspec beyond a link with exit 128, which reads as an unignored `tmp/`.
|
|
2479
|
+
try {
|
|
2480
|
+
validateWavePath(target, join(target, 'tmp', 'units', 'wave'))
|
|
2481
|
+
} catch {
|
|
2482
|
+
return directory
|
|
2483
|
+
}
|
|
2111
2484
|
const ignored = spawnSync('git', ['check-ignore', '-q', 'tmp/units/wave/probe'], {
|
|
2112
2485
|
cwd: target,
|
|
2113
2486
|
encoding: 'utf8',
|
|
2114
2487
|
windowsHide: true,
|
|
2115
2488
|
})
|
|
2116
|
-
return ignored.status === 0
|
|
2117
|
-
? join(target, 'tmp', 'units', 'wave', new Date().toISOString().replace(/[:.]/gu, '-'))
|
|
2118
|
-
: undefined
|
|
2489
|
+
return ignored.status === 0 ? directory : undefined
|
|
2119
2490
|
}
|
|
2120
2491
|
|
|
2121
2492
|
/**
|