envsync-le AGENTS.md

AGENTS.md — EnvSync-LE

Technical source of truth for this repo. README.md is the user-facing doc; this file is for anyone (human or agent) changing the code.

This repo hosts two products: the extension at the root (this document's scope) and the Rust CLI in crate/ (its own AGENTS.md + SPEC.md). The shared detection corpus lives at crate/fixtures/; scripts/check-detection-parity.ts fails CI when this extension drifts from it, and it also fails if any answer in the corpus carries a value rather than a key name.

What this is

A VS Code extension that compares the variable names (keys) across the .env files in a workspace and reports keys missing from some files. Values are never read into comparison output, files are never modified, and there is no network access. Comparison runs automatically on file changes (debounced), on demand (Show Issues, Compare Selected), and against an optional template file.

Architecture

extension.ts              activate(): build adapters -> createDetector -> registerAllCommands -> registerVSCodeWatchers -> initial checkSync
adapters/                 thin vscode wrappers, deps injected as typed bags:
  vscodeConfiguration     Configuration (get/has) over workspace.getConfiguration('envsync-le')
  vscodeFileSystem        findFiles/readFile/stat/asRelativePath
  vscodeNotifier          window messages, gated by notificationLevel
                          (all -> missing+extra+errors, important -> missing+errors, silent -> nothing)
  vscodeStatusBar         one status bar item; re-renders on config change
  vscodeTelemetry         local OutputChannel, only when telemetryEnabled
  vscodeUserInterface     quickPick (single + canPickMany), progress, messages
  vscodeWatcher           FileSystemWatcher per watchPattern; debounced checkSync;
                          rebuilt when watchPatterns changes
  vscodeCommand           CommandAdapter for openSettings
commands/                 one file per command; registerAllCommands wires the bag
detection/
  heuristics.ts           THE single place for basename/isEnvFileName/
                          detectFileType/shouldExcludeFile (glob matching)
  parser.ts               line-oriented key extraction; multiline quoted values
  comparator.ts           compareFiles(files, {mode, templatePath, caseSensitive})
                          -> SyncReport; extras only exist in template mode
  detector.ts             orchestrates discover -> parse -> compare -> notify/UI
config/config.ts          readConfig(configuration) snapshot; CONFIG_DEFAULTS table
utils/errors.ts           sanitizeErrorMessage/errorMessage — wired into every
                          user-facing error
types.ts                  shared types only — no logic