@orkestrel/scaffold 0.0.133 → 0.0.135
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-dispatch/scripts/bench.js +61 -96
- package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +48 -76
- package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +27 -66
- package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +31 -64
- package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +43 -57
- package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +43 -86
- package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +68 -104
- package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +35 -69
- package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +47 -84
- package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +134 -116
- package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +38 -90
- package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +39 -103
- package/dist/agents/skills/orkestrel-harden/scripts/measure.js +40 -89
- package/dist/agents/skills/orkestrel-harden/scripts/titles.js +41 -87
- package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +43 -88
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1568 -213
- package/dist/agents/skills/orkestrel-publish/scripts/compare.js +40 -60
- package/dist/agents/skills/orkestrel-publish/scripts/pins.js +47 -81
- package/dist/agents/skills/orkestrel-publish/scripts/steps.js +66 -104
- package/dist/agents/skills/orkestrel-publish/scripts/swap.js +74 -88
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +387 -109
- package/dist/agents/skills/orkestrel-publish/scripts/window.js +55 -96
- package/dist/agents/skills/orkestrel-scout/scripts/map.js +54 -101
- package/dist/bin/main.js +275 -33
- package/dist/bin/main.js.map +1 -1
- package/dist/host/AGENTS.md +1 -1
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
- package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
- package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
- package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
- package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
- package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
- package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1990 -274
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +28 -7
- package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
- package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
- package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
- package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +483 -127
- package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
- package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
- package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
- package/dist/host/claude/agents/orkestrel.md +16 -16
- 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 +7 -4
- package/dist/host/claude/rules/styles.md +1 -1
- package/dist/host/claude/rules/tests.md +3 -3
- package/dist/host/claude/rules/workspace.md +50 -37
- package/dist/host/configs/helpers.ts +117 -71
- package/dist/host/dotfiles/oxlintrc.json +6 -0
- package/dist/host/guides/agent.md +989 -395
- package/dist/host/guides/database.md +357 -342
- package/dist/host/guides/form.md +79 -4
- package/dist/host/guides/middleware.md +5 -5
- package/dist/host/guides/ollama.md +41 -42
- package/dist/host/guides/scaffold.md +170 -70
- package/dist/host/guides/study.md +12 -12
- package/dist/host/guides/table.md +20 -6
- package/dist/host/guides/test.md +166 -52
- package/dist/host/guides/toolbox.md +127 -81
- package/dist/host/guides/workspace.md +21 -14
- package/dist/host/manifest.json +54 -54
- package/dist/host/tests/config.test.ts +251 -7
- package/dist/host/tests/policy.test.ts +14 -21
- package/dist/host/tests/setupPolicy.ts +43 -36
- package/dist/src/core/index.cjs +533 -139
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +223 -16
- package/dist/src/core/index.d.ts +223 -16
- package/dist/src/core/index.js +524 -139
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +23 -14
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +3 -2
- package/dist/src/server/index.d.ts +3 -2
- package/dist/src/server/index.js +24 -15
- package/dist/src/server/index.js.map +1 -1
- package/package.json +2 -2
|
@@ -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
|
|
|
@@ -13,21 +13,42 @@ by hand only to repair it, then resume with `--from <step>`. Read a failed step'
|
|
|
13
13
|
its row names under the target's `tmp/units/wave/`, before running the step again. Journals and
|
|
14
14
|
overwrite receipts are written only where the work tree ignores `tmp/`.
|
|
15
15
|
|
|
16
|
-
1. Re-pin every range the audit's release readings name to
|
|
17
|
-
and install before the overwrite.
|
|
16
|
+
1. Re-pin every `dependencies` and `devDependencies` range the audit's release readings name to
|
|
17
|
+
the caret of its returned release, and install before the overwrite. Keep a published
|
|
18
|
+
`peerDependencies` range at the floor the release needs: raise it only when its floor fails the
|
|
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`
|
|
18
24
|
dependencies in `dependencies` and `devDependencies`, plus declared foreign tools that the
|
|
19
25
|
blueprint plans in those sections; exclude the fixed showcase tool pair from ordinary release lookups.
|
|
20
26
|
Look up fleet releases with `*`; look up foreign tools with
|
|
21
27
|
a caret over the declared major when one can be extracted, otherwise with the declared range.
|
|
22
28
|
Do not treat a declared minor or patch bound as the lookup bound. A lookup skips a deprecated
|
|
23
|
-
version, and skips a version above `latest` when the range is `*` or sits in `latest`'s major.
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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.
|
|
41
|
+
For example, with a peer `vite: ^8.3.7` and a development `vite: ^8.3.7` whose registry serves
|
|
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;
|
|
45
|
+
with a planned tool whose registry serves `8.3.4`, apply `vite: ~8.2.0 -> ^8.3.4` even though
|
|
46
|
+
the tilde excludes `8.3.4`.
|
|
27
47
|
Keep this pin step within each declared major; step 5 states the overwrite's lift.
|
|
28
48
|
A range joined by `||` names one supported major per
|
|
29
49
|
arm, so move only the arm in the release's major and keep every other arm: with
|
|
30
|
-
`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`.
|
|
31
52
|
For a workspace whose selected framework activates a
|
|
32
53
|
`TOOLCHAIN_HOLDS` row, keep the tool within that range's major; read the audit question for its reason. Prove
|
|
33
54
|
that framework on the later major before lifting its hold.
|
|
@@ -5,13 +5,15 @@
|
|
|
5
5
|
// compares against a local .tgz instead of fetching. Sourcemaps are excluded, a text file differs
|
|
6
6
|
// only when it differs with all whitespace removed, and a binary file differs on any byte. The
|
|
7
7
|
// summary lists the paths added, removed, and changed. Exit 0 when nothing material differs, 3 when
|
|
8
|
-
// something does, 2 when the tarball cannot be read, 64 on usage
|
|
9
|
-
//
|
|
8
|
+
// something does, 2 when the tarball cannot be read, 64 on usage. The script reads its flags with
|
|
9
|
+
// `parseArgs` in strict mode.
|
|
10
|
+
import type { ParseArgsOptionsConfig } from 'node:util'
|
|
10
11
|
import type { SpawnSyncReturns } from 'node:child_process'
|
|
11
12
|
import { spawnSync } from 'node:child_process'
|
|
12
13
|
import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
|
|
13
14
|
import { dirname, join, relative } from 'node:path'
|
|
14
15
|
import { gunzipSync } from 'node:zlib'
|
|
16
|
+
import { parseArgs } from 'node:util'
|
|
15
17
|
|
|
16
18
|
/** Holds the byte size of one tar block. */
|
|
17
19
|
export const BLOCK = 512
|
|
@@ -32,13 +34,52 @@ export const SKIPPED_DIRECTORIES: ReadonlySet<string> = new Set([
|
|
|
32
34
|
/** Holds the empty skip set, because a dist tree holds nothing a walk skips, so every emitted file counts. */
|
|
33
35
|
export const NOTHING_SKIPPED: ReadonlySet<string> = new Set()
|
|
34
36
|
|
|
35
|
-
/** Lists every flag the script reads, value flags and switches alike. */
|
|
36
|
-
export const FLAGS: readonly string[] = ['--package', '--version', '--tarball', '--dist', '--json']
|
|
37
|
-
|
|
38
37
|
/** Holds the usage line the script prints on a usage refusal. */
|
|
39
38
|
export const USAGE =
|
|
40
39
|
'usage: compare.ts [--package NAME] [--version V] [--tarball PATH] [--dist dist] [--json]'
|
|
41
40
|
|
|
41
|
+
/** Declares every flag the script reads, for `parseArgs`. */
|
|
42
|
+
export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
|
|
43
|
+
package: Object.freeze({ type: 'string' }),
|
|
44
|
+
version: Object.freeze({ type: 'string' }),
|
|
45
|
+
tarball: Object.freeze({ type: 'string' }),
|
|
46
|
+
dist: Object.freeze({ type: 'string' }),
|
|
47
|
+
json: Object.freeze({ type: 'boolean' }),
|
|
48
|
+
})
|
|
49
|
+
|
|
50
|
+
/** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
|
|
51
|
+
export interface Arguments {
|
|
52
|
+
readonly values: Readonly<
|
|
53
|
+
Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
|
|
54
|
+
>
|
|
55
|
+
readonly positionals: readonly string[]
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
|
|
59
|
+
export type ArgumentsResult =
|
|
60
|
+
| { readonly success: true; readonly value: Arguments }
|
|
61
|
+
| { readonly success: false; readonly error: string }
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Parses the arguments in strict mode against `OPTIONS`.
|
|
65
|
+
*
|
|
66
|
+
* @param argv - The arguments after the script path.
|
|
67
|
+
* @returns The values and positionals, or the message `parseArgs` refused the arguments with.
|
|
68
|
+
*/
|
|
69
|
+
export function parseArguments(argv: readonly string[]): ArgumentsResult {
|
|
70
|
+
try {
|
|
71
|
+
const { values, positionals } = parseArgs({
|
|
72
|
+
args: [...argv],
|
|
73
|
+
options: OPTIONS,
|
|
74
|
+
strict: true,
|
|
75
|
+
allowPositionals: false,
|
|
76
|
+
})
|
|
77
|
+
return { success: true, value: { values, positionals } }
|
|
78
|
+
} catch (error) {
|
|
79
|
+
return { success: false, error: error instanceof Error ? error.message : String(error) }
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
|
|
42
83
|
/** Describes the name and version a package manifest declares. */
|
|
43
84
|
export interface Manifest {
|
|
44
85
|
readonly name: string | undefined
|
|
@@ -80,60 +121,7 @@ export interface NpmCommand {
|
|
|
80
121
|
* @returns The same path with every backslash replaced by a slash.
|
|
81
122
|
*/
|
|
82
123
|
export function normalizeSlashes(path: string): string {
|
|
83
|
-
return path.
|
|
84
|
-
}
|
|
85
|
-
|
|
86
|
-
/**
|
|
87
|
-
* Reads the value that follows a flag.
|
|
88
|
-
*
|
|
89
|
-
* @remarks
|
|
90
|
-
* Reads `--flag value` pairs: the first occurrence of a flag wins, a following value that opens
|
|
91
|
-
* with `--` is a missing value, and the `--flag=value` form is not read.
|
|
92
|
-
*
|
|
93
|
-
* @param argv - The arguments after the script path.
|
|
94
|
-
* @param name - The flag, such as `--package`.
|
|
95
|
-
* @returns The value after the flag, or undefined when the flag is absent, last, or followed by
|
|
96
|
-
* another flag.
|
|
97
|
-
*/
|
|
98
|
-
export function readOption(argv: readonly string[], name: string): string | undefined {
|
|
99
|
-
const index = argv.indexOf(name)
|
|
100
|
-
const value = index === -1 ? undefined : argv[index + 1]
|
|
101
|
-
return value === undefined || value.startsWith('--') ? undefined : value
|
|
102
|
-
}
|
|
103
|
-
|
|
104
|
-
/**
|
|
105
|
-
* Names the value flags a caller gave with no value.
|
|
106
|
-
*
|
|
107
|
-
* @param argv - The arguments after the script path.
|
|
108
|
-
* @param names - The flags that take a value.
|
|
109
|
-
* @returns Each named flag that appears last or is followed by another flag, in argument order.
|
|
110
|
-
*/
|
|
111
|
-
export function readMissingFlags(
|
|
112
|
-
argv: readonly string[],
|
|
113
|
-
names: readonly string[],
|
|
114
|
-
): readonly string[] {
|
|
115
|
-
return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
|
|
116
|
-
}
|
|
117
|
-
|
|
118
|
-
/**
|
|
119
|
-
* Names the flags a caller gave that the script does not read.
|
|
120
|
-
*
|
|
121
|
-
* @remarks
|
|
122
|
-
* Reads the arguments before a bare `--`, which opens a command a script passes on. A `--flag=value`
|
|
123
|
-
* argument is unknown, because the script reads no such form.
|
|
124
|
-
*
|
|
125
|
-
* @param argv - The arguments after the script path.
|
|
126
|
-
* @param flags - Every flag the script reads, value flags and switches alike.
|
|
127
|
-
* @returns Each argument that opens with `--` and is not a read flag, in argument order.
|
|
128
|
-
*/
|
|
129
|
-
export function readUnknownFlags(
|
|
130
|
-
argv: readonly string[],
|
|
131
|
-
flags: readonly string[],
|
|
132
|
-
): readonly string[] {
|
|
133
|
-
const end = argv.indexOf('--')
|
|
134
|
-
return (end === -1 ? argv : argv.slice(0, end)).filter(
|
|
135
|
-
(argument) => argument.startsWith('--') && !flags.includes(argument),
|
|
136
|
-
)
|
|
124
|
+
return path.replaceAll('\\', '/')
|
|
137
125
|
}
|
|
138
126
|
|
|
139
127
|
/**
|
|
@@ -462,31 +450,22 @@ export function differs(left: Buffer, right: Buffer): boolean {
|
|
|
462
450
|
* cannot be read, 64 on usage.
|
|
463
451
|
*/
|
|
464
452
|
export async function main(argv: readonly string[]): Promise<number> {
|
|
465
|
-
const
|
|
466
|
-
if (
|
|
467
|
-
console.error(
|
|
468
|
-
`compare: unknown flag ${unknown.join(', ')}; give each flag and its value as separate arguments\n${USAGE}`,
|
|
469
|
-
)
|
|
470
|
-
return 64
|
|
471
|
-
}
|
|
472
|
-
const missing = readMissingFlags(argv, ['--package', '--version', '--tarball', '--dist'])
|
|
473
|
-
if (missing.length > 0) {
|
|
474
|
-
console.error(`compare: ${missing.join(', ')} given with no value`)
|
|
453
|
+
const parsed = parseArguments(argv)
|
|
454
|
+
if (!parsed.success) {
|
|
455
|
+
console.error(`compare: ${parsed.error}; ${USAGE}`)
|
|
475
456
|
return 64
|
|
476
457
|
}
|
|
458
|
+
const { values } = parsed.value
|
|
477
459
|
const manifest = readManifest('.')
|
|
478
|
-
const name =
|
|
479
|
-
const dist =
|
|
480
|
-
const tarball =
|
|
481
|
-
if (
|
|
482
|
-
name === undefined ||
|
|
483
|
-
!existsSync(dist) ||
|
|
484
|
-
(argv.includes('--tarball') && tarball === undefined)
|
|
485
|
-
) {
|
|
460
|
+
const name = typeof values.package === 'string' ? values.package : manifest.name
|
|
461
|
+
const dist = typeof values.dist === 'string' ? values.dist : 'dist'
|
|
462
|
+
const tarball = typeof values.tarball === 'string' ? values.tarball : undefined
|
|
463
|
+
if (name === undefined || !existsSync(dist)) {
|
|
486
464
|
console.error(USAGE)
|
|
487
465
|
return 64
|
|
488
466
|
}
|
|
489
|
-
const
|
|
467
|
+
const requested = typeof values.version === 'string' ? values.version : undefined
|
|
468
|
+
const source = await readSource(name, requested, tarball)
|
|
490
469
|
const { archive, version } = source
|
|
491
470
|
if (archive === undefined) {
|
|
492
471
|
console.error(`compare: ${source.failure}`)
|
|
@@ -532,7 +511,7 @@ export async function main(argv: readonly string[]): Promise<number> {
|
|
|
532
511
|
changed,
|
|
533
512
|
material,
|
|
534
513
|
}
|
|
535
|
-
if (
|
|
514
|
+
if (values.json === true) console.log(JSON.stringify(summary))
|
|
536
515
|
else {
|
|
537
516
|
console.log(
|
|
538
517
|
`compare: ${name}${version === undefined ? '' : `@${version}`} — ${published.size} published file(s), ${added.length} added, ${removed.length} removed, ${changed.length} changed`,
|
|
@@ -8,10 +8,12 @@
|
|
|
8
8
|
// range (`>=1.2.0 <2.0.0`, `8.x`) hits its literal bounded the same way and not preceded by another
|
|
9
9
|
// range operator. Each matching line prints once as path:line: text, naming the first requested
|
|
10
10
|
// literal that matched in the order --version then each --range, so the operator rules on it.
|
|
11
|
-
// Exit 0 with no hits, 3 with hits, 64 on usage
|
|
12
|
-
//
|
|
11
|
+
// Exit 0 with no hits, 3 with hits, 64 on usage. The script reads its flags with `parseArgs` in
|
|
12
|
+
// strict mode.
|
|
13
|
+
import type { ParseArgsOptionsConfig } from 'node:util'
|
|
13
14
|
import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
|
|
14
15
|
import { join } from 'node:path'
|
|
16
|
+
import { parseArgs } from 'node:util'
|
|
15
17
|
|
|
16
18
|
/** Matches the file extensions the sweep skips as binary. */
|
|
17
19
|
export const BINARY = /\.(png|jpg|jpeg|gif|webp|ico|woff2?|ttf|otf|eot|zip|tgz|gz|pdf|wasm)$/u
|
|
@@ -30,13 +32,51 @@ export const SKIPPED_DIRECTORIES: ReadonlySet<string> = new Set([
|
|
|
30
32
|
'.idea',
|
|
31
33
|
])
|
|
32
34
|
|
|
33
|
-
/** Lists every flag the script reads, value flags and switches alike. */
|
|
34
|
-
export const FLAGS: readonly string[] = ['--version', '--range', '--paths', '--json']
|
|
35
|
-
|
|
36
35
|
/** Holds the usage line the script prints on a usage refusal. */
|
|
37
36
|
export const USAGE =
|
|
38
37
|
'usage: pins.ts --version PRIOR [--range PRIOR_RANGE ...] [--paths src,tests,guides] [--json]'
|
|
39
38
|
|
|
39
|
+
/** Declares every flag the script reads, for `parseArgs`. */
|
|
40
|
+
export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
|
|
41
|
+
version: Object.freeze({ type: 'string' }),
|
|
42
|
+
range: Object.freeze({ type: 'string', multiple: true }),
|
|
43
|
+
paths: Object.freeze({ type: 'string' }),
|
|
44
|
+
json: Object.freeze({ type: 'boolean' }),
|
|
45
|
+
})
|
|
46
|
+
|
|
47
|
+
/** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
|
|
48
|
+
export interface Arguments {
|
|
49
|
+
readonly values: Readonly<
|
|
50
|
+
Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
|
|
51
|
+
>
|
|
52
|
+
readonly positionals: readonly string[]
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
|
|
56
|
+
export type ArgumentsResult =
|
|
57
|
+
| { readonly success: true; readonly value: Arguments }
|
|
58
|
+
| { readonly success: false; readonly error: string }
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Parses the arguments in strict mode against `OPTIONS`.
|
|
62
|
+
*
|
|
63
|
+
* @param argv - The arguments after the script path.
|
|
64
|
+
* @returns The values and positionals, or the message `parseArgs` refused the arguments with.
|
|
65
|
+
*/
|
|
66
|
+
export function parseArguments(argv: readonly string[]): ArgumentsResult {
|
|
67
|
+
try {
|
|
68
|
+
const { values, positionals } = parseArgs({
|
|
69
|
+
args: [...argv],
|
|
70
|
+
options: OPTIONS,
|
|
71
|
+
strict: true,
|
|
72
|
+
allowPositionals: false,
|
|
73
|
+
})
|
|
74
|
+
return { success: true, value: { values, positionals } }
|
|
75
|
+
} catch (error) {
|
|
76
|
+
return { success: false, error: error instanceof Error ? error.message : String(error) }
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
40
80
|
/** Describes one requested literal and the pattern that finds it in a line. */
|
|
41
81
|
export interface Literal {
|
|
42
82
|
readonly literal: string
|
|
@@ -64,74 +104,7 @@ export interface WalkedFile {
|
|
|
64
104
|
* @returns The same path with every backslash replaced by a slash.
|
|
65
105
|
*/
|
|
66
106
|
export function normalizeSlashes(path: string): string {
|
|
67
|
-
return path.
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
/**
|
|
71
|
-
* Reads the value that follows a flag.
|
|
72
|
-
*
|
|
73
|
-
* @remarks
|
|
74
|
-
* Reads `--flag value` pairs: the first occurrence of a flag wins, a following value that opens
|
|
75
|
-
* with `--` is a missing value, and the `--flag=value` form is not read.
|
|
76
|
-
*
|
|
77
|
-
* @param argv - The arguments after the script path.
|
|
78
|
-
* @param name - The flag, such as `--paths`.
|
|
79
|
-
* @returns The value after the flag, or undefined when the flag is absent, last, or followed by
|
|
80
|
-
* another flag.
|
|
81
|
-
*/
|
|
82
|
-
export function readOption(argv: readonly string[], name: string): string | undefined {
|
|
83
|
-
const index = argv.indexOf(name)
|
|
84
|
-
const value = index === -1 ? undefined : argv[index + 1]
|
|
85
|
-
return value === undefined || value.startsWith('--') ? undefined : value
|
|
86
|
-
}
|
|
87
|
-
|
|
88
|
-
/**
|
|
89
|
-
* Names the value flags a caller gave with no value.
|
|
90
|
-
*
|
|
91
|
-
* @param argv - The arguments after the script path.
|
|
92
|
-
* @param names - The flags that take a value.
|
|
93
|
-
* @returns Each named flag that appears last or is followed by another flag, in argument order.
|
|
94
|
-
*/
|
|
95
|
-
export function readMissingFlags(
|
|
96
|
-
argv: readonly string[],
|
|
97
|
-
names: readonly string[],
|
|
98
|
-
): readonly string[] {
|
|
99
|
-
return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
|
|
100
|
-
}
|
|
101
|
-
|
|
102
|
-
/**
|
|
103
|
-
* Names the flags a caller gave that the script does not read.
|
|
104
|
-
*
|
|
105
|
-
* @remarks
|
|
106
|
-
* Reads the arguments before a bare `--`, which opens a command a script passes on. A `--flag=value`
|
|
107
|
-
* argument is unknown, because the script reads no such form.
|
|
108
|
-
*
|
|
109
|
-
* @param argv - The arguments after the script path.
|
|
110
|
-
* @param flags - Every flag the script reads, value flags and switches alike.
|
|
111
|
-
* @returns Each argument that opens with `--` and is not a read flag, in argument order.
|
|
112
|
-
*/
|
|
113
|
-
export function readUnknownFlags(
|
|
114
|
-
argv: readonly string[],
|
|
115
|
-
flags: readonly string[],
|
|
116
|
-
): readonly string[] {
|
|
117
|
-
const end = argv.indexOf('--')
|
|
118
|
-
return (end === -1 ? argv : argv.slice(0, end)).filter(
|
|
119
|
-
(argument) => argument.startsWith('--') && !flags.includes(argument),
|
|
120
|
-
)
|
|
121
|
-
}
|
|
122
|
-
|
|
123
|
-
/**
|
|
124
|
-
* Reads every value that follows a repeatable flag.
|
|
125
|
-
*
|
|
126
|
-
* @param argv - The arguments after the script path.
|
|
127
|
-
* @param name - The flag, such as `--range`.
|
|
128
|
-
* @returns The values in order, empty when the flag never appears.
|
|
129
|
-
*/
|
|
130
|
-
export function readOptions(argv: readonly string[], name: string): readonly string[] {
|
|
131
|
-
return argv.flatMap((argument, index) => {
|
|
132
|
-
const value = argv[index + 1]
|
|
133
|
-
return argument === name && value !== undefined && !value.startsWith('--') ? [value] : []
|
|
134
|
-
})
|
|
107
|
+
return path.replaceAll('\\', '/')
|
|
135
108
|
}
|
|
136
109
|
|
|
137
110
|
/**
|
|
@@ -234,6 +207,18 @@ export function sweepFile(path: string, literals: readonly Literal[]): readonly
|
|
|
234
207
|
})
|
|
235
208
|
}
|
|
236
209
|
|
|
210
|
+
/**
|
|
211
|
+
* Collects the strings a repeatable flag's value holds.
|
|
212
|
+
*
|
|
213
|
+
* @param value - The value `parseArgs` read for a flag declared with `multiple: true`.
|
|
214
|
+
* @returns Each string in order, empty when the flag never appears.
|
|
215
|
+
*/
|
|
216
|
+
export function collectStrings(value: unknown): readonly string[] {
|
|
217
|
+
return Array.isArray(value)
|
|
218
|
+
? value.filter((member): member is string => typeof member === 'string')
|
|
219
|
+
: []
|
|
220
|
+
}
|
|
221
|
+
|
|
237
222
|
/**
|
|
238
223
|
* Runs the sweep and prints its hits.
|
|
239
224
|
*
|
|
@@ -241,21 +226,15 @@ export function sweepFile(path: string, literals: readonly Literal[]): readonly
|
|
|
241
226
|
* @returns The exit code: 0 with no hits, 3 with hits, 64 on usage.
|
|
242
227
|
*/
|
|
243
228
|
export function main(argv: readonly string[]): number {
|
|
244
|
-
const
|
|
245
|
-
if (
|
|
246
|
-
console.error(
|
|
247
|
-
`pins: unknown flag ${unknown.join(', ')}; give each flag and its value as separate arguments\n${USAGE}`,
|
|
248
|
-
)
|
|
249
|
-
return 64
|
|
250
|
-
}
|
|
251
|
-
const missing = readMissingFlags(argv, ['--version', '--range', '--paths'])
|
|
252
|
-
if (missing.length > 0) {
|
|
253
|
-
console.error(`pins: ${missing.join(', ')} given with no value`)
|
|
229
|
+
const parsed = parseArguments(argv)
|
|
230
|
+
if (!parsed.success) {
|
|
231
|
+
console.error(`pins: ${parsed.error}; ${USAGE}`)
|
|
254
232
|
return 64
|
|
255
233
|
}
|
|
256
|
-
const
|
|
257
|
-
const
|
|
258
|
-
const
|
|
234
|
+
const { values } = parsed.value
|
|
235
|
+
const version = typeof values.version === 'string' ? values.version : undefined
|
|
236
|
+
const ranges = collectStrings(values.range)
|
|
237
|
+
const paths = (typeof values.paths === 'string' ? values.paths : 'src,tests,guides').split(',')
|
|
259
238
|
if (version === undefined && ranges.length === 0) {
|
|
260
239
|
console.error(USAGE)
|
|
261
240
|
return 64
|
|
@@ -278,7 +257,7 @@ export function main(argv: readonly string[]): number {
|
|
|
278
257
|
.filter((file) => !BINARY.test(file))
|
|
279
258
|
.flatMap((file) => sweepFile(file, literals))
|
|
280
259
|
const names = literals.map((entry) => entry.literal)
|
|
281
|
-
if (
|
|
260
|
+
if (values.json === true) {
|
|
282
261
|
console.log(JSON.stringify({ literals: names, paths: present, skipped, hits }))
|
|
283
262
|
} else {
|
|
284
263
|
for (const hit of hits) console.log(`${hit.path}:${hit.line}: ${hit.text}`)
|