@orkestrel/scaffold 0.0.133 → 0.0.134

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 (82) 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 +1018 -194
  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 +95 -108
  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 +27 -3
  25. package/dist/bin/main.js.map +1 -1
  26. package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
  27. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
  28. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
  29. package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
  30. package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
  31. package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
  32. package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
  33. package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
  34. package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
  35. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
  36. package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
  37. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
  38. package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
  39. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
  40. package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
  41. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
  42. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
  43. package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
  44. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1288 -239
  45. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +10 -6
  46. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
  47. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
  48. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
  49. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
  50. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +130 -126
  51. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
  52. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  53. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
  54. package/dist/host/claude/agents/orkestrel.md +4 -4
  55. package/dist/host/claude/rules/documentation.md +1 -1
  56. package/dist/host/claude/rules/patterns.md +5 -4
  57. package/dist/host/claude/rules/styles.md +1 -1
  58. package/dist/host/claude/rules/tests.md +3 -3
  59. package/dist/host/claude/rules/workspace.md +47 -35
  60. package/dist/host/configs/helpers.ts +40 -15
  61. package/dist/host/dotfiles/oxlintrc.json +62 -0
  62. package/dist/host/guides/form.md +79 -4
  63. package/dist/host/guides/scaffold.md +93 -65
  64. package/dist/host/guides/table.md +20 -6
  65. package/dist/host/guides/test.md +9 -7
  66. package/dist/host/manifest.json +44 -44
  67. package/dist/host/tests/config.test.ts +201 -11
  68. package/dist/host/tests/policy.test.ts +14 -21
  69. package/dist/host/tests/setupPolicy.ts +43 -36
  70. package/dist/src/core/index.cjs +191 -93
  71. package/dist/src/core/index.cjs.map +1 -1
  72. package/dist/src/core/index.d.cts +27 -13
  73. package/dist/src/core/index.d.ts +27 -13
  74. package/dist/src/core/index.js +189 -93
  75. package/dist/src/core/index.js.map +1 -1
  76. package/dist/src/server/index.cjs +8 -9
  77. package/dist/src/server/index.cjs.map +1 -1
  78. package/dist/src/server/index.d.cts +1 -1
  79. package/dist/src/server/index.d.ts +1 -1
  80. package/dist/src/server/index.js +8 -9
  81. package/dist/src/server/index.js.map +1 -1
  82. package/package.json +2 -2
@@ -1,37 +1,36 @@
1
- // Compare two commands sample by sample under one host load. Run from the checkout root:
2
- // node .agents/skills/orkestrel-harden/scripts/interleave.ts --plan FILE.json --rounds N [--json] [--out FILE.json|FILE.txt]
3
- // The plan is a JSON object `{ "baseline": SIDE, "candidate": SIDE }`, each side
4
- // `{ "command": "...", "args": ["..."] }` with an optional `"cwd"` (a directory, relative to the
5
- // working directory) and `"env"` (a record of strings laid over this process's environment by
6
- // case-folded name). Identical sides are a supported A/A comparison, which calibrates the run.
7
- // `N` is an even whole number of at least 2. `baseline` runs first in each odd round and `candidate`
8
- // in each even round; an odd count is refused because the side with the extra lead puts its leading
9
- // readings at the median, and that order cost reads as a difference between the sides.
10
- // Each sample is a fresh process with no shell and closed stdin. The reading is the number the
11
- // child prints as its last non-empty standard output line, a finite non-negative decimal with an
12
- // optional fraction and exponent. The script reads no clock, so the child's marked region alone
13
- // decides what a reading covers, and process start stays out of it unless that region includes it.
14
- // A sample that cannot start, ends by a signal, exits nonzero, or prints no reading fails the run:
15
- // the script names the side and the round on stderr, runs no further sample, and prints no report,
16
- // so a statistic never omits a failed sample.
17
- // The report carries each side's samples in round order, its median, its deviation (the median
18
- // absolute deviation, which stays on the median's scale and moves little under one load spike, where
19
- // a standard deviation or a range follows the spike), its minimum and maximum, then `difference`
20
- // (candidate median minus baseline median) and `relative` (`difference` over the baseline median,
21
- // absent when that median is 0). It rules nothing: it carries no bar and no verdict.
22
- // Print text by default or one JSON line with `--json`; `--out` writes `.json` or `.txt`
23
- // independently. Launch the script through `launch.ts` from the dispatch skill for a cap. The script
24
- // refuses a flag it does not read, the `--flag=value` form included, and every positional argument.
25
- // Exit 0 when every sample read, 2 when a sample failed or `--out` could not be written, 64 on usage.
26
1
  import { spawnSync } from 'node:child_process';
