@venizia/vulcan 0.4.8 → 0.4.9-1

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