christiangeorgelucas/config-tools

import { ConvertConfigRequest, ConvertConfigResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import {
  parseByFormat,
  serializeByFormat,
  flattenSections,
  ConfigNodeError,
} from './helpers';

/**
 * Converts config text from one format to another: parses `text` as
 * `from_format` into the canonical ConfigDocument, then serializes it as
 * `to_format`. Converting a sectioned INI entry into an unsectioned format
 * (env or properties) dot-joins its key as "section.key" so no information
 * is silently dropped — see the field docs on ConvertConfigRequest for the
 * exact rule and why it is not reversible. `from_format`/`to_format` must
 * each be one of "env" | "ini" | "properties"; any other value is
 * INVALID_ARGUMENT.
 */
export function convertConfig(ax: AxiomContext, input: ConvertConfigRequest): ConvertConfigResult {
  const result = new ConvertConfigResult();
  const text = input.getText();
  try {
    const fromFormat = input.getFromFormat();
    const toFormat = input.getToFormat();
    let entries = parseByFormat(text, fromFormat);
    if (toFormat !== 'ini') {
      entries = flattenSections(entries);
    }
    result.setText(serializeByFormat(entries, toFormat, input.getSortKeys()));
  } catch (err) {
    if (err instanceof ConfigNodeError) {
      result.setError(err.proto);
      return result;
    }
    throw err;
  }
  return result;
}

import { DeleteConfigValueRequest, DeleteConfigValueResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { docToEntries, entriesToDoc, deleteConfigValue as deleteConfigValueImpl } from './helpers';

/**
 * Returns a new ConfigDocument with every entry matching (section, key)
 * removed (there is normally at most one; any duplicate is also removed),
 * and whether an entry was actually removed. Returns the document unchanged
 * (found=false) if no such entry existed.
 */
export function deleteConfigValue(ax: AxiomContext, input: DeleteConfigValueRequest): DeleteConfigValueResult {
  const result = new DeleteConfigValueResult();
  const entries = docToEntries(input.getDocument());
  const { entries: updated, found } = deleteConfigValueImpl(entries, input.getKey(), input.getSection());
  result.setDocument(entriesToDoc(updated));
  result.setFound(found);
  return result;
}

import { DetectFormatInput, DetectFormatResult, ConfigFormatScore } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { detectFormat as detectFormatImpl } from './helpers';

/**
 * Classifies text as "env" | "ini" | "properties" | "unknown" from
 * structural signals: a "[section]" header line is a strong, ini-unique
 * signal; a leading "export KEY=" line is a strong, env-unique signal; a
 * "!" comment line or a trailing unescaped line-continuation backslash is a
 * strong, properties-unique signal. All three formats otherwise accept
 * plain "key=value" lines, which is the weakest signal and does not
 * strongly favor any one format. Ties are broken ini > properties > env
 * (most-to-least structurally distinctive). Returns format="unknown" with
 * confidence 0 when no line has a section header, an export/quoted-value
 * prefix, a "!"/"#"/";" comment marker, a continuation backslash, or a
 * "="/":" separator. NOTE: java.util.Properties' bare whitespace-only
 * "key value" separator (no "=", ":", or other marker) is NOT scored as a
 * signal here — it's indistinguishable from ordinary prose by shape alone
 * — even though ParseProperties does accept it; see helpers.ts detectFormat.
 */
export function detectFormat(ax: AxiomContext, input: DetectFormatInput): DetectFormatResult {
  const result = new DetectFormatResult();
  const text = input.getText();
  const { format, confidence, candidates } = detectFormatImpl(text);
  result.setFormat(format);
  result.setConfidence(confidence);
  result.setCandidatesList(
    candidates.map((c) => {
      const s = new ConfigFormatScore();
      s.setFormat(c.format);
      s.setConfidence(c.confidence);
      return s;
    })
  );
  return result;
}

import { ExpandEnvVarsRequest, ExpandEnvVarsResult, UnresolvedRef } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { docToEntries, entriesToDoc, expandEnvVars as expandEnvVarsImpl, ConfigNodeError } from './helpers';

/**
 * Expands "${VAR}" references inside a ConfigDocument's own values,
 * resolving each VAR against the SAME document's entries (by key) — never
 * the host process's real environment. Expansion is recursive (a resolved
 * value may itself contain further "${VAR}" references) up to a depth of
 * 50, and a reference cycle (A -> B -> A) is rejected with CYCLE_DETECTED
 * instead of looping. A "${VAR}" with no matching key expands to "" and is
 * also listed in `unresolved` so the caller can distinguish "empty on
 * purpose" from "undefined reference."
 */
export function expandEnvVars(ax: AxiomContext, input: ExpandEnvVarsRequest): ExpandEnvVarsResult {
  const result = new ExpandEnvVarsResult();
  const entries = docToEntries(input.getDocument());
  try {
    const { entries: expanded, unresolved } = expandEnvVarsImpl(entries);
    result.setDocument(entriesToDoc(expanded));
    result.setUnresolvedList(
      unresolved.map((u) => {
        const ref = new UnresolvedRef();
        ref.setEntryKey(u.entryKey);
        ref.setVarName(u.varName);
        return ref;
      })
    );
  } catch (err) {
    if (err instanceof ConfigNodeError) {
      result.setError(err.proto);
      return result;
    }
    throw err;
  }
  return result;
}

import { GetConfigValueRequest, GetConfigValueResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { docToEntries, getConfigValue as getConfigValueImpl } from './helpers';

/**
 * Looks up a single (section, key) entry's value in a ConfigDocument. When
 * the same (section, key) appears more than once, the LAST entry wins
 * (matching .env/.properties/INI's own duplicate-key semantics). `found` is
 * false, and `value` is "", when no such entry exists.
 */
export function getConfigValue(ax: AxiomContext, input: GetConfigValueRequest): GetConfigValueResult {
  const result = new GetConfigValueResult();
  const entries = docToEntries(input.getDocument());
  const { value, found } = getConfigValueImpl(entries, input.getKey(), input.getSection());
  result.setValue(value);
  result.setFound(found);
  return result;
}

import { MergeConfigRequest, MergeConfigResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { docToEntries, entriesToDoc, mergeConfig as mergeConfigImpl } from './helpers';

/**
 * Merges two ConfigDocuments: `base`'s entries in `base`'s order, with any
 * (section, key) also present in `overlay` overridden by overlay's value
 * (overlay's own last occurrence wins if it has internal duplicates); any
 * (section, key) present only in `overlay` is appended, in overlay's order,
 * after all of `base`'s entries.
 */
export function mergeConfig(ax: AxiomContext, input: MergeConfigRequest): MergeConfigResult {
  const result = new MergeConfigResult();
  const base = docToEntries(input.getBase());
  const overlay = docToEntries(input.getOverlay());
  result.setDocument(entriesToDoc(mergeConfigImpl(base, overlay)));
  return result;
}

import { ParseEnvRequest, ParseEnvResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { entriesToDoc, parseEnvText } from './helpers';

/**
 * Parses .env (dotenv) text into a ConfigDocument. Wraps the `dotenv`
 * library's own parser directly: KEY=value lines, an optional leading
 * "export ", single/double/backtick-quoted values, "\n"/"\r" escapes inside
 * double-quoted values, and multi-line double-quoted values. dotenv is
 * deliberately permissive — a line it cannot parse as a key/value pair is
 * silently skipped rather than rejected, so this node never rejects input.
 */
export function parseEnv(ax: AxiomContext, input: ParseEnvRequest): ParseEnvResult {
  const result = new ParseEnvResult();
  const text = input.getText();
  const entries = parseEnvText(text);
  result.setDocument(entriesToDoc(entries));
  return result;
}

import { ParseIniRequest, ParseIniResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { entriesToDoc, parseIniText, ConfigNodeError } from './helpers';

/**
 * Parses INI text into a ConfigDocument, via the `ini` library. "[section]"
 * headers open a section; keys before any header get section "". Both ";"
 * and "#" start a comment line. A "key[]=value" repeated-key line becomes
 * multiple ConfigEntry rows with the same key. A section header nested more
 * than one level deep (e.g. "[a.b]") is rejected with INVALID_INPUT —
 * ConfigEntry supports exactly one section level.
 */
export function parseIni(ax: AxiomContext, input: ParseIniRequest): ParseIniResult {
  const result = new ParseIniResult();
  const text = input.getText();
  try {
    const entries = parseIniText(text);
    result.setDocument(entriesToDoc(entries));
  } catch (err) {
    if (err instanceof ConfigNodeError) {
      result.setError(err.proto);
      return result;
    }
    throw err;
  }
  return result;
}

import { ParsePropertiesRequest, ParsePropertiesResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { entriesToDoc, parsePropertiesText } from './helpers';

/**
 * Parses Java .properties text into a ConfigDocument, via the `dot-properties`
 * library, which implements java.util.Properties#load's rules directly: "#"
 * or "!" comment lines, "key=value" / "key:value" / "key value" separator
 * forms, a trailing unescaped "\" continuing a logical line onto the next
 * physical line, and "\uXXXX" unicode escapes in keys and values. Like
 * java.util.Properties itself, this format has no rejecting grammar — any
 * text produces SOME set of key/value pairs, so this node never rejects
 * input.
 */
export function parseProperties(ax: AxiomContext, input: ParsePropertiesRequest): ParsePropertiesResult {
  const result = new ParsePropertiesResult();
  const text = input.getText();
  const entries = parsePropertiesText(text);
  result.setDocument(entriesToDoc(entries));
  return result;
}

import { SerializeEnvRequest, SerializeEnvResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { docToEntries, serializeEnvText, ConfigNodeError } from './helpers';

/**
 * Serializes a ConfigDocument to .env text — one "KEY=value" line per
 * entry. A value is emitted bare when it needs no escaping, otherwise
 * quoted (preferring single, then double, then backtick quotes, whichever
 * the value doesn't itself contain) so the result re-parses via ParseEnv to
 * the same value. A key that isn't a valid .env variable name (letters,
 * digits, "_", ".", "-", not starting with a digit/./-) is rejected with
 * INVALID_ARGUMENT rather than emitted as text that wouldn't parse back.
 */
export function serializeEnv(ax: AxiomContext, input: SerializeEnvRequest): SerializeEnvResult {
  const result = new SerializeEnvResult();
  const entries = docToEntries(input.getDocument());
  try {
    result.setText(serializeEnvText(entries, input.getSortKeys()));
  } catch (err) {
    if (err instanceof ConfigNodeError) {
      result.setError(err.proto);
      return result;
    }
    throw err;
  }
  return result;
}

import { SerializeIniRequest, SerializeIniResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { docToEntries, serializeIniText } from './helpers';

/**
 * Serializes a ConfigDocument to INI text via the `ini` library:
 * section-"" entries first with no header, then each named section as a
 * "[section]" block.
 */
export function serializeIni(ax: AxiomContext, input: SerializeIniRequest): SerializeIniResult {
  const result = new SerializeIniResult();
  const entries = docToEntries(input.getDocument());
  result.setText(serializeIniText(entries, input.getSortKeys()));
  return result;
}

import { SerializePropertiesRequest, SerializePropertiesResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { docToEntries, serializePropertiesText } from './helpers';

/**
 * Serializes a ConfigDocument to Java .properties text via `dot-properties`:
 * one "key = value" line per entry (no line folding), with keys/values
 * escaped per java.util.Properties#store (control characters, "=", ":",
 * leading whitespace in keys, and — by default — any non-Latin-1 character
 * as "\uXXXX").
 */
export function serializeProperties(ax: AxiomContext, input: SerializePropertiesRequest): SerializePropertiesResult {
  const result = new SerializePropertiesResult();
  const entries = docToEntries(input.getDocument());
  result.setText(serializePropertiesText(entries, input.getSortKeys()));
  return result;
}

import { SetConfigValueRequest, SetConfigValueResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { docToEntries, entriesToDoc, setConfigValue as setConfigValueImpl } from './helpers';

/**
 * Returns a new ConfigDocument with the (section, key) entry's value set to
 * `value`: updated in place at its existing position if that (section, key)
 * already occurs (any earlier duplicate of the same pair is dropped, so the
 * result has exactly one entry for it), or appended at the end if it did
 * not occur. The input document is never mutated — SetConfigValueResult
 * carries a distinct document.
 */
export function setConfigValue(ax: AxiomContext, input: SetConfigValueRequest): SetConfigValueResult {
  const result = new SetConfigValueResult();
  const entries = docToEntries(input.getDocument());
  const updated = setConfigValueImpl(entries, input.getKey(), input.getValue(), input.getSection());
  result.setDocument(entriesToDoc(updated));
  return result;
}

import { ValidateConfigRequest, ValidateConfigResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { validateConfig as validateConfigImpl } from './helpers';

/**
 * Checks whether `text` is well-formed in `format` ("env" | "ini" |
 * "properties"). env and properties are parsed by libraries with no
 * rejecting grammar at all (see ParseEnv/ParseProperties) — any text
 * produces SOME set of key/value pairs — so those two formats are always
 * valid=true. ini validation additionally rejects a section nested more
 * than one level deep (e.g. "[a.b]"), reporting the offending line. An
 * unrecognized `format` name is reported as valid=false with
 * `error_message` explaining why (matching how a real syntax error is
 * reported, rather than as a separate error field).
 */
export function validateConfig(ax: AxiomContext, input: ValidateConfigRequest): ValidateConfigResult {
  const result = new ValidateConfigResult();
  const text = input.getText();
  const outcome = validateConfigImpl(text, input.getFormat());
  result.setValid(outcome.valid);
  result.setErrorMessage(outcome.message);
  result.setLine(outcome.line);
  result.setColumn(outcome.column);
  return result;
}