27
2
  import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
28
3
  import { dirname, extname, resolve } from 'node:path';
29
- /** Lists the flags that take a value. */
30
- export const VALUE_FLAGS = ['--plan', '--rounds', '--out'];
31
- /** Lists every flag the script reads, value flags and switches alike. */
32
- export const FLAGS = [...VALUE_FLAGS, '--json'];
4
+ import { parseArgs } from 'node:util';
33
5
  /** Holds the usage line printed when a call names no plan or no round count. */
34
6
  export const USAGE = 'usage: interleave.ts --plan FILE.json --rounds N [--json] [--out FILE.json|FILE.txt]';
7
+ /** Declares every flag the script reads, for `parseArgs`. */
8
+ export const OPTIONS = Object.freeze({
9
+ plan: Object.freeze({ type: 'string' }),
10
+ rounds: Object.freeze({ type: 'string' }),
11
+ out: Object.freeze({ type: 'string' }),
12
+ json: Object.freeze({ type: 'boolean' }),
13
+ });
14
+ /**
15
+ * Parses the arguments in strict mode against `OPTIONS`.
16
+ *
17
+ * @param argv - The arguments after the script path.
18
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
19
+ */
20
+ export function parseArguments(argv) {
21
+ try {
22
+ const { values, positionals } = parseArgs({
23
+ args: [...argv],
24
+ options: OPTIONS,
25
+ strict: true,
26
+ allowPositionals: false,
27
+ });
28
+ return { success: true, value: { values, positionals } };
29
+ }
30
+ catch (error) {
31
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
32
+ }
33
+ }
35
34
  /** Caps the characters of an untrusted text a diagnostic echoes. */
36
35
  export const QUOTE_LIMIT = 200;
37
36
  /** Holds the significant digits a text report gives a computed statistic. */
@@ -40,60 +39,6 @@ export const REPORT_PRECISION = 6;
40
39
  export const READING = /^\d+(?:\.\d+)?(?:[eE][-+]?\d+)?$/u;
41
40
  /** Matches a whole number with no sign, exponent, or leading zero. */
42
41
  export const WHOLE = /^[1-9]\d*$/u;
43
- /**
44
- * Reads the value that follows a flag.
45
- *
46
- * @remarks
47
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
48
- * and the `--flag=value` form is not read.
49
- *
50
- * @param argv - The arguments after the script path.
51
- * @param name - The flag, such as `--plan`.
52
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
53
- * another flag.
54
- */
55
- export function readOption(argv, name) {
56
- const index = argv.indexOf(name);
57
- const value = index === -1 ? undefined : argv[index + 1];
58
- return value === undefined || value.startsWith('--') ? undefined : value;
59
- }
60
- /**
61
- * Names the value flags a caller gave with no value.
62
- *
63
- * @param argv - The arguments after the script path.
64
- * @param names - The flags that take a value.
65
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
66
- */
67
- export function readMissingFlags(argv, names) {
68
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
69
- }
70
- /**
71
- * Names the flags a caller gave that the script does not read.
72
- *
73
- * @remarks
74
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
75
- * scan.
76
- *
77
- * @param argv - The arguments after the script path.
78
- * @param flags - Every flag the script reads, value flags and switches alike.
79
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
80
- */
81
- export function readUnknownFlags(argv, flags) {
82
- const end = argv.indexOf('--');
83
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
84
- }
85
- /**
86
- * Reads the arguments the script has no place for: a positional, or a bare `--`, which would open a
87
- * command this script does not pass on.
88
- *
89
- * @param argv - The arguments after the script path.
90
- * @param valueFlags - The flags that take a value.
91
- * @returns Each such argument in order.
92
- */
93
- export function readStrayArguments(argv, valueFlags) {
94
- return argv.filter((argument, index) => (argument === '--' || !argument.startsWith('--')) &&
95
- !valueFlags.includes(argv[index - 1] ?? ''));
96
- }
97
42
  /**
98
43
  * Checks whether a value is a non-null, non-array object.
99
44
  *
@@ -357,7 +302,7 @@ export function runSchedule(sides, schedule) {
357
302
  export function computeMedian(values) {
358
303
  if (values.length === 0)
359
304
  throw new Error('interleave: a median needs at least one number');
360
- const sorted = [...values].sort((left, right) => left - right);
305
+ const sorted = values.toSorted((left, right) => left - right);
361
306
  const middle = sorted.slice(Math.floor((sorted.length - 1) / 2), Math.floor(sorted.length / 2) + 1);
362
307
  return middle.reduce((sum, value) => sum + value, 0) / middle.length;
363
308
  }
@@ -476,35 +421,26 @@ export function writeOutput(path, text) {
476
421
  * written, 64 on usage.
477
422
  */
