@venizia/vulcan 0.4.10-2 → 0.4.10-21

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 (208) hide show
  1. package/README.md +30 -23
  2. package/base/checks/wiki-source-links.ts +17 -1
  3. package/base/claude/events.json +1 -11
  4. package/base/claude/settings.json +5 -76
  5. package/base/extensions/vulcan-guards.ts +81 -18
  6. package/base/hooks/guard-git.ts +95 -19
  7. package/base/hooks/guard-outside.ts +163 -43
  8. package/base/hooks/guard-writes.ts +15 -36
  9. package/base/hooks/session-start.ts +1 -1
  10. package/base/make/vulcan.mk +8 -5
  11. package/base/packs/venizia.md +16 -0
  12. package/base/references/delegation-brief.md +3 -5
  13. package/base/references/testing.md +1 -9
  14. package/base/rules.md +33 -38
  15. package/base/skills/build-a-feature/SKILL.md +4 -4
  16. package/base/skills/docs-update/SKILL.md +19 -8
  17. package/base/skills/fix-a-bug/SKILL.md +4 -2
  18. package/base/skills/plan-a-change/SKILL.md +1 -1
  19. package/base/skills/research/SKILL.md +1 -1
  20. package/base/skills/retro/SKILL.md +2 -2
  21. package/base/skills/review-a-change/SKILL.md +1 -1
  22. package/base/skills/visualize-work/SKILL.md +3 -3
  23. package/base/skills/visualize-work/references/spec.md +6 -3
  24. package/base/templates/AGENTS.md +9 -7
  25. package/base/templates/board.html +10 -110
  26. package/package.json +3 -3
  27. package/src/agents/atlas-block.ts +8 -31
  28. package/src/agents/codex-hooks.ts +1 -1
  29. package/src/agents/generated-block.ts +52 -0
  30. package/src/agents/hooks-json.ts +22 -3
  31. package/src/agents/index.ts +2 -0
  32. package/src/agents/render.ts +15 -2
  33. package/src/agents/resolve.ts +1 -0
  34. package/src/agents/rules-block.ts +92 -0
  35. package/src/board/command.ts +92 -30
  36. package/src/board/common/constants.ts +26 -0
  37. package/src/board/common/types.ts +10 -3
  38. package/src/board/fold.ts +1 -1
  39. package/src/board/github.ts +1 -2
  40. package/src/board/gitlab.ts +436 -0
  41. package/src/board/index.ts +1 -0
  42. package/src/board/logo.ts +49 -0
  43. package/src/board/open-file.ts +110 -0
  44. package/src/board/page.ts +57 -5
  45. package/src/board/schema.ts +4 -1
  46. package/src/board/server.ts +87 -3
  47. package/src/board/settings.ts +21 -24
  48. package/src/commands/changelog.command.ts +40 -0
  49. package/src/commands/clean.command.ts +6 -1
  50. package/src/commands/help.command.ts +2 -63
  51. package/src/commands/index.ts +6 -1
  52. package/src/commands/migrate.command.ts +71 -0
  53. package/src/commands/profile.command.ts +1 -1
  54. package/src/commands/runners.command.ts +43 -0
  55. package/src/commands/sync.command.ts +8 -4
  56. package/src/commands/table.ts +362 -0
  57. package/src/commit/check.ts +1 -0
  58. package/src/commit/common/constants.ts +4 -0
  59. package/src/commit/hook.ts +112 -8
  60. package/src/common/constants.ts +11 -9
  61. package/src/common/env-variables.ts +41 -0
  62. package/src/common/index.ts +1 -0
  63. package/src/common/layout-folder.ts +3 -4
  64. package/src/common/record.ts +5 -0
  65. package/src/config/common/constants.ts +28 -22
  66. package/src/config/loader.ts +22 -0
  67. package/src/config/schema.ts +330 -146
  68. package/src/create/add-app.ts +7 -2
  69. package/src/create/add-lib.ts +2 -4
  70. package/src/create/common/constants.ts +5 -3
  71. package/src/create/preset.ts +1 -0
  72. package/src/create/scratch.ts +2 -1
  73. package/src/doctor/checks.ts +277 -448
  74. package/src/doctor/common/constants.ts +27 -19
  75. package/src/doctor/private-values.ts +4 -1
  76. package/src/doctor/runner.ts +5 -12
  77. package/src/doctor/schema.ts +4 -0
  78. package/src/events/common/actor-names.ts +12 -0
  79. package/src/events/common/constants.ts +65 -38
  80. package/src/events/common/index.ts +1 -0
  81. package/src/events/hook.ts +5 -56
  82. package/src/events/text.ts +41 -6
  83. package/src/hooks/command-view.ts +80 -19
  84. package/src/hooks/common/constants.ts +26 -17
  85. package/src/hooks/common/types.ts +13 -24
  86. package/src/hooks/decision.ts +30 -12
  87. package/src/hooks/git-queries.ts +113 -0
  88. package/src/hooks/guard-git.ts +76 -24
  89. package/src/hooks/guard-outside.ts +334 -311
  90. package/src/hooks/guard-runner.ts +206 -0
  91. package/src/hooks/guard-writes.ts +87 -184
  92. package/src/hooks/hook-input.ts +57 -0
  93. package/src/hooks/index.ts +3 -6
  94. package/src/hooks/link-makers.ts +315 -0
  95. package/src/hooks/package-runners.ts +268 -0
  96. package/src/hooks/project-guards.ts +81 -44
  97. package/src/hooks/project-tmp.ts +39 -4
  98. package/src/hooks/runner-scan.ts +257 -0
  99. package/src/hooks/script-runners.ts +400 -0
  100. package/src/hooks/session-digest.ts +27 -117
  101. package/src/hooks/shell-folders.ts +760 -0
  102. package/src/hooks/shell-writes.ts +646 -0
  103. package/src/hooks/shell.ts +1421 -194
  104. package/src/hooks/subagent-card.ts +2 -2
  105. package/src/hooks/write-commands.ts +898 -0
  106. package/src/init/scaffold.ts +2 -3
  107. package/src/local/auto-clean.ts +2 -1
  108. package/src/local/browser-socket.ts +33 -0
  109. package/src/local/clean.ts +37 -6
  110. package/src/local/constants.ts +15 -1
  111. package/src/local/index.ts +1 -0
  112. package/src/local/scan.ts +41 -10
  113. package/src/manifest/render.ts +84 -30
  114. package/src/owner/constants.ts +4 -5
  115. package/src/owner/index.ts +0 -2
  116. package/src/owner/profile.ts +1 -0
  117. package/src/owner/schema.ts +51 -27
  118. package/src/owner/survey.ts +0 -3
  119. package/src/owner/view.ts +0 -9
  120. package/src/router.ts +8 -132
  121. package/src/rules/base.ts +12 -7
  122. package/src/rules/index.ts +1 -0
  123. package/src/rules/packs.ts +44 -0
  124. package/src/runners/check.ts +130 -0
  125. package/src/skills/frontmatter.ts +1 -0
  126. package/src/sync/agents-block.ts +104 -0
  127. package/src/sync/base-rules.ts +3 -3
  128. package/src/sync/claude-launch.ts +12 -12
  129. package/src/sync/common/constants.ts +0 -2
  130. package/src/sync/index.ts +1 -1
  131. package/src/sync/local-choice.ts +32 -3
  132. package/src/sync/planner.ts +2 -15
  133. package/src/sync/settings.ts +0 -17
  134. package/src/theme/index.ts +1 -0
  135. package/src/theme/tokens.ts +410 -0
  136. package/src/ui/prompt.ts +1 -0
  137. package/src/visualize/architecture.ts +504 -0
  138. package/src/visualize/assets.ts +41 -30
  139. package/src/visualize/compare-render.ts +22 -24
  140. package/src/visualize/constants.ts +27 -0
  141. package/src/visualize/diagrams.ts +13 -121
  142. package/src/visualize/kinds-render.ts +2 -2
  143. package/src/visualize/kinds-schema.ts +49 -0
  144. package/src/visualize/labels-vi.ts +25 -0
  145. package/src/visualize/labels.ts +2 -0
  146. package/src/visualize/layout.ts +415 -66
  147. package/src/visualize/page.ts +82 -15
  148. package/src/visualize/render.ts +2 -1
  149. package/src/visualize/schema.ts +29 -1
  150. package/src/visualize/sections.ts +78 -9
  151. package/src/visualize/theme.ts +49 -18
  152. package/src/wiki/anchors.ts +1 -0
  153. package/src/wiki/command.ts +10 -3
  154. package/src/wiki/source-links.ts +57 -18
  155. package/base/ci-global.json +0 -13
  156. package/base/claude/remote-hosts.json +0 -15
  157. package/base/hooks/guard-manifest.ts +0 -27
  158. package/base/hooks/guard-package.ts +0 -30
  159. package/base/hooks/guard-remote-hosts.ts +0 -70
  160. package/base/hooks/guard-scripting.ts +0 -32
  161. package/base/hooks/post-tool.ts +0 -37
  162. package/base/hooks/prompt-submit.ts +0 -54
  163. package/base/hooks/stop.ts +0 -40
  164. package/base/skills/build-a-feature/evals/evals.json +0 -29
  165. package/base/skills/docs-update/evals/evals.json +0 -23
  166. package/base/skills/docs-writing/evals/evals.json +0 -17
  167. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  168. package/base/skills/knowledge-sync/SKILL.md +0 -81
  169. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  170. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  171. package/base/skills/plan-a-change/evals/evals.json +0 -47
  172. package/base/skills/report-back/evals/evals.json +0 -23
  173. package/base/skills/research/evals/evals.json +0 -17
  174. package/base/skills/retro/evals/evals.json +0 -17
  175. package/base/skills/review-a-change/evals/evals.json +0 -17
  176. package/base/skills/ship/evals/evals.json +0 -23
  177. package/base/skills/visualize-work/evals/evals.json +0 -17
  178. package/base/templates/ci/github-actions.yml +0 -75
  179. package/base/templates/ci/gitlab-ci.yml +0 -52
  180. package/base/templates/trusted-hosts.local.example +0 -11
  181. package/src/ci/affected.ts +0 -176
  182. package/src/ci/command.ts +0 -166
  183. package/src/ci/common/constants.ts +0 -76
  184. package/src/ci/common/index.ts +0 -2
  185. package/src/ci/common/types.ts +0 -37
  186. package/src/ci/git.ts +0 -72
  187. package/src/ci/global.ts +0 -48
  188. package/src/ci/graph.ts +0 -43
  189. package/src/ci/index.ts +0 -7
  190. package/src/ci/workspace.ts +0 -119
  191. package/src/commands/ci.command.ts +0 -4
  192. package/src/hooks/guard-manifest.ts +0 -109
  193. package/src/hooks/guard-package.ts +0 -226
  194. package/src/hooks/guard-scripting.ts +0 -36
  195. package/src/hooks/host-pattern.ts +0 -17
  196. package/src/hooks/owner-reply.ts +0 -162
  197. package/src/hooks/post-tool.ts +0 -138
  198. package/src/hooks/remote-hosts.ts +0 -1013
  199. package/src/hooks/trusted-scripts.ts +0 -212
  200. package/src/owner/shape.ts +0 -496
  201. package/src/owner/violations.ts +0 -332
  202. package/src/signals/claims.ts +0 -73
  203. package/src/signals/classify.ts +0 -137
  204. package/src/signals/constants.ts +0 -88
  205. package/src/signals/index.ts +0 -5
  206. package/src/signals/loop.ts +0 -48
  207. package/src/signals/state.ts +0 -271
  208. package/src/sync/atlas-block.ts +0 -56
