@venizia/vulcan 0.4.9-0 → 0.4.9-2

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 (141) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +2 -2
  3. package/base/hooks/codex-guards.ts +15 -5
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +4 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +5 -6
  8. package/base/hooks/guard-remote-hosts.ts +6 -7
  9. package/base/hooks/guard-scripting.ts +5 -6
  10. package/base/hooks/guard-writes.ts +8 -9
  11. package/base/hooks/post-tool.ts +2 -2
  12. package/base/hooks/prompt-submit.ts +2 -2
  13. package/base/hooks/session-start.ts +3 -3
  14. package/base/hooks/stop.ts +2 -2
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/skills/docs-update/SKILL.md +4 -2
  17. package/base/skills/visualize-work/SKILL.md +9 -0
  18. package/package.json +3 -3
  19. package/src/agents/atlas-block.ts +43 -43
  20. package/src/agents/codex-hooks.ts +45 -43
  21. package/src/agents/detect.ts +19 -16
  22. package/src/agents/exclude.ts +96 -97
  23. package/src/agents/hooks-json.ts +38 -36
  24. package/src/agents/local.ts +46 -43
  25. package/src/agents/prompt.ts +45 -42
  26. package/src/agents/render.ts +201 -195
  27. package/src/agents/resolve.ts +133 -134
  28. package/src/agents/table.ts +12 -8
  29. package/src/commands/add.command.ts +2 -2
  30. package/src/commands/agents.command.ts +11 -17
  31. package/src/commands/clean.command.ts +6 -6
  32. package/src/commands/doctor.command.ts +4 -4
  33. package/src/commands/init.command.ts +12 -8
  34. package/src/commands/preset.command.ts +2 -2
  35. package/src/commands/profile.command.ts +42 -49
  36. package/src/commands/sync.command.ts +109 -111
  37. package/src/commands/upgrade.command.ts +80 -75
  38. package/src/commands/visualize.command.ts +7 -13
  39. package/src/commands/x.command.ts +55 -50
  40. package/src/common/format.ts +23 -21
  41. package/src/common/json.ts +8 -5
  42. package/src/common/layout-folder.ts +94 -91
  43. package/src/common/paths.ts +14 -12
  44. package/src/config/loader.ts +52 -49
  45. package/src/config/packages.ts +14 -11
  46. package/src/config/schema.ts +3 -3
  47. package/src/create/add-app.ts +519 -509
  48. package/src/create/add-lib.ts +237 -240
  49. package/src/create/bunfig.ts +26 -23
  50. package/src/create/checks.ts +36 -34
  51. package/src/create/diff.ts +21 -23
  52. package/src/create/dockerignore.ts +26 -24
  53. package/src/create/files.ts +7 -5
  54. package/src/create/init-monorepo.ts +75 -80
  55. package/src/create/lib-preset.ts +59 -63
  56. package/src/create/manifest-json.ts +10 -4
  57. package/src/create/names.ts +217 -210
  58. package/src/create/next.ts +26 -23
  59. package/src/create/plan.ts +15 -12
  60. package/src/create/preset-diff.ts +301 -303
  61. package/src/create/preset-menu.ts +38 -32
  62. package/src/create/preset.ts +202 -197
  63. package/src/create/process.ts +79 -72
  64. package/src/create/scratch.ts +48 -49
  65. package/src/create/workspace.ts +404 -396
  66. package/src/doctor/checks.ts +1027 -1014
  67. package/src/doctor/makefile.ts +17 -13
  68. package/src/doctor/runner.ts +88 -118
  69. package/src/doctor/skills.ts +97 -95
  70. package/src/doctor/tags.ts +42 -37
  71. package/src/hooks/codex-patch.ts +25 -22
  72. package/src/hooks/command-view.ts +44 -39
  73. package/src/hooks/decision.ts +37 -37
  74. package/src/hooks/guard-git.ts +51 -49
  75. package/src/hooks/guard-manifest.ts +58 -55
  76. package/src/hooks/guard-outside.ts +93 -91
  77. package/src/hooks/guard-package.ts +82 -79
  78. package/src/hooks/guard-scripting.ts +19 -14
  79. package/src/hooks/guard-writes.ts +154 -149
  80. package/src/hooks/owner-reply.ts +127 -127
  81. package/src/hooks/post-tool.ts +94 -93
  82. package/src/hooks/project-guards.ts +65 -62
  83. package/src/hooks/project-tmp.ts +27 -24
  84. package/src/hooks/remote-hosts.ts +153 -130
  85. package/src/hooks/session-digest.ts +98 -101
  86. package/src/hooks/shell.ts +509 -499
  87. package/src/hooks/subagent-card.ts +11 -7
  88. package/src/hooks/trusted-scripts.ts +106 -104
  89. package/src/init/scaffold.ts +135 -132
  90. package/src/local/clean.ts +38 -36
  91. package/src/local/format.ts +21 -17
  92. package/src/local/scan.ts +144 -138
  93. package/src/manifest/render.ts +110 -104
  94. package/src/owner/card.ts +51 -46
  95. package/src/owner/profile.ts +99 -93
  96. package/src/owner/reply-switch.ts +9 -6
  97. package/src/owner/shape.ts +71 -69
  98. package/src/owner/survey.ts +173 -171
  99. package/src/owner/view.ts +62 -59
  100. package/src/owner/violations.ts +119 -123
  101. package/src/rules/base.ts +15 -11
  102. package/src/rules/parser.ts +39 -32
  103. package/src/rules/slots.ts +8 -6
  104. package/src/signals/claims.ts +30 -28
  105. package/src/signals/classify.ts +38 -33
  106. package/src/signals/loop.ts +39 -37
  107. package/src/signals/state.ts +79 -81
  108. package/src/skills/frontmatter.ts +28 -28
  109. package/src/sync/agent-files.ts +217 -199
  110. package/src/sync/agent-removal.ts +56 -59
  111. package/src/sync/atlas-block.ts +45 -43
  112. package/src/sync/base-rules.ts +32 -30
  113. package/src/sync/claude-launch.ts +36 -34
  114. package/src/sync/exclude.ts +77 -69
  115. package/src/sync/local-choice.ts +50 -47
  116. package/src/sync/planner.ts +59 -61
  117. package/src/sync/prune.ts +52 -48
  118. package/src/sync/settings.ts +166 -167
  119. package/src/ui/capability.ts +12 -7
  120. package/src/ui/keyboard.ts +38 -38
  121. package/src/ui/prompt.ts +79 -77
  122. package/src/visualize/assets.ts +33 -24
  123. package/src/visualize/charts.ts +179 -176
  124. package/src/visualize/compare-css.ts +3 -2
  125. package/src/visualize/compare-render.ts +9 -7
  126. package/src/visualize/diagrams.ts +189 -174
  127. package/src/visualize/grid-span.ts +34 -0
  128. package/src/visualize/icons.ts +7 -5
  129. package/src/visualize/kinds-render.ts +50 -45
  130. package/src/visualize/kinds-validate.ts +12 -10
  131. package/src/visualize/labels.ts +21 -17
  132. package/src/visualize/layout.ts +112 -97
  133. package/src/visualize/page.ts +92 -104
  134. package/src/visualize/render.ts +143 -140
  135. package/src/visualize/sections.ts +395 -384
  136. package/src/visualize/sources.ts +2 -2
  137. package/src/visualize/theme.ts +12 -10
  138. package/src/visualize/validate.ts +13 -9
  139. package/src/wiki/anchors.ts +38 -36
  140. package/src/wiki/command.ts +4 -4
  141. package/src/wiki/source-links.ts +46 -44
