@cogs/config 0.4.0 → 0.5.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.
@@ -0,0 +1,311 @@
1
+ /**
2
+ * `config-lint` CLI core. All logic lives here behind injectable dependencies so
3
+ * it is unit-testable without a real filesystem; `cli.ts` is a thin `main()`
4
+ * wrapper. Split and posture follow `packages/env-doctor/src/cli-core.ts` +
5
+ * `cli.ts`.
6
+ *
7
+ * Deliberately NOT re-exported from `index.ts`: `@cogs/config` is preloaded into
8
+ * every consumer's process via `./preload`, and the bin's code has no business
9
+ * in that path's transitive footprint.
10
+ *
11
+ * Safety posture:
12
+ * - **Read-only by default.** `--fix` is the only path that writes, and it only
13
+ * rewrites single-line entries it can locate byte-exactly in the source.
14
+ * - **No value is ever printed in full**, in human or `--json` output: every
15
+ * finding message arrives pre-masked to its last 4 characters by
16
+ * `redact.ts`'s `maskLast4` — a package-local port of
17
+ * `packages/env-doctor/src/redact.ts`, not a cross-package import.
18
+ */
19
+ import { existsSync as nodeExistsSync, readFileSync as nodeReadFileSync, writeFileSync as nodeWriteFileSync, } from 'node:fs';
20
+ import { dotenvKeyCheckers, dotenvLineCheckers, } from './dotenv-checkers.js';
21
+ import { correlateRawValues } from './dotenv-correlation.js';
22
+ import { resolveDotenvFileChain } from './dotenv-files.js';
23
+ import { dotenvKeyFixers, dotenvLineFixers } from './dotenv-fixers.js';
24
+ export const TOOL_NAME = 'config-lint';
25
+ /** Read from this package's own `package.json` — resolves the same from `src/` and `dist/`. */
26
+ export const VERSION = (() => {
27
+ try {
28
+ const raw = nodeReadFileSync(new URL('../package.json', import.meta.url), 'utf8');
29
+ const parsed = JSON.parse(raw);
30
+ const version = parsed.version;
31
+ return typeof version === 'string' ? version : '0.0.0';
32
+ }
33
+ catch {
34
+ return '0.0.0';
35
+ }
36
+ })();
37
+ /** 0 clean · 1 unexpected error · 2 usage error · 3 findings present. */
38
+ export const EXIT = {
39
+ CLEAN: 0,
40
+ ERROR: 1,
41
+ USAGE: 2,
42
+ FINDINGS: 3,
43
+ };
44
+ export const HELP = `
45
+ ${TOOL_NAME} — lint an app's layered .env* chain for quote-wrapping mistakes
46
+
47
+ Catches, at its source, the value that gets copy-pasted verbatim out of a
48
+ shell-quoted .env file and into a deploy provider's env-var box — where the
49
+ quotes stop being syntax and become part of the secret.
50
+
51
+ Usage:
52
+ ${TOOL_NAME} <path-to-app-dir> [--json] [--fix]
53
+
54
+ Options:
55
+ --json Emit the findings array as JSON on stdout instead of human text.
56
+ --fix Rewrite fixable single-line entries in place. See the warning below.
57
+ -h, --help
58
+ --version Print the installed version and exit.
59
+
60
+ Exit codes:
61
+ 0 clean — no findings
62
+ 1 unexpected error
63
+ 2 usage error
64
+ 3 findings present
65
+
66
+ The .env* chain is resolved exactly as \`envs()\` resolves it, honoring NODE_ENV
67
+ and ENV from the environment:
68
+ .env → .env.local (skipped when NODE_ENV=test) → .env.\${ENV} → .env.\${ENV}.local
69
+
70
+ KNOWN LIMITATIONS, disclosed rather than silently inherited:
71
+
72
+ --fix applies quoteCharacterFixer and valueWithoutQuotesFixer, which strip and
73
+ add quotes GLOBALLY rather than as a matched pair. A value containing an
74
+ internal apostrophe or backtick can therefore be corrupted. Fixing those
75
+ fixers is out of scope for the change that introduced this bin; review every
76
+ --fix diff before committing it.
77
+
78
+ --fix also applies dotenvKeyFixers to the key (e.g. lowercase keys are
79
+ rewritten to uppercase), not just the value fixers described above.
80
+
81
+ --fix only rewrites entries it can locate on a single physical line. Multiline
82
+ quoted values are reported but never rewritten.
83
+
84
+ trailingWhitespaceChecker is a known-broken checker that was deliberately left
85
+ unfixed. It is run for completeness but essentially cannot fire against a
86
+ correctly correlated value, and its output should not be trusted.
87
+ `.trim();
88
+ const resolveDeps = (deps) => ({
89
+ existsSync: deps.existsSync ?? ((path) => nodeExistsSync(path)),
90
+ readFileSync: deps.readFileSync ??
91
+ ((path) => nodeReadFileSync(path, { encoding: 'utf8' })),
92
+ writeFileSync: deps.writeFileSync ??
93
+ ((path, data) => nodeWriteFileSync(path, data, { encoding: 'utf8' })),
94
+ log: deps.log ?? ((message) => console.log(message)),
95
+ error: deps.error ?? ((message) => console.error(message)),
96
+ env: deps.env ?? process.env,
97
+ });
98
+ export class CliUsageError extends Error {
99
+ }
100
+ export const parseArgs = (argv) => {
101
+ const positionals = [];
102
+ let json = false;
103
+ let fix = false;
104
+ let help = false;
105
+ let version = false;
106
+ for (const arg of argv) {
107
+ if (arg === '-h' || arg === '--help')
108
+ help = true;
109
+ else if (arg === '--version')
110
+ version = true;
111
+ else if (arg === '--json')
112
+ json = true;
113
+ else if (arg === '--fix')
114
+ fix = true;
115
+ else if (arg.startsWith('--'))
116
+ throw new CliUsageError(`unknown flag: ${arg}`);
117
+ else
118
+ positionals.push(arg);
119
+ }
120
+ if (help || version) {
121
+ return { appDirectory: '', json, fix, help, version };
122
+ }
123
+ const appDirectory = positionals[0];
124
+ if (appDirectory === undefined) {
125
+ throw new CliUsageError('missing required <path-to-app-dir> argument');
126
+ }
127
+ if (positionals.length > 1) {
128
+ throw new CliUsageError('exactly one <path-to-app-dir> is accepted');
129
+ }
130
+ return { appDirectory, json, fix, help, version };
131
+ };
132
+ // --------------------------------------------------------------------------
133
+ // Checker plumbing
134
+ // --------------------------------------------------------------------------
135
+ /**
136
+ * `quoteCharacterChecker` and `valueWithoutQuotesChecker` return a
137
+ * {@link Finding}; the four checkers that were out of scope for the fix still
138
+ * report `true` plus a `console.log` side effect.
139
+ */
140
+ const isFinding = (value) => typeof value === 'object' &&
141
+ value !== null &&
142
+ 'key' in value &&
143
+ 'rule' in value &&
144
+ 'message' in value;
145
+ /** `quoteCharacterChecker` → `quote-character`. */
146
+ const ruleFor = (checker) => checker.name
147
+ .replace(/Checker$/, '')
148
+ .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
149
+ .toLowerCase();
150
+ /**
151
+ * Run one checker and normalize its result to a {@link Finding}.
152
+ *
153
+ * The legacy checkers report by `console.log` side effect. That output is
154
+ * captured rather than suppressed — it keeps their (useful) message text while
155
+ * leaving `--json`'s stdout machine-readable, which a stray `console.log` would
156
+ * otherwise corrupt.
157
+ */
158
+ const runChecker = (checker, key, value) => {
159
+ const captured = [];
160
+ const original = console.log;
161
+ console.log = (...args) => {
162
+ captured.push(args.map(String).join(' '));
163
+ };
164
+ let result;
165
+ try {
166
+ result = checker(key, value);
167
+ }
168
+ finally {
169
+ console.log = original;
170
+ }
171
+ if (isFinding(result))
172
+ return result;
173
+ if (!result)
174
+ return;
175
+ const rule = ruleFor(checker);
176
+ return {
177
+ key,
178
+ rule,
179
+ message: captured[0]?.replace(/^warning:\s*/, '') ?? `'${key}' failed ${rule}.`,
180
+ };
181
+ };
182
+ /** Lint one file's raw contents. */
183
+ export const lintContents = (contents) => {
184
+ const findings = [];
185
+ for (const [key, rawValue] of correlateRawValues(contents)) {
186
+ for (const checker of dotenvKeyCheckers) {
187
+ const finding = runChecker(checker, key, rawValue);
188
+ if (finding)
189
+ findings.push(finding);
190
+ }
191
+ for (const checker of dotenvLineCheckers) {
192
+ const finding = runChecker(checker, key, rawValue);
193
+ if (finding)
194
+ findings.push(finding);
195
+ }
196
+ }
197
+ return findings;
198
+ };
199
+ // --------------------------------------------------------------------------
200
+ // --fix
201
+ // --------------------------------------------------------------------------
202
+ /** `[indent][export ][KEY][ = ]` — the fixed prefix of a single-line entry. */
203
+ const ENTRY_PREFIX = /^(\s*)(export\s+)?([\w.-]+)(\s*=\s*)/;
204
+ /**
205
+ * Rewrite the fixable single-line entries in `contents`.
206
+ *
207
+ * Conservative by construction. The raw values come from correlating the
208
+ * **whole file** — never the physical line in isolation — and an entry is only
209
+ * rewritten when that whole-file value is single-line AND can be located
210
+ * byte-exactly within the line. Correlating a line in isolation would see the
211
+ * opening half of a multiline quoted value (`ML="line1`) as a complete unquoted
212
+ * value and let `quoteCharacterFixer` strip its opening quote, corrupting the
213
+ * file. Anything the whole-file correlation and the line splitting disagree
214
+ * about — multiline values, duplicate keys, continuation lines that happen to
215
+ * look like entries — is left untouched rather than guessed at.
216
+ *
217
+ * See HELP's known limitations for the separate, pre-existing corruption risk
218
+ * the underlying fixers themselves carry.
219
+ */
220
+ export const applyFixes = (contents) => {
221
+ const rawValues = correlateRawValues(contents);
222
+ return contents
223
+ .split('\n')
224
+ .map((line) => {
225
+ const match = ENTRY_PREFIX.exec(line);
226
+ if (!match)
227
+ return line;
228
+ const [prefix, indent = '', exportPrefix = '', key = '', assign = '='] = match;
229
+ const rawValue = rawValues.get(key);
230
+ if (rawValue === undefined || rawValue.includes('\n'))
231
+ return line;
232
+ const valueStart = line.indexOf(rawValue, prefix?.length ?? 0);
233
+ if (valueStart === -1)
234
+ return line;
235
+ const trailer = line.slice(valueStart + rawValue.length);
236
+ let nextKey = key;
237
+ let nextValue = rawValue;
238
+ for (const fixer of [...dotenvKeyFixers, ...dotenvLineFixers]) {
239
+ const [fixedKey, fixedValue] = fixer(nextKey, nextValue);
240
+ nextKey = fixedKey ?? nextKey;
241
+ nextValue = fixedValue ?? nextValue;
242
+ }
243
+ if (nextKey === key && nextValue === rawValue)
244
+ return line;
245
+ return `${indent}${exportPrefix}${nextKey}${assign}${nextValue}${trailer}`;
246
+ })
247
+ .join('\n');
248
+ };
249
+ export async function main(argv, deps = {}) {
250
+ const { existsSync, readFileSync, writeFileSync, log, error, env } = resolveDeps(deps);
251
+ let args;
252
+ try {
253
+ args = parseArgs(argv);
254
+ }
255
+ catch (err) {
256
+ if (err instanceof CliUsageError) {
257
+ error(`${TOOL_NAME}: ${err.message}`);
258
+ error(HELP);
259
+ return EXIT.USAGE;
260
+ }
261
+ throw err;
262
+ }
263
+ if (args.version) {
264
+ log(VERSION);
265
+ return EXIT.CLEAN;
266
+ }
267
+ if (args.help) {
268
+ log(HELP);
269
+ return EXIT.CLEAN;
270
+ }
271
+ try {
272
+ const files = resolveDotenvFileChain({
273
+ appDirectory: args.appDirectory,
274
+ nodeEnv: env.NODE_ENV,
275
+ env: env.ENV,
276
+ }).filter((file) => existsSync(file) && !file.endsWith('.json'));
277
+ const findings = [];
278
+ for (const file of files) {
279
+ const contents = readFileSync(file);
280
+ for (const finding of lintContents(contents)) {
281
+ findings.push({ ...finding, file });
282
+ }
283
+ if (args.fix) {
284
+ const fixed = applyFixes(contents);
285
+ if (fixed !== contents)
286
+ writeFileSync(file, fixed);
287
+ }
288
+ }
289
+ if (args.json) {
290
+ log(JSON.stringify(findings, null, 2));
291
+ }
292
+ else if (findings.length === 0) {
293
+ log(files.length === 0
294
+ ? `${TOOL_NAME}: no .env* files found under ${args.appDirectory}`
295
+ : `${TOOL_NAME}: clean — ${files.length} file(s) checked`);
296
+ }
297
+ else {
298
+ for (const finding of findings) {
299
+ log(`${finding.file}: warning: ${finding.message}`);
300
+ }
301
+ log(`${TOOL_NAME}: ${findings.length} finding(s)`);
302
+ }
303
+ return findings.length === 0 ? EXIT.CLEAN : EXIT.FINDINGS;
304
+ }
305
+ catch (err) {
306
+ // Never let a raw stack — which may quote a .env line — reach stderr.
307
+ error(`${TOOL_NAME}: ${err instanceof Error ? err.message : String(err)}`);
308
+ return EXIT.ERROR;
309
+ }
310
+ }
311
+ //# sourceMappingURL=cli-core.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli-core.js","sourceRoot":"","sources":["../src/cli-core.ts"],"names":[],"mappings":"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"}
package/dist/cli.d.ts ADDED
@@ -0,0 +1,9 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * `config-lint` CLI entrypoint. All logic lives in `cli-core.ts` behind
4
+ * injectable deps so it is unit-testable; this file only slices argv, invokes
5
+ * `main`, and maps the returned code to the process exit code. Mirrors
6
+ * `packages/env-doctor/src/cli.ts`.
7
+ */
8
+ export {};
9
+ //# sourceMappingURL=cli.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}
package/dist/cli.js ADDED
@@ -0,0 +1,17 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * `config-lint` CLI entrypoint. All logic lives in `cli-core.ts` behind
4
+ * injectable deps so it is unit-testable; this file only slices argv, invokes
5
+ * `main`, and maps the returned code to the process exit code. Mirrors
6
+ * `packages/env-doctor/src/cli.ts`.
7
+ */
8
+ import { main } from './cli-core.js';
9
+ main(process.argv.slice(2)).then((code) => {
10
+ process.exitCode = code;
11
+ }, (err) => {
12
+ // main() is designed not to reject, but guard anyway — never leak a stack
13
+ // that might quote a .env line to stderr.
14
+ console.error(err instanceof Error ? err.message : String(err));
15
+ process.exitCode = 1;
16
+ });
17
+ //# sourceMappingURL=cli.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAEpC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC9B,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAA;AACzB,CAAC,EACD,CAAC,GAAG,EAAE,EAAE;IACN,0EAA0E;IAC1E,0CAA0C;IAC1C,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;IAC/D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAA;AACtB,CAAC,CACF,CAAA"}
@@ -1,3 +1,16 @@
1
+ /**
2
+ * A single `.env` hygiene finding.
3
+ *
4
+ * Returned by the value checkers instead of a `console.log` side effect so the
5
+ * caller (`envs()` or the `config-lint` bin) is the sole place that formats,
6
+ * prints, or serializes findings. `message` never contains an unmasked value —
7
+ * see {@link maskLast4}.
8
+ */
9
+ export interface Finding {
10
+ key: string;
11
+ rule: string;
12
+ message: string;
13
+ }
1
14
  /**
2
15
  * Checks if a given key has incorrect delimiters. Delimiters should occur
3
16
  * between characters, not as the initial character. This function removes
@@ -24,13 +37,26 @@ export declare const leadingCharacterChecker: (key: string) => true | undefined;
24
37
  */
