@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.
Files changed (92) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js +61 -96
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +48 -76
  3. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +27 -66
  4. package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +31 -64
  5. package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +43 -57
  6. package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +43 -86
  7. package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +68 -104
  8. package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +35 -69
  9. package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +47 -84
  10. package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +134 -116
  11. package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +38 -90
  12. package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +39 -103
  13. package/dist/agents/skills/orkestrel-harden/scripts/measure.js +40 -89
  14. package/dist/agents/skills/orkestrel-harden/scripts/titles.js +41 -87
  15. package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +43 -88
  16. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1568 -213
  17. package/dist/agents/skills/orkestrel-publish/scripts/compare.js +40 -60
  18. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +47 -81
  19. package/dist/agents/skills/orkestrel-publish/scripts/steps.js +66 -104
  20. package/dist/agents/skills/orkestrel-publish/scripts/swap.js +74 -88
  21. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +387 -109
  22. package/dist/agents/skills/orkestrel-publish/scripts/window.js +55 -96
  23. package/dist/agents/skills/orkestrel-scout/scripts/map.js +54 -101
  24. package/dist/bin/main.js +275 -33
  25. package/dist/bin/main.js.map +1 -1
  26. package/dist/host/AGENTS.md +1 -1
  27. package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
  28. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
  29. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
  30. package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
  31. package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
  32. package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
  33. package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
  34. package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
  35. package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
  36. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
  37. package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
  38. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
  39. package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
  40. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
  41. package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
  42. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
  43. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
  44. package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
  45. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1990 -274
  46. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  47. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +28 -7
  48. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
  49. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
  50. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
  51. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
  52. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +483 -127
  53. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
  54. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  55. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
  56. package/dist/host/claude/agents/orkestrel.md +16 -16
  57. package/dist/host/claude/rules/architecture.md +1 -1
  58. package/dist/host/claude/rules/documentation.md +1 -1
  59. package/dist/host/claude/rules/patterns.md +7 -4
  60. package/dist/host/claude/rules/styles.md +1 -1
  61. package/dist/host/claude/rules/tests.md +3 -3
  62. package/dist/host/claude/rules/workspace.md +50 -37
  63. package/dist/host/configs/helpers.ts +117 -71
  64. package/dist/host/dotfiles/oxlintrc.json +6 -0
  65. package/dist/host/guides/agent.md +989 -395
  66. package/dist/host/guides/database.md +357 -342
  67. package/dist/host/guides/form.md +79 -4
  68. package/dist/host/guides/middleware.md +5 -5
  69. package/dist/host/guides/ollama.md +41 -42
  70. package/dist/host/guides/scaffold.md +170 -70
  71. package/dist/host/guides/study.md +12 -12
  72. package/dist/host/guides/table.md +20 -6
  73. package/dist/host/guides/test.md +166 -52
  74. package/dist/host/guides/toolbox.md +127 -81
  75. package/dist/host/guides/workspace.md +21 -14
  76. package/dist/host/manifest.json +54 -54
  77. package/dist/host/tests/config.test.ts +251 -7
  78. package/dist/host/tests/policy.test.ts +14 -21
  79. package/dist/host/tests/setupPolicy.ts +43 -36
  80. package/dist/src/core/index.cjs +533 -139
  81. package/dist/src/core/index.cjs.map +1 -1
  82. package/dist/src/core/index.d.cts +223 -16
  83. package/dist/src/core/index.d.ts +223 -16
  84. package/dist/src/core/index.js +524 -139
  85. package/dist/src/core/index.js.map +1 -1
  86. package/dist/src/server/index.cjs +23 -14
  87. package/dist/src/server/index.cjs.map +1 -1
  88. package/dist/src/server/index.d.cts +3 -2
  89. package/dist/src/server/index.d.ts +3 -2
  90. package/dist/src/server/index.js +24 -15
  91. package/dist/src/server/index.js.map +1 -1
  92. 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 the caret of its returned release,
17
- and install before the overwrite. Read the audit population as the declared `@orkestrel`
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. Peer-only dependencies produce no release reading;
24
- rewrite a peer range only when its name shares an audited release reading. For example, with
25
- peer-only `@orkestrel/peer-only: ^0.0.1`, leave that peer unchanged; with a planned tool whose
26
- registry serves `8.3.4`, apply `vite: ~8.2.0 -> ^8.3.4` even though the tilde excludes `8.3.4`.
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, including a flag the script does
9
- // not read and the `--flag=value` form.
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.split('\\').join('/')
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 unknown = readUnknownFlags(argv, FLAGS)
466
- if (unknown.length > 0) {
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 = readOption(argv, '--package') ?? manifest.name
479
- const dist = readOption(argv, '--dist') ?? 'dist'
480
- const tarball = readOption(argv, '--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 source = await readSource(name, readOption(argv, '--version'), tarball)
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 (argv.includes('--json')) console.log(JSON.stringify(summary))
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, including a flag the script does not read and the
12
- // `--flag=value` form.
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.split('\\').join('/')
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 unknown = readUnknownFlags(argv, FLAGS)
245
- if (unknown.length > 0) {
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 version = readOptions(argv, '--version')[0]
257
- const ranges = readOptions(argv, '--range')
258
- const paths = (readOptions(argv, '--paths')[0] ?? 'src,tests,guides').split(',')
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 (argv.includes('--json')) {
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}`)