feat: block tags — grouped environments, slide-on-pick, symmetry lint, encrypted blocks

[devark28]

Summary

This PR adds tags to block definitions, turning envmn's flat block list into a two-dimensional model: the block name is the environment (local, remote), and tags describe the resource (db, smtp). Everything else in the PR builds on that: tag-aware picking with slide semantics, a variable-symmetry lint, and a plaintext-keys format for encrypted blocks.

#@ local [db]
DB_HOST=localhost
##

#@ remote [db]
DB_HOST=example.com
##

Syntax & validation

• Block headers accept #@ name [tag1, tag2]. Two blocks may share a name as long as their tags differ (block identity = name + tag set).
• Tag names follow block-name rules ([a-z_][a-z0-9_]*). Dunder-form tags (__x__) are reserved; the only recognized one is __encrypted__. Malformed brackets, invalid characters, and unknown reserved tags are parse errors with line numbers.

Picking

Blocks sharing a resource tag form a group competing for the same variables; the last block of a group is the active one (last-wins). Picking no longer shuffles blocks to the bottom of the file:

• A picked tagged block slides to just after the last block of its group — related blocks stay visually together and the rest of the file doesn't move. Picking an already-active block is a no-op.
• pick <name> picks all blocks with that name (atomic environment switch, each within its own group); --tag/-t (repeatable) narrows to specific resources.
• A multi-tag block (#@ remote [db, cache]) means "these switch together": it slides after all blocks it shares a tag with.
• Every tagged pick reports what changed on stderr (stdout stays clean for piping):

  db: 'local [db]' now active (was 'remote [db]')
  

• Untagged blocks keep the classic move-to-bottom behavior — plain .env files are unaffected.

Lint: variable symmetry

lint (previously parse-only) now checks that blocks sharing a resource tag define the same variable keys. Single-tag blocks are the ground truth for their tag; multi-tag blocks are checked against the union of their tags (extra keys are only flagged when every tag has a ground truth). Findings are advisory: warnings on stderr, exit code 0.

warning: 'remote [db]' is missing variable 'DB_PORT' defined by its group
warning: 'remote [db, cache]' defines variable 'FOO' that belongs to none of its tags

Encrypted blocks

__encrypted__ marks a block whose values are ciphertext while keys stay plaintext (keys are rarely the secret, values are). Encrypted blocks therefore parse, list, format, pick, and lint like any other block. Actual encrypt/decrypt commands are future work.

#@ local [smtp, __encrypted__]
MAILGUN_API_KEY=08debe3d42ade91671f783a784fbed31dd3e897abae5439be07f885887217136
##

Recommended layout (advisory)

The README documents the opinionated style: one resource tag per block, using shared names to bundle resources into environments. pick remote switches the whole environment; later fine-grained picks (pick other --tag cache) compose any mix via last-wins. Multi-tag blocks remain supported for deliberate all-or-nothing bundles.

Notes

• Fixes a lookup bug where tagged blocks could never be found by pick (block identity includes tags, but lookup constructed a tagless probe).
• Removes a leftover dbg! in the parser.
• No behavior change for untagged files: list, format, lint, and pick work exactly as before.

Testing

• 104 tests passing: unit tests for tag parsing/validation, block identity, slide/pick-all/no-op/union placement (including multi-tag edge cases), symmetry warnings; end-to-end tests driving the compiled binary for tagged list, pick --tag, environment-wide pick, stderr summaries, encrypted round-trip via format, and lint warnings.
• Verified manually against the sample .env.tagged and an untagged .env.

[Copilot]

Pull request overview

This PR introduces block tags to extend envmn’s block model from a single dimension (block name) to a two-dimensional identity (name + tag set), enabling tag-aware listing, picking with slide semantics, and a new lint rule that checks variable-key symmetry across tag groups. It also adds support for a reserved __encrypted__ tag to mark blocks whose values are ciphertext while keys remain plaintext.

Changes:

• Add tag parsing/validation and incorporate tags into block identity and display (name [tag1, tag2]).
• Update pick to be tag-aware (including --tag/-t) with “slide within group” behavior and stderr summaries.
• Extend lint to emit advisory symmetry warnings for tagged groups; add extensive unit/E2E test coverage and README documentation.

Reviewed changes

Copilot reviewed 20 out of 24 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/tags_tests.rs	New end-to-end tests covering tagged list/pick/slide/no-op/errors and encrypted round-trips.
tests/pick_tests.rs	Minor formatting fix in existing pick tests.
tests/list_tests.rs	Minor formatting fix in existing list tests.
tests/lint_tests.rs	Adds tests for symmetry warnings and encrypted-key symmetry behavior.
tests/format_tests.rs	Minor whitespace/formatting cleanup in format tests.
tests/common/mod.rs	Minor formatting fix.
src/parser/validators/tag_validator.rs	New tag validation (syntax rules + reserved tag handling).
src/parser/validators/mod.rs	Exposes tag validator APIs.
src/parser/tokens/document.rs	Implements tag-aware lookup, active-by-tag tracking, and sliding pick destination logic.
src/parser/tokens/block.rs	Adds tags to Block, identifier formatting, resource-tag filtering, and tag-aware equality/hash.
src/parser/parser.rs	Parses optional [tag1, tag2] syntax in block headers and validates tags.
src/parser/mod.rs	Module ordering/exports adjustment.
src/parser/engine/pick.rs	Updates CLI pick processing to accept tags and report activation changes on stderr.
src/parser/engine/mod.rs	Wires in new lint implementation and updated pick signature.
src/parser/engine/list.rs	Makes list print full block identifiers including tags.
src/parser/engine/lint.rs	New symmetry lint implementation for tagged blocks.
src/parser/constants.rs	Adds tag delimiter constants and __encrypted__ tag constant.
src/error/parsing.rs	Adds malformed-tags parse error.
src/error/naming.rs	Adds tag-related naming errors, including unknown reserved tags.
src/cli/mod.rs	Minor module ordering change.
src/cli/cli.rs	Extends Pick command to carry tag filters.
src/cli/args.rs	Adds --tag/-t (repeatable) to the pick subcommand.
README.md	Documents tags, tagged picking semantics, reserved tags, and symmetry lint behavior.
.gitignore	Ignores .env* files.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.