Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 51 additions & 21 deletions docs/primer/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ SPDX-License-Identifier: Apache-2.0 -->

# Vaar Primer

This page is a short introduction to Vaar for new developers. It explains what the project does, how a lint execution moves through the codebase and how to run the tool locally.
This page is a short introduction to Vaar for new developers. It explains what the project does, how lint and diff executions move through the codebase and how to run the tool locally.

This primer complements the reference docs: [System Overview](../system-overview.md)
for package boundaries, [Usage](../usage.md) for the command map and
Expand All @@ -19,7 +19,7 @@ Vaar is a Go command-line tool for checking environment configuration. It discov

`.env` files are rarely reviewed with the same rigor as code. Because they are sensitive, they are difficult to share and diff. So duplicate keys, wrong delimiters, stray whitespaces, non-portable key names and other such issues slip through unnoticed. Vaar makes that drift visible and, where a fix is unambiguous, repairs it.

### What Vaar Checks
### What Vaar Checks

By default Vaar discovers `.env` and any filename beginning with `.env.`, such
as `.env.example`, `.env.local` or `.env.preview-local`. It does not treat
Expand All @@ -33,39 +33,69 @@ These principles detailed in the [System Overview](../system-overview.md) and ar

- Deterministic first. Every rule is currently under `internal/lint/rules/deterministic/` and reports an exact finding from file content.
- Stable ordering and output. Findings are sorted by file, line, severity, rule and message so scripts and CI can rely on the result.
- Preserve original file state where possible. Parsing keeps original bytes, line numbers, BOM state and line-ending information available to later stages.
- Preserve original file state where possible. The dotenv source keeps original
bytes, line numbers, BOM state and line-ending information available to the
source and mutation boundaries, while analysis exposes only safe facts.
- Keep the command layer thin. `internal/cli/` handles command wiring, flags and exit codes while the main logic stays in focused packages.

## Components

A lint run passes through a small set of packages. Each package has one main
responsibility.

| Stage | Package | Responsibility |
| ----- | ------- | -------------- |
| Entrypoint | `cmd/vaar/` | Starts the binary and hands control to `internal/cli`. |
| CLI layer | `internal/cli/` | Cobra command wiring, flag translation, exit codes and user-facing errors. |
| Discovery / walk | `internal/fs/` | Walks the tree, matches known dotenv filenames and skips ignored directories such as `.git`, `build`, `dist`, `node_modules`, `testdata` and `vendor` (`Discover`). |
| Envfile parser | `internal/envfile/` | Parses bytes into a line-aware model and provides `Normalize`/`Write` for safe rewrites. |
| Rule engine | `internal/lint/` | Selects rules with `--only`/`--skip`, runs them, sorts findings and drives the fix pass (`Runner`). |
| Rule registry | `internal/lint/rules/` | `All()` returns the built-in rule set in a stable order over the category packages. |
| Report / output | `internal/report/` | Renders findings as plain text or JSON. |
Lint and diff runs pass through a small set of packages. Each package has one
main responsibility.

| Stage | Package | Responsibility |
| ----------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Entrypoint | `cmd/vaar/` | Starts the binary and hands control to `internal/cli`. |
| CLI layer | `internal/cli/` | Cobra command wiring, flag translation, exit codes and user-facing errors. |
| Scope / discovery | `internal/scope/`, `internal/fs/` | Selects targets, walks the tree, matches known dotenv filenames and skips ignored directories such as `.git`, `build`, `dist`, `node_modules`, `testdata` and `vendor`. |
| Dotenv source | `internal/source/dotenv/` | Loads files, parses them into a source-owned line-aware model and provides pure dotenv byte transforms. |
| Analysis | `internal/analysis/`, `internal/analysis/dotenv/` | Converts source documents into ordered, value-free facts and key inventories. |
| Rule engine | `internal/lint/` | Selects rules with `--only`/`--skip`, runs them against analysis and sorts findings. |
| Lint application | `internal/application/lint/` | Coordinates loading, analysis, lint execution and optional mutation re-analysis. |
| Mutations | `internal/mutations/` | Plans, validates and safely applies selected fixes through `internal/fs/`. |
| Diff application | `internal/application/diff/`, `internal/diff/` | Loads both operands, builds analysis inventories and compares keys. |
| Rule registry | `internal/lint/rules/` | `All()` returns the built-in rule set in a stable order over the category packages. |
| Report / output | `internal/output/` | Renders typed lint and diff results as plain text or JSON. |

### How A Lint Run Works

The `Runner` in `internal/lint/runner.go` ties these packages together:
The lint application service in `internal/application/lint/` ties the source,
analysis, lint and output boundaries together:

1. Select the active rules after applying `--only` and `--skip`.
2. Resolve the lint scope: the whole repository, one `--target` file or one `--target-dir` tree.
3. Discover dotenv files and load them into in-memory snapshots.
4. Run the selected rules against those snapshots.
5. If `--fix` is enabled, apply safe fixes, re-parse the changed files, re-run the rules and mark findings that disappeared as `[fixed]`.
3. Load selected dotenv sources and convert them into a value-free analysis snapshot.
4. Run the selected rules against that snapshot.
5. If `--fix` is enabled, build and apply a safe mutation plan, reload the
changed files, rebuild analysis and rerun the rules, marking findings that
disappeared as `[fixed]`.
6. Sort the findings into a stable order.
7. Render text or JSON output.
8. Exit based on the findings that remain after fixing.
7. Render the typed result through `internal/output/`.
8. Map the result to an exit code in `internal/cli/`.

Each finding carries a severity (`warn` or `error`), a rule name, the file, a line number and a message. The built-in rules are catalogued in [docs/lint/rules/README.md](../lint/rules/README.md).

### How A Diff Run Works

The diff application service in `internal/application/diff/` ties the source,
analysis, diff and output boundaries together:

1. The CLI validates that exactly two dotenv paths were provided.
2. The application service loads both operands through
`internal/source/dotenv/`, preserving their order and display paths.
3. The source documents are converted into value-free analysis documents.
4. `internal/analysis/` builds a key inventory for each document.
5. `internal/diff/` compares key presence between the two inventories.
6. The service returns a typed diff result containing paths, missing keys and
difference status.
7. `internal/output/diff/` renders the result as text or JSON.
8. `internal/cli/` maps the result to the process exit code.

Diff compares key presence only. It does not compare dotenv values, raw source
lines or source bytes. A clean comparison exits with `0`, a comparison with
missing keys exits with `1`, and an input, loading or rendering failure exits
with `2`.

## Getting Started

### Build And Verify
Expand Down
83 changes: 57 additions & 26 deletions docs/system-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,54 +3,85 @@ SPDX-License-Identifier: Apache-2.0 -->

# System Overview

Vaar keeps the command layer thin and pushes the real logic into a few focused packages. That makes the project easier to test, easier to extend and easier to keep stable as it grows. This page explains the current layout, the lint pipeline and the right place for new work. For command usage, see [Usage](./usage.md).
Vaar keeps the command layer thin and pushes the real logic into a few focused packages. That makes the project easier to test, easier to extend and easier to keep stable as it grows. This page explains the current layout, the lint and diff pipeline and the right place for new work. For command usage, see [Usage](./usage.md).

## Design Principles

- Keep the command layer thin and declarative in nature.
- Keep parsing, writing and line-aware file modeling in `internal/envfile/`.
- Keep parsing, source modeling and pure byte transforms in
`internal/source/`; keep generic filesystem mechanics in `internal/fs/`.
- Keep normalized analysis facts value-free in `internal/analysis/`.
- Make repository discovery explicit and deterministic.
- Prefer stable ordering and stable output so that scripts can rely on results.
- Preserve original environment file state unless a safe fix intentionally changes them.
- Treat documentation as part of the public contract that has to be maintained.

## Package Map

| Package | Responsibility | Notes |
| ------------------------------------ | ---------------------------------- | --------------------------------------------------------------------- |
| `cmd/vaar/` | Program entrypoint | Starts the binary and hands control to `internal/cli`. |
| `internal/cli/` | Command wiring and exit codes | Handles Cobra setup, flag translation and user-facing error handling. |
| `internal/fs/` | Repository discovery | Finds dotenv files and skips generated, vendored and fixture paths. |
| `internal/envfile/` | Parsing and file modeling | Preserves line-level detail, original bytes and newline state. |
| `internal/lint/` | Lint orchestration | Selects rules, runs them, sorts findings and applies safe fixes. |
| `internal/lint/rules/` | Rule catalog | Exposes `All()` and compatibility helpers for the rule packages. |
| `internal/lint/rules/deterministic/` | Deterministic rule implementations | One file per rule along with focused tests and docs. |
| `internal/report/` | Output rendering | Produces text and JSON output for humans and automation. |
| Package | Responsibility | Notes |
| ------------------------------------ | ---------------------------------- | ----------------------------------------------------------------------------------------- |
| `cmd/vaar/` | Program entrypoint | Starts the binary and hands control to `internal/cli`. |
| `internal/cli/` | Command wiring and exit codes | Handles Cobra setup, flag translation and user-facing error handling. |
| `internal/fs/` | Filesystem utilities | Walks repositories, validates paths, preserves modes and performs safe atomic operations. |
| `internal/scope/` | Scope selection | Decides which paths the command should analyse. |
| `internal/source/dotenv/` | Dotenv source boundary | Loads files, owns the dotenv parser/model and pure source-specific byte transforms. |
| `internal/analysis/` | Shared analysis facts | Stores ordered, value-free snapshots and key inventories. |
| `internal/analysis/dotenv/` | Dotenv analysis adapter | Converts source documents into value-free analysis documents. |
| `internal/lint/` | Lint engine and rule contracts | Selects rules, executes them against analysis and sorts findings. |
| `internal/lint/rules/` | Rule catalog | Exposes `All()` and compatibility helpers for the rule packages. |
| `internal/lint/rules/deterministic/` | Deterministic rule implementations | One file per rule along with focused tests and docs. |
| `internal/application/lint/` | Lint application workflow | Coordinates scope, source loading, analysis, linting and optional mutations. |
| `internal/mutations/` | Mutation planning/application | Validates plans and applies safe, permission-preserving replacements. |
| `internal/diff/` | Diff engine | Compares analysis key inventories. |
| `internal/application/diff/` | Diff application workflow | Coordinates source loading, analysis and diff comparison. |
| `internal/output/` | Output adapters | Produces typed terminal and JSON representations for command results. |