@@ -1,24 +1,98 @@
1
+ import type { TConstValue } from '../common/types.ts';
2
+
1
3
  /** One simple command of a shell line: its words, the files it redirects into, its leading `NAME=value` words. */
2
4
  export interface ISimpleCommand {
3
5
  words: string[];
4
6
  redirects: string[];
7
+ /** The `>&word` targets that hold an expansion (`>&$fd`): a descriptor or a file, the line does not say which. They are in `redirects` too. */
8
+ copies?: string[];
9
+ /** The bodies of the heredocs whose delimiter is not quoted: the shell expands them before the command reads them. */
10
+ expandedBodies?: string[];
5
11
  assignments: string[];
6
12
  /** The body of the heredoc this command reads, when it is not read as commands itself (data, or a query or script for another program). */
7
13
  heredoc?: string;
14
+ /** What the line feeds the command's standard input; absent when the line feeds it nothing. */
15
+ input?: ICommandInput;
16
+ /**
17
+ * Where the command runs, when not at the top of the line: `/N` is the subshell `( ... )` numbered N and
18
+ * `>N` the command line numbered N that a word carries (`$(...)`, `sh -c`), each segment inside the one before.
19
+ */
20
+ scope?: string;
21
+ /** The command whose word carries this command's line (`$(...)`, `sh -c`): the line starts in its folder. */
22
+ carrier?: ISimpleCommand;
23
+ /**
24
+ * The words (and redirect targets, and assignments as `NAME=value`) of this command that hold a `$` the line quoted or
25
+ * escaped (`'$S'`, `\$S`): their text reads as a live `$S` but the shell takes the `$` as a character. A guard that
26
+ * expands variables must not expand these.
27
+ */
28
+ literalDollars?: string[];
29
+ }
30
+
31
+ /** The standard input of a simple command, as far as the line shows it. */
32
+ export interface ICommandInput {
33
+ /** The files a `<` reads. */
34
+ files: string[];
35
+ /** The command whose output a `|` feeds in. */
36
+ pipedFrom?: ISimpleCommand;
37
+ /** The text of each here-string (`<<< text`). */
38
+ texts: string[];
39
+ /** A heredoc feeds it: its body is on `heredoc`, or read as commands of the line when a shell reads it. */
40
+ hasHeredoc: boolean;
41
+ }
42
+
43
+ /** How a shell runs: the text of `-c`, a script file, its standard input, or nothing (`-n` only checks the syntax). */
44
+ export class ShellModes {
45
+ static readonly COMMAND = 'command';
46
+ static readonly FILE = 'file';
47
+ static readonly STDIN = 'stdin';
48
+ static readonly CHECK = 'check';
49
+ }
50
+
51
+ export type TShellMode = TConstValue<typeof ShellModes>;
52
+
53
+ /** A shell call read past its own options: how it runs, and its first word that is not an option. */
54
+ export interface IShellCall {
55
+ mode: TShellMode;
56
+ /** The `-c` text, the script, or the first argument after `-s`; `undefined` when there is none. */
57
+ word: string | undefined;
8
58
  }
9
59
 
60
+ /** The long options of a shell that take the next word as their value; every other long option is a switch. */
61
+ const SHELL_LONG_VALUES = new Set(['--rcfile', '--init-file']);
62
+
63
+ const inputOf = (opts: { command: ISimpleCommand }): ICommandInput => {
64
+ opts.command.input ??= { files: [], texts: [], hasHeredoc: false };
65
+
66
+ return opts.command.input;
67
+ };
68
+
10
69
  interface IWordRead {
11
70
  value: string;
12
71
  next: number;
13
72
  /** Text of every `$(...)` and backtick substitution met, each parsed as commands of its own. */
14
73
  nested: string[];
74
+ /** A `$` of the word was quoted or escaped, so it is a character and not an expansion. */
75
+ hasLiteralDollar: boolean;
15
76
  }
16
77
 
78
+ /** Remembers on `command` that `word` holds a `$` the line quoted or escaped. */
79
+ const markLiteralDollar = (opts: {
80
+ command: ISimpleCommand;
81
+ value: string;
82
+ read: IWordRead;
83
+ }): void => {
84
+ if (opts.read.hasLiteralDollar) {
85
+ (opts.command.literalDollars ??= []).push(opts.value);
86
+ }
87
+ };
88
+
17
89
  /** What a backslash inside double quotes escapes, as the shell reads it. */
18
90
  const DOUBLE_QUOTE_ESCAPES = new Set(['$', '`', '"', '\\', '\n']);
19
91
 
20
92
  /** What stops an unquoted word. */
21
93
  const WORD_END = new Set([' ', '\t', '\n', ';', '|', '&', '<', '>', '(', ')']);
94
+ /** The keywords that end a compound command: a redirect after one belongs to the whole command. */
95
+ const CLOSING_KEYWORDS = new Set(['}', 'fi', 'done', 'esac']);
22
96
  /** Shell keywords and braces that open a command: the program is the word after them. */
23
97
  const KEYWORDS = new Set([
24
98
  '{',
@@ -81,6 +155,7 @@ const WRAPPER_OPTIONS: Record<string, IWrapperOptions> = {
81
155
  longValues: ['--unset', '--chdir', '--split-string', '--argv0', '--file'],
82
156
  }),
83
157
  command: wrapperOptions({}),
158
+ builtin: wrapperOptions({}),
84
159
  time: wrapperOptions({ shortValues: 'fo', longValues: ['--format', '--output'] }),
85
160
  nohup: wrapperOptions({}),
86
161
  exec: wrapperOptions({ shortValues: 'a' }),
@@ -96,6 +171,8 @@ const WRAPPER_OPTIONS: Record<string, IWrapperOptions> = {
96
171
  positionals: 1,
97
172
  }),
98
173
  setsid: wrapperOptions({}),
174
+ // `busybox ln ...`: the applet is the program.
175
+ busybox: wrapperOptions({}),
99
176
  watch: wrapperOptions({ shortValues: 'nq', longValues: ['--interval', '--equexit'] }),
100
177
  // `--eof`, `--max-lines` and `--replace` take an optional value attached with `=`, never the next word.
101
178
  xargs: wrapperOptions({
@@ -109,7 +186,7 @@ const WRAPPER_OPTIONS: Record<string, IWrapperOptions> = {
109
186
  '--process-slot-var',
110
187
  ],
111
188
  }),
112
- // Not a wrapper of a local command: its options are known so `remote-hosts` can read past them.
189
+ // Not a wrapper of a local command: its options are known so a reader can read past them.
113
190
  sshpass: wrapperOptions({ shortValues: 'pfPd' }),
114
191
  };
115
192
  /** The programs whose words after their own options are the command they run. */