@@ -115,36 +115,6 @@ const WRAPPER_OPTIONS: Record<string, IWrapperOptions> = {
115
115
  /** The programs whose words after their own options are the command they run. */
116
116
  const WRAPPERS = new Set(Object.keys(WRAPPER_OPTIONS).filter((name) => name !== 'sshpass'));
117
117
 
118
- /** Whether the option word `word` of `wrapper` takes the next word as its value. */
119
- export const optionTakesNextWord = (opts: { wrapper: string; word: string }): boolean => {
120
- const options = WRAPPER_OPTIONS[opts.wrapper];
121
-
122
- if (options === undefined || !opts.word.startsWith('-') || opts.word === '-') {
123
- return false;
124
- }
125
-
126
- // A long option may be shortened to any prefix (`--adj 5` is `--adjustment 5`), as getopt_long reads it.
127
- if (opts.word.startsWith('--')) {
128
- const name = opts.word.slice(2);
129
-
130
- return (
131
- name !== '' &&
132
- !name.includes('=') &&
133
- options.longValues.some((long) => long.slice(2).startsWith(name))
134
- );
135
- }
136
-
137
- // A cluster such as `-nu`: the first letter that takes a value ends it; with letters left after it the
138
- // rest is the value, and with none left the value is the next word.
139
- for (let at = 1; at < opts.word.length; at += 1) {
140
- if (options.shortValues.includes(opts.word[at] ?? '')) {
141
- return at === opts.word.length - 1;
142
- }
143
- }
144
-
145
- return false;
146
- };
147
-
148
118
  /** The plain words a wrapper takes before its command (`timeout 5 cmd`). */
149
119
  const wrapperPositionals = (opts: { wrapper: string }): number =>
150
120
  WRAPPER_OPTIONS[opts.wrapper]?.positionals ?? 0;
@@ -158,23 +128,8 @@ export class ShellPrograms {
158
128
  }
159
129
 
160
130
  const SHELLS = new Set(ShellPrograms.SHELL_NAMES);
161
- const MAX_DEPTH = 4;
162
-
163
- /** What the parser reads of one command line at most: a guard that reads more would be slow, and a slow guard is skipped. */
164
- export class ShellBudget {
165
- static readonly MAX_COMMANDS = 2000;
166
- static readonly MAX_WORDS = 20_000;
167
- /** The characters of a line and of every text nested in it, together: a line over it is not read at all. */
168
- static readonly MAX_CHARS = 100_000;
169
- }
170
131
 
171
- interface IBudget {
172
- commands: number;
173
- words: number;
174
- chars: number;
175
- /** Something was not read: the budget ran out, or a command nests deeper than the depth limit. */
176
- isOver: boolean;
177
- }
132
+ const MAX_DEPTH = 4;
178
133
 
179
134
  /**
180
135
  * The index of the character that closes what was opened just before `from` (`$(` or a backtick), or the end
@@ -397,9 +352,6 @@ const readWord = (opts: { text: string; from: number }): IWordRead => {
397
352
  /** `NAME=value`: a leading assignment, not a program. */
398
353
  const isAssignment = (opts: { word: string }): boolean => /^[A-Za-z_]\w*=/.test(opts.word);
399
354
 
400
- export const basenameOf = (opts: { word: string }): string =>
401
- opts.word.split('/').pop() ?? opts.word;
402
-
403
355
  /**
404
356
  * The command line `env -S` (`--split-string`) holds in one word, from its value on: `-S 'a b'`, `-S'a b'`,
405
357
  * `-iS 'a b'`, `--split-string='a b'`, `--split-string 'a b'`. `takesNext` says the value is the next word.
@@ -458,72 +410,26 @@ const ENV_ESCAPES: Record<string, string> = {
458
410
  };
459
411
 
460
412
  /**
461
- * The words `env -S` makes of its value, by `env`'s own rules and not the shell's: blanks separate, quotes
462
- * group (in single quotes only `\\\\` and `\\'` are escapes), `\\_` separates outside double quotes and is a
463
- * space inside them, `\\c` ends the string, a `#` at the start of a word starts a comment, and `;`, `|`
464
- * and `$(...)` mean nothing. An empty quoted string is a word.
413
+ * The delimiter of a heredoc started on `line`: a `<<WORD` outside quotes. `<<<` is a here-string, and a `<<`
414
+ * inside quotes is text.
465
415
  */
466
- export const splitEnvString = (opts: { value: string }): string[] => {
467
- const { value } = opts;
468
- const words: string[] = [];
469
- let current = '';
470
- let hasWord = false;
416
+ const heredocOf = (opts: {
417
+ line: string;
418
+ }): { delimiter: string; stripTabs: boolean; at: number } | undefined => {
419
+ const { line } = opts;
471
420
  let quote: string | undefined;
472
421
 
473
- const flush = (): void => {
474
- if (hasWord) {
475
- words.push(current);
476
- }
477
-
478
- current = '';
479
- hasWord = false;
480
- };
481
-
482
- for (let index = 0; index < value.length; index += 1) {
483
- const char = value[index] ?? '';
484
-
485
- if (char === '\\') {
486
- const next = value[index + 1];
422
+ for (let index = 0; index < line.length; index += 1) {
423
+ const char = line[index];
487
424
 
425
+ if (char === '\\' && quote !== "'") {
488
426
  index += 1;
489
-
490
- if (next === undefined) {
491
- break;
492
- }
493
-
494
- // In single quotes only `\\` and `\'` are escapes: every other backslash stays, `\c` and `\_` included.
495
- if (quote === "'") {
496
- current += next === '\\' || next === "'" ? next : `\\${next}`;
497
- hasWord = true;
498
- continue;
499
- }
500
-
501
- if (next === 'c') {
502
- break;
503
- }
504
-
505
- if (next === '_') {
506
- if (quote === '"') {
507
- current += ' ';
508
- hasWord = true;
509
- } else {
510
- flush();
511
- }
512
-
513
- continue;
514
- }
515
-
516
- current += ENV_ESCAPES[next] ?? next;
517
- hasWord = true;
518
427
  continue;
519
428
  }
520
429
 
521
430
  if (quote !== undefined) {
522
431
  if (char === quote) {
523
432
  quote = undefined;
524
- } else {
525
- current += char;
526
- hasWord = true;
527
433
  }
528
434
 
529
435
  continue;
@@ -531,536 +437,640 @@ export const splitEnvString = (opts: { value: string }): string[] => {
531
437
 
532
438
  if (char === "'" || char === '"') {
533
439
  quote = char;
534
- hasWord = true;
535
440
  continue;
536
441
  }
537
442
 
538
- if (char === '#' && !hasWord) {
539
- break;
540
- }
443
+ if (char === '<' && line[index + 1] === '<') {
444
+ if (line[index + 2] === '<') {
445
+ index += 2;
446
+ continue;
447
+ }
541
448
 
542
- if (/\s/.test(char)) {
543
- flush();
544
- continue;
545
- }
449
+ const match = /^<<(-?)\s*(["']?)([A-Za-z_]\w*)\2/.exec(line.slice(index));
546
450
 
547
- current += char;
548
- hasWord = true;
451
+ if (match !== null) {
452
+ return { delimiter: match[3] ?? '', stripTabs: match[1] === '-', at: index };
453
+ }
454
+
455
+ index += 1;
456
+ }
549
457
  }
550
458
 
551
- flush();
459
+ return undefined;
460
+ };
552
461
 
553
- return words;
462
+ /** Appends every item; a spread into `push` overflows the stack at a few hundred thousand items. */
463
+ const pushAll = (opts: { target: string[]; items: string[] }): void => {
464
+ for (const item of opts.items) {
465
+ opts.target.push(item);
466
+ }
554
467
  };
555
468
 
556
- /**
557
- * The program a command runs, past wrappers such as `sudo`, `env` and `time`, and the command `env -S`
558
- * carries: the words `env` makes of the value, then the words after it, behind an `env` word, so its own
559
- * options inside the value apply. Only the first `-S` of a command counts: it holds the rest of the line.
560
- * `--` ends the options, so a word after it is the program even when it starts with a dash.
561
- */
562
- export const programOf = (opts: {
563
- command: ISimpleCommand;
564
- }): { name: string; index: number; args: string[]; splitCommands: string[][] } => {
565
- let index = 0;
566
- let wrapper = '';
567
- let positionals = 0;
568
- let optionsEnded = false;
569
- const splitCommands: string[][] = [];
570
-
571
- while (index < opts.command.words.length) {
572
- const word = opts.command.words[index];
573
-
574
- if (WRAPPERS.has(basenameOf({ word }))) {
575
- wrapper = basenameOf({ word });
576
- positionals = wrapperPositionals({ wrapper });
577
- optionsEnded = false;
578
- index += 1;
579
- continue;
580
- }
469
+ /** What the parser reads of one command line at most: a guard that reads more would be slow, and a slow guard is skipped. */
470
+ export class ShellBudget {
471
+ static readonly MAX_COMMANDS = 2000;
472
+ static readonly MAX_WORDS = 20_000;
473
+ /** The characters of a line and of every text nested in it, together: a line over it is not read at all. */
474
+ static readonly MAX_CHARS = 100_000;
475
+ }
581
476
 
582
- if (isAssignment({ word }) || KEYWORDS.has(word)) {
583
- index += 1;
584
- continue;
477
+ export class ShellParser {
478
+ /** The program of the last simple command of `prefix`: what a heredoc that starts after it is fed to. */
479
+ private static programBefore(opts: { prefix: string }): string {
480
+ const { prefix } = opts;
481
+ let words: string[] = [];
482
+ let index = 0;
483
+
484
+ while (index < prefix.length) {
485
+ const char = prefix[index] ?? '';
486
+
487
+ if (char === ' ' || char === '\t') {
488
+ index += 1;
489
+ continue;
490
+ }
491
+
492
+ if (';|&()\n'.includes(char)) {
493
+ words = [];
494
+ index += 1;
495
+ continue;
496
+ }
497
+
498
+ if (char === '>' || char === '<') {
499
+ // A redirect and its target are not words of the command.
500
+ let cursor = index + 1;
501
+
502
+ while (prefix[cursor] === '>' || prefix[cursor] === '&' || prefix[cursor] === ' ') {
503
+ cursor += 1;
504
+ }
505
+
506
+ index = Math.max(readWord({ text: prefix, from: cursor }).next, index + 1);
507
+ continue;
508
+ }
509
+
510
+ const word = readWord({ text: prefix, from: index });
511
+
512
+ words.push(word.value);
513
+ index = Math.max(word.next, index + 1);
585
514
  }
586
515
 
587
- if (word === '--') {
588
- optionsEnded = true;
589
- index += 1;
590
- continue;
516
+ return ShellParser.basenameOf({
517
+ word: ShellParser.programOf({ command: { words, redirects: [], assignments: [] } }).name,
518
+ });
519
+ }
520
+
521
+ /**
522
+ * The command lines a command carries as text: the script of `sh -c`, the words of `eval`, and the string
523
+ * `watch` joins its words into and hands to a shell (`watch 'git push'`).
524
+ */
525
+ private static nestedScripts(opts: {
526
+ command: ISimpleCommand;
527
+ program: ReturnType<typeof ShellParser.programOf>;
528
+ }): string[] {
529
+ const { command, program } = opts;
530
+
531
+ if (program.index === -1) {
532
+ return [];
591
533
  }
592
534
 
593
- if (!optionsEnded && /^-/.test(word)) {
594
- const split =
595
- wrapper === 'env' && splitCommands.length === 0
596
- ? splitStringOf({ word, next: opts.command.words[index + 1] })
597
- : undefined;
598
-
599
- if (split !== undefined && split.value !== '') {
600
- splitCommands.push([
601
- 'env',
602
- ...splitEnvString({ value: split.value }),
603
- ...opts.command.words.slice(index + (split.takesNext ? 2 : 1)),
604
- ]);
535
+ const name = ShellParser.basenameOf({ word: program.name });
536
+ const scripts: string[] = [];
537
+
538
+ if (SHELLS.has(name)) {
539
+ const flag = command.words.findIndex(
540
+ (word, position) => position > program.index && /^-[a-zA-Z]*c$/.test(word),
541
+ );
542
+ const script = flag === -1 ? undefined : command.words[flag + 1];
543
+
544
+ if (script !== undefined) {
545
+ scripts.push(script);
605
546
  }
547
+ }
606
548
 
607
- // An option of the wrapper; `-u X` and `nice -n 5` take a value that is not the program.
608
- index += optionTakesNextWord({ wrapper, word }) ? 2 : 1;
609
- continue;
549
+ if (name === 'eval') {
550
+ scripts.push(program.args.join(' '));
610
551
  }
611
552
 
612
- // `timeout 5 cmd`: a plain word the wrapper itself takes.
613
- if (positionals > 0) {
614
- positionals -= 1;
615
- index += 1;
616
- continue;
553
+ if (
554
+ /\s/.test(program.name) &&
555
+ command.words
556
+ .slice(0, program.index)
557
+ .some((word) => ShellParser.basenameOf({ word }) === 'watch')
558
+ ) {
559
+ scripts.push([program.name, ...program.args].join(' '));
617
560
  }
618
561
 
619
- return { name: word, index, args: opts.command.words.slice(index + 1), splitCommands };
562
+ return scripts;
620
563
  }
621
564
 
622
- return { name: '', index: -1, args: [], splitCommands };
623
- };
565
+ /** Whether the command carries another command line to read: a script, an eval, a `watch` string, or an `env -S`. */
566
+ private static nests(opts: { command: ISimpleCommand }): boolean {
567
+ const program = ShellParser.programOf({ command: opts.command });
624
568
 
625
- /**
626
- * The delimiter of a heredoc started on `line`: a `<<WORD` outside quotes. `<<<` is a here-string, and a `<<`
627
- * inside quotes is text.
628
- */
629
- const heredocOf = (opts: {
630
- line: string;
631
- }): { delimiter: string; stripTabs: boolean; at: number } | undefined => {
632
- const { line } = opts;
633
- let quote: string | undefined;
569
+ return (
570
+ program.splitCommands.length > 0 ||
571
+ ShellParser.nestedScripts({ command: opts.command, program }).length > 0
572
+ );
573
+ }
634
574
 
635
- for (let index = 0; index < line.length; index += 1) {
636
- const char = line[index];
575
+ /**
576
+ * The simple commands of a shell line, in order: `;`, `&&`, `||`, `|`, `&` and newlines split them;
577
+ * `$(...)`, backticks, `sh -c '...'` arguments and the command line of `env -S` are parsed as commands too. It
578
+ * reads quoting, not every corner of the shell: a line it cannot follow yields fewer commands, never an error.
579
+ */
580
+ private static parseWithBudget(opts: {
581
+ command: string;
582
+ depth: number;
583
+ budget: IBudget;
584
+ }): ISimpleCommand[] {
585
+ const { depth, budget } = opts;
586
+
587
+ // The characters of every text read count together, nested texts too: a line over the cap is not read.
588
+ budget.chars += opts.command.length;
589
+
590
+ if (budget.chars > ShellBudget.MAX_CHARS) {
591
+ budget.isOver = true;
637
592
 
638
- if (char === '\\' && quote !== "'") {
639
- index += 1;
640
- continue;
593
+ return [];
641
594
  }
642
595
 
643
- if (quote !== undefined) {
644
- if (char === quote) {
645
- quote = undefined;
596
+ const heredocSplit = ShellParser.splitHeredocs({ command: opts.command });
597
+ const { text } = heredocSplit;
598
+ let heredocIndex = 0;
599
+ const commands: ISimpleCommand[] = [];
600
+ const nestedTexts: string[] = [];
601
+ let current: ISimpleCommand = { words: [], redirects: [], assignments: [] };
602
+ let index = 0;
603
+
604
+ const finish = (): void => {
605
+ if (
606
+ current.words.length > 0 ||
607
+ current.redirects.length > 0 ||
608
+ current.assignments.length > 0
609
+ ) {
610
+ commands.push(current);
646
611
  }
647
612
 
648
- continue;
649
- }
613
+ current = { words: [], redirects: [], assignments: [] };
614
+ };
650
615
 
651
- if (char === "'" || char === '"') {
652
- quote = char;
653
- continue;
654
- }
616
+ while (index < text.length) {
617
+ const char = text[index];
655
618
 
656
- if (char === '<' && line[index + 1] === '<') {
657
- if (line[index + 2] === '<') {
658
- index += 2;
619
+ if (char === ' ' || char === '\t') {
620
+ index += 1;
659
621
  continue;
660
622
  }
661
623
 
662
- const match = /^<<(-?)\s*(["']?)([A-Za-z_]\w*)\2/.exec(line.slice(index));
624
+ // A backslash before a newline joins the lines: both vanish.
625
+ if (char === '\\' && text[index + 1] === '\n') {
626
+ index += 2;
627
+ continue;
628
+ }
663
629
 
664
- if (match !== null) {
665
- return { delimiter: match[3] ?? '', stripTabs: match[1] === '-', at: index };
630
+ if (char === ';' || char === '\n' || char === '|' || char === '(' || char === ')') {
631
+ finish();
632
+ index += 1;
633
+ continue;
666
634
  }
667
635
 
668
- index += 1;
669
- }
670
- }
636
+ if (char === '&' && text[index + 1] !== '>') {
637
+ finish();
638
+ index += 1;
639
+ continue;
640
+ }
671
641
 
672
- return undefined;
673
- };
642
+ if (char === '>' || char === '&') {
643
+ // `>`, `>>`, `>|`, `&>`, `&>>`; `>&2` duplicates a descriptor and names no file.
644
+ let cursor = index + (char === '&' ? 1 : 0);
674
645
 
675
- /** The program of the last simple command of `prefix`: what a heredoc that starts after it is fed to. */
676
- const programBefore = (opts: { prefix: string }): string => {
677
- const { prefix } = opts;
678
- let words: string[] = [];
679
- let index = 0;
646
+ while (text[cursor] === '>' || text[cursor] === '|') {
647
+ cursor += 1;
648
+ }
680
649
 
681
- while (index < prefix.length) {
682
- const char = prefix[index] ?? '';
650
+ if (text[cursor] === '&' && /[\d-]/.test(text[cursor + 1] ?? '')) {
651
+ index = cursor + 2;
652
+ continue;
653
+ }
683
654
 
684
- if (char === ' ' || char === '\t') {
685
- index += 1;
686
- continue;
687
- }
655
+ while (text[cursor] === ' ' || text[cursor] === '\t') {
656
+ cursor += 1;
657
+ }
688
658
 
689
- if (';|&()\n'.includes(char)) {
690
- words = [];
691
- index += 1;
692
- continue;
693
- }
659
+ const target = readWord({ text, from: cursor });
694
660
 
695
- if (char === '>' || char === '<') {
696
- // A redirect and its target are not words of the command.
697
- let cursor = index + 1;
661
+ if (target.value !== '') {
662
+ current.redirects.push(target.value);
663
+ }
698
664
 
699
- while (prefix[cursor] === '>' || prefix[cursor] === '&' || prefix[cursor] === ' ') {
700
- cursor += 1;
665
+ pushAll({ target: nestedTexts, items: target.nested });
666
+ index = Math.max(target.next, cursor + 1);
667
+ continue;
701
668
  }
702
669
 
703
- index = Math.max(readWord({ text: prefix, from: cursor }).next, index + 1);
704
- continue;
705
- }
670
+ if (char === '<') {
671
+ const operator =
672
+ text[index + 2] === '<' ? null : /^<<-?\s*["']?[A-Za-z_]\w*["']?/.exec(text.slice(index));
706
673
 
707
- const word = readWord({ text: prefix, from: index });
674
+ if (operator !== null) {
675
+ // The delimiter is part of the operator, not a word; the body goes to the command that reads it.
676
+ const heredoc = heredocSplit.heredocs[heredocIndex];
708
677
 
709
- words.push(word.value);
710
- index = Math.max(word.next, index + 1);
711
- }
678
+ heredocIndex += 1;
712
679
 
713
- return basenameOf({
714
- word: programOf({ command: { words, redirects: [], assignments: [] } }).name,
715
- });
716
- };
680
+ if (heredoc !== undefined && !heredoc.isInline) {
681
+ current.heredoc = heredoc.body;
682
+ }
717
683
 
718
- interface IHeredoc {
719
- body: string;
720
- /** The body was left in the text because a shell reads it as commands (`bash <<EOF`). */
721
- isInline: boolean;
722
- }
684
+ index += operator[0].length;
685
+ continue;
686
+ }
723
687
 
724
- /**
725
- * A heredoc's body is data for the command that reads it (a commit message, a file), not commands: the
726
- * lines between `<<WORD` and the line `WORD` are taken out of the text and kept in `heredocs`, in order, for
727
- * the command to carry. A body fed to a shell (`bash <<EOF`) is a script: it stays in the text and is read
728
- * as commands.
729
- */
730
- export const splitHeredocs = (opts: {
731
- command: string;
732
- }): { text: string; heredocs: IHeredoc[] } => {
733
- const lines = opts.command.split('\n');
734
- const kept: string[] = [];
735
- const heredocs: IHeredoc[] = [];
736
- let terminator: string | undefined;
737
- let stripTabs = false;
738
- let body: string[] = [];
739
- let isInline = false;
740
-
741
- for (const line of lines) {
742
- if (terminator !== undefined) {
743
- if ((stripTabs ? line.replace(/^\t+/, '') : line).trim() === terminator) {
744
- terminator = undefined;
745
- heredocs.push({ body: body.join('\n'), isInline });
688
+ index += 1;
746
689
  continue;
747
690
  }
748
691
 
749
- body.push(line);
692
+ const word = readWord({ text, from: index });
750
693
 
751
- if (isInline) {
752
- kept.push(line);
694
+ // A digit just before `>` is a descriptor (`2>file`), not a word.
695
+ if (/^\d$/.test(word.value) && text[word.next] === '>') {
696
+ index = word.next;
697
+ continue;
753
698
  }
754
699
 
755
- continue;
700
+ pushAll({ target: nestedTexts, items: word.nested });
701
+
702
+ if (current.words.length === 0 && isAssignment({ word: word.value })) {
703
+ current.assignments.push(word.value);
704
+ } else {
705
+ current.words.push(word.value);
706
+ }
707
+
708
+ index = Math.max(word.next, index + 1);
756
709
  }
757
710
 
758
- kept.push(line);
711
+ finish();
759
712
 
760
- const heredoc = heredocOf({ line });
713
+ budget.commands += commands.length;
714
+ budget.words += commands.reduce((sum, command) => sum + command.words.length, 0);
761
715
 
762
- if (heredoc !== undefined) {
763
- stripTabs = heredoc.stripTabs;
764
- terminator = heredoc.delimiter;
765
- body = [];
766
- isInline = SHELLS.has(programBefore({ prefix: line.slice(0, heredoc.at) }));
716
+ if (budget.commands > ShellBudget.MAX_COMMANDS || budget.words > ShellBudget.MAX_WORDS) {
717
+ budget.isOver = true;
718
+
719
+ return commands;
767
720
  }
768
- }
769
721
 
770
- if (terminator !== undefined) {
771
- heredocs.push({ body: body.join('\n'), isInline });
772
- }
722
+ // At the depth limit nothing nests further; a command that would is a part of the line left unread.
723
+ if (depth >= MAX_DEPTH) {
724
+ budget.isOver ||=
725
+ nestedTexts.length > 0 || commands.some((command) => ShellParser.nests({ command }));
773
726
 
774
- return { text: kept.join('\n'), heredocs };
775
- };
727
+ return commands;
728
+ }
776
729
 
777
- /** Appends every item; a spread into `push` overflows the stack at a few hundred thousand items. */
778
- const pushAll = (opts: { target: string[]; items: string[] }): void => {
779
- for (const item of opts.items) {
780
- opts.target.push(item);
781
- }
782
- };
730
+ // `env -S "git push -f origin main"` is a command line in one word: the command it makes joins the queue,
731
+ // one nesting level deeper, and is read like any other.
732
+ const synthesized: ISimpleCommand[] = [];
733
+ const queue = commands.map((command) => ({ command, level: 0 }));
783
734
 
784
- /**
785
- * The command lines a command carries as text: the script of `sh -c`, the words of `eval`, and the string
786
- * `watch` joins its words into and hands to a shell (`watch 'git push'`).
787
- */
788
- const nestedScripts = (opts: {
789
- command: ISimpleCommand;
790
- program: ReturnType<typeof programOf>;
791
- }): string[] => {
792
- const { command, program } = opts;
793
-
794
- if (program.index === -1) {
795
- return [];
796
- }
735
+ for (const { command, level } of queue) {
736
+ const program = ShellParser.programOf({ command });
797
737
 
798
- const name = basenameOf({ word: program.name });
799
- const scripts: string[] = [];
738
+ if (depth + level < MAX_DEPTH) {
739
+ for (const words of program.splitCommands) {
740
+ const split: ISimpleCommand = { words, redirects: [], assignments: [] };
800
741
 
801
- if (SHELLS.has(name)) {
802
- const flag = command.words.findIndex(
803
- (word, position) => position > program.index && /^-[a-zA-Z]*c$/.test(word),
804
- );
805
- const script = flag === -1 ? undefined : command.words[flag + 1];
742
+ budget.commands += 1;
743
+ budget.words += words.length;
806
744
 
807
- if (script !== undefined) {
808
- scripts.push(script);
745
+ if (budget.commands > ShellBudget.MAX_COMMANDS || budget.words > ShellBudget.MAX_WORDS) {
746
+ budget.isOver = true;
747
+
748
+ return [...commands, ...synthesized];
749
+ }
750
+
751
+ synthesized.push(split);
752
+ queue.push({ command: split, level: level + 1 });
753
+ }
754
+ } else if (program.splitCommands.length > 0) {
755
+ budget.isOver = true;
756
+ }
757
+
758
+ pushAll({ target: nestedTexts, items: ShellParser.nestedScripts({ command, program }) });
809
759
  }
810
- }
811
760
 
812
- if (name === 'eval') {
813
- scripts.push(program.args.join(' '));
761
+ return [
762
+ ...commands,
763
+ ...synthesized,
764
+ ...nestedTexts.flatMap((nested) =>
765
+ ShellParser.parseWithBudget({ command: nested, depth: depth + 1, budget }),
766
+ ),
767
+ ];
814
768
  }
815
769
 
816
- if (
817
- /\s/.test(program.name) &&
818
- command.words.slice(0, program.index).some((word) => basenameOf({ word }) === 'watch')
819
- ) {
820
- scripts.push([program.name, ...program.args].join(' '));
770
+ /**
771
+ * The commands of a line and whether all of it was read. A guard that can refuse must treat
772
+ * `isOverBudget` as "ask": an unread part is never an "allow".
773
+ */
774
+ /** A parse that throws (a stack or memory limit) reads nothing and says so: the line is not allowed by silence. */
775
+ private static parseGuarded(opts: {
776
+ command: string;
777
+ depth: number;
778
+ budget: IBudget;
779
+ }): ISimpleCommand[] {
780
+ try {
781
+ return ShellParser.parseWithBudget(opts);
782
+ } catch {
783
+ opts.budget.isOver = true;
784
+
785
+ return [];
786
+ }
821
787
  }
822
788
 
823
- return scripts;
824
- };
789
+ /** Whether the option word `word` of `wrapper` takes the next word as its value. */
790
+ static optionTakesNextWord(opts: { wrapper: string; word: string }): boolean {
791
+ const options = WRAPPER_OPTIONS[opts.wrapper];
825
792
 
826
- /** Whether the command carries another command line to read: a script, an eval, a `watch` string, or an `env -S`. */
827
- const nests = (opts: { command: ISimpleCommand }): boolean => {
828
- const program = programOf({ command: opts.command });
793
+ if (options === undefined || !opts.word.startsWith('-') || opts.word === '-') {
794
+ return false;
795
+ }
829
796
 
830
- return (
831
- program.splitCommands.length > 0 || nestedScripts({ command: opts.command, program }).length > 0
832
- );
833
- };
797
+ // A long option may be shortened to any prefix (`--adj 5` is `--adjustment 5`), as getopt_long reads it.
798
+ if (opts.word.startsWith('--')) {
799
+ const name = opts.word.slice(2);
834
800
 
835
- /**
836
- * The simple commands of a shell line, in order: `;`, `&&`, `||`, `|`, `&` and newlines split them;
837
- * `$(...)`, backticks, `sh -c '...'` arguments and the command line of `env -S` are parsed as commands too. It
838
- * reads quoting, not every corner of the shell: a line it cannot follow yields fewer commands, never an error.
839
- */
840
- const parseWithBudget = (opts: {
841
- command: string;
842
- depth: number;
843
- budget: IBudget;
844
- }): ISimpleCommand[] => {
845
- const { depth, budget } = opts;
801
+ return (
802
+ name !== '' &&
803
+ !name.includes('=') &&
804
+ options.longValues.some((long) => long.slice(2).startsWith(name))
805
+ );
806
+ }
846
807
 
847
- // The characters of every text read count together, nested texts too: a line over the cap is not read.
848
- budget.chars += opts.command.length;
808
+ // A cluster such as `-nu`: the first letter that takes a value ends it; with letters left after it the
809
+ // rest is the value, and with none left the value is the next word.
810
+ for (let at = 1; at < opts.word.length; at += 1) {
811
+ if (options.shortValues.includes(opts.word[at] ?? '')) {
812
+ return at === opts.word.length - 1;
813
+ }
814
+ }
849
815
 
850
- if (budget.chars > ShellBudget.MAX_CHARS) {
851
- budget.isOver = true;
816
+ return false;
817
+ }
852
818
 
853
- return [];
819
+ static basenameOf(opts: { word: string }): string {
820
+ return opts.word.split('/').pop() ?? opts.word;
854
821
  }
855
822
 
856
- const heredocSplit = splitHeredocs({ command: opts.command });
857
- const { text } = heredocSplit;
858
- let heredocIndex = 0;
859
- const commands: ISimpleCommand[] = [];
860
- const nestedTexts: string[] = [];
861
- let current: ISimpleCommand = { words: [], redirects: [], assignments: [] };
862
- let index = 0;
823
+ /**
824
+ * The words `env -S` makes of its value, by `env`'s own rules and not the shell's: blanks separate, quotes
825
+ * group (in single quotes only `\\\\` and `\\'` are escapes), `\\_` separates outside double quotes and is a
826
+ * space inside them, `\\c` ends the string, a `#` at the start of a word starts a comment, and `;`, `|`
827
+ * and `$(...)` mean nothing. An empty quoted string is a word.
828
+ */
829
+ static splitEnvString(opts: { value: string }): string[] {
830
+ const { value } = opts;
831
+ const words: string[] = [];
832
+ let current = '';
833
+ let hasWord = false;
834
+ let quote: string | undefined;
835
+
836
+ const flush = (): void => {
837
+ if (hasWord) {
838
+ words.push(current);
839
+ }
863
840
 
864
- const finish = (): void => {
865
- if (
866
- current.words.length > 0 ||
867
- current.redirects.length > 0 ||
868
- current.assignments.length > 0
869
- ) {
870
- commands.push(current);
871
- }
841
+ current = '';
842
+ hasWord = false;
843
+ };
872
844
 
873
- current = { words: [], redirects: [], assignments: [] };
874
- };
845
+ for (let index = 0; index < value.length; index += 1) {
846
+ const char = value[index] ?? '';
875
847
 
876
- while (index < text.length) {
877
- const char = text[index];
848
+ if (char === '\\') {
849
+ const next = value[index + 1];
878
850
 
879
- if (char === ' ' || char === '\t') {
880
- index += 1;
881
- continue;
882
- }
851
+ index += 1;
883
852
 
884
- // A backslash before a newline joins the lines: both vanish.
885
- if (char === '\\' && text[index + 1] === '\n') {
886
- index += 2;
887
- continue;
888
- }
853
+ if (next === undefined) {
854
+ break;
855
+ }
889
856
 
890
- if (char === ';' || char === '\n' || char === '|' || char === '(' || char === ')') {
891
- finish();
892
- index += 1;
893
- continue;
894
- }
857
+ // In single quotes only `\\` and `\'` are escapes: every other backslash stays, `\c` and `\_` included.
858
+ if (quote === "'") {
859
+ current += next === '\\' || next === "'" ? next : `\\${next}`;
860
+ hasWord = true;
861
+ continue;
862
+ }
895
863
 
896
- if (char === '&' && text[index + 1] !== '>') {
897
- finish();
898
- index += 1;
899
- continue;
900
- }
864
+ if (next === 'c') {
865
+ break;
866
+ }
901
867
 
902
- if (char === '>' || char === '&') {
903
- // `>`, `>>`, `>|`, `&>`, `&>>`; `>&2` duplicates a descriptor and names no file.
904
- let cursor = index + (char === '&' ? 1 : 0);
868
+ if (next === '_') {
869
+ if (quote === '"') {
870
+ current += ' ';
871
+ hasWord = true;
872
+ } else {
873
+ flush();
874
+ }
905
875
 
906
- while (text[cursor] === '>' || text[cursor] === '|') {
907
- cursor += 1;
876
+ continue;
877
+ }
878
+
879
+ current += ENV_ESCAPES[next] ?? next;
880
+ hasWord = true;
881
+ continue;
908
882
  }
909
883
 
910
- if (text[cursor] === '&' && /[\d-]/.test(text[cursor + 1] ?? '')) {
911
- index = cursor + 2;
884
+ if (quote !== undefined) {
885
+ if (char === quote) {
886
+ quote = undefined;
887
+ } else {
888
+ current += char;
889
+ hasWord = true;
890
+ }
891
+
912
892
  continue;
913
893
  }
914
894
 
915
- while (text[cursor] === ' ' || text[cursor] === '\t') {
916
- cursor += 1;
895
+ if (char === "'" || char === '"') {
896
+ quote = char;
897
+ hasWord = true;
898
+ continue;
917
899
  }
918
900
 
919
- const target = readWord({ text, from: cursor });
901
+ if (char === '#' && !hasWord) {
902
+ break;
903
+ }
920
904
 
921
- if (target.value !== '') {
922
- current.redirects.push(target.value);
905
+ if (/\s/.test(char)) {
906
+ flush();
907
+ continue;
923
908
  }
924
909
 
925
- pushAll({ target: nestedTexts, items: target.nested });
926
- index = Math.max(target.next, cursor + 1);
927
- continue;
910
+ current += char;
911
+ hasWord = true;
928
912
  }
929
913
 
930
- if (char === '<') {
931
- const operator =
932
- text[index + 2] === '<' ? null : /^<<-?\s*["']?[A-Za-z_]\w*["']?/.exec(text.slice(index));
933
-
934
- if (operator !== null) {
935
- // The delimiter is part of the operator, not a word; the body goes to the command that reads it.
936
- const heredoc = heredocSplit.heredocs[heredocIndex];
914
+ flush();
937
915
 
938
- heredocIndex += 1;
916
+ return words;
917
+ }
939
918
 
940
- if (heredoc !== undefined && !heredoc.isInline) {
941
- current.heredoc = heredoc.body;
942
- }
919
+ /**
920
+ * The program a command runs, past wrappers such as `sudo`, `env` and `time`, and the command `env -S`
921
+ * carries: the words `env` makes of the value, then the words after it, behind an `env` word, so its own
922
+ * options inside the value apply. Only the first `-S` of a command counts: it holds the rest of the line.
923
+ * `--` ends the options, so a word after it is the program even when it starts with a dash.
924
+ */
925
+ static programOf(opts: { command: ISimpleCommand }): {
926
+ name: string;
927
+ index: number;
928
+ args: string[];
929
+ splitCommands: string[][];
930
+ } {
931
+ let index = 0;
932
+ let wrapper = '';
933
+ let positionals = 0;
934
+ let optionsEnded = false;
935
+ const splitCommands: string[][] = [];
936
+
937
+ while (index < opts.command.words.length) {
938
+ const word = opts.command.words[index];
939
+
940
+ if (WRAPPERS.has(ShellParser.basenameOf({ word }))) {
941
+ wrapper = ShellParser.basenameOf({ word });
942
+ positionals = wrapperPositionals({ wrapper });
943
+ optionsEnded = false;
944
+ index += 1;
945
+ continue;
946
+ }
943
947
 
944
- index += operator[0].length;
948
+ if (isAssignment({ word }) || KEYWORDS.has(word)) {
949
+ index += 1;
945
950
  continue;
946
951
  }
947
952
 
948
- index += 1;
949
- continue;
950
- }
953
+ if (word === '--') {
954
+ optionsEnded = true;
955
+ index += 1;
956
+ continue;
957
+ }
951
958
 
952
- const word = readWord({ text, from: index });
959
+ if (!optionsEnded && /^-/.test(word)) {
960
+ const split =
961
+ wrapper === 'env' && splitCommands.length === 0
962
+ ? splitStringOf({ word, next: opts.command.words[index + 1] })
963
+ : undefined;
964
+
965
+ if (split !== undefined && split.value !== '') {
966
+ splitCommands.push([
967
+ 'env',
968
+ ...ShellParser.splitEnvString({ value: split.value }),
969
+ ...opts.command.words.slice(index + (split.takesNext ? 2 : 1)),
970
+ ]);
971
+ }
953
972
 
954
- // A digit just before `>` is a descriptor (`2>file`), not a word.
955
- if (/^\d$/.test(word.value) && text[word.next] === '>') {
956
- index = word.next;
957
- continue;
958
- }
973
+ // An option of the wrapper; `-u X` and `nice -n 5` take a value that is not the program.
974
+ index += ShellParser.optionTakesNextWord({ wrapper, word }) ? 2 : 1;
975
+ continue;
976
+ }
959
977
 
960
- pushAll({ target: nestedTexts, items: word.nested });
978
+ // `timeout 5 cmd`: a plain word the wrapper itself takes.
979
+ if (positionals > 0) {
980
+ positionals -= 1;
981
+ index += 1;
982
+ continue;
983
+ }
961
984
 
962
- if (current.words.length === 0 && isAssignment({ word: word.value })) {
963
- current.assignments.push(word.value);
964
- } else {
965
- current.words.push(word.value);
985
+ return { name: word, index, args: opts.command.words.slice(index + 1), splitCommands };
966
986
  }
967
987
 
968
- index = Math.max(word.next, index + 1);
988
+ return { name: '', index: -1, args: [], splitCommands };
969
989
  }
970
990
 
971
- finish();
972
-
973
- budget.commands += commands.length;
974
- budget.words += commands.reduce((sum, command) => sum + command.words.length, 0);
975
-
976
- if (budget.commands > ShellBudget.MAX_COMMANDS || budget.words > ShellBudget.MAX_WORDS) {
977
- budget.isOver = true;
991
+ /**
992
+ * A heredoc's body is data for the command that reads it (a commit message, a file), not commands: the
993
+ * lines between `<<WORD` and the line `WORD` are taken out of the text and kept in `heredocs`, in order, for
994
+ * the command to carry. A body fed to a shell (`bash <<EOF`) is a script: it stays in the text and is read
995
+ * as commands.
996
+ */
997
+ static splitHeredocs(opts: { command: string }): { text: string; heredocs: IHeredoc[] } {
998
+ const lines = opts.command.split('\n');
999
+ const kept: string[] = [];
1000
+ const heredocs: IHeredoc[] = [];
1001
+ let terminator: string | undefined;
1002
+ let stripTabs = false;
1003
+ let body: string[] = [];
1004
+ let isInline = false;
1005
+
1006
+ for (const line of lines) {
1007
+ if (terminator !== undefined) {
1008
+ if ((stripTabs ? line.replace(/^\t+/, '') : line).trim() === terminator) {
1009
+ terminator = undefined;
1010
+ heredocs.push({ body: body.join('\n'), isInline });
1011
+ continue;
1012
+ }
978
1013
 
979
- return commands;
980
- }
1014
+ body.push(line);
981
1015
 
982
- // At the depth limit nothing nests further; a command that would is a part of the line left unread.
983
- if (depth >= MAX_DEPTH) {
984
- budget.isOver ||= nestedTexts.length > 0 || commands.some((command) => nests({ command }));
1016
+ if (isInline) {
1017
+ kept.push(line);
1018
+ }
985
1019
 
986
- return commands;
987
- }
1020
+ continue;
1021
+ }
988
1022
 
989
- // `env -S "git push -f origin main"` is a command line in one word: the command it makes joins the queue,
990
- // one nesting level deeper, and is read like any other.
991
- const synthesized: ISimpleCommand[] = [];
992
- const queue = commands.map((command) => ({ command, level: 0 }));
1023
+ kept.push(line);
993
1024
 
994
- for (const { command, level } of queue) {
995
- const program = programOf({ command });
1025
+ const heredoc = heredocOf({ line });
996
1026
 
997
- if (depth + level < MAX_DEPTH) {
998
- for (const words of program.splitCommands) {
999
- const split: ISimpleCommand = { words, redirects: [], assignments: [] };
1027
+ if (heredoc !== undefined) {
1028
+ stripTabs = heredoc.stripTabs;
1029
+ terminator = heredoc.delimiter;
1030
+ body = [];
1031
+ isInline = SHELLS.has(ShellParser.programBefore({ prefix: line.slice(0, heredoc.at) }));
1032
+ }
1033
+ }
1000
1034
 
1001
- budget.commands += 1;
1002
- budget.words += words.length;
1035
+ if (terminator !== undefined) {
1036
+ heredocs.push({ body: body.join('\n'), isInline });
1037
+ }
1003
1038
 
1004
- if (budget.commands > ShellBudget.MAX_COMMANDS || budget.words > ShellBudget.MAX_WORDS) {
1005
- budget.isOver = true;
1039
+ return { text: kept.join('\n'), heredocs };
1040
+ }
1006
1041
 
1007
- return [...commands, ...synthesized];
1008
- }
1042
+ static parseChecked(opts: { command: string }): IParsedShell {
1043
+ const budget: IBudget = { commands: 0, words: 0, chars: 0, isOver: false };
1044
+ const commands = ShellParser.parseGuarded({ command: opts.command, depth: 0, budget });
1009
1045
 
1010
- synthesized.push(split);
1011
- queue.push({ command: split, level: level + 1 });
1012
- }
1013
- } else if (program.splitCommands.length > 0) {
1014
- budget.isOver = true;
1015
- }
1046
+ return { commands, isOverBudget: budget.isOver };
1047
+ }
1016
1048
 
1017
- pushAll({ target: nestedTexts, items: nestedScripts({ command, program }) });
1049
+ static parse(opts: { command: string; depth?: number }): ISimpleCommand[] {
1050
+ return ShellParser.parseGuarded({
1051
+ command: opts.command,
1052
+ depth: opts.depth ?? 0,
1053
+ budget: { commands: 0, words: 0, chars: 0, isOver: false },
1054
+ });
1018
1055
  }
1056
+ }
1019
1057
 
1020
- return [
1021
- ...commands,
1022
- ...synthesized,
1023
- ...nestedTexts.flatMap((nested) =>
1024
- parseWithBudget({ command: nested, depth: depth + 1, budget }),
1025
- ),
1026
- ];
1027
- };
1058
+ interface IBudget {
1059
+ commands: number;
1060
+ words: number;
1061
+ chars: number;
1062
+ /** Something was not read: the budget ran out, or a command nests deeper than the depth limit. */
1063
+ isOver: boolean;
1064
+ }
1065
+
1066
+ interface IHeredoc {
1067
+ body: string;
1068
+ /** The body was left in the text because a shell reads it as commands (`bash <<EOF`). */
1069
+ isInline: boolean;
1070
+ }
1028
1071
 
1029
1072
  interface IParsedShell {
1030
1073
  commands: ISimpleCommand[];
1031
1074
  /** Part of the line was not read: it is larger, or nests deeper, than the parser's budget. */
1032
1075
  isOverBudget: boolean;
1033
1076
  }
1034
-
1035
- /**
1036
- * The commands of a line and whether all of it was read. A guard that can refuse must treat
1037
- * `isOverBudget` as "ask": an unread part is never an "allow".
1038
- */
1039
- /** A parse that throws (a stack or memory limit) reads nothing and says so: the line is not allowed by silence. */
1040
- const parseGuarded = (opts: {
1041
- command: string;
1042
- depth: number;
1043
- budget: IBudget;
1044
- }): ISimpleCommand[] => {
1045
- try {
1046
- return parseWithBudget(opts);
1047
- } catch {
1048
- opts.budget.isOver = true;
1049
-
1050
- return [];
1051
- }
1052
- };
1053
-
1054
- export const parseShellChecked = (opts: { command: string }): IParsedShell => {
1055
- const budget: IBudget = { commands: 0, words: 0, chars: 0, isOver: false };
1056
- const commands = parseGuarded({ command: opts.command, depth: 0, budget });
1057
-
1058
- return { commands, isOverBudget: budget.isOver };
1059
- };
1060
-
1061
- export const parseShell = (opts: { command: string; depth?: number }): ISimpleCommand[] =>
1062
- parseGuarded({
1063
- command: opts.command,
1064
- depth: opts.depth ?? 0,
1065
- budget: { commands: 0, words: 0, chars: 0, isOver: false },
1066
- });