25
38
  export declare const lowercaseKeyChecker: (key: string) => true | undefined;
26
39
  /**
27
- * Checks if a value contains quote characters (`'` or `"`), but skips if the
28
- * value is multiline, contains whitespaces, newline characters, or hash signs.
40
+ * Checks whether a value carries quote characters it does not need — the
41
+ * copy-paste-a-shell-quoted-secret-verbatim mistake this package exists to catch
42
+ * at its source.
29
43
  *
30
- * @param line - The value to be checked for quote characters.
31
- * @returns True if quote characters are found in the value, undefined otherwise.
44
+ * Skips values whose quoting is load-bearing or whose semantics we cannot judge
45
+ * from the raw text: multiline values, values containing whitespace (where the
46
+ * quotes are what keep the value one token), `${VAR}` expansions, and values
47
+ * containing a `#`.
48
+ *
49
+ * `rawValue` must be the **raw pre-parse** value as captured from the `.env`
50
+ * source — wrapping quotes intact — not the post-`dotenv.parse` value, which has
51
+ * already had its wrapping quotes stripped and so can never exhibit the defect
52
+ * this checker looks for. See `dotenv-correlation.ts` for the contract.
53
+ *
54
+ * @param key - The key the value belongs to.
55
+ * @param rawValue - The raw captured value, quotes intact. `''` for `KEY=`.
56
+ * @returns A {@link Finding} when unnecessary quote characters are found,
57
+ * undefined otherwise.
32
58
  */