478
423
  export function main(argv) {
479
- const unknown = readUnknownFlags(argv, FLAGS);
480
- if (unknown.length > 0) {
481
- console.error(`interleave: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`);
482
- return 64;
483
- }
484
- const missing = readMissingFlags(argv, VALUE_FLAGS);
485
- if (missing.length > 0) {
486
- console.error(`interleave: ${missing.join(', ')} given with no value`);
487
- return 64;
488
- }
489
- const stray = readStrayArguments(argv, VALUE_FLAGS);
490
- if (stray.length > 0) {
491
- console.error(`interleave: ${stray.map(quote).join(', ')} is not an argument; ${USAGE}`);
424
+ const parsed = parseArguments(argv);
425
+ if (!parsed.success) {
426
+ console.error(`interleave: ${parsed.error}; ${USAGE}`);
492
427
  return 64;
493
428
  }
494
- const path = readOption(argv, '--plan');
495
- const count = readOption(argv, '--rounds');
496
- const out = readOption(argv, '--out');
429
+ const { values } = parsed.value;
430
+ const path = typeof values.plan === 'string' ? values.plan : undefined;
431
+ const count = typeof values.rounds === 'string' ? values.rounds : undefined;
432
+ const out = typeof values.out === 'string' ? values.out : undefined;
497
433
  if (path === undefined || count === undefined) {
498
434
  console.error(USAGE);
499
435
  return 64;
500
436
  }
501
437
  if (out !== undefined && !['.json', '.txt'].includes(extname(out))) {
502
- console.error(`interleave: --out takes a .json or .txt file, got ${quote(out)}`);
438
+ console.error(`interleave: --out takes a .json or .txt file, not ${quote(out)}; ${USAGE}`);
503
439
  return 64;
504
440
  }
505
441
  const rounds = parseRounds(count);
506
442
  if (rounds === undefined) {
507
- console.error(`interleave: --rounds takes an even whole number of at least 2, got ${quote(count)}`);
443
+ console.error(`interleave: --rounds takes an even whole number of at least 2, not ${quote(count)}; ${USAGE}`);
508
444
  return 64;
509
445
  }
510
446
  const text = readPlanText(path);
@@ -526,7 +462,7 @@ export function main(argv) {
526
462
  const report = computeReport(run.readings);
527
463
  const json = JSON.stringify(report);
528
464
  const rendered = renderReport(report);
529
- console.log(argv.includes('--json') ? json : rendered);
465
+ console.log(values.json === true ? json : rendered);
530
466
  const refusal = out === undefined ? undefined : writeOutput(out, extname(out) === '.json' ? json : rendered);
531
467
  if (refusal !== undefined) {
532
468
  console.error(`interleave: --out could not be written: ${quote(refusal)}`);
@@ -1,32 +1,34 @@
1
- // Count one lint rule's hits before it is enabled. Run from the checkout root:
2
- // node .agents/skills/orkestrel-harden/scripts/measure.ts --rule ID [--options JSON] PATH...
3
- // The script reads the workspace's `.oxlintrc.json` for its `plugins` and `jsPlugins` (a relative
4
- // plugin specifier becomes absolute, so the policy plugin loads from the checkout), writes a
5
- // variant config that enables only `ID` as an error under `tmp/probes/lint/<ID>/.oxlintrc.json`,
6
- // runs the installed oxlint with `--format json` over the named paths from the checkout root, and
7
- // prints `rule=ID hits=N files=N` then one `N<TAB>path` line per file with a hit, most hits first.
8
- // `--options` is a JSON value given to the rule: an array spreads into the rule's arguments after
9
- // `error`, any other value is the one argument. The workspace's `ignorePatterns` and its override
10
- // blocks are not carried over, so a rule measured here reads exactly the named paths with no
11
- // per-file override. A rule that reads `context.cwd` must run from the checkout root, so run the
12
- // script there. Enable only the rule under measure to count a rule the workspace might drop. A hit
13
- // is a diagnostic whose `code` names the rule (`<plugin>(<name>)`, with `eslint` for an unprefixed
14
- // id and the plugin's own scope for a built-in plugin such as `typescript-eslint`); any other
15
- // diagnostic, a parse error included, is not a hit and refuses the measurement, because a file the
16
- // linter could not read has no count. A linter that exits other than 0 or 1, or exits 1 with no
17
- // diagnostic, refuses it too. The script refuses a flag it does not read, the `--flag=value` form
18
- // included, and names an unknown flag before a flag given with no value.
19
- // Exit 0 when the rule has no hit, 3 when it has, 2 when the linter cannot run or reports another
20
- // diagnostic, 64 on usage.
21
1
  import { spawnSync } from 'node:child_process';
22
2
  import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
23
3
  import { isAbsolute, join, resolve } from 'node:path';
24
- /** Lists the flags that take a value. */
25
- export const VALUE_FLAGS = ['--rule', '--options'];
26
- /** Lists every flag the script reads, value flags and switches alike. */
27
- export const FLAGS = VALUE_FLAGS;
4
+ import { parseArgs } from 'node:util';
28
5
  /** Holds the usage line printed when a call names no rule or no path. */
29
6
  export const USAGE = 'usage: measure.ts --rule ID [--options JSON] PATH...';
7
+ /** Declares every flag the script reads, for `parseArgs`. */
8
+ export const OPTIONS = Object.freeze({
9
+ rule: Object.freeze({ type: 'string' }),
10
+ options: Object.freeze({ type: 'string' }),
11
+ });
12
+ /**
13
+ * Parses the arguments in strict mode against `OPTIONS`.
14
+ *
15
+ * @param argv - The arguments after the script path.
16
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
17
+ */
18
+ export function parseArguments(argv) {
19
+ try {
20
+ const { values, positionals } = parseArgs({
21
+ args: [...argv],
22
+ options: OPTIONS,
23
+ strict: true,
24
+ allowPositionals: true,
25
+ });
26
+ return { success: true, value: { values, positionals } };
27
+ }
28
+ catch (error) {
29
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
30
+ }
31
+ }
30
32
  /** Holds the directory, under the working directory, that keeps the variant configs. */
31
33
  export const PROBE_ROOT = 'tmp/probes/lint';
32
34
  /** Holds the linter entry, under the working directory, that the script runs. */
@@ -37,58 +39,6 @@ export const CODE_SCOPES = Object.freeze({
37
39
  node: 'eslint-plugin-n',
38
40
  nextjs: 'eslint-plugin-next',
39
41
  });
40
- /**
41
- * Reads the value that follows a flag.
42
- *
43
- * @remarks
44
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
45
- * and the `--flag=value` form is not read.
46
- *
47
- * @param argv - The arguments after the script path.
48
- * @param name - The flag, such as `--rule`.
49
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
50
- * another flag.
51
- */
52
- export function readOption(argv, name) {
53
- const index = argv.indexOf(name);
54
- const value = index === -1 ? undefined : argv[index + 1];
55
- return value === undefined || value.startsWith('--') ? undefined : value;
56
- }
57
- /**
58
- * Names the value flags a caller gave with no value.
59
- *
60
- * @param argv - The arguments after the script path.
61
- * @param names - The flags that take a value.
62
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
63
- */
64
- export function readMissingFlags(argv, names) {
65
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
66
- }
67
- /**
68
- * Names the flags a caller gave that the script does not read.
69
- *
70
- * @remarks
71
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
72
- * scan.
73
- *
74
- * @param argv - The arguments after the script path.
75
- * @param flags - Every flag the script reads, value flags and switches alike.
76
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
77
- */
78
- export function readUnknownFlags(argv, flags) {
79
- const end = argv.indexOf('--');
80
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
81
- }
82
- /**
83
- * Reads the arguments that are neither a flag nor the value of a value flag.
84
- *
85
- * @param argv - The arguments after the script path.
86
- * @param valueFlags - The flags that take a value.
87
- * @returns The positional arguments in order.
88
- */
89
- export function readPositionals(argv, valueFlags) {
90
- return argv.filter((argument, index) => !argument.startsWith('--') && !valueFlags.includes(argv[index - 1] ?? ''));
91
- }
92
42
  /**
93
43
  * Checks whether a value is a non-null, non-array object.
94
44
  *
@@ -105,7 +55,7 @@ export function isRecord(value) {
105
55
  * @returns The same path with every backslash replaced by a slash.
106
56
  */
107
57
  export function normalizeSlashes(path) {
108
- return path.split('\\').join('/');
58
+ return path.replaceAll('\\', '/');
109
59
  }
110
60
  /**
111
61
  * Quotes an untrusted text for a diagnostic, JSON-encoded and cut to a bounded length.
@@ -302,25 +252,26 @@ export function formatHits(rule, hits) {
302
252
  * 64 on usage.
303
253
  */
304
254
  export function main(argv) {
305
- const unknown = readUnknownFlags(argv, FLAGS);
306
- if (unknown.length > 0) {
307
- console.error(`measure: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`);
255
+ const parsed = parseArguments(argv);
256
+ if (!parsed.success) {
257
+ console.error(`measure: ${parsed.error}; ${USAGE}`);
308
258
  return 64;
309
259
  }
310
- const missing = readMissingFlags(argv, VALUE_FLAGS);
311
- if (missing.length > 0) {
312
- console.error(`measure: ${missing.join(', ')} given with no value`);
313
- return 64;
314
- }
315
- const rule = readOption(argv, '--rule');
316
- const paths = readPositionals(argv, VALUE_FLAGS);
260
+ const { values, positionals: paths } = parsed.value;
261
+ const rule = typeof values.rule === 'string' ? values.rule : undefined;
317
262
  if (rule === undefined || paths.length === 0) {
318
263
  console.error(USAGE);
319
264
  return 64;
320
265
  }
321
- const options = readRuleOptions(readOption(argv, '--options'));
266
+ const dashed = paths.filter((path) => path.startsWith('-'));
267
+ if (dashed.length > 0) {
268
+ console.error(`measure: PATH takes a path that does not open with "-", which the linter reads as a flag, not ${dashed.map(quote).join(', ')}; ${USAGE}`);
269
+ return 64;
270
+ }
271
+ const text = typeof values.options === 'string' ? values.options : undefined;
272
+ const options = readRuleOptions(text);
322
273
  if (options === undefined) {
323
- console.error(`measure: --options ${quote(readOption(argv, '--options') ?? '')} is not JSON`);
274
+ console.error(`measure: --options takes a JSON value, not ${quote(text ?? '')}; ${USAGE}`);
324
275
  return 64;
325
276
  }
326
277
  const root = process.cwd();
@@ -1,37 +1,36 @@
1
- // Run from the checkout root:
2
- // node .agents/skills/orkestrel-harden/scripts/titles.ts --base REV [--root DIR] [--json] [--out FILE]
3
- // Each value is a separate argument: `--flag=value` and any flag the script does not read exit 64,
4
- // and so does a REV that opens with `-`. The baseline is read from the tree REV names, resolved
5
- // once with `--end-of-options`, with paths relative to --root, so a --root below the repository top
6
- // works.
7
- // Compare exact decoded describe/it/test/suite title counts in tests/**/*.test.ts against REV. A
8
- // baseline title with a deficit is moved when another tests/**/*.ts string literal spells it, and
9
- // missing otherwise. A moved row is a claim to rule, not proof: a literal that only spells the
10
- // title (an assertion value, a data table) also holds it, so the reader rules each moved row by
11
- // reading its holder, as it rules each missing row. Read a registration at any token position, with
12
- // its modifiers: `.each` tables (call or tagged template) and `.skipIf(...)` and `.runIf(...)` read
13
- // the title of the call that follows. A title that is no string or template literal is a dynamic
14
- // row, named per tree with its source spelling: the comparison cannot follow it, and a removed
15
- // `.each` table row leaves its one registered title in place. A file with fewer dynamic
16
- // registrations than at REV is a lost-dynamic row, which the comparison cannot rule on, so it
17
- // exits 3 as a missing row does. A title registered through an alias (a `test.extend` result bound
18
- // to another name, or `const spec = it`) is not read, and a `test.extend({...})` call itself reads
19
- // as one dynamic registration. Decode quote and backslash escapes only.
20
- // Balance each-table parentheses over code tokens, skipping lexical regions. Print text by default
21
- // or one JSON line with --json; --out writes .json or .txt independently. Text rows escape tab and
22
- // newline. Compare interpolated templates by full raw spelling. Refuse unclosed lexical tokens.
23
- // Track lexical brace context without a syntax tree. Function-expression and arrow bodies cannot
24
- // establish a following slash's grammar; refuse that detectable ambiguity instead of claiming a move.
25
- // Only .test.ts files register titles; a .test.tsx or .test.mts file is invisible to it.
26
- // Exit 0 with no missing or moved titles and no lost-dynamic file, 3 with any, 2 on git, filesystem
27
- // or token refusal, 64 on usage.
28
1
  import { spawnSync } from 'node:child_process';
29
2
  import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from 'node:fs';
30
3
  import { dirname, extname, join, relative, resolve } from 'node:path';
31
- /** Lists the flags this script reads, value flags and switches alike. */
32
- export const FLAGS = ['--base', '--root', '--json', '--out'];
4
+ import { parseArgs } from 'node:util';
33
5
  /** Holds the usage line printed on a usage refusal. */
34
6
  export const USAGE = 'usage: titles.ts --base REV [--root DIR] [--json] [--out FILE.json|FILE.txt]';
7
+ /** Declares every flag the script reads, for `parseArgs`. */
8
+ export const OPTIONS = Object.freeze({
9
+ base: Object.freeze({ type: 'string' }),
10
+ root: Object.freeze({ type: 'string' }),
11
+ json: Object.freeze({ type: 'boolean' }),
12
+ out: Object.freeze({ type: 'string' }),
13
+ });
14
+ /**
15
+ * Parses the arguments in strict mode against `OPTIONS`.
16
+ *
17
+ * @param argv - The arguments after the script path.
18
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
19
+ */
20
+ export function parseArguments(argv) {
21
+ try {
22
+ const { values, positionals } = parseArgs({
23
+ args: [...argv],
24
+ options: OPTIONS,
25
+ strict: true,
26
+ allowPositionals: false,
27
+ });
28
+ return { success: true, value: { values, positionals } };
29
+ }
30
+ catch (error) {
31
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
32
+ }
33
+ }
35
34
  /** Caps the characters of a name an error message echoes. */
36
35
  export const NAME_LIMIT = 80;
37
36
  /** Names the directories a tree walk skips, so build output and notes stay unread. */
@@ -62,49 +61,7 @@ export const CLOSERS = [')', ']', '}'];
62
61
  * @returns The same path with every backslash replaced by a slash.
63
62
  */
64
63
  export function normalizeSlashes(path) {
65
- return path.split('\\').join('/');
66
- }
67
- /**
68
- * Reads the value that follows a flag.
69
- *
70
- * @remarks
71
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
72
- * and the `--flag=value` form is not read.
73
- *
74
- * @param argv - The arguments after the script path.
75
- * @param name - The flag, such as `--base`.
76
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
77
- * another flag.
78
- */
79
- export function readOption(argv, name) {
80
- const index = argv.indexOf(name);
81
- const value = index === -1 ? undefined : argv[index + 1];
82
- return value === undefined || value.startsWith('--') ? undefined : value;
83
- }
84
- /**
85
- * Names the value flags a caller gave with no value.
86
- *
87
- * @param argv - The arguments after the script path.
88
- * @param names - The flags that take a value.
89
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
90
- */
91
- export function readMissingFlags(argv, names) {
92
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
93
- }
94
- /**
95
- * Names the flags a caller gave that the script does not read.
96
- *
97
- * @remarks
98
- * Reads the arguments before a bare `--`. A `--flag=value` argument is unknown, because the script
99
- * reads `--flag value` pairs only.
100
- *
101
- * @param argv - The arguments after the script path.
102
- * @param flags - Every flag the script reads, value flags and switches alike.
103
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
104
- */
105
- export function readUnknownFlags(argv, flags) {
106
- const end = argv.indexOf('--');
107
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
64
+ return path.replaceAll('\\', '/');
108
65
  }
109
66
  /**
110
67
  * Lists every regular file beneath a directory, skipping the named directories at any depth.
@@ -671,28 +628,25 @@ export function renderReport(report) {
671
628
  * failure, 64 usage.
672
629
  */
673
630
  export function main(argv) {
674
- const unknown = readUnknownFlags(argv, FLAGS);
675
- if (unknown.length > 0) {
676
- console.error(`titles: ${unknown.map(describeName).join(', ')} is not a flag this script reads; give each value as its own argument. ${USAGE}`);
677
- return 64;
678
- }
679
- const missing = readMissingFlags(argv, ['--base', '--root', '--out']);
680
- if (missing.length > 0) {
681
- console.error(`titles: ${missing.join(', ')} given with no value`);
631
+ const parsed = parseArguments(argv);
632
+ if (!parsed.success) {
633
+ console.error(`titles: ${parsed.error}; ${USAGE}`);
682
634
  return 64;
683
635
  }
684
- const base = readOption(argv, '--base');
685
- const out = readOption(argv, '--out');
686
- if (base === undefined || (out !== undefined && !['.json', '.txt'].includes(extname(out)))) {
636
+ const { values } = parsed.value;
637
+ const base = typeof values.base === 'string' ? values.base : undefined;
638
+ const out = typeof values.out === 'string' ? values.out : undefined;
639
+ if (base === undefined) {
687
640
  console.error(USAGE);
688
641
  return 64;
689
642
  }
690
- if (base.startsWith('-')) {
691
- console.error(`titles: --base ${describeName(base)} opens with "-"; give a revision name or hash`);
643
+ if (out !== undefined && !['.json', '.txt'].includes(extname(out))) {
644
+ console.error(`titles: --out takes a .json or .txt file, not ${describeName(out)}; ${USAGE}`);
692
645
  return 64;
693
646
  }
694
647
  try {
695
- const report = readReport(base, resolve(readOption(argv, '--root') ?? process.cwd()));
648
+ const root = typeof values.root === 'string' ? values.root : process.cwd();
649
+ const report = readReport(base, resolve(root));
696
650
  const json = JSON.stringify(report);
697
651
  const text = renderReport(report);
698
652
  if (out !== undefined) {
@@ -700,7 +654,7 @@ export function main(argv) {
700
654
  mkdirSync(dirname(target), { recursive: true });
701
655
  writeFileSync(target, `${extname(target) === '.json' ? json : text}\n`);
702
656
  }
703
- console.log(argv.includes('--json') ? json : text);
657
+ console.log(values.json === true ? json : text);
704
658
  return report.missing.length + report.moved.length + report.lostDynamic.length > 0 ? 3 : 0;
705
659
  }
706
660
  catch (error) {