@kaynooo/cli-env 0.8.0 → 0.9.0

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.
package/src/fix.ts ADDED
@@ -0,0 +1,294 @@
1
+ import { chmod, chown, lstat, rm, stat } from 'node:fs/promises'
2
+ import { dirname, join } from 'node:path'
3
+ import { compose } from '@kaynooo/cli-kit'
4
+ import { isInlineSecret } from './audit'
5
+ import { entries, escapeDouble, LINE_BREAK, parseDotenv, serializeDotenv, setLine } from './dotenv'
6
+ import { writeAtomic } from './files'
7
+
8
+ export interface Left {
9
+ key: string
10
+ why: string
11
+ }
12
+
13
+ export interface ComposeFix {
14
+ path: string
15
+ env: string
16
+ moved: string[]
17
+ left: Left[]
18
+ // The compose file or .env another account owns, so its mode could not be changed.
19
+ open: string[]
20
+ // How `docker compose config` compared before and after: undefined when nothing moved.
21
+ check?: 'same' | 'rolled back' | 'no docker' | 'fails before'
22
+ }
23
+
24
+ // One environment entry of a compose line: its value as compose reads it, and the line with the value swapped for a reference, or why it cannot be swapped.
25
+ type Entry = { key: string, value: string } & ({ swap: (ref: string) => string } | { unmovable: string })
26
+
27
+ const MAP_ENTRY = /^(\s*)(["']?)([A-Z0-9_]+)\2(\s*:)(.*)$/
28
+ const LIST_ENTRY = /^(\s*-[ \t]*)(["']?)([A-Z0-9_]+)=(.*)$/
29
+ const TRAILING = /^\s*(?:#.*)?$/
30
+ const PLAIN_COMMENT = /\s+#.*$/
31
+ const NOT_PLAIN = /^[|>&*![{]/
32
+ const ENV_PLAIN = /^[^\s#"'\\$`]*$/
33
+
34
+ // The inside of a YAML quoted scalar starting after its opening quote: double quotes take only \\ and \" escapes here.
35
+ function quoted(text: string, quote: string): { value: string, after: string } | undefined {
36
+ let value = ''
37
+
38
+ for (let index = 0; index < text.length; index++) {
39
+ const char = text[index] ?? ''
40
+ const next = text[index + 1]
41
+
42
+ if (quote === '\'' && char === '\'' && next === '\'') {
43
+ value += '\''
44
+ index++
45
+ }
46
+ else if (quote === '"' && char === '\\') {
47
+ if (next !== '\\' && next !== '"')
48
+ return undefined
49
+
50
+ value += next
51
+ index++
52
+ }
53
+ else if (char === quote) {
54
+ return { value, after: text.slice(index + 1) }
55
+ }
56
+ else {
57
+ value += char
58
+ }
59
+ }
60
+
61
+ return undefined
62
+ }
63
+
64
+ function plain(text: string): { value: string, after: string } {
65
+ const value = text.replace(PLAIN_COMMENT, '').trimEnd()
66
+
67
+ return { value, after: text.slice(value.length) }
68
+ }
69
+
70
+ export function composeEntry(line: string): Entry | undefined {
71
+ const map = MAP_ENTRY.exec(line)
72
+
73
+ if (map !== null) {
74
+ const [, indent = '', keyQuote = '', key = '', colon = '', spaced = ''] = map
75
+ const rest = spaced.trimStart()
76
+ const separator = colon + spaced.slice(0, spaced.length - rest.length)
77
+ const quote = rest[0] === '"' || rest[0] === '\'' ? rest[0] : ''
78
+ const scalar = quote === '' ? plain(rest) : quoted(rest.slice(1), quote)
79
+
80
+ if (scalar === undefined || !TRAILING.test(scalar.after))
81
+ return { key, value: rest, unmovable: 'its value is written in a form ev does not rewrite' }
82
+
83
+ if (quote === '' && NOT_PLAIN.test(scalar.value))
84
+ return { key, value: scalar.value, unmovable: 'its value is a block, anchor, alias, tag or collection' }
85
+
86
+ return { key, value: scalar.value, swap: ref => `${indent}${keyQuote}${key}${keyQuote}${separator}${quote}${ref}${quote}${scalar.after}` }
87
+ }
88
+
89
+ const list = LIST_ENTRY.exec(line)
90
+
91
+ if (list === null)
92
+ return undefined
93
+
94
+ const [, dash = '', quote = '', key = '', rest = ''] = list
95
+ const scalar = quote === '' ? plain(rest) : quoted(rest, quote)
96
+
97
+ if (scalar === undefined || !TRAILING.test(scalar.after))
98
+ return { key, value: rest, unmovable: 'its value is written in a form ev does not rewrite' }
99
+
100
+ return { key, value: scalar.value, swap: ref => `${dash}${quote}${key}=${ref}${quote}${scalar.after}` }
101
+ }
102
+
103
+ // The .env line holding a value compose and Bun both read literally: plain when nothing needs quoting, single-quoted otherwise, double-quoted with each `$` escaped when it holds one since Bun expands it even in single quotes.
104
+ export function envLine(key: string, value: string): string | undefined {
105
+ if (ENV_PLAIN.test(value))
106
+ return `${key}=${value}`
107
+
108
+ if (LINE_BREAK.test(value))
109
+ return undefined
110
+
111
+ if (value.includes('$'))
112
+ return `${key}="${escapeDouble(value)}"`
113
+
114
+ return value.includes('\'') ? undefined : `${key}='${value}'`
115
+ }
116
+
117
+ // A link, dangling or not: writing through it would change a file elsewhere.
118
+ async function isLink(path: string): Promise<boolean> {
119
+ try {
120
+ return (await lstat(path)).isSymbolicLink()
121
+ }
122
+ catch (error) {
123
+ if ((error as NodeJS.ErrnoException).code === 'ENOENT')
124
+ return false
125
+
126
+ throw error
127
+ }
128
+ }
129
+
130
+ // What `docker compose config` resolves the file to, never printed; undefined when it fails.
131
+ async function resolved(path: string): Promise<string | undefined> {
132
+ const { code, stdout } = await compose(['config', '--format', 'json'], { flags: ['-f', path], cwd: dirname(path) })
133
+
134
+ return code === 0 ? stdout : undefined
135
+ }
136
+
137
+ interface Resolved {
138
+ services?: Record<string, { environment?: Record<string, unknown> }>
139
+ }
140
+
141
+ // The services a key reached only once moved: they load the .env through env_file.
142
+ function gainedBy(before: string, after: string, key: string): string[] {
143
+ const services = (config: string) => Object.entries((JSON.parse(config) as Resolved).services ?? {})
144
+ const had = new Set(services(before).filter(([, service]) => service.environment?.[key] !== undefined).map(([name]) => name))
145
+
146
+ return services(after).filter(([name, service]) => service.environment?.[key] !== undefined && !had.has(name)).map(([name]) => name)
147
+ }
148
+
149
+ // Takes others, and the group too when `group`, out of the file's mode. False when another account owns the file, so only it or root can change its mode.
150
+ export async function shutOthersOut(path: string, group = false): Promise<boolean> {
151
+ try {
152
+ await chmod(path, (await stat(path)).mode & (group ? 0o700 : 0o770))
153
+
154
+ return true
155
+ }
156
+ catch (error) {
157
+ if ((error as NodeJS.ErrnoException).code === 'EPERM')
158
+ return false
159
+
160
+ throw error
161
+ }
162
+ }
163
+
164
+ // Moves each inline secret of a compose file into the .env beside it, swapping the value for `${KEY}`, then shuts others out of both. A key the .env sets to another value stays put, and a move `docker compose config` resolves differently is put back.
165
+ export async function fixCompose(path: string, group = false): Promise<ComposeFix> {
166
+ const env = join(dirname(path), '.env')
167
+ const compose = await Bun.file(path).text()
168
+ const envBefore = await Bun.file(env).exists() ? await Bun.file(env).text() : undefined
169
+ const dotenv = parseDotenv(envBefore ?? '')
170
+ const known = entries(dotenv)
171
+ const fix: ComposeFix = { path, env, moved: [], left: [], open: [] }
172
+ const linked = await isLink(env)
173
+
174
+ const lines = compose.split('\n').map((line) => {
175
+ const entry = composeEntry(line)
176
+
177
+ if (entry === undefined || !isInlineSecret(entry.key, entry.value))
178
+ return line
179
+
180
+ const { key } = entry
181
+
182
+ if ('unmovable' in entry) {
183
+ fix.left.push({ key, why: entry.unmovable })
184
+
185
+ return line
186
+ }
187
+
188
+ if (linked) {
189
+ fix.left.push({ key, why: 'its .env is a symbolic link' })
190
+
191
+ return line
192
+ }
193
+
194
+ if (entry.value.replaceAll('$$', '').includes('$')) {
195
+ fix.left.push({ key, why: 'its value reads another variable' })
196
+
197
+ return line
198
+ }
199
+
200
+ const value = entry.value.replaceAll('$$', '$')
201
+ const existing = known.get(key)
202
+
203
+ if (existing === undefined) {
204
+ const raw = envLine(key, value)
205
+
206
+ if (raw === undefined) {
207
+ fix.left.push({ key, why: 'its value holds a quote or line break a .env cannot keep literal' })
208
+
209
+ return line
210
+ }
211
+
212
+ setLine(dotenv, key, value, raw)
213
+ known.set(key, value)
214
+ }
215
+ else if (existing !== value) {
216
+ fix.left.push({ key, why: `${env.slice(env.lastIndexOf('/') + 1)} already sets it to another value` })
217
+
218
+ return line
219
+ }
220
+
221
+ if (!fix.moved.includes(key))
222
+ fix.moved.push(key)
223
+
224
+ return entry.swap(`\${${key}}`)
225
+ })
226
+
227
+ if (fix.moved.length > 0)
228
+ await move(fix, compose, lines.join('\n'), envBefore, serializeDotenv(dotenv))
229
+
230
+ for (const file of [path, env]) {
231
+ if (!(file === env && linked) && await Bun.file(file).exists() && !await shutOthersOut(file, group))
232
+ fix.open.push(file)
233
+ }
234
+
235
+ return fix
236
+ }
237
+
238
+ async function move(fix: ComposeFix, compose: string, composeAfter: string, envBefore: string | undefined, envAfter: string): Promise<void> {
239
+ const { path, env } = fix
240
+ const docker = Bun.which('docker') !== null
241
+ const before = docker ? await resolved(path) : undefined
242
+
243
+ if (envBefore === undefined) {
244
+ await writeAtomic(env, envAfter)
245
+
246
+ // A root run gives the .env to whoever owns the compose file; anyone else already owns what they write.
247
+ const { uid, gid } = await stat(path)
248
+
249
+ try {
250
+ await chown(env, uid, gid)
251
+ }
252
+ catch {}
253
+ }
254
+ else {
255
+ await writeAtomic(env, envAfter)
256
+ }
257
+
258
+ await writeAtomic(path, composeAfter)
259
+
260
+ if (!docker) {
261
+ fix.check = 'no docker'
262
+
263
+ return
264
+ }
265
+
266
+ if (before === undefined) {
267
+ fix.check = 'fails before'
268
+
269
+ return
270
+ }
271
+
272
+ const after = await resolved(path)
273
+
274
+ if (after === before) {
275
+ fix.check = 'same'
276
+
277
+ return
278
+ }
279
+
280
+ await writeAtomic(path, compose)
281
+
282
+ if (envBefore === undefined)
283
+ await rm(env)
284
+ else
285
+ await writeAtomic(env, envBefore)
286
+
287
+ fix.check = 'rolled back'
288
+ fix.left.push(...fix.moved.map((key) => {
289
+ const gained = after === undefined ? [] : gainedBy(before, after, key)
290
+
291
+ return { key, why: gained.length > 0 ? `${gained.join(', ')} ${gained.length > 1 ? 'load' : 'loads'} the .env through env_file and would gain it, so it was put back` : 'docker compose config resolved differently once moved, so it was put back' }
292
+ }))
293
+ fix.moved = []
294
+ }
@@ -0,0 +1,114 @@
1
+ import { splitCommand, tokenize } from '@kaynooo/cli-kit/shell'
2
+
3
+ const OPENER = /^[({]+/
4
+ const DUMP_FLAGS = /^-[a-z]*[px]/
5
+ // Git commands whose output carries the content of tracked files.
6
+ const GIT_PATCHES = new Set(['diff', 'log', 'show', 'whatchanged', 'format-patch', 'grep'])
7
+ const GIT_NO_PATCH = new Set(['--stat', '--numstat', '--shortstat', '--name-only', '--name-status', '--summary', '-s', '--no-patch', '--check', '--quiet'])
8
+ const GIT_VALUE_OPTIONS = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path'])
9
+ const GIT_PATCH_FLAGS = new Set(['-p', '-u', '--patch', '-c', '--cc', '--patch-with-stat', '--patch-with-raw'])
10
+
11
+ export const GIT_EXCLUDE = /^:(?:!|\^|\(exclude\))/
12
+ // Programs printing a process's whole environment.
13
+ const ENV_PRINTERS = new Set(['env', 'printenv'])
14
+ const DOCKER = new Set(['docker', 'docker-compose'])
15
+ const SHELLS = new Set(['sh', 'bash', 'zsh', 'ash'])
16
+ // `-c`, and `-lc`, `-ic` or `-ce` where the short flags are combined.
17
+ const SHELL_COMMAND_FLAG = /^-[abd-z]*c[a-z]*$/
18
+ // Options taking a value, before a docker or compose subcommand, and before exec's container.
19
+ const DOCKER_VALUE_OPTIONS = new Set(['-f', '--file', '-p', '--project-name', '--profile', '--env-file', '--project-directory', '--ansi', '--progress', '--parallel', '-H', '--host', '-c', '--context', '--config', '-l', '--log-level'])
20
+ const EXEC_VALUE_OPTIONS = new Set(['-e', '--env', '--env-file', '-u', '--user', '-w', '--workdir', '--index', '--detach-keys'])
21
+ // `compose config` options printing names, never values.
22
+ const CONFIG_LISTS = new Set(['--services', '--volumes', '--profiles', '--images', '--networks', '--hash', '-q', '--quiet'])
23
+ const FORMAT_OPTIONS = new Set(['-f', '--format'])
24
+ // An inspect format still printing the environment, or everything.
25
+ const WHOLE_FORMAT = /Env|\{\{\s*json\s+\.\s*\}\}|^json$/
26
+
27
+ // The index of the first word that is no option, past the values the options given take.
28
+ function firstOperand(words: readonly string[], valueOptions: ReadonlySet<string>): number {
29
+ for (let i = 0; i < words.length; i++) {
30
+ const word = words[i] ?? ''
31
+
32
+ if (valueOptions.has(word))
33
+ i++
34
+ else if (!word.startsWith('-'))
35
+ return i
36
+ }
37
+
38
+ return words.length
39
+ }
40
+
41
+ // The command a container runs prints its environment: `env` or `printenv` as the program, or as one run by `sh -c`.
42
+ function printsEnv([program = '', ...args]: readonly string[]): boolean {
43
+ const flags = args.findIndex(arg => !arg.startsWith('-') || SHELL_COMMAND_FLAG.test(arg))
44
+
45
+ if (SHELLS.has(program) && SHELL_COMMAND_FLAG.test(args[flags] ?? ''))
46
+ return splitCommand(args[flags + 1] ?? '').some(piece => ENV_PRINTERS.has(tokenize(piece.command)[0] ?? ''))
47
+
48
+ return ENV_PRINTERS.has(program)
49
+ }
50
+
51
+ // A docker call printing a container's environment: `env` or `printenv` run through exec, `compose config` and `inspect`, which spell it out.
52
+ export function dumpsContainerEnv(program: string, args: string[]): boolean {
53
+ if (!DOCKER.has(program))
54
+ return false
55
+
56
+ const afterOptions = (words: readonly string[]) => words.slice(firstOperand(words, DOCKER_VALUE_OPTIONS))
57
+ let rest = afterOptions(args)
58
+ const isCompose = program === 'docker-compose' || rest[0] === 'compose'
59
+
60
+ if (program === 'docker' && isCompose)
61
+ rest = afterOptions(rest.slice(1))
62
+
63
+ const [subcommand = '', ...after] = rest
64
+
65
+ if (subcommand === 'exec')
66
+ return printsEnv(after.slice(firstOperand(after, EXEC_VALUE_OPTIONS) + 1))
67
+
68
+ if (isCompose)
69
+ return subcommand === 'config' && !after.some(word => CONFIG_LISTS.has(word))
70
+
71
+ if (subcommand !== 'inspect' && (subcommand !== 'container' || after[0] !== 'inspect'))
72
+ return false
73
+
74
+ const format = after.find((_, i) => FORMAT_OPTIONS.has(after[i - 1] ?? '')) ?? after.find(word => word.startsWith('--format='))?.slice('--format='.length)
75
+
76
+ return format === undefined || WHOLE_FORMAT.test(format)
77
+ }
78
+
79
+ // Programs printing the environment of the shell they run in: `env` and `printenv` alone, `export -p`, `declare -x`, a bare `set`.
80
+ export function dumpsEnvironment(program: string, args: readonly string[], tokens: readonly string[]): boolean {
81
+ const isBare = args.every(arg => arg.startsWith('-'))
82
+
83
+ if (program === 'printenv' || program === 'export')
84
+ return isBare
85
+
86
+ if (program === 'declare' || program === 'typeset')
87
+ return isBare && args.some(arg => DUMP_FLAGS.test(arg))
88
+
89
+ if (program === 'set')
90
+ return args.length === 0
91
+
92
+ return program === '' && tokens.some(token => token.replace(OPENER, '') === 'env')
93
+ }
94
+
95
+ // Whether a git command prints the content of a tracked env file: a patch or a search with no pathspec leaving env files out.
96
+ export function printsTrackedEnv(program: string, args: readonly string[]): boolean {
97
+ if (program !== 'git')
98
+ return false
99
+
100
+ const at = args.findIndex((arg, i) => !arg.startsWith('-') && !GIT_VALUE_OPTIONS.has(args[i - 1] ?? ''))
101
+ const name = args[at] ?? ''
102
+ const rest = args.slice(at + 1)
103
+
104
+ if (!GIT_PATCHES.has(name) || rest.some(arg => GIT_EXCLUDE.test(arg)))
105
+ return false
106
+
107
+ if (name === 'grep')
108
+ return true
109
+
110
+ if (name === 'log' || name === 'whatchanged')
111
+ return rest.some(arg => GIT_PATCH_FLAGS.has(arg))
112
+
113
+ return !rest.some(arg => GIT_NO_PATCH.has(arg))
114
+ }
@@ -0,0 +1,107 @@
1
+ import type { Piece, Word } from '@kaynooo/cli-kit/shell'
2
+ import { braceExpand, parseCommand, splitCommand, tokenize, words } from '@kaynooo/cli-kit/shell'
3
+ import { GIT_EXCLUDE } from './guard-dumps'
4
+ import { isEnvFile, namesEnvFile } from './guard-paths'
5
+ import { GREP_VALUE_OPTIONS, GREPS, listsFiles, patternIndex, printsNamesOnly, RG_VALUE_OPTIONS } from './guard-search'
6
+
7
+ const ENV_NAME_IN_CODE = /(?:^|[^\w.-])(\.env(?:\.[\w.-]*\w)?|\.envrc)(?![\w-])/g
8
+ const PYTHON_ENVIRON = /\bos\.environ\b(?!\s*(?:\[|\.get\b))/
9
+ const VARIABLE = /\$(?:(\w+)|\{(\w+)\})/
10
+ const ASSIGNMENT = /^\w+=/
11
+ const MAX_VARIANTS = 64
12
+ // Programs running the code they are given, which may read an env file or print the environment.
13
+ const INTERPRETERS = new Set(['bun', 'deno', 'node', 'python', 'python3', 'ruby', 'perl', 'php', 'lua', 'awk', 'gawk'])
14
+ const CODE_OPTIONS = new Set(['-e', '-c', '-p', '-E', '-pe', '-r', '--eval', '--print', '--command'])
15
+ // What a script needs to open a file or run a command: file, process and shell APIs, imports, command substitution and backticks.
16
+ const CAN_REACH_FILES = /read|write|open|exec|spawn|system|popen|import|require|eval|load|fetch|glob|stream|source|getline|constructor|file(?!s\b)|\bcat\b|\b(?:Bun|Deno|fs|os|io|sh|bash|process|globalThis|window|Function|qx)\b|\$\s*[`({]|`/i
17
+ const DECLARERS = new Set(['export', 'declare', 'local', 'readonly', 'typeset'])
18
+ // Programs that name an env file without reading it: listing, testing, or loading it into a process that prints nothing.
19
+ const HARMLESS = new Set(['ev', 'redact', 'ls', 'stat', 'test', '[', '[[', 'touch'])
20
+ const GIT_HARMLESS = new Set(['check-ignore', 'ls-files', 'status'])
21
+
22
+ // The values each variable is given in a command, by assignment, `export` or a `for` list.
23
+ export function variablesOf(command: string): Map<string, string[]> {
24
+ const variables = new Map<string, string[]>()
25
+ const add = (assignment: string) => {
26
+ const at = assignment.indexOf('=')
27
+ const name = assignment.slice(0, at)
28
+
29
+ variables.set(name, [...variables.get(name) ?? [], assignment.slice(at + 1)])
30
+ }
31
+
32
+ for (const piece of splitCommand(command)) {
33
+ const { program, args, assignments } = parseCommand(piece.command)
34
+ const tokens = tokenize(piece.command)
35
+
36
+ const declared = DECLARERS.has(program) ? args.filter(arg => ASSIGNMENT.test(arg)) : []
37
+
38
+ for (const assignment of [...assignments, ...declared])
39
+ add(assignment)
40
+
41
+ if (tokens[0] === 'for' && tokens[2] === 'in' && tokens[1] !== undefined)
42
+ variables.set(tokens[1], [...variables.get(tokens[1]) ?? [], ...tokens.slice(3)])
43
+ }
44
+
45
+ return variables
46
+ }
47
+
48
+ // The words a word stands for once the variables it uses and its `{a,b}` lists are replaced.
49
+ function variantsOf(word: Word, variables: ReadonlyMap<string, string[]>): string[] {
50
+ let found = [word.text]
51
+
52
+ for (let round = 0; round < 4 && found.some(each => VARIABLE.test(each)); round++) {
53
+ found = found.flatMap((each) => {
54
+ const match = VARIABLE.exec(each)
55
+ const values = variables.get(match?.[1] ?? match?.[2] ?? '')
56
+
57
+ if (match === null || values === undefined)
58
+ return [each.replace(VARIABLE, '')]
59
+
60
+ return values.map(value => each.slice(0, match.index) + value + each.slice(match.index + match[0].length))
61
+ }).slice(0, MAX_VARIANTS)
62
+ }
63
+
64
+ return found.flatMap(each => word.hasBrace ? braceExpand(each) : [each])
65
+ }
66
+
67
+ // Whether code names an env file and could open it: a mention in code that calls nothing able to read a file, run a command or import a module (`/\.env files/.test(x)`) is only text. Deliberately generous, so a doubtful script stays refused.
68
+ function codeReadsEnvFile(code: string): boolean {
69
+ return [...code.matchAll(ENV_NAME_IN_CODE)].some(match => isEnvFile(match[1] ?? '')) && CAN_REACH_FILES.test(code)
70
+ }
71
+
72
+ // Whether code run by an interpreter, given as an argument or fed as a heredoc, reads an env file or dumps the environment of a Python process.
73
+ function codeReadsEnv(found: readonly Word[], heredocs: readonly string[]): boolean {
74
+ const sources = [...found.filter((word, i) => word.isProse || CODE_OPTIONS.has(found[i - 1]?.text ?? '')).map(word => word.text), ...heredocs]
75
+
76
+ return sources.some(code => PYTHON_ENVIRON.test(code) || codeReadsEnvFile(code))
77
+ }
78
+
79
+ export function readsEnv(piece: Piece, variables: ReadonlyMap<string, string[]>): boolean {
80
+ const { program, args } = parseCommand(piece.command)
81
+
82
+ if (program === '' || HARMLESS.has(program) || (program === 'git' && GIT_HARMLESS.has(args[0] ?? '')))
83
+ return false
84
+
85
+ if (INTERPRETERS.has(program) && codeReadsEnv(words(piece.command), piece.heredocs))
86
+ return true
87
+
88
+ if (printsNamesOnly(program, args) || listsFiles(program, args))
89
+ return false
90
+
91
+ return namesEnv(piece, variables)
92
+ }
93
+
94
+ // Whether a piece has a word naming an env file, whatever it does with it.
95
+ export function namesEnv(piece: Piece, variables: ReadonlyMap<string, string[]>): boolean {
96
+ const { program, args } = parseCommand(piece.command)
97
+ const found = words(piece.command)
98
+
99
+ // a git pathspec like `:!.env` leaves the file out
100
+ const isExclusion = (word: Word) => program === 'git' && GIT_EXCLUDE.test(word.text)
101
+ // the pattern of a search is a regex, not a file
102
+ const isSearch = GREPS.has(program) || program === 'rg' || program === 'ag'
103
+ const patternAt = isSearch ? patternIndex(args, GREPS.has(program) ? GREP_VALUE_OPTIONS : RG_VALUE_OPTIONS) : undefined
104
+ const pattern = patternAt === undefined ? undefined : found.length - args.length + patternAt
105
+
106
+ return found.some((word, index) => index !== pattern && !word.isProse && !isExclusion(word) && variantsOf(word, variables).some(variant => namesEnvFile(variant, found[index - 1]?.text, word.hasGlob)))
107
+ }
@@ -0,0 +1,80 @@
1
+ import { braceExpand } from '@kaynooo/cli-kit/shell'
2
+ import { ENV_FILE, TEMPLATE } from './files'
3
+
4
+ const REDIRECT = /^\d*[<>]+&?/
5
+ const ENVRC = '.envrc'
6
+ const PROC_ENVIRON = /^\/proc\/[^/]+\/environ$/
7
+ // Names a glob could stand for, to tell whether it reaches an env file.
8
+ const ENV_SAMPLES = ['.env', '.env.local', '.env.production', '.envrc']
9
+ const REGEX_SPECIALS = /[.+^${}()|\\[\]]/g
10
+ const NEGATED_CLASS = /^!/
11
+ const GLOB_CHAR = /[*?[]/
12
+
13
+ export const EXCLUDE_OPTIONS = new Set(['--exclude', '--exclude-dir', '-g', '--glob', '--iglob'])
14
+
15
+ // The name past the last `/`, or past the `:` of `HEAD~1:api/.env` as git spells a file at a revision; the `.env*` glob reaches one too.
16
+ export function isEnvFile(path: string): boolean {
17
+ const name = path.slice(Math.max(path.lastIndexOf('/'), path.lastIndexOf(':')) + 1)
18
+
19
+ return (ENV_FILE.test(name) || name === '.env*' || name === ENVRC) && !TEMPLATE.test(name)
20
+ }
21
+
22
+ // The regex a shell glob stands for, `*` and `?` matching a name's characters and `[...]` a class.
23
+ function globRegex(glob: string): RegExp {
24
+ let source = ''
25
+
26
+ for (let i = 0; i < glob.length; i++) {
27
+ const char = glob[i] ?? ''
28
+ const close = char === '[' ? glob.indexOf(']', i + 2) : -1
29
+
30
+ if (char === '*') {
31
+ source += '.*'
32
+ }
33
+ else if (char === '?') {
34
+ source += '.'
35
+ }
36
+ else if (close === -1) {
37
+ source += char.replace(REGEX_SPECIALS, String.raw`\$&`)
38
+ }
39
+ else {
40
+ source += `[${glob.slice(i + 1, close).replace(NEGATED_CLASS, '^')}]`
41
+ i = close
42
+ }
43
+ }
44
+
45
+ return new RegExp(`^${source}$`)
46
+ }
47
+
48
+ // A dotted glob such as `.en?` or `.e*` reaching an env file; the shell never matches a leading dot with a wildcard, so the glob has to spell it.
49
+ function globReachesEnv(path: string): boolean {
50
+ const name = path.slice(path.lastIndexOf('/') + 1)
51
+
52
+ if (!name.startsWith('.') || !GLOB_CHAR.test(name))
53
+ return false
54
+
55
+ const regex = globRegex(name)
56
+
57
+ return ENV_SAMPLES.some(sample => regex.test(sample))
58
+ }
59
+
60
+ // Whether the path or glob a file tool is given reaches an env file, `{a,b}` lists and wildcards included.
61
+ export function reachesEnvFile(path: string): boolean {
62
+ return braceExpand(path).some(each => isEnvFile(each) || globReachesEnv(each))
63
+ }
64
+
65
+ // The path a word stands for, past any redirect and `--flag=` prefix.
66
+ function targetOf(word: string): string {
67
+ const bare = word.replace(REDIRECT, '')
68
+
69
+ return bare.includes('=') ? bare.slice(bare.indexOf('=') + 1) : bare
70
+ }
71
+
72
+ // A word naming an env file, past any redirect and `--flag=` prefix; an `--env-file` value only loads it, so it is let through.
73
+ export function namesEnvFile(word: string, previous: string | undefined, isGlob: boolean): boolean {
74
+ if (previous === '--env-file' || word.startsWith('--env-file=') || word.startsWith('--exclude') || EXCLUDE_OPTIONS.has(previous ?? ''))
75
+ return false
76
+
77
+ const path = targetOf(word)
78
+
79
+ return isEnvFile(path) || PROC_ENVIRON.test(path) || (isGlob && globReachesEnv(path))
80
+ }
@@ -0,0 +1,76 @@
1
+ import type { Piece } from '@kaynooo/cli-kit/shell'
2
+ import { parseCommand, tokenize } from '@kaynooo/cli-kit/shell'
3
+ import { namesEnv } from './guard-names'
4
+ import { searchesEnvNames } from './guard-search'
5
+
6
+ // Programs an `xargs` can run on a listing of names without printing a line of the files.
7
+ const XARGS_SAFE = new Set(['ls', 'stat', 'wc', 'test', '[', 'touch', 'echo', 'printf', 'basename', 'dirname', 'ev', 'redact', ''])
8
+ // GNU parallel's options taking their value as the next word, before the command it runs.
9
+ const PARALLEL_VALUE_OPTIONS = new Set(['-j', '--jobs', '-P', '--max-procs', '-S', '--sshlogin', '-C', '--colsep', '-n', '--max-args', '-N', '-d', '--delimiter', '-E', '-I', '--timeout', '--delay', '--joblog', '--results', '--tmpdir', '-a', '--arg-file', '--halt', '--retries', '--tag-string'])
10
+ const IDENTIFIER = /^[A-Z_]\w*$/i
11
+ // `read`'s options taking a value, which is not a variable it fills.
12
+ const READ_VALUE_OPTIONS = new Set(['-a', '-d', '-i', '-n', '-N', '-p', '-t', '-u'])
13
+
14
+ // Whether a piece further up the pipeline that `index` starts lists env files by name.
15
+ function listsEnvUpstream(pieces: readonly Piece[], index: number, variables: ReadonlyMap<string, string[]>): boolean {
16
+ for (let at = index - 1; at >= 0 && pieces[at]?.separator.startsWith('|'); at--) {
17
+ if (namesEnv(pieces[at] as Piece, variables) || searchesEnvNames(pieces[at] as Piece))
18
+ return true
19
+ }
20
+
21
+ return false
22
+ }
23
+
24
+ // The program GNU parallel runs on each name it is fed, `cat` in `parallel -j4 cat {}`.
25
+ function parallelRunner(args: readonly string[]): string {
26
+ const at = args.findIndex((arg, i) => !arg.startsWith('-') && !PARALLEL_VALUE_OPTIONS.has(args[i - 1] ?? ''))
27
+
28
+ return at === -1 ? '' : (args[at] ?? '').split('/').at(-1) ?? ''
29
+ }
30
+
31
+ // Whether the piece is an `xargs` or `parallel` running a command that may print the files it is given the names of, on a listing naming an env file further up its pipeline (harmless alone, but each name gets opened).
32
+ export function runnerReadsListedEnv(pieces: readonly Piece[], index: number, variables: ReadonlyMap<string, string[]>): boolean {
33
+ const command = pieces[index]?.command ?? ''
34
+ const { program, args, isWrapped } = parseCommand(command)
35
+ // parseCommand sees through `xargs` and `parallel` to the command they run
36
+ const isXargs = isWrapped && tokenize(command).some(word => word === 'xargs' || word === 'parallel')
37
+
38
+ if (program !== 'parallel' && !isXargs)
39
+ return false
40
+
41
+ return !XARGS_SAFE.has(isXargs ? program : parallelRunner(args)) && listsEnvUpstream(pieces, index, variables)
42
+ }
43
+
44
+ // The variables a `read` fills, REPLY when it names none.
45
+ function readVariables(args: readonly string[]): string[] {
46
+ const names = args.filter((arg, i) => !arg.startsWith('-') && !READ_VALUE_OPTIONS.has(args[i - 1] ?? '') && IDENTIFIER.test(arg))
47
+
48
+ return names.length === 0 ? ['REPLY'] : names
49
+ }
50
+
51
+ // Whether the piece sits in the body of a `while read` loop fed a listing naming an env file, and hands one of the names read to a command that may print the file.
52
+ export function loopReadsListedEnv(pieces: readonly Piece[], index: number, variables: ReadonlyMap<string, string[]>): boolean {
53
+ const { program } = parseCommand(pieces[index]?.command ?? '')
54
+
55
+ if (XARGS_SAFE.has(program) || program === 'done')
56
+ return false
57
+
58
+ for (let at = index - 1; at >= 0; at--) {
59
+ const piece = pieces[at] as Piece
60
+ const head = parseCommand(piece.command)
61
+
62
+ if (head.program === 'done')
63
+ return false
64
+
65
+ const opener = tokenize(piece.command)[0]
66
+
67
+ if (head.program !== 'read' || (opener !== 'while' && opener !== 'until'))
68
+ continue
69
+
70
+ const used = readVariables(head.args).some(name => new RegExp(`\\$\\{?${name}\\b`).test(pieces[index]?.command ?? ''))
71
+
72
+ return used && listsEnvUpstream(pieces, at, variables)
73
+ }
74
+
75
+ return false
76
+ }