33
- export declare const quoteCharacterChecker: (line: string) => true | undefined;
59
+ export declare const quoteCharacterChecker: (key: string, rawValue: string) => Finding | undefined;
34
60
  /**
35
61
  * Checks if a line has trailing whitespace characters (spaces or tabs).
36
62
  *
@@ -39,15 +65,39 @@ export declare const quoteCharacterChecker: (line: string) => true | undefined;
39
65
  */
40
66
  export declare const trailingWhitespaceChecker: (line: string) => true | undefined;
41
67
  /**
42
- * Checks if a value contains whitespaces and doesn't contain quote characters
43
- * (`'` / `"`).
68
+ * Checks whether a value contains whitespace but is not wrapped in quotes, which
69
+ * makes it fragile across shells and dotenv reimplementations.
70
+ *
71
+ * Like {@link quoteCharacterChecker} this must be fed the raw pre-parse value,
72
+ * quotes intact: `dotenv.parse` strips wrapping quotes, so a correctly quoted
73
+ * multi-word value would look unquoted (and false-positive) after parsing.
44
74
  *
45
- * @param line - The value to be checked for whitespaces and lack of quotes.
46
- * @returns True if the value has whitespaces without quotes, undefined otherwise.
75
+ * @param key - The key the value belongs to.
76
+ * @param rawValue - The raw captured value, quotes intact. `''` for `KEY=`.
77
+ * @returns A {@link Finding} when the value has whitespace without wrapping
78
+ * quotes, undefined otherwise.
47
79
  */