## How a Lint Run Works

1. Resolve the repository root.
2. Discover dotenv files in the tree.
3. Create an in-memory snapshot of each discovered `.env` file.
4. Select the rules to apply.
5. Parse each file and run the rules against the original snapshot.
1. If automatic safe fixing is enabled with `--fix`:
1. Apply the safe fixes.
2. Re-parse the files and re-run the rules after fixing, marking disappeared findings as fixed while retaining findings that remain.
1. Resolve the repository root and selected scope.
2. Load the selected files through `internal/source/dotenv`.
3. Convert source documents into a value-free `internal/analysis` snapshot.
4. Select rules and run the lint engine against that snapshot.
5. If automatic safe fixing is enabled with `--fix`, build and validate a
mutation plan, apply it through the mutation/filesystem boundaries, then
reload and re-analyse the same scope.
6. Sort findings into a stable order.
7. Render text or JSON output.
8. Exit based on the post-fix findings.
7. Render the typed result through `internal/output`.
8. Map the final result to the command exit code at the CLI boundary.

The parser keeps the original bytes, line numbers, BOM state and line-ending information available to later stages. This ensures safe rewrites.
The source boundary keeps original bytes, line numbers, BOM state and
line-ending information available to source and mutation stages. The analysis
snapshot exposes only safe, value-free facts to engines and reporters.

## How a Diff Run Works

1. Accept exactly two dotenv paths at the CLI boundary.
2. Pass both paths to `internal/application/diff/`.
3. Load both files through `internal/source/dotenv/`, preserving operand order
and display paths.
4. Convert both source documents into value-free analysis documents.
5. Build document-local key inventories through `internal/analysis/`.
6. Compare the inventories through `internal/diff/`.
7. Produce a typed diff result containing only paths, missing keys and the
difference status.
8. Render text or JSON through `internal/output/diff/`.
9. Map the final result to the command exit code at the CLI boundary.

Diff compares key presence only. It does not compare dotenv values, raw source
lines or source bytes.

## Where to Add New Functionality/Code

- New command or flag behavior: `internal/cli/`
- Repository walking or ignore logic: `internal/fs/`
- Parsing, formatting or write-back semantics: `internal/envfile/`
- Rule selection or rule orchestration: `internal/lint/`
- Dotenv parsing and source-specific formatting transforms: `internal/source/dotenv/`
- Scope selection: `internal/scope/`
- Rule selection and execution: `internal/lint/`
- Lint workflow orchestration: `internal/application/lint/`
- Mutation planning and application: `internal/mutations/`
- Diff comparison: `internal/diff/` and `internal/application/diff/`
- A new deterministic lint rule: `internal/lint/rules/deterministic/`
- Reporter changes: `internal/report/`
- Reporter changes: `internal/output/`
- User-facing documentation: `README.md`, `docs/usage.md`, `docs/lint/README.md` or the relevant rule page

If a change affects user-facing behaviour, add or update tests and document the behaviour appropriately.
Expand Down
2 changes: 1 addition & 1 deletion internal/analysis/doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
// discovery, rule execution, diff comparison, query evaluation, file writes,
// output rendering, serialization/JSON, exit-code mapping, source conversion,
// or caller integration. Source conversion lives outside this package. This
// package must not depend on or integrate with internal/envfile,
// package must not depend on or integrate with source parser packages,
// internal/source/dotenv, internal/fs, internal/scope, internal/lint,
// internal/diff, internal/output, internal/cli, or Cobra. Raw values, raw
// lines, raw bytes, lengths, hashes, masks, and secret-bearing errors are
Expand Down
Loading
Loading