Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
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
25 changes: 18 additions & 7 deletions docs/primer/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,10 @@ 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. 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.
- Preserve original file state where possible. The dotenv source and mutation
boundaries may retain original bytes, line numbers, BOM state and
line-ending information, while analysis exposes only safe facts to engines
and reporters.
- Keep the command layer thin. `internal/cli/` handles command wiring, flags and exit codes while the main logic stays in focused packages.

## Components
Expand All @@ -52,7 +53,7 @@ main responsibility.
| 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/`. |
| Mutations | `internal/mutations/` | Plans fixes without filesystem I/O, validates the complete plan and applies safe per-file replacements 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. |
Expand All @@ -66,15 +67,25 @@ analysis, lint and output boundaries together:
2. Resolve the lint scope: the whole repository, one `--target` file or one `--target-dir` tree.
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]`.
5. If `--fix` is enabled, build a safe mutation plan, validate the
complete plan, apply safe changes, reload the selected scope, rebuild
analysis and rerun the rules, marking findings that disappeared as
`[fixed]`.
Comment thread
TFM-HITESH marked this conversation as resolved.
Resolved
6. Sort the findings into a stable order.
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).

Mutation application validates every planned destination before it creates a
replacement. It rejects duplicate physical destinations, coordinates Vaar
writers through shared locks, and rechecks the target identity, content and
permission bits before finalization. Each replacement uses a same-directory
temporary file and the captured permission mode. The plan applies changes in
order; it does not provide a transaction or rollback across multiple files.
Vaar's stale-state guarantee covers writers that use the shared filesystem
primitives.

### How A Diff Run Works

The diff application service in `internal/application/diff/` ties the source,
Expand Down
28 changes: 22 additions & 6 deletions docs/system-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ Vaar keeps the command layer thin and pushes the real logic into a few focused p
- 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/`.
- Keep raw source state inside the source and mutation boundaries. Engines and
reporters consume value-free analysis facts and typed results.
- 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.
Expand Down Expand Up @@ -42,16 +44,28 @@ Vaar keeps the command layer thin and pushes the real logic into a few focused p
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.
5. If automatic safe fixing is enabled with `--fix`, build a safe
mutation plan, validate the complete plan, apply it through the
mutation/filesystem helpers, then reload and re-analyse the same scope.
6. Sort findings into a stable order.
7. Render the typed result through `internal/output`.
8. Map the final result to the command exit code at the CLI boundary.

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.
The source boundary may retain original bytes, line numbers, BOM state and
line-ending information for source and mutation stages. The analysis snapshot
exposes only safe, value-free facts to engines and reporters. Mutation planning
does not read or write the filesystem; it operates on documents that the
application has already loaded.

Mutation application validates every planned destination before it creates a
replacement. It rejects duplicate physical destinations, coordinates Vaar
writers through shared path and target locks, and revalidates target identity,
content and permission bits before finalization. Each replacement uses a
same-directory temporary file and applies the captured permission mode before
the destination changes. The plan applies replacements in document order. It
does not provide a transaction or rollback across the complete plan, so a
later failure does not undo an earlier successful replacement. The stale-state
guarantee covers writers that use Vaar's shared filesystem primitives.

## How a Diff Run Works

Expand All @@ -76,6 +90,8 @@ lines or source bytes.
- Repository walking or ignore logic: `internal/fs/`
- Dotenv parsing and source-specific formatting transforms: `internal/source/dotenv/`
- Scope selection: `internal/scope/`
- Shared value-free facts and key inventories: `internal/analysis/`
- Dotenv-to-analysis conversion: `internal/analysis/dotenv/`
- Rule selection and execution: `internal/lint/`
- Lint workflow orchestration: `internal/application/lint/`
- Mutation planning and application: `internal/mutations/`
Expand Down
Loading