48
- export declare const valueWithoutQuotesChecker: (line: string) => true | undefined;
80
+ export declare const valueWithoutQuotesChecker: (key: string, rawValue: string) => Finding | undefined;
49
81
  /**
50
82
  * An array of functions for checking various aspects of .env file entries.
83
+ *
84
+ * @deprecated Use dotenvKeyCheckers / dotenvLineCheckers instead. Will be
85
+ * removed in a future 1.0.0. The two groupings distinguish checkers that take a
86
+ * key from checkers that take a raw value, which this flat array cannot express.
87
+ */
88
+ export declare const dotenvCheckers: (((key: string, line: string) => true | undefined) | ((key: string, rawValue: string) => Finding | undefined))[];
89
+ /**
90
+ * Checkers that take a `.env` **key**. Mirrors `dotenvKeyFixers`.
91
+ */
92
+ export declare const dotenvKeyCheckers: ((key: string, line: string) => true | undefined)[];
93
+ /**
94
+ * Checkers that take a `.env` **value**. Mirrors `dotenvLineFixers`.
95
+ *
96
+ * ⚠️ `trailingWhitespaceChecker` is a known, tracked exception: it was NOT
97
+ * fixed in the pass that corrected the other two, so it still binds its single
98
+ * parameter to whatever the caller passes first and its output should not be
99
+ * trusted. Its membership here reflects the family it belongs to, not a claim
100
+ * that it works. See the README's "Known limitations".
51
101
  */