@@ -119,60 +196,23 @@ const WRAPPERS = new Set(Object.keys(WRAPPER_OPTIONS).filter((name) => name !==
119
196
  const wrapperPositionals = (opts: { wrapper: string }): number =>
120
197
  WRAPPER_OPTIONS[opts.wrapper]?.positionals ?? 0;
121
198
 
122
- /** The program names `remote-hosts.ts` reads too: one table here, so the two parsers cannot drift apart. */
199
+ /** The program names the guards read: one table here, so the readers cannot drift apart. */
123
200
  export class ShellPrograms {
124
201
  /** Every wrapper whose options the parser knows, `command` and `sshpass` included; a reader drops what it handles apart. */
125
202
  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'];
203
+ /** The shells whose heredoc body is read as commands. */
204
+ static readonly SHELL_NAMES: readonly string[] = ['bash', 'sh', 'zsh', 'dash', 'ksh'];
205
+ /** The options of `find` that run a command, each ended by a `;` or a `+`. */
206
+ static readonly FIND_RUN_OPTIONS: readonly string[] = ['-exec', '-execdir', '-ok', '-okdir'];
128
207
  }
129
208
 
130
209
  const SHELLS = new Set(ShellPrograms.SHELL_NAMES);
210
+ const FIND_RUN_OPTIONS = new Set(ShellPrograms.FIND_RUN_OPTIONS);
131
211
 
132
- const MAX_DEPTH = 4;
133
-
134
- /**
135
- * The index of the character that closes what was opened just before `from` (`$(` or a backtick), or the end
136
- * of the text when it never closes. Quotes and backslashes are read: a `)` inside quotes does not close.
137
- */
138
- const closingOf = (opts: { text: string; from: number; open: string; close: string }): number => {
139
- let depth = 1;
140
- let quote: string | undefined;
141
-
142
- for (let index = opts.from; index < opts.text.length; index += 1) {
143
- const char = opts.text[index];
144
-
145
- if (char === '\\' && quote !== "'") {
146
- index += 1;
147
- continue;
148
- }
149
-
150
- if (quote !== undefined) {
151
- if (char === quote) {
152
- quote = undefined;
153
- }
154
-
155
- continue;
156
- }
157
-
158
- if (char === "'" || char === '"') {
159
- quote = char;
160
- continue;
161
- }
162
-
163
- if (char === opts.open && opts.open !== opts.close) {
164
- depth += 1;
165
- } else if (char === opts.close) {
166
- depth -= 1;
167
- }
168
-
169
- if (depth === 0) {
170
- return index;
171
- }
172
- }
212
+ /** The mark of an open `case` among the groups the parser tracks: its `)` closes a pattern. */
213
+ const CASE_GROUP = 'case';
173
214
 
174
- return opts.text.length;
175
- };
215
+ const MAX_DEPTH = 4;
176
216
 
177
217
  const ANSI_C_ESCAPES: Record<string, string> = {
178
218
  a: '\x07',
@@ -261,13 +301,58 @@ const readAnsiC = (opts: { text: string; from: number }): { value: string; next:
261
301
  return { value, next: Math.min(end + 1, text.length) };
262
302
  };
263
303
 
264
- /** One word from `from`: quotes and escapes resolved, substitutions set aside in `nested`. */
265
- const readWord = (opts: { text: string; from: number }): IWordRead => {
266
- const { text } = opts;
304
+ /** The text of a backtick substitution as the shell reads it again: a backslash before `\`, a backtick or `$` goes. */
305
+ const unescapeBackticks = (opts: { text: string }): string =>
306
+ opts.text.replace(/\\([\\`$])/g, '$1');
307
+
308
+ /** Appends every item; a spread into `push` overflows the stack at a few hundred thousand items. */
309
+ const pushAll = <T>(opts: { target: T[]; items: T[] }): void => {
310
+ for (const item of opts.items) {
311
+ opts.target.push(item);
312
+ }
313
+ };
314
+
315
+ /** The text of each substitution between `from` and `to`, outermost only, by the positions `layout` holds. */
316
+ const substitutionsIn = (opts: {
317
+ text: string;
318
+ from: number;
319
+ to: number;
320
+ layout: IShellLayout;
321
+ }): string[] => {
322
+ const { text, layout } = opts;
323
+ const found: string[] = [];
324
+ let index = opts.from;
325
+
326
+ while (index < opts.to) {
327
+ const close = layout.closes.get(index);
328
+
329
+ if (close === undefined) {
330
+ index += 1;
331
+ continue;
332
+ }
333
+
334
+ found.push(
335
+ text[index] === '`'
336
+ ? unescapeBackticks({ text: text.slice(index + 1, close) })
337
+ : text.slice(index + 2, close),
338
+ );
339
+ index = close + 1;
340
+ }
341
+
342
+ return found;
343
+ };
344
+
345
+ /**
346
+ * One word from `from`: quotes and escapes resolved, substitutions set aside in `nested`. `layout` is what the
347
+ * scanner found in `text`: where each substitution and arithmetic closes.
348
+ */
349
+ const readWord = (opts: { text: string; from: number; layout: IShellLayout }): IWordRead => {
350
+ const { text, layout } = opts;
267
351
  const nested: string[] = [];
268
352
  let value = '';
269
353
  let index = opts.from;
270
354
  let quote: string | undefined;
355
+ let hasLiteralDollar = false;
271
356
 
272
357
  while (index < text.length) {
273
358
  const char = text[index];
@@ -292,6 +377,7 @@ const readWord = (opts: { text: string; from: number }): IWordRead => {
292
377
  continue;
293
378
  }
294
379
 
380
+ hasLiteralDollar ||= next === '$';
295
381
  value += next;
296
382
  index += 2;
297
383
  continue;
@@ -301,6 +387,7 @@ const readWord = (opts: { text: string; from: number }): IWordRead => {
301
387
  if (quote === undefined && char === '$' && text[index + 1] === "'") {
302
388
  const decoded = readAnsiC({ text, from: index + 2 });
303
389
 
390
+ hasLiteralDollar ||= decoded.value.includes('$');
304
391
  value += decoded.value;
305
392
  index = decoded.next;
306
393
  continue;
@@ -324,8 +411,21 @@ const readWord = (opts: { text: string; from: number }): IWordRead => {
324
411
  continue;
325
412
  }
326
413
 
414
+ // `$((...))` and `$[...]` are arithmetic: only the substitutions inside them are commands.
415
+ const arithmeticEnd = quote === "'" ? undefined : layout.ariths.get(index);
416
+
417
+ if (arithmeticEnd !== undefined) {
418
+ pushAll({
419
+ target: nested,
420
+ items: substitutionsIn({ text, from: index + 1, to: arithmeticEnd, layout }),
421
+ });
422
+ value += text.slice(index, arithmeticEnd + 1);
423
+ index = arithmeticEnd + 1;
424
+ continue;
425
+ }
426
+
327
427
  if (quote !== "'" && char === '$' && text[index + 1] === '(') {
328
- const end = closingOf({ text, from: index + 2, open: '(', close: ')' });
428
+ const end = layout.closes.get(index) ?? text.length;
329
429
 
330
430
  nested.push(text.slice(index + 2, end));
331
431
  value += text.slice(index, end + 1);
@@ -334,19 +434,24 @@ const readWord = (opts: { text: string; from: number }): IWordRead => {
334
434
  }
335
435
 
336
436
  if (quote !== "'" && char === '`') {
337
- const end = closingOf({ text, from: index + 1, open: '`', close: '`' });
437
+ const end = layout.closes.get(index) ?? text.length;
338
438
 
339
- nested.push(text.slice(index + 1, end));
439
+ nested.push(unescapeBackticks({ text: text.slice(index + 1, end) }));
340
440
  value += text.slice(index, end + 1);
341
441
  index = end + 1;
342
442
  continue;
343
443
  }
344
444
 
445
+ // A `$` that starts no expansion is a character: one in single quotes, or one before a closing quote, a backslash, a blank or the
446
+ // end (`"$"S`, `$\S`), where the text after quote removal still reads as `$S`.
447
+ hasLiteralDollar ||=
448
+ char === '$' &&
449
+ (quote === "'" || (text[index - 1] !== '$' && !/[\w{(@*#?$!-]/.test(text[index + 1] ?? '')));
345
450
  value += char;
346
451
  index += 1;
347
452
  }
348
453
 
349
- return { value, next: index, nested };
454
+ return { value, next: index, nested, hasLiteralDollar };
350
455
  };
351
456
 
352
457
  /** `NAME=value`: a leading assignment, not a program. */
@@ -409,80 +514,760 @@ const ENV_ESCAPES: Record<string, string> = {
409
514
  "'": "'",
410
515
  };
411
516
 
517
+ /** What the parser reads of one command line at most: a guard that reads more would be slow, and a slow guard is skipped. */
518
+ export class ShellBudget {
519
+ static readonly MAX_COMMANDS = 2000;
520
+ static readonly MAX_WORDS = 20_000;
521
+ /** The characters of a line and of every text nested in it, together: a line over it is not read at all. */
522
+ static readonly MAX_CHARS = 100_000;
523
+ /** Quotes, substitutions and arithmetic open inside each other at once: a line deeper than this is not followed. */
524
+ static readonly MAX_NESTING = 64;
525
+ }
526
+
527
+ /** What the scanner can be inside. */
528
+ class ScanKinds {
529
+ /** Commands: the line itself, `$(...)`, `<(...)`, `>(...)`. */
530
+ static readonly COMMAND = 'command';
531
+ static readonly BACKTICK = 'backtick';
532
+ static readonly DOUBLE = 'double';
533
+ /** `$((...))`, `((...))` and `$[...]`. */
534
+ static readonly ARITHMETIC = 'arithmetic';
535
+ /** `${...}`. */
536
+ static readonly BRACE = 'brace';
537
+ /** The body of a heredoc whose delimiter is not quoted: only substitutions mean something in it. */
538
+ static readonly BODY = 'body';
539
+ }
540
+
541
+ type TScanKind = TConstValue<typeof ScanKinds>;
542
+
543
+ /** A heredoc whose operator was read and whose body starts at the next newline of its context. */
544
+ interface IPendingHeredoc {
545
+ delimiter: string;
546
+ stripTabs: boolean;
547
+ isQuoted: boolean;
548
+ /** The operator in the kept text: where it starts and where it ends. */
549
+ at: number;
550
+ end: number;
551
+ /** A shell reads the body as commands (`bash <<EOF`). */
552
+ isInline: boolean;
553
+ }
554
+
555
+ interface IScanContext {
556
+ kind: TScanKind;
557
+ /** Where the opener starts in the kept text: the key of `closes` or `ariths`. */
558
+ at: number;
559
+ /** What closes it: `)`, a backtick, `))`, `]`, `}`, `"`, or nothing for the outermost text. */
560
+ close: string;
561
+ /** Parentheses, brackets or braces opened inside it and not closed yet. */
562
+ depth: number;
563
+ pending: IPendingHeredoc[];
564
+ /** Where its current command starts in the kept text, and the program found for the command that starts there. */
565
+ commandStart: number;
566
+ program: { start: number; name: string };
567
+ isOuter: boolean;
568
+ /** Inside double quotes, where a single quote is a character. */
569
+ isQuoted: boolean;
570
+ /** The `case` commands opened in it and not yet closed by `esac`: a `)` there ends a pattern. */
571
+ cases: number;
572
+ }
573
+
574
+ /** A heredoc of the outermost text, keyed by where its operator starts in the kept text. */
575
+ interface IHeredocAt {
576
+ heredoc: IHeredoc;
577
+ /** Where the operator ends in the kept text. */
578
+ end: number;
579
+ /** The substitutions of a body whose delimiter is not quoted: bash runs them. */
580
+ substitutions: string[];
581
+ /** The delimiter is quoted: the body is data. */
582
+ isQuoted: boolean;
583
+ }
584
+
585
+ /** What the scanner found in a text, every position an index of the kept text. */
586
+ interface IShellLayout {
587
+ /**
588
+ * The text without comments and without the heredoc bodies of the outermost text that are data. A body inside
589
+ * a substitution stays, for the substitution to be read again with it.
590
+ */
591
+ text: string;
592
+ /** `text` without the data bodies inside substitutions too: what a reader of the whole line sees run. */
593
+ view: string;
594
+ heredocs: IHeredoc[];
595
+ heredocAt: Map<number, IHeredocAt>;
596
+ /** The index of the character that closes each `$(`, `<(`, `>(` and backtick, by the index of its opener. */
597
+ closes: Map<number, number>;
598
+ /** The index of the last character of each `$((...))`, `((...))` and `$[...]`, by the index of its opener. */
599
+ ariths: Map<number, number>;
600
+ /** Something could not be followed to its end: a quote, a substitution or a heredoc operator. */
601
+ isUncertain: boolean;
602
+ /** The bodies of heredocs whose delimiter never came, the end of the text ending them. */
603
+ unterminated: string[];
604
+ }
605
+
606
+ interface IScanOptions {
607
+ text: string;
608
+ /** The heredoc bodies read as scripts around the text. */
609
+ depth: number;
610
+ /** The text is a heredoc body, where only substitutions mean something. */
611
+ isBody: boolean;
612
+ /** The program of the command that starts at `from` in `text`: a shell reads its heredoc body as commands. */
613
+ programBefore: (opts: { text: string; from: number; layout: IShellLayout }) => string;
614
+ }
615
+
616
+ /** The characters before which a `#` starts a comment and `((` starts arithmetic. */
617
+ const WORD_STARTS = new Set([' ', '\t', '\n', ';', '&', '|', '(', ')', '<', '>']);
618
+
412
619
  /**
413
- * The delimiter of a heredoc started on `line`: a `<<WORD` outside quotes. `<<<` is a here-string, and a `<<`
414
- * inside quotes is text.
620
+ * Reads a text left to right the way bash does, once: quotes (single, double, `$'...'`, backticks), `$(...)` and
621
+ * `${...}` nesting, arithmetic, escapes and comments, across lines. It finds each heredoc (a `<<WORD` outside
622
+ * quotes, comments and arithmetic) and its body, which starts at the next newline of the same context and ends
623
+ * at the delimiter line. Whatever it cannot follow to its end it flags, and never hides.
415
624
  */
416
- const heredocOf = (opts: {
417
- line: string;
418
- }): { delimiter: string; stripTabs: boolean; at: number } | undefined => {
419
- const { line } = opts;
420
- let quote: string | undefined;
625
+ class ShellScanner {
626
+ /** The heredoc operator at `from` (`<<`, `<<-`, then the delimiter word); `undefined` when there is no word. */
627
+ private static operatorAt(opts: {
628
+ text: string;
629
+ from: number;
630
+ }): { delimiter: string; isQuoted: boolean; stripTabs: boolean; end: number } | undefined {
631
+ const { text } = opts;
632
+ let index = opts.from + 2;
633
+ const stripTabs = text[index] === '-';
634
+
635
+ index += stripTabs ? 1 : 0;
636
+
637
+ while (text[index] === ' ' || text[index] === '\t') {
638
+ index += 1;
639
+ }
640
+
641
+ // The delimiter is a word with its quotes removed; any quote or backslash in it means the body is not expanded.
642
+ let delimiter = '';
643
+ let isQuoted = false;
644
+
645
+ while (index < text.length && !WORD_END.has(text[index] ?? '')) {
646
+ const char = text[index] ?? '';
647
+
648
+ if (char === '\\') {
649
+ isQuoted = true;
650
+ delimiter += text[index + 1] ?? '';
651
+ index += 2;
652
+ continue;
653
+ }
654
+
655
+ if (char === "'" || char === '"') {
656
+ const close = text.indexOf(char, index + 1);
657
+
658
+ if (close === -1) {
659
+ return undefined;
660
+ }
661
+
662
+ isQuoted = true;
663
+ delimiter += text.slice(index + 1, close);
664
+ index = close + 1;
665
+ continue;
666
+ }
667
+
668
+ delimiter += char;
669
+ index += 1;
670
+ }
671
+
672
+ return delimiter === '' && !isQuoted
673
+ ? undefined
674
+ : { delimiter, isQuoted, stripTabs, end: index };
675
+ }
676
+
677
+ /** Whether `line` ends with a backslash that is not itself escaped. */
678
+ private static endsEscaped(opts: { line: string }): boolean {
679
+ let count = 0;
680
+
681
+ while (opts.line[opts.line.length - 1 - count] === '\\') {
682
+ count += 1;
683
+ }
684
+
685
+ return count % 2 === 1;
686
+ }
687
+
688
+ /** The index of the second `<` of a `<<` at `index`, a backslash-newline between them allowed; -1 when there is none. */
689
+ private static secondAngleAt(opts: { text: string; index: number }): number {
690
+ const { text, index } = opts;
691
+
692
+ if (text[index + 1] === '<') {
693
+ return index + 1;
694
+ }
695
+
696
+ return text.startsWith('\\\n<', index + 1) ? index + 3 : -1;
697
+ }
698
+
699
+ /**
700
+ * `case` or `esac` when the word at `index` is that reserved word where a command starts: after an
701
+ * operator, an opening parenthesis or backtick, `then`, `else`, `do` or `{`. Anything else is an empty string.
702
+ */
703
+ private static reservedAt(opts: { text: string; index: number }): string {
704
+ const { text, index } = opts;
705
+ const word = text.slice(index, index + 4);
706
+
707
+ if (
708
+ (word !== 'case' && word !== 'esac') ||
709
+ !/^(?:[\s;&|()<>]|$)/.test(text.slice(index + 4, index + 5))
710
+ ) {
711
+ return '';
712
+ }
713
+
714
+ let before = index - 1;
715
+
716
+ while (text[before] === ' ' || text[before] === '\t') {
717
+ before -= 1;
718
+ }
719
+
720
+ const lead = text.slice(Math.max(0, before - 4), before + 1);
721
+
722
+ return before < 0 || /(?:[;&|(\n`]|(?:^|[\s;&|(])(?:then|else|do|\{))$/.test(lead) ? word : '';
723
+ }
724
+
725
+ /** Moves every position of `from` by `shift` into `into`: a text scanned apart and spliced in. */
726
+ private static merge(opts: { into: IShellLayout; from: IShellLayout; shift: number }): void {
727
+ const { into, from, shift } = opts;
728
+
729
+ pushAll({ target: into.heredocs, items: from.heredocs });
730
+ pushAll({ target: into.unterminated, items: from.unterminated });
731
+ into.isUncertain ||= from.isUncertain;
732
+
733
+ for (const [at, heredoc] of from.heredocAt) {
734
+ into.heredocAt.set(at + shift, { ...heredoc, end: heredoc.end + shift });
735
+ }
736
+
737
+ for (const [at, end] of from.closes) {
738
+ into.closes.set(at + shift, end + shift);
739
+ }
740
+
741
+ for (const [at, end] of from.ariths) {
742
+ into.ariths.set(at + shift, end + shift);
743
+ }
744
+ }
745
+
746
+ /** The substitutions bash runs in a heredoc body whose delimiter is not quoted. */
747
+ private static substitutionsOfBody(opts: { body: string; scan: IScanOptions }): {
748
+ texts: string[];
749
+ isUncertain: boolean;
750
+ } {
751
+ const layout = ShellScanner.scan({
752
+ ...opts.scan,
753
+ text: opts.body,
754
+ depth: opts.scan.depth + 1,
755
+ isBody: true,
756
+ });
757
+
758
+ return {
759
+ texts: substitutionsIn({
760
+ text: layout.text,
761
+ from: 0,
762
+ to: layout.text.length,
763
+ layout,
764
+ }),
765
+ isUncertain: layout.isUncertain,
766
+ };
767
+ }
768
+
769
+ /** Scans `opts.text`. */
770
+ static scan(opts: IScanOptions): IShellLayout {
771
+ const { text, depth } = opts;
772
+ const layout: IShellLayout = {
773
+ text: '',
774
+ view: '',
775
+ heredocs: [],
776
+ heredocAt: new Map(),
777
+ closes: new Map(),
778
+ ariths: new Map(),
779
+ isUncertain: false,
780
+ unterminated: [],
781
+ };
782
+ const outer: IScanContext = {
783
+ kind: opts.isBody ? ScanKinds.BODY : ScanKinds.COMMAND,
784
+ at: 0,
785
+ close: '',
786
+ depth: 0,
787
+ pending: [],
788
+ commandStart: 0,
789
+ program: { start: -1, name: '' },
790
+ isOuter: true,
791
+ isQuoted: false,
792
+ cases: 0,
793
+ };
794
+ const stack: IScanContext[] = [outer];
795
+ // `out` is the kept text the positions point into; `view` drops the data bodies inside substitutions too.
796
+ let out = '';
797
+ let view = '';
798
+ let index = 0;
799
+ // Where a word may start: after a blank or an operator of a command context, never right after an expansion.
800
+ let breakAt = 0;
801
+
802
+ const append = (piece: string): void => {
803
+ out += piece;
804
+ view += piece;
805
+ };
806
+
807
+ const copy = (length: number): void => {
808
+ append(text.slice(index, index + length));
809
+ index += length;
810
+ };
811
+
812
+ const open = (opener: { kind: TScanKind; close: string; length: number }): void => {
813
+ const parent = stack[stack.length - 1] ?? outer;
814
+
815
+ stack.push({
816
+ kind: opener.kind,
817
+ at: out.length,
818
+ close: opener.close,
819
+ depth: 0,
820
+ pending: [],
821
+ commandStart: out.length + opener.length,
822
+ program: { start: -1, name: '' },
823
+ isOuter: false,
824
+ isQuoted: opener.kind === ScanKinds.DOUBLE || parent.isQuoted,
825
+ cases: 0,
826
+ });
827
+ copy(opener.length);
828
+ breakAt = index;
829
+ };
830
+
831
+ const pop = (): void => {
832
+ const closed = stack.pop();
833
+
834
+ // A heredoc opened inside a substitution that closes before its body starts.
835
+ layout.isUncertain ||= (closed?.pending.length ?? 0) > 0;
836
+ };
837
+
838
+ // What cannot be followed is kept as it is, and flagged.
839
+ const giveUp = (): void => {
840
+ layout.isUncertain = true;
841
+ append(text.slice(index));
842
+ index = text.length;
843
+ };
844
+
845
+ const record = (entry: {
846
+ pending: IPendingHeredoc;
847
+ body: string;
848
+ substitutions: string[];
849
+ }): void => {
850
+ const heredoc: IHeredoc = { body: entry.body, isInline: entry.pending.isInline };
851
+
852
+ layout.heredocs.push(heredoc);
853
+ layout.heredocAt.set(entry.pending.at, {
854
+ heredoc,
855
+ end: entry.pending.end,
856
+ substitutions: entry.substitutions,
857
+ isQuoted: entry.pending.isQuoted,
858
+ });
859
+ };
860
+
861
+ // At a newline of `context`: the bodies of its heredocs, in order, each up to its delimiter line.
862
+ const readBodies = (context: IScanContext): void => {
863
+ for (const pending of context.pending) {
864
+ const start = index;
865
+ let bodyEnd = text.length;
866
+ let next = text.length;
867
+ let isFound = false;
868
+ // In a body whose delimiter is not quoted, a backslash-newline joins two lines into one.
869
+ let carry = '';
870
+
871
+ while (index < text.length) {
872
+ const newline = text.indexOf('\n', index);
873
+ const lineEnd = newline === -1 ? text.length : newline;
874
+ const line = carry + text.slice(index, lineEnd);
875
+ const after = newline === -1 ? text.length : newline + 1;
876
+ const isJoined =
877
+ !pending.isQuoted && newline !== -1 && ShellScanner.endsEscaped({ line });
878
+
879
+ // A joined line longer than the delimiter can never be it: a newline marks it, and costs nothing to carry.
880
+ const isShort = line.length <= pending.delimiter.length + 1;
881
+
882
+ carry = isJoined && isShort ? line.slice(0, -1) : '';
883
+ carry = isJoined && !isShort ? '\n' : carry;
884
+
885
+ // The delimiter line is the delimiter exactly; `<<-` strips leading tabs first.
886
+ if (
887
+ !isJoined &&
888
+ (pending.stripTabs ? line.replace(/^\t+/, '') : line) === pending.delimiter
889
+ ) {
890
+ bodyEnd = Math.max(start, index - 1);
891
+ next = after;
892
+ isFound = true;
893
+ break;
894
+ }
895
+
896
+ index = after;
897
+ }
898
+
899
+ const body = text.slice(start, bodyEnd);
900
+
901
+ index = next;
902
+
903
+ // Inside a substitution the body stays in the kept text: the substitution is read again on its own.
904
+ if (!context.isOuter) {
905
+ out += text.slice(start, next);
906
+ view += pending.isInline ? text.slice(start, next) : '';
907
+ continue;
908
+ }
909
+
910
+ if (pending.isInline) {
911
+ if (depth + 1 > MAX_DEPTH) {
912
+ layout.isUncertain = true;
913
+ append(body);
914
+ } else {
915
+ const script = ShellScanner.scan({ ...opts, text: body, depth: depth + 1 });
916
+
917
+ ShellScanner.merge({ into: layout, from: script, shift: out.length });
918
+ out += script.text;
919
+ view += script.view;
920
+ }
921
+
922
+ append(isFound && body !== '' ? '\n' : '');
923
+ record({ pending, body, substitutions: [] });
924
+ continue;
925
+ }
926
+
927
+ const expanded = pending.isQuoted
928
+ ? { texts: [], isUncertain: false }
929
+ : ShellScanner.substitutionsOfBody({ body, scan: opts });
930
+
931
+ layout.isUncertain ||= expanded.isUncertain;
932
+
933
+ if (!isFound && body.trim() !== '') {
934
+ layout.unterminated.push(body);
935
+ }
936
+
937
+ record({ pending, body, substitutions: expanded.texts });
938
+ }
939
+
940
+ context.pending = [];
941
+ };
942
+
943
+ while (index < text.length) {
944
+ if (stack.length > ShellBudget.MAX_NESTING) {
945
+ giveUp();
946
+ break;
947
+ }
948
+
949
+ const context = stack[stack.length - 1] ?? outer;
950
+ const { kind } = context;
951
+ const char = text[index] ?? '';
952
+ const next = text[index + 1] ?? '';
953
+ const isCommand = kind === ScanKinds.COMMAND || kind === ScanKinds.BACKTICK;
954
+ const isWordStart = index === breakAt;
955
+ const takesSingle =
956
+ isCommand ||
957
+ kind === ScanKinds.ARITHMETIC ||
958
+ (kind === ScanKinds.BRACE && !context.isQuoted);
959
+
960
+ if (char === '\\') {
961
+ // A backslash-newline is removed before words are read: a word that started before it still starts.
962
+ const isJoin = next === '\n' && isWordStart;
963
+
964
+ copy(2);
965
+ breakAt = isJoin ? index : breakAt;
966
+ continue;
967
+ }
968
+
969
+ if (char === "'" && takesSingle) {
970
+ const close = text.indexOf("'", index + 1);
971
+
972
+ if (close === -1) {
973
+ giveUp();
974
+ break;
975
+ }
976
+
977
+ copy(close + 1 - index);
978
+ continue;
979
+ }
980
+
981
+ if (char === '$' && next === "'" && takesSingle) {
982
+ let end = index + 2;
983
+
984
+ while (end < text.length && text[end] !== "'") {
985
+ end += text[end] === '\\' ? 2 : 1;
986
+ }
987
+
988
+ if (end >= text.length) {
989
+ giveUp();
990
+ break;
991
+ }
992
+
993
+ copy(end + 1 - index);
994
+ continue;
995
+ }
996
+
997
+ if (char === '"' && kind === ScanKinds.DOUBLE) {
998
+ copy(1);
999
+ pop();
1000
+ continue;
1001
+ }
1002
+
1003
+ if (char === '"' && kind !== ScanKinds.BODY) {
1004
+ open({ kind: ScanKinds.DOUBLE, close: '"', length: 1 });
1005
+ continue;
1006
+ }
1007
+
1008
+ if (char === '$' && next === '"' && isCommand) {
1009
+ open({ kind: ScanKinds.DOUBLE, close: '"', length: 2 });
1010
+ continue;
1011
+ }
1012
+
1013
+ if (char === '$' && next === '(' && text[index + 2] === '(') {
1014
+ open({ kind: ScanKinds.ARITHMETIC, close: '))', length: 3 });
1015
+ continue;
1016
+ }
1017
+
1018
+ if (char === '$' && next === '(') {
1019
+ open({ kind: ScanKinds.COMMAND, close: ')', length: 2 });
1020
+ continue;
1021
+ }
1022
+
1023
+ if (char === '$' && next === '[') {
1024
+ open({ kind: ScanKinds.ARITHMETIC, close: ']', length: 2 });
1025
+ continue;
1026
+ }
1027
+
1028
+ if (char === '$' && next === '{') {
1029
+ open({ kind: ScanKinds.BRACE, close: '}', length: 2 });
1030
+ continue;
1031
+ }
1032
+
1033
+ if (char === '`' && kind === ScanKinds.BACKTICK) {
1034
+ layout.closes.set(context.at, out.length);
1035
+ copy(1);
1036
+ pop();
1037
+ continue;
1038
+ }
1039
+
1040
+ if (char === '`') {
1041
+ open({ kind: ScanKinds.BACKTICK, close: '`', length: 1 });
1042
+ continue;
1043
+ }
1044
+
1045
+ if (kind === ScanKinds.ARITHMETIC) {
1046
+ const isBracket = context.close === ']';
1047
+
1048
+ if (char === (isBracket ? '[' : '(')) {
1049
+ context.depth += 1;
1050
+ copy(1);
1051
+ continue;
1052
+ }
1053
+
1054
+ if (char === (isBracket ? ']' : ')') && context.depth > 0) {
1055
+ context.depth -= 1;
1056
+ copy(1);
1057
+ continue;
1058
+ }
1059
+
1060
+ if (char === ']' && isBracket) {
1061
+ layout.ariths.set(context.at, out.length);
1062
+ copy(1);
1063
+ pop();
1064
+ continue;
1065
+ }
1066
+
1067
+ if (char === ')') {
1068
+ // `((` that does not end in `))` is not arithmetic: bash reads it again as subshells.
1069
+ if (next === ')') {
1070
+ layout.ariths.set(context.at, out.length + 1);
1071
+ } else {
1072
+ layout.isUncertain = true;
1073
+ }
1074
+
1075
+ copy(next === ')' ? 2 : 1);
1076
+ pop();
1077
+ continue;
1078
+ }
1079
+
1080
+ copy(1);
1081
+ continue;
1082
+ }
1083
+
1084
+ if (kind === ScanKinds.BRACE) {
1085
+ if (char === '{') {
1086
+ context.depth += 1;
1087
+ } else if (char === '}' && context.depth > 0) {
1088
+ context.depth -= 1;
1089
+ } else if (char === '}') {
1090
+ copy(1);
1091
+ pop();
1092
+ continue;
1093
+ }
1094
+
1095
+ copy(1);
1096
+ continue;
1097
+ }
1098
+
1099
+ if (!isCommand) {
1100
+ copy(1);
1101
+ continue;
1102
+ }
1103
+
1104
+ // A comment runs to the end of the line; it is dropped from the outermost text.
1105
+ if (char === '#' && isWordStart) {
1106
+ const newline = text.indexOf('\n', index);
1107
+ const end = newline === -1 ? text.length : newline;
1108
+
1109
+ if (context.isOuter) {
1110
+ index = end;
1111
+ } else {
1112
+ copy(end - index);
1113
+ }
1114
+
1115
+ continue;
1116
+ }
1117
+
1118
+ if (char === '(' && next === '(' && isWordStart) {
1119
+ open({ kind: ScanKinds.ARITHMETIC, close: '))', length: 2 });
1120
+ continue;
1121
+ }
1122
+
1123
+ // `case WORD in` opens patterns, each ended by a `)` that closes no substitution; `esac` ends them.
1124
+ if (isWordStart && !context.isOuter) {
1125
+ const reserved = ShellScanner.reservedAt({ text, index });
1126
+
1127
+ context.cases += reserved === 'case' ? 1 : 0;
1128
+ context.cases -= reserved === 'esac' && context.cases > 0 ? 1 : 0;
1129
+ }
1130
+
1131
+ if ((char === '<' || char === '>') && next === '(') {
1132
+ open({ kind: ScanKinds.COMMAND, close: ')', length: 2 });
1133
+ continue;
1134
+ }
1135
+
1136
+ // The second `<` of an operator, past a backslash-newline between the two.
1137
+ const second = char === '<' ? ShellScanner.secondAngleAt({ text, index }) : -1;
1138
+
1139
+ if (second !== -1 && text[second + 1] === '<') {
1140
+ copy(second + 2 - index);
1141
+ breakAt = index;
1142
+ continue;
1143
+ }
1144
+
1145
+ if (second !== -1) {
1146
+ const operator = ShellScanner.operatorAt({ text, from: second - 1 });
1147
+
1148
+ if (operator === undefined) {
1149
+ layout.isUncertain = true;
1150
+ copy(2);
1151
+ continue;
1152
+ }
1153
+
1154
+ // The program is found once per command, however many heredocs it has.
1155
+ if (context.program.start !== context.commandStart) {
1156
+ context.program = {
1157
+ start: context.commandStart,
1158
+ name: opts.programBefore({ text: out, from: context.commandStart, layout }),
1159
+ };
1160
+ }
1161
+
1162
+ const at = out.length;
1163
+
1164
+ copy(operator.end - index);
1165
+ context.pending.push({
1166
+ ...operator,
1167
+ at,
1168
+ end: out.length,
1169
+ isInline: SHELLS.has(context.program.name),
1170
+ });
1171
+ continue;
1172
+ }
421
1173
 
422
- for (let index = 0; index < line.length; index += 1) {
423
- const char = line[index];
1174
+ if (char === '\n') {
1175
+ copy(1);
1176
+ context.commandStart = out.length;
424
1177
 
425
- if (char === '\\' && quote !== "'") {
426
- index += 1;
427
- continue;
428
- }
1178
+ if (context.pending.length > 0) {
1179
+ readBodies(context);
1180
+ context.commandStart = out.length;
1181
+ }
429
1182
 
430
- if (quote !== undefined) {
431
- if (char === quote) {
432
- quote = undefined;
1183
+ breakAt = index;
1184
+ continue;
433
1185
  }
434
1186
 
435
- continue;
436
- }
1187
+ // Inside a substitution: a subshell, the `)` of a case pattern, or the end of the substitution.
1188
+ const isNestedParen = !context.isOuter && (char === '(' || char === ')');
1189
+ const isOwnClose =
1190
+ char === ')' && context.close === ')' && context.depth === 0 && context.cases === 0;
437
1191
 
438
- if (char === "'" || char === '"') {
439
- quote = char;
440
- continue;
441
- }
1192
+ if (isNestedParen && !isOwnClose) {
1193
+ context.depth += char === '(' ? 1 : -Math.min(1, context.depth);
1194
+ copy(1);
1195
+ context.commandStart = out.length;
1196
+ breakAt = index;
1197
+ continue;
1198
+ }
442
1199
 
443
- if (char === '<' && line[index + 1] === '<') {
444
- if (line[index + 2] === '<') {
445
- index += 2;
1200
+ if (isOwnClose) {
1201
+ layout.closes.set(context.at, out.length);
1202
+ copy(1);
1203
+ pop();
446
1204
  continue;
447
1205
  }
448
1206
 
449
- const match = /^<<(-?)\s*(["']?)([A-Za-z_]\w*)\2/.exec(line.slice(index));
1207
+ copy(1);
450
1208
 
451
- if (match !== null) {
452
- return { delimiter: match[3] ?? '', stripTabs: match[1] === '-', at: index };
1209
+ if (';&|()'.includes(char)) {
1210
+ context.commandStart = out.length;
453
1211
  }
454
1212
 
455
- index += 1;
1213
+ if (WORD_STARTS.has(char)) {
1214
+ breakAt = index;
1215
+ }
456
1216
  }
457
- }
458
1217
 
459
- return undefined;
460
- };
1218
+ // A heredoc at the very end, with no newline after it, has an empty body.
1219
+ for (const pending of outer.pending) {
1220
+ record({ pending, body: '', substitutions: [] });
1221
+ }
461
1222
 
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);
1223
+ layout.isUncertain ||= stack.length > 1;
1224
+ layout.text = out;
1225
+ layout.view = view;
1226
+
1227
+ return layout;
466
1228
  }
467
- };
1229
+ }
468
1230
 
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;
1231
+ /** Why a guard could not read a line in full: it asks, because an unread part is never an allow. */
1232
+ export class ShellUnread {
1233
+ /** The line is over `ShellBudget`, or nests past the depth limit. */
1234
+ static readonly OVER_BUDGET =
1235
+ 'this command line is larger, or nests deeper, than the guard reads, so it could not be checked';
1236
+ /** The scanner could not follow part of the line to its end. */
1237
+ static readonly UNCERTAIN =
1238
+ 'this command line has a quote, substitution or heredoc that does not close, or a form the guard does not follow, so it could not be checked';
1239
+
1240
+ /** A command runs a program the line does not show: a variable or a substitution in its place. */
1241
+ static readonly UNKNOWN_PROGRAM =
1242
+ 'a command on this line runs a program named by a variable, a substitution, a glob or a brace pattern, or runs a ${var@P} expansion, so it could not be checked';
1243
+
1244
+ /** The reason a parse was not read in full, or `undefined` when all of it was read. */
1245
+ static reasonOf(opts: {
1246
+ isOverBudget: boolean;
1247
+ isUncertain: boolean;
1248
+ hasUnknownProgram: boolean;
1249
+ }): string | undefined {
1250
+ if (opts.isOverBudget) {
1251
+ return ShellUnread.OVER_BUDGET;
1252
+ }
1253
+
1254
+ if (opts.isUncertain) {
1255
+ return ShellUnread.UNCERTAIN;
1256
+ }
1257
+
1258
+ return opts.hasUnknownProgram ? ShellUnread.UNKNOWN_PROGRAM : undefined;
1259
+ }
475
1260
  }
476
1261
 
477
1262
  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;
1263
+ /** The program of the last simple command of `text` from `from`: what a heredoc that starts after it is fed to. */
1264
+ private static programBefore(opts: { text: string; from: number; layout: IShellLayout }): string {
1265
+ const { text, layout } = opts;
481
1266
  let words: string[] = [];
482
- let index = 0;
1267
+ let index = opts.from;
483
1268
 
484
- while (index < prefix.length) {
485
- const char = prefix[index] ?? '';
1269
+ while (index < text.length) {
1270
+ const char = text[index] ?? '';
486
1271
 
487
1272
  if (char === ' ' || char === '\t') {
488
1273
  index += 1;
@@ -499,15 +1284,15 @@ export class ShellParser {
499
1284
  // A redirect and its target are not words of the command.
500
1285
  let cursor = index + 1;
501
1286
 
502
- while (prefix[cursor] === '>' || prefix[cursor] === '&' || prefix[cursor] === ' ') {
1287
+ while (text[cursor] === '>' || text[cursor] === '&' || text[cursor] === ' ') {
503
1288
  cursor += 1;
504
1289
  }
505
1290
 
506
- index = Math.max(readWord({ text: prefix, from: cursor }).next, index + 1);
1291
+ index = Math.max(readWord({ text, from: cursor, layout }).next, index + 1);
507
1292
  continue;
508
1293
  }
509
1294
 
510
- const word = readWord({ text: prefix, from: index });
1295
+ const word = readWord({ text, from: index, layout });
511
1296
 
512
1297
  words.push(word.value);
513
1298
  index = Math.max(word.next, index + 1);
@@ -536,13 +1321,14 @@ export class ShellParser {
536
1321
  const scripts: string[] = [];
537
1322
 
538
1323
  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];
1324
+ const call = ShellParser.shellCallOf({ args: program.args });
543
1325
 
544
- if (script !== undefined) {
545
- scripts.push(script);
1326
+ if (call.mode === ShellModes.COMMAND && call.word !== undefined) {
1327
+ scripts.push(call.word);
1328
+ }
1329
+
1330
+ if (call.mode === ShellModes.STDIN) {
1331
+ scripts.push(...ShellParser.stdinScriptsOf({ command }));
546
1332
  }
547
1333
  }
548
1334
 
@@ -550,6 +1336,12 @@ export class ShellParser {
550
1336
  scripts.push(program.args.join(' '));
551
1337
  }
552
1338
 
1339
+ const trapCode = ShellParser.trapCodeOf({ args: program.args });
1340
+
1341
+ if (name === 'trap' && trapCode !== undefined) {
1342
+ scripts.push(trapCode);
1343
+ }
1344
+
553
1345
  if (
554
1346
  /\s/.test(program.name) &&
555
1347
  command.words
@@ -562,6 +1354,111 @@ export class ShellParser {
562
1354
  return scripts;
563
1355
  }
564
1356
 
1357
+ /**
1358
+ * The text a shell reads from its standard input, when the line shows it: a here-string, what `echo` or
1359
+ * `printf` prints into it, or the body of the heredoc of a `cat` that feeds it.
1360
+ */
1361
+ private static stdinScriptsOf(opts: { command: ISimpleCommand }): string[] {
1362
+ const { input } = opts.command;
1363
+
1364
+ if (input === undefined) {
1365
+ return [];
1366
+ }
1367
+
1368
+ const scripts = [...input.texts];
1369
+ const source = input.pipedFrom;
1370
+
1371
+ if (source !== undefined) {
1372
+ const { name, args } = ShellParser.programOf({ command: source });
1373
+ const program = ShellParser.basenameOf({ word: name });
1374
+
1375
+ if (program === 'echo' || program === 'printf') {
1376
+ scripts.push(ShellParser.printedBy({ program, args }).replaceAll('\\n', '\n'));
1377
+ }
1378
+
1379
+ if (program === 'cat' && source.heredoc !== undefined) {
1380
+ scripts.push(source.heredoc);
1381
+ }
1382
+ }
1383
+
1384
+ return scripts;
1385
+ }
1386
+
1387
+ /**
1388
+ * What `echo` or `printf` prints: `echo` its words, joined by spaces (an option is a word the parser skips); `printf` its format
1389
+ * with each conversion (`%s`, `%b`...) filled from the words that follow, the format again while words are
1390
+ * left. A guess toward a hit: a conversion is never read as a width or an escape, only as a place for a word.
1391
+ */
1392
+ private static printedBy(opts: { program: string; args: string[] }): string {
1393
+ if (opts.program === 'echo') {
1394
+ return opts.args.join(' ');
1395
+ }
1396
+
1397
+ const words = opts.args[0] === '--' ? opts.args.slice(1) : opts.args;
1398
+ const [format = '', ...rest] = words;
1399
+ const conversion = /%%|%[-+ #0-9.*]*[a-zA-Z]/g;
1400
+
1401
+ if (![...format.matchAll(conversion)].some((match) => match[0] !== '%%')) {
1402
+ return format;
1403
+ }
1404
+
1405
+ let next = 0;
1406
+ let printed = '';
1407
+
1408
+ do {
1409
+ printed += format.replace(conversion, (found) =>
1410
+ found === '%%' ? '%' : (rest[next++] ?? ''),
1411
+ );
1412
+ } while (next < rest.length);
1413
+
1414
+ return printed;
1415
+ }
1416
+
1417
+ /**
1418
+ * The code `trap` sets: its first operand, when signals follow it. `-p` and `-l` print, `-` resets, and a
1419
+ * lone operand names a signal: none of them is code.
1420
+ */
1421
+ private static trapCodeOf(opts: { args: string[] }): string | undefined {
1422
+ if (/^-[pl]+$/.test(opts.args[0] ?? '')) {
1423
+ return undefined;
1424
+ }
1425
+
1426
+ const at = opts.args[0] === '--' ? 1 : 0;
1427
+
1428
+ const code = opts.args[at];
1429
+
1430
+ return code === undefined || code === '-' || opts.args.length <= at + 1 ? undefined : code;
1431
+ }
1432
+
1433
+ /**
1434
+ * Whether a word of the command is `${x@P}`, which runs the commands in the value of `x` wherever it stands, an
1435
+ * `echo` argument included.
1436
+ */
1437
+ static hasPromptExpansion(opts: { command: ISimpleCommand }): boolean {
1438
+ return [
1439
+ ...opts.command.words,
1440
+ ...opts.command.assignments,
1441
+ ...(opts.command.expandedBodies ?? []),
1442
+ ].some((text) => /\$\{[^}]*@P\}/.test(text));
1443
+ }
1444
+
1445
+ /**
1446
+ * Whether a command's program is a variable, a substitution, a glob or a brace pattern, which the line does not show. An expansion
1447
+ * anywhere in the word counts, not only in its last part: an unquoted `$k/deploy.yaml` is split at the blanks
1448
+ * of `k`, so its first word is the program. No variable is exempt, `HOME` included: the same line can set it.
1449
+ */
1450
+ static isUnknownProgram(opts: { command: ISimpleCommand }): boolean {
1451
+ const { name } = ShellParser.programOf({ command: opts.command });
1452
+
1453
+ return (
1454
+ /[$`*?]/.test(name) ||
1455
+ /\[[^\]]+\]/.test(name) ||
1456
+ /\{[^{}]*(?:,|\.\.)[^{}]*\}/.test(name) ||
1457
+ name.startsWith('<(') ||
1458
+ name.startsWith('>(') ||
1459
+ ShellParser.hasPromptExpansion({ command: opts.command })
1460
+ );
1461
+ }
565
1462
  /** Whether the command carries another command line to read: a script, an eval, a `watch` string, or an `env -S`. */
566
1463
  private static nests(opts: { command: ISimpleCommand }): boolean {
567
1464
  const program = ShellParser.programOf({ command: opts.command });
@@ -581,8 +1478,11 @@ export class ShellParser {
581
1478
  command: string;
582
1479
  depth: number;
583
1480
  budget: IBudget;
1481
+ scope?: string;
1482
+ carrier?: ISimpleCommand;
584
1483
  }): ISimpleCommand[] {
585
1484
  const { depth, budget } = opts;
1485
+ const base = opts.scope ?? '';
586
1486
 
587
1487
  // The characters of every text read count together, nested texts too: a line over the cap is not read.
588
1488
  budget.chars += opts.command.length;
@@ -593,24 +1493,56 @@ export class ShellParser {
593
1493
  return [];
594
1494
  }
595
1495
 
596
- const heredocSplit = ShellParser.splitHeredocs({ command: opts.command });
597
- const { text } = heredocSplit;
598
- let heredocIndex = 0;
1496
+ const layout = ShellParser.layoutOf({ command: opts.command });
1497
+ const { text } = layout;
1498
+
1499
+ budget.isUncertain ||= layout.isUncertain;
1500
+
599
1501
  const commands: ISimpleCommand[] = [];
600
- const nestedTexts: string[] = [];
1502
+ const nestedTexts: { text: string; scope: string; carrier: ISimpleCommand }[] = [];
601
1503
  let current: ISimpleCommand = { words: [], redirects: [], assignments: [] };
602
1504
  let index = 0;
1505
+ // The command before a `|`: it feeds the next one.
1506
+ let pipeSource: ISimpleCommand | undefined;
1507
+ // The open subshells, and a `case` marker while its `)` patterns are read.
1508
+ const groups: string[] = [];
1509
+ const scopeOf = (): string =>
1510
+ `${base}${groups.filter((group) => group !== CASE_GROUP).join('')}`;
1511
+ const nest = (nested: { texts: string[] }): void => {
1512
+ for (const nestedText of nested.texts) {
1513
+ nestedTexts.push({ text: nestedText, scope: scopeOf(), carrier: current });
1514
+ }
1515
+ };
1516
+
1517
+ const finish = (): ISimpleCommand | undefined => {
1518
+ const finished = current;
1519
+ const isEmpty =
1520
+ finished.words.length === 0 &&
1521
+ finished.redirects.length === 0 &&
1522
+ finished.assignments.length === 0;
1523
+
1524
+ if (!isEmpty) {
1525
+ if (pipeSource !== undefined) {
1526
+ inputOf({ command: finished }).pipedFrom = pipeSource;
1527
+ }
1528
+
1529
+ const scope = scopeOf();
1530
+
1531
+ if (scope !== '') {
1532
+ finished.scope = scope;
1533
+ }
1534
+
1535
+ if (opts.carrier !== undefined) {
1536
+ finished.carrier = opts.carrier;
1537
+ }
603
1538
 
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);
1539
+ commands.push(finished);
611
1540
  }
612
1541
 
1542
+ pipeSource = undefined;
613
1543
  current = { words: [], redirects: [], assignments: [] };
1544
+
1545
+ return isEmpty ? undefined : finished;
614
1546
  };
615
1547
 
616
1548
  while (index < text.length) {
@@ -627,8 +1559,48 @@ export class ShellParser {
627
1559
  continue;
628
1560
  }
629
1561
 
630
- if (char === ';' || char === '\n' || char === '|' || char === '(' || char === ')') {
1562
+ // `||` runs the next command after this one; `|` and `|&` feed this one's output into it.
1563
+ if (char === '|') {
1564
+ if (text[index + 1] === '|') {
1565
+ finish();
1566
+ index += 2;
1567
+ continue;
1568
+ }
1569
+
1570
+ const source = finish();
1571
+
1572
+ pipeSource = source;
1573
+ index += text[index + 1] === '&' ? 2 : 1;
1574
+ continue;
1575
+ }
1576
+
1577
+ // `(( ... ))` is arithmetic: only the substitutions inside it are commands.
1578
+ const arithmeticEnd = char === '(' ? layout.ariths.get(index) : undefined;
1579
+
1580
+ if (arithmeticEnd !== undefined) {
1581
+ finish();
1582
+ nest({ texts: substitutionsIn({ text, from: index, to: arithmeticEnd, layout }) });
1583
+ index = arithmeticEnd + 1;
1584
+ continue;
1585
+ }
1586
+
1587
+ if (char === ';' || char === '\n') {
1588
+ finish();
1589
+ index += 1;
1590
+ continue;
1591
+ }
1592
+
1593
+ // A `(` opens a subshell; a `)` closes it, unless it ends a pattern of an open `case`.
1594
+ if (char === '(' || char === ')') {
631
1595
  finish();
1596
+
1597
+ if (char === '(') {
1598
+ budget.scopes += 1;
1599
+ groups.push(`/${budget.scopes}`);
1600
+ } else if (groups.length > 0 && groups.at(-1) !== CASE_GROUP) {
1601
+ groups.pop();
1602
+ }
1603
+
632
1604
  index += 1;
633
1605
  continue;
634
1606
  }
@@ -639,6 +1611,40 @@ export class ShellParser {
639
1611
  continue;
640
1612
  }
641
1613
 
1614
+ // `<(...)` and `>(...)`: a process substitution is a word (a path the command reads or writes), its text
1615
+ // commands of their own.
1616
+ const substitutionEnd =
1617
+ (char === '<' || char === '>') && text[index + 1] === '('
1618
+ ? layout.closes.get(index)
1619
+ : undefined;
1620
+
1621
+ if (substitutionEnd !== undefined) {
1622
+ nest({ texts: [text.slice(index + 2, substitutionEnd)] });
1623
+ current.words.push(text.slice(index, substitutionEnd + 1));
1624
+ index = substitutionEnd + 1;
1625
+ continue;
1626
+ }
1627
+
1628
+ // A heredoc, read by the scanner: the delimiter is part of the operator, not a word, and the body goes to
1629
+ // the command that reads it.
1630
+ const heredoc = char === '<' ? layout.heredocAt.get(index) : undefined;
1631
+
1632
+ if (heredoc !== undefined) {
1633
+ inputOf({ command: current }).hasHeredoc = true;
1634
+
1635
+ if (!heredoc.heredoc.isInline) {
1636
+ current.heredoc = heredoc.heredoc.body;
1637
+ }
1638
+
1639
+ if (!heredoc.isQuoted) {
1640
+ (current.expandedBodies ??= []).push(heredoc.heredoc.body);
1641
+ }
1642
+
1643
+ nest({ texts: heredoc.substitutions });
1644
+ index = heredoc.end;
1645
+ continue;
1646
+ }
1647
+
642
1648
  if (char === '>' || char === '&') {
643
1649
  // `>`, `>>`, `>|`, `&>`, `&>>`; `>&2` duplicates a descriptor and names no file.
644
1650
  let cursor = index + (char === '&' ? 1 : 0);
@@ -647,59 +1653,127 @@ export class ShellParser {
647
1653
  cursor += 1;
648
1654
  }
649
1655
 
650
- if (text[cursor] === '&' && /[\d-]/.test(text[cursor + 1] ?? '')) {
651
- index = cursor + 2;
652
- continue;
1656
+ // `>&2` and `>&-` duplicate or close a descriptor; `>&file` writes the file, as `&>file` does.
1657
+ const isAmpersand = char === '>' && text[cursor] === '&';
1658
+
1659
+ if (isAmpersand) {
1660
+ cursor += 1;
653
1661
  }
654
1662
 
655
1663
  while (text[cursor] === ' ' || text[cursor] === '\t') {
656
1664
  cursor += 1;
657
1665
  }
658
1666
 
659
- const target = readWord({ text, from: cursor });
1667
+ const target = readWord({ text, from: cursor, layout });
1668
+
1669
+ if (isAmpersand && /^(?:\d+-?|-)$/.test(target.value)) {
1670
+ nest({ texts: target.nested });
1671
+ index = Math.max(target.next, cursor + 1);
1672
+ continue;
1673
+ }
660
1674
 
661
1675
  if (target.value !== '') {
662
1676
  current.redirects.push(target.value);
1677
+ markLiteralDollar({ command: current, value: target.value, read: target });
1678
+
1679
+ if (isAmpersand && /[$`]/.test(target.value)) {
1680
+ (current.copies ??= []).push(target.value);
1681
+ }
663
1682
  }
664
1683
 
665
- pushAll({ target: nestedTexts, items: target.nested });
1684
+ nest({ texts: target.nested });
666
1685
  index = Math.max(target.next, cursor + 1);
667
1686
  continue;
668
1687
  }
669
1688
 
670
1689
  if (char === '<') {
671
- const operator =
672
- text[index + 2] === '<' ? null : /^<<-?\s*["']?[A-Za-z_]\w*["']?/.exec(text.slice(index));
1690
+ // `<<< text`: a here-string, its text fed to the command.
1691
+ if (text[index + 1] === '<' && text[index + 2] === '<') {
1692
+ let cursor = index + 3;
673
1693
 
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];
1694
+ while (text[cursor] === ' ' || text[cursor] === '\t') {
1695
+ cursor += 1;
1696
+ }
677
1697
 
678
- heredocIndex += 1;
1698
+ const value = readWord({ text, from: cursor, layout });
679
1699
 
680
- if (heredoc !== undefined && !heredoc.isInline) {
681
- current.heredoc = heredoc.body;
682
- }
1700
+ inputOf({ command: current }).texts.push(value.value);
1701
+ nest({ texts: value.nested });
1702
+ index = Math.max(value.next, cursor);
1703
+ continue;
1704
+ }
683
1705
 
684
- index += operator[0].length;
1706
+ // A `<<` the scanner did not read as a heredoc (it has no delimiter) names no file.
1707
+ if (text[index + 1] === '<') {
1708
+ index += 2;
685
1709
  continue;
686
1710
  }
687
1711
 
688
- index += 1;
1712
+ let cursor = index + 1;
1713
+
1714
+ // `<&3` and `<&-` duplicate or close a descriptor and name no file.
1715
+ if (text[cursor] === '&') {
1716
+ index = cursor + 2;
1717
+ continue;
1718
+ }
1719
+
1720
+ // `<>` opens the file for reading and writing: it is a write target too.
1721
+ const isReadWrite = text[cursor] === '>';
1722
+
1723
+ if (isReadWrite) {
1724
+ cursor += 1;
1725
+ }
1726
+
1727
+ while (text[cursor] === ' ' || text[cursor] === '\t') {
1728
+ cursor += 1;
1729
+ }
1730
+
1731
+ // The file stays a word of the command too, where the guards that read words have always found it.
1732
+ const source = readWord({ text, from: cursor, layout });
1733
+
1734
+ if (source.value !== '') {
1735
+ inputOf({ command: current }).files.push(source.value);
1736
+ markLiteralDollar({ command: current, value: source.value, read: source });
1737
+
1738
+ if (isReadWrite) {
1739
+ current.redirects.push(source.value);
1740
+ }
1741
+
1742
+ const isClosing =
1743
+ current.words.length === 1 && CLOSING_KEYWORDS.has(current.words[0] ?? '');
1744
+
1745
+ if (current.words.length > 0 && !isClosing) {
1746
+ current.words.push(source.value);
1747
+ }
1748
+ }
1749
+
1750
+ nest({ texts: source.nested });
1751
+ index = Math.max(source.next, index + 1);
689
1752
  continue;
690
1753
  }
691
1754
 
692
- const word = readWord({ text, from: index });
1755
+ const word = readWord({ text, from: index, layout });
693
1756
 
694
1757
  // A digit just before `>` is a descriptor (`2>file`), not a word.
695
- if (/^\d$/.test(word.value) && text[word.next] === '>') {
1758
+ if (/^\d+$/.test(word.value) && (text[word.next] === '>' || text[word.next] === '<')) {
696
1759
  index = word.next;
697
1760
  continue;
698
1761
  }
699
1762
 
700
- pushAll({ target: nestedTexts, items: word.nested });
1763
+ nest({ texts: word.nested });
1764
+
1765
+ const isFirst = current.words.length === 0;
1766
+
1767
+ // In `case x in a) ...;; esac` each `)` ends a pattern, not a subshell.
1768
+ if (isFirst && word.value === 'case') {
1769
+ groups.push(CASE_GROUP);
1770
+ } else if (isFirst && word.value === 'esac' && groups.includes(CASE_GROUP)) {
1771
+ groups.splice(groups.lastIndexOf(CASE_GROUP));
1772
+ }
1773
+
1774
+ markLiteralDollar({ command: current, value: word.value, read: word });
701
1775
 
702
- if (current.words.length === 0 && isAssignment({ word: word.value })) {
1776
+ if (isFirst && isAssignment({ word: word.value })) {
703
1777
  current.assignments.push(word.value);
704
1778
  } else {
705
1779
  current.words.push(word.value);
@@ -710,6 +1784,23 @@ export class ShellParser {
710
1784
 
711
1785
  finish();
712
1786
 
1787
+ budget.hasUnknownProgram ||= commands.some((command) =>
1788
+ ShellParser.isUnknownProgram({ command }),
1789
+ );
1790
+
1791
+ // A body whose delimiter never came is data, as bash reads it; its lines are also read as commands, on the side. The
1792
+ // guards ask: a start the scanner got wrong would otherwise hide what follows it.
1793
+ if (layout.unterminated.length > 0) {
1794
+ budget.isUncertain = true;
1795
+ }
1796
+
1797
+ for (const body of layout.unterminated) {
1798
+ pushAll({
1799
+ target: budget.unterminated,
1800
+ items: ShellParser.parseWithBudget({ command: body, depth: depth + 1, budget }),
1801
+ });
1802
+ }
1803
+
713
1804
  budget.commands += commands.length;
714
1805
  budget.words += commands.reduce((sum, command) => sum + command.words.length, 0);
715
1806
 
@@ -739,6 +1830,10 @@ export class ShellParser {
739
1830
  for (const words of program.splitCommands) {
740
1831
  const split: ISimpleCommand = { words, redirects: [], assignments: [] };
741
1832
 
1833
+ if (command.scope !== undefined) {
1834
+ split.scope = command.scope;
1835
+ }
1836
+
742
1837
  budget.commands += 1;
743
1838
  budget.words += words.length;
744
1839
 
@@ -748,6 +1843,7 @@ export class ShellParser {
748
1843
  return [...commands, ...synthesized];
749
1844
  }
750
1845
 
1846
+ budget.hasUnknownProgram ||= ShellParser.isUnknownProgram({ command: split });
751
1847
  synthesized.push(split);
752
1848
  queue.push({ command: split, level: level + 1 });
753
1849
  }
@@ -755,22 +1851,28 @@ export class ShellParser {
755
1851
  budget.isOver = true;
756
1852
  }
757
1853
 
758
- pushAll({ target: nestedTexts, items: ShellParser.nestedScripts({ command, program }) });
1854
+ for (const script of ShellParser.nestedScripts({ command, program })) {
1855
+ nestedTexts.push({ text: script, scope: command.scope ?? base, carrier: command });
1856
+ }
759
1857
  }
760
1858
 
761
1859
  return [
762
1860
  ...commands,
763
1861
  ...synthesized,
764
- ...nestedTexts.flatMap((nested) =>
765
- ShellParser.parseWithBudget({ command: nested, depth: depth + 1, budget }),
766
- ),
1862
+ ...nestedTexts.flatMap((nested) => {
1863
+ budget.scopes += 1;
1864
+
1865
+ return ShellParser.parseWithBudget({
1866
+ command: nested.text,
1867
+ depth: depth + 1,
1868
+ budget,
1869
+ scope: `${nested.scope}>${budget.scopes}`,
1870
+ carrier: nested.carrier,
1871
+ });
1872
+ }),
767
1873
  ];
768
1874
  }
769
1875
 
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
1876
  /** A parse that throws (a stack or memory limit) reads nothing and says so: the line is not allowed by silence. */
775
1877
  private static parseGuarded(opts: {
776
1878
  command: string;
@@ -816,6 +1918,64 @@ export class ShellParser {
816
1918
  return false;
817
1919
  }
818
1920
 
1921
+ /**
1922
+ * How a shell (`bash`, `sh`, `zsh`, `dash`, `ksh`) runs, from the words after its name. Only `-o`, `-O` (in a
1923
+ * cluster too, `-euo pipefail`), `--rcfile` and `--init-file` take the next word; every other option is a
1924
+ * switch. `-` and `--` end the options. `-c` runs its first word as text, `-n` runs nothing, and `-s`, or no
1925
+ * word at all, reads the commands from standard input.
1926
+ */
1927
+ static shellCallOf(opts: { args: string[] }): IShellCall {
1928
+ let isCommand = false;
1929
+ let isCheck = false;
1930
+ let isStdin = false;
1931
+ let word: string | undefined;
1932
+
1933
+ for (let index = 0; index < opts.args.length; index += 1) {
1934
+ const arg = opts.args[index] ?? '';
1935
+
1936
+ if (arg === '-' || arg === '--') {
1937
+ word = opts.args[index + 1];
1938
+ break;
1939
+ }
1940
+
1941
+ if (arg.startsWith('--')) {
1942
+ index += SHELL_LONG_VALUES.has(arg) ? 1 : 0;
1943
+ continue;
1944
+ }
1945
+
1946
+ if (/^[-+][A-Za-z]+$/.test(arg)) {
1947
+ const letters = arg.slice(1);
1948
+
1949
+ // `+c`, `+s` and `+n` turn an option off; they do not set the mode.
1950
+ if (arg.startsWith('-')) {
1951
+ isCommand ||= letters.includes('c');
1952
+ isStdin ||= letters.includes('s');
1953
+ isCheck ||= letters.includes('n');
1954
+ }
1955
+
1956
+ index += [...letters].filter((letter) => letter === 'o' || letter === 'O').length;
1957
+ continue;
1958
+ }
1959
+
1960
+ word = arg;
1961
+ break;
1962
+ }
1963
+
1964
+ if (isCommand) {
1965
+ return { mode: ShellModes.COMMAND, word };
1966
+ }
1967
+
1968
+ if (isCheck) {
1969
+ return { mode: ShellModes.CHECK, word };
1970
+ }
1971
+
1972
+ if (isStdin || word === undefined) {
1973
+ return { mode: ShellModes.STDIN, word };
1974
+ }
1975
+
1976
+ return { mode: ShellModes.FILE, word };
1977
+ }
1978
+
819
1979
  static basenameOf(opts: { word: string }): string {
820
1980
  return opts.word.split('/').pop() ?? opts.word;
821
1981
  }
@@ -950,6 +2110,22 @@ export class ShellParser {
950
2110
  continue;
951
2111
  }
952
2112
 
2113
+ // `coproc [NAME] command`: a NAME is there only before a compound command (`{ ...; }`).
2114
+ if (word === 'coproc') {
2115
+ const name = opts.command.words[index + 1];
2116
+ const isNamed =
2117
+ name !== undefined && !KEYWORDS.has(name) && opts.command.words[index + 2] === '{';
2118
+
2119
+ index += isNamed ? 2 : 1;
2120
+ continue;
2121
+ }
2122
+
2123
+ // `function NAME { ...; }`: the name is not a program; the body is read as the commands it holds.
2124
+ if (word === 'function') {
2125
+ index += 2;
2126
+ continue;
2127
+ }
2128
+
953
2129
  if (word === '--') {
954
2130
  optionsEnded = true;
955
2131
  index += 1;
@@ -982,85 +2158,130 @@ export class ShellParser {
982
2158
  continue;
983
2159
  }
984
2160
 
985
- return { name: word, index, args: opts.command.words.slice(index + 1), splitCommands };
2161
+ const args = opts.command.words.slice(index + 1);
2162
+
2163
+ if (ShellParser.basenameOf({ word }) === 'find') {
2164
+ splitCommands.push(...ShellParser.findRunsOf({ args }));
2165
+ }
2166
+
2167
+ return { name: word, index, args, splitCommands };
986
2168
  }
987
2169
 
988
2170
  return { name: '', index: -1, args: [], splitCommands };
989
2171
  }
990
2172
 
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
- }
2173
+ /** The commands `find` runs: the words after each `-exec`, `-execdir`, `-ok` or `-okdir`, up to its `;` or `+`. */
2174
+ private static findRunsOf(opts: { args: string[] }): string[][] {
2175
+ const runs: string[][] = [];
1013
2176
 
1014
- body.push(line);
2177
+ for (let index = 0; index < opts.args.length; index += 1) {
2178
+ if (!FIND_RUN_OPTIONS.has(opts.args[index] ?? '')) {
2179
+ continue;
2180
+ }
1015
2181
 
1016
- if (isInline) {
1017
- kept.push(line);
1018
- }
2182
+ let end = index + 1;
1019
2183
 
1020
- continue;
2184
+ while (end < opts.args.length && opts.args[end] !== ';' && opts.args[end] !== '+') {
2185
+ end += 1;
1021
2186
  }
1022
2187
 
1023
- kept.push(line);
2188
+ if (end === opts.args.length) {
2189
+ end = -1;
2190
+ }
1024
2191
 
1025
- const heredoc = heredocOf({ line });
2192
+ const words = opts.args.slice(index + 1, end === -1 ? undefined : end);
1026
2193
 
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) }));
2194
+ if (words.length > 0) {
2195
+ runs.push(words);
1032
2196
  }
1033
- }
1034
2197
 
1035
- if (terminator !== undefined) {
1036
- heredocs.push({ body: body.join('\n'), isInline });
2198
+ index = end === -1 ? opts.args.length : end;
1037
2199
  }
1038
2200
 
1039
- return { text: kept.join('\n'), heredocs };
2201
+ return runs;
1040
2202
  }
1041
2203
 
2204
+ /**
2205
+ * A heredoc's body is data for the command that reads it (a commit message, a file), not commands: the
2206
+ * body is taken out of the text and kept in `heredocs`, in order, for the command to carry. A body fed to a
2207
+ * shell (`bash <<EOF`) is a script: it stays in the text and is read as commands. The text is read left to
2208
+ * right as bash reads it, so a `<<` in a comment, in arithmetic or in a quote that spans lines starts no
2209
+ * heredoc, and a comment is dropped from the text. `isUncertain` says part of it could not be followed to
2210
+ * its end (a quote or a substitution that never closes, a `<<` with no delimiter).
2211
+ */
2212
+ static splitHeredocs(opts: { command: string }): {
2213
+ text: string;
2214
+ heredocs: IHeredoc[];
2215
+ isUncertain: boolean;
2216
+ } {
2217
+ const layout = ShellParser.layoutOf(opts);
2218
+
2219
+ return { text: layout.view, heredocs: layout.heredocs, isUncertain: layout.isUncertain };
2220
+ }
2221
+
2222
+ /** What the scanner finds in a line, every position an index of its kept text. */
2223
+ private static layoutOf(opts: { command: string }): IShellLayout {
2224
+ return ShellScanner.scan({
2225
+ text: opts.command,
2226
+ depth: 0,
2227
+ isBody: false,
2228
+ programBefore: (scanned) => ShellParser.programBefore(scanned),
2229
+ });
2230
+ }
2231
+
2232
+ /**
2233
+ * The commands of a line and whether all of it was read. A guard that can refuse treats `isOverBudget`
2234
+ * and `isUncertain` as "ask" (`ShellUnread.reasonOf`): an unread part is never an "allow".
2235
+ */
1042
2236
  static parseChecked(opts: { command: string }): IParsedShell {
1043
- const budget: IBudget = { commands: 0, words: 0, chars: 0, isOver: false };
2237
+ const budget = ShellParser.budgetOf();
1044
2238
  const commands = ShellParser.parseGuarded({ command: opts.command, depth: 0, budget });
1045
2239
 
1046
- return { commands, isOverBudget: budget.isOver };
2240
+ return {
2241
+ commands,
2242
+ isOverBudget: budget.isOver,
2243
+ isUncertain: budget.isUncertain,
2244
+ hasUnknownProgram: budget.hasUnknownProgram,
2245
+ unterminatedHeredocCommands: budget.unterminated,
2246
+ };
1047
2247
  }
1048
2248
 
1049
2249
  static parse(opts: { command: string; depth?: number }): ISimpleCommand[] {
1050
2250
  return ShellParser.parseGuarded({
1051
2251
  command: opts.command,
1052
2252
  depth: opts.depth ?? 0,
1053
- budget: { commands: 0, words: 0, chars: 0, isOver: false },
2253
+ budget: ShellParser.budgetOf(),
1054
2254
  });
1055
2255
  }
2256
+
2257
+ private static budgetOf(): IBudget {
2258
+ return {
2259
+ commands: 0,
2260
+ words: 0,
2261
+ chars: 0,
2262
+ scopes: 0,
2263
+ isOver: false,
2264
+ isUncertain: false,
2265
+ hasUnknownProgram: false,
2266
+ unterminated: [],
2267
+ };
2268
+ }
1056
2269
  }
1057
2270
 
1058
2271
  interface IBudget {
1059
2272
  commands: number;
1060
2273
  words: number;
1061
2274
  chars: number;
2275
+ /** The subshells and nested command lines numbered so far, so each scope is unique in the line. */
2276
+ scopes: number;
1062
2277
  /** Something was not read: the budget ran out, or a command nests deeper than the depth limit. */
1063
2278
  isOver: boolean;
2279
+ /** Something could not be followed to its end. */
2280
+ isUncertain: boolean;
2281
+ /** A command's program is a variable or a substitution. */
2282
+ hasUnknownProgram: boolean;
2283
+ /** The commands of heredoc bodies whose delimiter never came. */
2284
+ unterminated: ISimpleCommand[];
1064
2285
  }
1065
2286
 
1066
2287
  interface IHeredoc {
@@ -1073,4 +2294,10 @@ interface IParsedShell {
1073
2294
  commands: ISimpleCommand[];
1074
2295
  /** Part of the line was not read: it is larger, or nests deeper, than the parser's budget. */
1075
2296
  isOverBudget: boolean;
2297
+ /** Part of the line could not be followed to its end: a quote, a substitution or a heredoc operator. */
2298
+ isUncertain: boolean;
2299
+ /** A command runs a program the line does not show (`$cmd`, `"$@"`, `$(tool)`): a guard cannot tell what it is. */
2300
+ hasUnknownProgram: boolean;
2301
+ /** The lines of a heredoc body whose delimiter never came, read as commands: data to bash, a second view to a guard. */
2302
+ unterminatedHeredocCommands: ISimpleCommand[];
1076
2303
  }