@kindgi/dotenv-file 0.0.0-stage → 0.1.0

package/src/expand.ts

@@ -0,0 +1,185 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `${VAR}` expansion over parsed dotenv values.
+ *
+ * Host frameworks expand with `dotenv-expand`, but not one version:
+ * Next.js 16 bundles v10's algorithm, Vite uses v12, and the two differ
+ * (v10 resolves references to keys defined later in the file, v12
+ * does not). This module implements one well-defined semantics that
+ * agrees with BOTH on everything they agree on — verified by
+ * `tests/conformance.test.ts` — and picks Next.js's (order-independent)
+ * answer where they differ.
+ *
+ * Syntax:
+ *   - `$NAME` (`[A-Za-z_][A-Za-z0-9_]*`) and `${NAME}`
+ *   - `${NAME:-default}` — default when NAME is unset or empty
+ *   - `${NAME-default}`  — default when NAME is unset
+ *   - `${NAME:+alt}`     — alt when NAME is set and non-empty, else empty
+ *   - `${NAME+alt}`      — alt when NAME is set, else empty
+ *   - `\$` — a literal `$` (the writer escapes every `$` this way)
+ *   Defaults / alts are themselves expanded. A `$` not followed by a
+ *   name or `{…}` is literal.
+ *
+ * Lookup: a name defined in the files resolves to its (expanded) file
+ * value, wherever in the files it is defined. Only a name defined in no
+ * file falls back to `options.env` (so `${HOME}` works). Unlike
+ * `dotenv-expand`, the caller's env never overrides a file's own value:
+ * the files are the source, the environment only fills gaps. Nothing
+ * reads `process.env` implicitly — callers pass what they mean.
+ *
+ * Undefined references expand to `''` and cycles (`A=$B`, `B=$A`) are
+ * cut at the repeated name; both are reported in `diagnostics`.
+ */
+
+export interface ExpandOptions {
+  /** Fallback for names no file defines. Never overrides a file value. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+}
+
+export interface ExpandDiagnostic {
+  readonly kind: 'unresolved' | 'cycle';
+  /** The key whose value contains the reference. */
+  readonly key: string;
+  /** The referenced name. */
+  readonly ref: string;
+}
+
+export interface ExpandResult {
+  readonly values: Record<string, string>;
+  readonly diagnostics: readonly ExpandDiagnostic[];
+}
+
+const NAME_START = /[A-Za-z_]/;
+const NAME_CHAR = /[A-Za-z0-9_]/;
+const OPERATORS = [':-', ':+', '-', '+'] as const;
+type Operator = (typeof OPERATORS)[number];
+
+export function expandEnv(
+  values: Readonly<Record<string, string>>,
+  options: ExpandOptions = {},
+): ExpandResult {
+  const env = options.env ?? {};
+  const resolved = new Map<string, string>();
+  const stack: string[] = [];
+  const diagnostics: ExpandDiagnostic[] = [];
+  const has = (name: string): boolean => Object.prototype.hasOwnProperty.call(values, name);
+
+  function lookup(name: string, fromKey: string): string | undefined {
+    if (has(name)) {
+      if (stack.includes(name)) {
+        diagnostics.push({ kind: 'cycle', key: fromKey, ref: name });
+        return undefined;
+      }
+      return resolve(name);
+    }
+    const fromEnv = env[name];
+    return typeof fromEnv === 'string' ? fromEnv : undefined;
+  }
+
+  function resolve(key: string): string {
+    const cached = resolved.get(key);
+    if (cached !== undefined) return cached;
+    stack.push(key);
+    const out = expandString(values[key] ?? '', key);
+    stack.pop();
+    resolved.set(key, out);
+    return out;
+  }
+
+  function evaluate(expression: string, key: string): string {
+    const { name, op, operand } = splitExpression(expression);
+    const value = lookup(name, key);
+    if (op !== undefined) return APPLY[op](value, () => expandString(operand, key));
+    if (value !== undefined) return value;
+    if (!diagnostics.some((d) => d.key === key && d.ref === name)) {
+      diagnostics.push({ kind: 'unresolved', key, ref: name });
+    }
+    return '';
+  }
+
+  function expandString(input: string, key: string): string {
+    let out = '';
+    let i = 0;
+    while (i < input.length) {
+      const token = readToken(input, i);
+      if (token === undefined) {
+        out += input[i];
+        i += 1;
+        continue;
+      }
+      out += token.kind === 'escape' ? '$' : evaluate(token.expression, key);
+      i = token.end;
+    }
+    return out;
+  }
+
+  const out: Record<string, string> = {};
+  for (const key of Object.keys(values)) out[key] = resolve(key);
+  return { values: out, diagnostics };
+}
+
+/** Operator semantics (bash): `:` also treats an empty value as unset. */
+const APPLY: Readonly<
+  Record<Operator, (value: string | undefined, operand: () => string) => string>
+> = {
+  ':-': (value, operand) => (value === undefined || value === '' ? operand() : value),
+  '-': (value, operand) => (value === undefined ? operand() : value),
+  ':+': (value, operand) => (value !== undefined && value !== '' ? operand() : ''),
+  '+': (value, operand) => (value !== undefined ? operand() : ''),
+};
+
+type Token =
+  | { readonly kind: 'escape'; readonly end: number }
+  | { readonly kind: 'ref'; readonly expression: string; readonly end: number };
+
+/** The escape or reference starting at `i`, if any. */
+function readToken(input: string, i: number): Token | undefined {
+  if (input[i] === '\\' && input[i + 1] === '$') return { kind: 'escape', end: i + 2 };
+  if (input[i] !== '$') return undefined;
+  const next = input[i + 1];
+  if (next === '{') {
+    const close = findBraceClose(input, i + 2);
+    return close === -1
+      ? undefined
+      : { kind: 'ref', expression: input.slice(i + 2, close), end: close + 1 };
+  }
+  if (next === undefined || !NAME_START.test(next)) return undefined;
+  let end = i + 2;
+  while (end < input.length && NAME_CHAR.test(input[end] ?? '')) end += 1;
+  return { kind: 'ref', expression: input.slice(i + 1, end), end };
+}
+
+/**
+ * Index of the `}` closing a `${…}` whose body starts at `from`, or -1
+ * when it is not an expression (empty body, unterminated, or a bare `{`
+ * inside). A nested `${…}` — e.g. in a default — nests; `\$` is skipped.
+ */
+function findBraceClose(input: string, from: number): number {
+  const tokens = /\\\$|\$\{|[{}]/g;
+  tokens.lastIndex = from;
+  let depth = 1;
+  for (let m = tokens.exec(input); m !== null; m = tokens.exec(input)) {
+    if (m[0] === '{') return -1;
+    if (m[0] === '${') depth += 1;
+    else if (m[0] === '}') depth -= 1;
+    if (depth === 0) return m.index === from ? -1 : m.index;
+  }
+  return -1;
+}
+
+function splitExpression(expression: string): {
+  readonly name: string;
+  readonly op: Operator | undefined;
+  readonly operand: string;
+} {
+  for (let i = 1; i < expression.length; i += 1) {
+    for (const op of OPERATORS) {
+      if (expression.startsWith(op, i)) {
+        return { name: expression.slice(0, i), op, operand: expression.slice(i + op.length) };
+      }
+    }
+  }
+  return { name: expression, op: undefined, operand: '' };
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/dotenv-file` — dotenv files the way applications read them,
+ * written the way people edit them.
+ *
+ *   - **Read** (`parse.ts`): `dotenv`'s grammar (verified against the
+ *     version Next.js bundles), returned as structured lines so edits
+ *     round-trip losslessly.
+ *   - **Expand** (`expand.ts`): `${VAR}` / `${VAR:-default}` / `\$`,
+ *     agreeing with `dotenv-expand` wherever its versions agree.
+ *   - **Layer** (`layers.ts`): several files (`.env` < `.env.local`) as
+ *     one view, with per-key origin.
+ *   - **Write** (`serialize.ts`): `setKey` / `unsetKey` touch one key and
+ *     keep every other byte; values are quoted so they read back
+ *     exactly.
+ *
+ * Zero runtime dependencies and no filesystem access — callers read and
+ * write the files. See `README.md`.
+ */
+
+export {
+  type ExpandDiagnostic,
+  type ExpandOptions,
+  type ExpandResult,
+  expandEnv,
+} from './expand.js';
+export {
+  type EnvDiagnostic,
+  type EnvLayer,
+  type LayeredEnv,
+  readEnv,
+  readEnvLayers,
+} from './layers.js';
+export {
+  DOTENV_KEY_REGEX,
+  ENV_KEY_REGEX,
+  type EnvLine,
+  envLinesToRecord,
+  parseEntryRaw,
+  parseEnvFile,
+} from './parse.js';
+export {
+  EnvValueNotRepresentableError,
+  renderEntry,
+  serializeEnvFile,
+  setKey,
+  unsetKey,
+} from './serialize.js';

package/src/layers.ts

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Layered env files — several dotenv files read as one view, the way
+ * an application reads `.env` + `.env.local`.
+ *
+ * Layers are ordered LOWEST precedence first: a key in a later layer
+ * overrides the same key in an earlier one. Raw values are merged
+ * first, then expanded once over the merged view, so a reference in
+ * `.env` to a name defined in `.env.local` sees the `.env.local` value
+ * (matching how Next.js loads its files). Pure — the caller reads the
+ * files and passes their contents (`null` for a file that doesn't
+ * exist), so this module never touches the filesystem.
+ */
+
+import { type ExpandDiagnostic, type ExpandOptions, expandEnv } from './expand.js';
+import { parseEnvFile } from './parse.js';
+
+export interface EnvLayer {
+  /** Where the contents came from (a path, usually). Reported back in `origin`. */
+  readonly source: string;
+  /** File contents, or `null` when the file does not exist. */
+  readonly contents: string | null;
+}
+
+export type EnvDiagnostic =
+  | (ExpandDiagnostic & { readonly source: string })
+  | {
+      readonly kind: 'malformed';
+      readonly source: string;
+      /** 1-based line number in `source`. */
+      readonly line: number;
+      /** The line's text. May hold a secret — show `source:line` to users, not this. */
+      readonly raw: string;
+      readonly reason: string;
+    };
+
+export interface LayeredEnv {
+  /** Merged, expanded values. */
+  readonly values: Readonly<Record<string, string>>;
+  /** Merged values as written (before expansion). */
+  readonly raw: Readonly<Record<string, string>>;
+  /** For each key, the `source` of the layer that supplied it. */
+  readonly origin: Readonly<Record<string, string>>;
+  /** Sources that exist (non-`null` contents), in layer order. */
+  readonly present: readonly string[];
+  /** Malformed lines (ignored, as dotenv does), unresolved references, cycles. */
+  readonly diagnostics: readonly EnvDiagnostic[];
+}
+
+export function readEnvLayers(
+  layers: readonly EnvLayer[],
+  options: ExpandOptions = {},
+): LayeredEnv {
+  const raw: Record<string, string> = {};
+  const origin: Record<string, string> = {};
+  const present: string[] = [];
+  const diagnostics: EnvDiagnostic[] = [];
+
+  for (const layer of layers) {
+    if (layer.contents === null) continue;
+    present.push(layer.source);
+    let lineNo = 1;
+    for (const line of parseEnvFile(layer.contents)) {
+      if (line.kind === 'entry' && line.key !== undefined && line.value !== undefined) {
+        raw[line.key] = line.value;
+        origin[line.key] = layer.source;
+      } else if (line.kind === 'malformed') {
+        diagnostics.push({
+          kind: 'malformed',
+          source: layer.source,
+          line: lineNo,
+          raw: line.raw,
+          reason: line.reason ?? 'not a `KEY=value` line',
+        });
+      }
+      lineNo += line.raw.split('\n').length;
+    }
+  }
+
+  const expanded = expandEnv(raw, options);
+  for (const d of expanded.diagnostics) {
+    diagnostics.push({ ...d, source: origin[d.key] ?? '' });
+  }
+  return { values: expanded.values, raw, origin, present, diagnostics };
+}
+
+/** One file's values, parsed and expanded. */
+export function readEnv(contents: string, options: ExpandOptions = {}): Record<string, string> {
+  return { ...readEnvLayers([{ source: '', contents }], options).values };
+}

package/src/parse.ts

@@ -0,0 +1,266 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Structured, lossless dotenv parser.
+ *
+ * **Grammar = `dotenv`'s `parse()`** (verified against `dotenv@16.3.1`,
+ * the version Next.js 16 bundles, by `tests/conformance.test.ts`). An
+ * application Kindgi is embedded in reads its `.env` files with that
+ * parser; Kindgi reading the same file must see the same values.
+ *
+ *   - `KEY=value` or `KEY: value` (colon + at least one space).
+ *     Optional leading whitespace and an optional `export ` prefix.
+ *   - Keys: `[A-Za-z0-9_.-]+` (dotenv accepts lowercase, dots, dashes).
+ *   - Unquoted values end at the first `#` (inline comment) and are
+ *     trimmed.
+ *   - `'…'`, `"…"` and `` `…` `` values may span lines. The closing
+ *     quote must be followed only by whitespace or a `# comment` on its
+ *     line; otherwise the value is read unquoted. Inside double quotes
+ *     `\n` / `\r` become newline / carriage return; nothing else is
+ *     unescaped (`\"` stays `\"`, exactly as dotenv does).
+ *   - Duplicate keys: the last one wins.
+ *   - Anything else is ignored by dotenv; here it surfaces as a
+ *     `malformed` line so hand-edited files round-trip untouched.
+ *
+ * Deliberate divergence (pathological inputs only): dotenv's regex lets
+ * a key's separator or an empty value's leading whitespace run across
+ * a newline (`KEY=` followed by a line that starts with a quote joins
+ * the two). Here a key, its separator, and the start of its value are
+ * always on one line.
+ *
+ * Variable expansion (`${VAR}`) is a separate step — see `expand.ts`.
+ * `parseEnvFile` returns values exactly as written.
+ */
+
+export interface EnvLine {
+  readonly kind: 'blank' | 'comment' | 'entry' | 'malformed';
+  /**
+   * The line's source text. For an `entry` whose quoted value spans
+   * several lines, `raw` holds all of them joined with `\n`.
+   */
+  readonly raw: string;
+  readonly key?: string;
+  /** Parsed (unexpanded) value. */
+  readonly value?: string;
+  /** `true` when the entry was written with an `export ` prefix. */
+  readonly exported?: boolean;
+  readonly reason?: string;
+}
+
+/** Keys dotenv accepts when READING a file. */
+export const DOTENV_KEY_REGEX = /^[\w.-]+$/;
+
+/**
+ * Keys Kindgi WRITES: POSIX-shell env-var shape. Stricter than
+ * `DOTENV_KEY_REGEX` so every name Kindgi writes is also exportable
+ * from a shell.
+ */
+export const ENV_KEY_REGEX = /^[A-Z_][A-Z0-9_]*$/;
+
+const ENTRY_HEAD = /^\s*(export\s+)?([\w.-]+)(?:\s*=|:\s)\s*/;
+const TRAILER = /^\s*(?:#.*)?$/;
+const QUOTES = new Set(["'", '"', '`']);
+
+/**
+ * Split dotenv text into structured lines. `serializeEnvFile` of the
+ * result reproduces the input (line endings normalised to `\n`, which
+ * is also what dotenv does before parsing).
+ */
+export function parseEnvFile(raw: string): readonly EnvLine[] {
+  if (raw === '') return [];
+  const physical = raw.split(/\r\n?|\n/);
+  const lines =
+    physical.length > 0 && physical[physical.length - 1] === '' ? physical.slice(0, -1) : physical;
+  const out: EnvLine[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const { line, consumed } = parseAt(lines, i);
+    out.push(line);
+    i += consumed;
+  }
+  return out;
+}
+
+/**
+ * Parse a single entry's source text (possibly multi-line). Returns
+ * `undefined` unless the whole text is exactly one entry. Used by the
+ * serializer to decide whether an entry's `raw` is still faithful to
+ * its `key` / `value`.
+ */
+export function parseEntryRaw(raw: string): EnvLine | undefined {
+  const lines = parseEnvFile(raw);
+  if (lines.length !== 1) return undefined;
+  const [only] = lines;
+  return only?.kind === 'entry' ? only : undefined;
+}
+
+/** Flatten entries into a record (last duplicate wins). Values are unexpanded. */
+export function envLinesToRecord(lines: readonly EnvLine[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of lines) {
+    if (line.kind === 'entry' && line.key !== undefined && line.value !== undefined) {
+      out[line.key] = line.value;
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------
+
+interface ParseStep {
+  readonly line: EnvLine;
+  readonly consumed: number;
+}
+
+function parseAt(lines: readonly string[], i: number): ParseStep {
+  const first = lines[i] ?? '';
+  if (first.trim() === '') return { line: { kind: 'blank', raw: first }, consumed: 1 };
+  if (first.trimStart().startsWith('#')) {
+    return { line: { kind: 'comment', raw: first }, consumed: 1 };
+  }
+
+  const head = ENTRY_HEAD.exec(first);
+  if (head === null) {
+    return {
+      line: { kind: 'malformed', raw: first, reason: 'not a `KEY=value` line' },
+      consumed: 1,
+    };
+  }
+  const key = head[2] ?? '';
+  const exported = head[1] !== undefined;
+  const valueStart = head[0].length;
+  const opener = first[valueStart];
+
+  if (opener !== undefined && QUOTES.has(opener)) {
+    const quoted = scanQuoted(lines, i, valueStart, opener);
+    if (quoted !== undefined) {
+      const raw = lines.slice(i, i + quoted.lineCount).join('\n');
+      return {
+        line: entry(raw, key, unescapeQuoted(quoted.inner, opener), exported),
+        consumed: quoted.lineCount,
+      };
+    }
+  }
+
+  return { line: entry(first, key, unquotedValue(first.slice(valueStart)), exported), consumed: 1 };
+}
+
+function entry(raw: string, key: string, value: string, exported: boolean): EnvLine {
+  return exported
+    ? { kind: 'entry', raw, key, value, exported: true }
+    : { kind: 'entry', raw, key, value };
+}
+
+/**
+ * Unquoted value: everything up to the first `#`, trimmed. dotenv then
+ * strips one pair of matching outer quotes from the trimmed text (e.g.
+ * `KEY="a" "b"` → `a" "b`), and expands `\n` / `\r` if that pair was
+ * double quotes. Replicated exactly.
+ */
+function unquotedValue(rest: string): string {
+  const hash = rest.indexOf('#');
+  const v = (hash === -1 ? rest : rest.slice(0, hash)).trim();
+  const q = v[0];
+  if (v.length >= 2 && q !== undefined && QUOTES.has(q) && v[v.length - 1] === q) {
+    return unescapeQuoted(v.slice(1, -1), q);
+  }
+  return v;
+}
+
+function unescapeQuoted(inner: string, quote: string): string {
+  return quote === '"' ? inner.replace(/\\n/g, '\n').replace(/\\r/g, '\r') : inner;
+}
+
+interface QuotedScan {
+  readonly inner: string;
+  readonly lineCount: number;
+}
+
+interface Position {
+  readonly line: number;
+  readonly col: number;
+}
+
+/**
+ * Closing-quote candidates in the order dotenv's regex tries them: the
+ * first quote not preceded by a backslash, then each backslash-escaped
+ * quote before it, last to first.
+ */
+function closingCandidates(
+  lines: readonly string[],
+  startLine: number,
+  startCol: number,
+  quote: string,
+): Position[] {
+  const escaped: Position[] = [];
+  for (let line = startLine; line < lines.length; line += 1) {
+    const text = lines[line] ?? '';
+    const found = scanLine(text, line === startLine ? startCol + 1 : 0, quote);
+    for (const col of found.escaped) escaped.push({ line, col });
+    if (found.closing !== -1) return [{ line, col: found.closing }, ...escaped.reverse()];
+  }
+  return escaped.reverse();
+}
+
+/** One line's escaped-quote columns, and the first unescaped quote (-1 if none). */
+function scanLine(
+  text: string,
+  from: number,
+  quote: string,
+): { readonly escaped: readonly number[]; readonly closing: number } {
+  const escaped: number[] = [];
+  let col = from;
+  while (col < text.length) {
+    if (text[col] === '\\' && text[col + 1] === quote) {
+      escaped.push(col + 1);
+      col += 2;
+    } else if (text[col] === quote) {
+      return { escaped, closing: col };
+    } else {
+      col += 1;
+    }
+  }
+  return { escaped, closing: -1 };
+}
+
+/**
+ * Find the closing quote the way dotenv's `'(?:\\'|[^'])*'` alternative
+ * does (per quote character): the first quote not preceded by a
+ * backslash is tried first; then, backtracking, each backslash-escaped
+ * quote before it, last to first. A candidate is accepted when the rest
+ * of its line is whitespace or a `# comment`. `undefined` = no candidate
+ * works and the value is read unquoted.
+ */
+function scanQuoted(
+  lines: readonly string[],
+  startLine: number,
+  startCol: number,
+  quote: string,
+): QuotedScan | undefined {
+  for (const c of closingCandidates(lines, startLine, startCol, quote)) {
+    const closingLine = lines[c.line] ?? '';
+    if (!TRAILER.test(closingLine.slice(c.col + 1))) continue;
+    return {
+      inner: sliceAcross(lines, startLine, startCol + 1, c.line, c.col),
+      lineCount: c.line - startLine + 1,
+    };
+  }
+  return undefined;
+}
+
+function sliceAcross(
+  lines: readonly string[],
+  fromLine: number,
+  fromCol: number,
+  toLine: number,
+  toCol: number,
+): string {
+  if (fromLine === toLine) return (lines[fromLine] ?? '').slice(fromCol, toCol);
+  const parts = [(lines[fromLine] ?? '').slice(fromCol)];
+  for (let li = fromLine + 1; li < toLine; li += 1) parts.push(lines[li] ?? '');
+  parts.push((lines[toLine] ?? '').slice(0, toCol));
+  return parts.join('\n');
+}