52
- export declare const dotenvCheckers: ((key: string, line: string) => true | undefined)[];
102
+ export declare const dotenvLineCheckers: (((key: string, rawValue: string) => Finding | undefined) | ((line: string) => true | undefined))[];
53
103
  //# sourceMappingURL=dotenv-checkers.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"dotenv-checkers.d.ts","sourceRoot":"","sources":["../src/dotenv-checkers.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,qBAUlE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAAI,KAAK,MAAM,qBASlD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,qBAO9C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM,MAAM,qBAcjD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,MAAM,MAAM,qBAKrD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,MAAM,MAAM,qBASrD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,SAtGoB,MAAM,QAAQ,MAAM,wBA6GlE,CAAA"}
1
+ {"version":3,"file":"dotenv-checkers.d.ts","sourceRoot":"","sources":["../src/dotenv-checkers.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,qBAUlE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAAI,KAAK,MAAM,qBASlD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,qBAO9C,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,qBAAqB,GAChC,KAAK,MAAM,EACX,UAAU,MAAM,KACf,OAAO,GAAG,SAwBZ,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,MAAM,MAAM,qBAKrD,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,GACpC,KAAK,MAAM,EACX,UAAU,MAAM,KACf,OAAO,GAAG,SAiBZ,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,UArJoB,MAAM,QAAQ,MAAM,gCAkE5D,MAAM,YACD,MAAM,KACf,OAAO,GAAG,SAAS,IAwFrB,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,SAjKiB,MAAM,QAAQ,MAAM,wBAqKlE,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,UA9GxB,MAAM,YACD,MAAM,KACf,OAAO,GAAG,SAAS,YAgC0B,MAAM,yBAgFrD,CAAA"}
@@ -1,3 +1,4 @@
1
+ import { maskLast4 } from './redact.js';
1
2
  import { removeInvalidLeadingChars } from './utils.js';
2
3
  /**
3
4
  * Checks if a given key has incorrect delimiters. Delimiters should occur
@@ -47,22 +48,43 @@ export const lowercaseKeyChecker = (key) => {
47
48
  return true;
48
49
  };
49
50
  /**
50
- * Checks if a value contains quote characters (`'` or `"`), but skips if the
51
- * value is multiline, contains whitespaces, newline characters, or hash signs.
51
+ * Checks whether a value carries quote characters it does not need — the
52
+ * copy-paste-a-shell-quoted-secret-verbatim mistake this package exists to catch
53
+ * at its source.
52
54
  *
53
- * @param line - The value to be checked for quote characters.
54
- * @returns True if quote characters are found in the value, undefined otherwise.
55
+ * Skips values whose quoting is load-bearing or whose semantics we cannot judge
56
+ * from the raw text: multiline values, values containing whitespace (where the
57
+ * quotes are what keep the value one token), `${VAR}` expansions, and values
58
+ * containing a `#`.
59
+ *
60
+ * `rawValue` must be the **raw pre-parse** value as captured from the `.env`
61
+ * source — wrapping quotes intact — not the post-`dotenv.parse` value, which has
62
+ * already had its wrapping quotes stripped and so can never exhibit the defect
63
+ * this checker looks for. See `dotenv-correlation.ts` for the contract.
64
+ *
65
+ * @param key - The key the value belongs to.
66
+ * @param rawValue - The raw captured value, quotes intact. `''` for `KEY=`.
67
+ * @returns A {@link Finding} when unnecessary quote characters are found,
68
+ * undefined otherwise.
55
69
  */
56
- export const quoteCharacterChecker = (line) => {
57
- if (line.includes('\n') ||
58
- /[ \t\r\n\f]/.test(line) ||
59
- line.includes('$') ||
60
- line.includes('#')) {
70
+ export const quoteCharacterChecker = (key, rawValue) => {
71
+ if (rawValue.includes('\n') ||
72
+ /[ \t\r\n\f]/.test(rawValue) ||
73
+ rawValue.includes('$') ||
74
+ rawValue.includes('#')) {
61
75
  return;
62
76
  }
63
- if (line.includes('"') || line.includes("'")) {
64
- console.log(`warning: '${line}' contains quote characters.`);
65
- return true;
77
+ // Backtick is a third wrapping quote character dotenv supports
78
+ // (`node_modules/.pnpm/dotenv@16.6.1/node_modules/dotenv/lib/main.js:8`), so a
79
+ // backtick-wrapped secret is the same defect as a `'`- or `"`-wrapped one.
80
+ if (rawValue.includes('"') ||
81
+ rawValue.includes("'") ||
82
+ rawValue.includes('`')) {
83
+ return {
84
+ key,
85
+ rule: 'quote-character',
86
+ message: `'${key}' value ${maskLast4(rawValue)} contains quote characters.`,
87
+ };
66
88
  }
67
89
  };
68
90
  /**
@@ -78,22 +100,40 @@ export const trailingWhitespaceChecker = (line) => {
78
100
  }
79
101
  };
80
102
  /**
81
- * Checks if a value contains whitespaces and doesn't contain quote characters
82
- * (`'` / `"`).
103
+ * Checks whether a value contains whitespace but is not wrapped in quotes, which
104
+ * makes it fragile across shells and dotenv reimplementations.
83
105
  *
84
- * @param line - The value to be checked for whitespaces and lack of quotes.
85
- * @returns True if the value has whitespaces without quotes, undefined otherwise.
106
+ * Like {@link quoteCharacterChecker} this must be fed the raw pre-parse value,
107
+ * quotes intact: `dotenv.parse` strips wrapping quotes, so a correctly quoted
108
+ * multi-word value would look unquoted (and false-positive) after parsing.
109
+ *
110
+ * @param key - The key the value belongs to.
111
+ * @param rawValue - The raw captured value, quotes intact. `''` for `KEY=`.
112
+ * @returns A {@link Finding} when the value has whitespace without wrapping
113
+ * quotes, undefined otherwise.
86
114
  */
87
- export const valueWithoutQuotesChecker = (line) => {
88
- line = line.trim();
89
- if (/[ \t\r\n\f]/.test(line) &&
90
- !(line.startsWith("'") && line.endsWith("'")) &&
91
- !(line.startsWith('"') && line.endsWith('"'))) {
92
- return true;
115
+ export const valueWithoutQuotesChecker = (key, rawValue) => {
116
+ const value = rawValue.trim();
117
+ if (/[ \t\r\n\f]/.test(value) &&
118
+ !(value.startsWith("'") && value.endsWith("'")) &&
119
+ !(value.startsWith('"') && value.endsWith('"')) &&
120
+ // Backtick is a valid dotenv wrapping quote; without this a
121
+ // `TOK=\`multi word\`` line false-positives, and `valueWithoutQuotesFixer`
122
+ // would then re-wrap an already-quoted value.
123
+ !(value.startsWith('`') && value.endsWith('`'))) {
124
+ return {
125
+ key,
126
+ rule: 'value-without-quotes',
127
+ message: `'${key}' value ${maskLast4(value)} contains whitespace but is not quoted.`,
128
+ };
93
129
  }
94
130
  };
95
131
  /**
96
132
  * An array of functions for checking various aspects of .env file entries.
133
+ *
134
+ * @deprecated Use dotenvKeyCheckers / dotenvLineCheckers instead. Will be
135
+ * removed in a future 1.0.0. The two groupings distinguish checkers that take a
136
+ * key from checkers that take a raw value, which this flat array cannot express.
97
137
  */
98
138
  export const dotenvCheckers = [
99
139
  incorrectDelimiterChecker,
@@ -103,4 +143,26 @@ export const dotenvCheckers = [
103
143
  trailingWhitespaceChecker,
104
144
  valueWithoutQuotesChecker,
105
145
  ];
146
+ /**
147
+ * Checkers that take a `.env` **key**. Mirrors `dotenvKeyFixers`.
148
+ */
149
+ export const dotenvKeyCheckers = [
150
+ incorrectDelimiterChecker,
151
+ leadingCharacterChecker,
152
+ lowercaseKeyChecker,
153
+ ];
154
+ /**
155
+ * Checkers that take a `.env` **value**. Mirrors `dotenvLineFixers`.
156
+ *
157
+ * ⚠️ `trailingWhitespaceChecker` is a known, tracked exception: it was NOT
158
+ * fixed in the pass that corrected the other two, so it still binds its single
159
+ * parameter to whatever the caller passes first and its output should not be
160
+ * trusted. Its membership here reflects the family it belongs to, not a claim
161
+ * that it works. See the README's "Known limitations".
162
+ */
163
+ export const dotenvLineCheckers = [
164
+ quoteCharacterChecker,
165
+ trailingWhitespaceChecker,
166
+ valueWithoutQuotesChecker,
167
+ ];
106
168
  //# sourceMappingURL=dotenv-checkers.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"dotenv-checkers.js","sourceRoot":"","sources":["../src/dotenv-checkers.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"dotenv-checkers.js","sourceRoot":"","sources":["../src/dotenv-checkers.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Correlates each key in a raw `.env` file's contents back to the value **as it
3
+ * literally appears in the file**, wrapping quotes intact.
4
+ *
5
+ * Why this module exists: `dotenv.parse` strips wrapping quotes at parse time
6
+ * (`dotenv-with-expand.ts:70`), so a checker fed a parsed value structurally
7
+ * cannot observe the quote-wrapping defect it exists to detect. The checkers
8
+ * need the pre-parse substring, and `dotenv` exports no line splitter to get it
9
+ * (its parser is a single module-private regex).
10
+ *
11
+ * Internal module — deliberately NOT re-exported from `index.ts`.
12
+ */
13
+ /**
14
+ * Map every key in `contents` to its raw pre-parse value.
15
+ *
16
+ * Duplicate keys resolve **last-match-wins**, matching `dotenv.parse`'s own
17
+ * behavior (verified: parsing `DUP=first\nDUP=second` returns `{DUP:'second'}`).
18
+ *
19
+ * @param contents - The raw text of a `.env` file.
20
+ * @returns Key → raw value, quotes intact. See {@link normalizeRawValue}.
21
+ */
22
+ export declare const correlateRawValues: (contents: string) => Map<string, string>;
23
+ //# sourceMappingURL=dotenv-correlation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dotenv-correlation.d.ts","sourceRoot":"","sources":["../src/dotenv-correlation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0DH;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAoBvE,CAAA"}