feat(config): add prettify-field-keys option (#1315)

Add config file option to control whether underscores in field keys are replaced with hyphens in formatted output.

Configuration:
- Set `prettify-field-keys = false` to preserve original underscores
- Set `prettify-field-keys = true` for hyphen replacement (default)
- Config-only option (no CLI flags)

Behavior:
- Default (`true`) preserves current behavior for backward compatibility
- When disabled, field keys like `request_id` display as `request_id`
- When enabled, field keys like `request_id` display as `request-id`
- Applies to all key segments including nested/flattened keys
- `--raw-fields` flag takes precedence when active

Co-authored-by: Claude Sonnet 4.5 <[email protected]>

Author: pamburus

.specify/memory/constitution.md

@@ -1,10 +1,16 @@
-<!-- 
+<!--
 Sync Impact Report:
-- Version: 1.1.0 → 1.2.0
-- Added: Principle VII - Test Data Management
-- Rationale: MINOR version bump - new principle added to governance
-- Templates requiring updates: ✅ All templates reviewed and compatible
-- Date: 2025-01-07
+- Version: 1.4.2 → 1.4.3
+- Modified Sections:
+  - Development Workflow & Quality Gates (Version Check): Added git fetch -t requirement
+- Rationale: PATCH version bump - workflow clarification to fetch latest tags
+- Templates requiring updates:
+  - ✅ plan-template.md: Compatible - no structural changes needed
+  - ✅ spec-template.md: Compatible - no structural changes needed
+  - ✅ tasks-template.md: Compatible - workflow guidance orthogonal to task structure
+- Modified Requirements:
+  - Step 2 of version check now includes git fetch -t to ensure latest tags
+- Date: 2026-02-04
 -->
 
 # hl (High-performance Log viewer) Constitution
@@ -32,6 +38,29 @@ Comprehensive error handling with graceful degradation. All input validated; mal
 <!-- TDD mandatory; no exceptions for performance-critical code -->
 Unit tests for algorithms and parsers. Integration tests for end-to-end CLI workflows. Property-based tests for streaming behavior. Performance benchmarks tracked and enforced. All tests must pass before merging. Coverage must not decrease: patches must maintain or improve the project's average code coverage.
 
+**Schema Validation Requirements:**
+When modifying configuration file structure (`src/settings.rs`, `etc/defaults/config.toml`) or theme configuration files, the corresponding JSON schema files (`schema/json/config.schema.json`, `schema/json/theme.schema.*.json`) MUST be updated to reflect the changes.
+
+**Schema Build Workflow:**
+After updating schema files, the following workflow MUST be followed:
+1. Run `cargo build` to automatically update embedded schema references
+2. Only after build completes successfully, run `just ci` for validation
+3. This order is mandatory because the build process updates schema references that CI validates
+
+This ensures:
+- Configuration validation tooling remains accurate
+- IDE autocomplete and validation work correctly
+- Documentation stays synchronized with implementation
+- Embedded schema references are current before validation
+
+**Coverage Validation Requirements:**
+After implementing any new feature, run `just uncovered` to identify changed lines lacking test coverage. If uncovered lines appear:
+- MUST add tests to cover them unless they require environmental interaction (file I/O, network, OS-specific behavior)
+- Document why coverage cannot be added if environmental interaction prevents testing
+- Aim to maintain or improve overall project coverage percentage
+
+This ensures new features are properly tested and maintains the high-quality bar established by existing code.
+
 ### VI. Specification & Cross-Reference Integrity
 <!-- Maintain referential integrity across all documentation and code -->
 **Avoid renumbering identifiers whenever possible.** Prefer adding new requirements at the end of sections or using sub-identifiers (e.g., FR-030c, FR-030d) to insert requirements without disrupting existing numbering.
@@ -73,11 +102,83 @@ Tests MUST use external data files instead of inline multiline string literals f
 ## Development Workflow & Quality Gates
 
 **Code Review**: All PRs require at least one review. Performance-sensitive changes require benchmark verification.
+
 **Testing Gates**: All tests must pass (`cargo test`). Benchmarks must not regress (`cargo bench`). Clippy warnings must be resolved.
+
 **Documentation**: Features documented before or concurrent with implementation. Breaking changes documented in CHANGELOG.
+
 **Performance**: New features benchmarked. Regressions >5% must be justified and documented.
+
 **Backwards Compatibility**: Maintained across minor versions. Deprecation period required before removing features.
 
+**Version Check Before Implementation**: Before starting feature implementation, ensure version is properly bumped:
+
+1. Run `just version` to get current version (e.g., `0.36.0-alpha.5`)
+2. Run `git fetch -t && just previous-tag` to get latest tags and previous release tag (e.g., `v0.35.3`)
+3. Compare the major.minor versions:
+   - Extract major.minor from current version (e.g., `0.36`)
+   - Extract major.minor from previous tag, removing `v` prefix (e.g., `0.35`)
+4. If major.minor versions are the SAME:
+   - Calculate next minor version: `major.(minor+1).0-alpha.1`
+   - Run `cargo set-version <next-version>` (e.g., `cargo set-version 0.36.0-alpha.1`)
+5. If major.minor versions are DIFFERENT:
+   - Run `just bump` to increment alpha version (e.g., `0.36.0-alpha.5` → `0.36.0-alpha.6`)
+
+**Rationale**: This ensures each feature branch has a unique version identifier, preventing version conflicts and enabling proper release tracking.
+
+**Commit Workflow**: When using speckit workflow commands, commits MUST follow this discipline:
+
+1. **Pre-commit Validation**: Before ANY commit, run `just ci` which executes:
+   - `check`: Cargo check for compilation errors
+   - `test`: Full test suite execution
+   - `lint`: Clippy warnings resolution
+   - `audit`: Security vulnerability checks
+   - `fmt-check`: Code formatting verification
+   - `check-schema`: JSON schema validation
+
+   ALL reported issues MUST be resolved before proceeding with the commit.
+
+2. **Conventional Commits**: After completing each speckit step, create a commit using conventional commit format:
+   - After `/speckit.specify`: `docs(spec): add [feature-name] specification`
+   - After `/speckit.clarify`: `docs(spec): clarify [aspect] in [feature-name]`
+   - After `/speckit.tasks`: `docs(tasks): generate task breakdown for [feature-name]`
+   - After `/speckit.implement`: `feat([scope]): [user-visible change]` or `fix([scope]): [user-visible fix]`
+
+3. **Commit Message Content Guidelines**:
+   Commit messages are used to automatically generate release notes and MUST focus on user-visible behavior:
+
+   **DO write about**:
+   - New features users can access
+   - Bug fixes that affect user experience
+   - Configuration options added or changed
+   - Command-line flags or arguments modified
+   - Output format changes
+   - Performance improvements users will notice
+   - Breaking changes requiring user action
+
+   **DO NOT write about**:
+   - Implementation details (functions, structs, modules)
+   - Source code references (file names, line numbers)
+   - Test statistics ("1464 tests passing")
+   - CI validation status ("Full CI validation passed")
+   - Internal refactoring unless it affects users
+   - Code quality metrics
+
+   **Exception**: Internal changes with no user-visible impact may include brief technical context, but still avoid source code specifics. Focus on "what changed" in system behavior, not "how it was implemented."
+
+   **Examples**:
+   - ✅ Good: `feat(config): add prettify-field-keys option to control key prettification`
+   - ✅ Good: `fix(parser): handle timestamps with microsecond precision correctly`
+   - ❌ Bad: `feat(formatting): implement prettify_field_keys in RecordFormatter struct`
+   - ❌ Bad: `fix: update formatting.rs line 1211 to check prettify flag. All 1464 tests pass`
+
+4. **Rationale**: This workflow ensures:
+   - Clean, atomic commits representing logical completion points
+   - All code passing quality gates before entering version control
+   - Clear commit history enabling easy navigation and rollback
+   - Prevention of broken commits that fail CI pipelines
+   - Release notes are immediately useful to end users
+
 ## Governance
 
 This constitution supersedes all other practices and informal conventions. All PRs and code reviews must verify compliance with these principles. Complexity introduced must be justified against the principles and documented.
@@ -90,4 +191,4 @@ This constitution supersedes all other practices and informal conventions. All P
 3. Documentation of rationale
 4. Migration plan for any breaking changes
 
-**Version**: 1.2.0 | **Ratified**: 2025-11-02 | **Last Amended**: 2025-01-07
+**Version**: 1.4.3 | **Ratified**: 2025-11-02 | **Last Amended**: 2026-02-04

CLAUDE.md

@@ -0,0 +1,30 @@
+# hl Development Guidelines
+
+Auto-generated from all feature plans. Last updated: 2026-02-04
+
+## Active Technologies
+
+- Rust (stable, edition 2024) + serde (config deserialization), clap (CLI argument parsing) (009-key-prettification)
+
+## Project Structure
+
+```text
+src/
+tests/
+```
+
+## Commands
+
+- cargo test
+- cargo clippy
+
+## Code Style
+
+Rust (stable, edition 2024): Follow standard conventions
+
+## Recent Changes
+
+- 009-key-prettification: Added Rust (stable, edition 2024) + serde (config deserialization), clap (CLI argument parsing)
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

Cargo.lock

@@ -23,7 +23,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.36.0-alpha.5"
+version = "0.36.0-alpha.6"
 edition = "2024"
 repository = "https://github.com/pamburus/hl"
 license = "MIT"

Cargo.toml

@@ -1,4 +1,4 @@
-#:schema https://raw.githubusercontent.com/pamburus/hl/v0.35.3/schema/json/config.schema.json
+#:schema ../../schema/json/config.schema.json
 
 # Settings for fields processing.
 [fields]

etc/defaults/config-ecs.toml

@@ -1,4 +1,4 @@
-#:schema https://raw.githubusercontent.com/pamburus/hl/v0.35.3/schema/json/config.schema.json
+#:schema ../../schema/json/config.schema.json
 
 # Configuration of the predefined set of fields.
 [fields.predefined]

etc/defaults/config-k8s.toml

@@ -1,4 +1,4 @@
-#:schema https://raw.githubusercontent.com/pamburus/hl/v0.35.3/schema/json/config.schema.json
+#:schema ../../schema/json/config.schema.json
 
 #
 # Time format, see https://man7.org/linux/man-pages/man1/date.1.html for details.
@@ -127,6 +127,9 @@ names = []
 #
 # Flatten nested fields by joining them with a dot. Options: ["always", "never"].
 flatten = "always"
+#
+# Prettify field keys by replacing underscores with hyphens. Options: [true, false].
+prettify-field-keys = true
 
 # Message format [auto-quoted, always-quoted, always-double-quoted, delimited, raw]:
 # * "auto-quoted"          • Automatically enables or disables message quotation to improve clarity or avoid ambiguities.

etc/defaults/config.toml

@@ -321,6 +321,9 @@
               "$ref": "#/definitions/display-variant"
             }
           }
+        },
+        "prettify-field-keys": {
+          "type": "boolean"
         }
       }
     },

schema/json/config.schema.json

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Key Prettification Config Option
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-02-04
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All items pass validation.
+- The spec is ready for `/speckit.clarify` or `/speckit.plan`.

specs/009-key-prettification/checklists/requirements.md

@@ -0,0 +1,49 @@
+# Data Model: Key Prettification Config Option
+
+## Modified Entities
+
+### Formatting (settings.rs)
+
+Config-level representation of formatting preferences.
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| flatten | `Option<FlattenOption>` | `None` | Existing |
+| expansion | `ExpansionOptions` | `default()` | Existing |
+| message | `MessageFormatting` | `default()` | Existing |
+| punctuation | `Punctuation` | `default()` | Existing |
+| **prettify_field_keys** | **`Option<bool>`** | **`None`** | **New. `None` = use default (`true`). Deserialized from TOML as `prettify-field-keys`.** |
+
+### RecordFormatter (formatting.rs)
+
+Immutable formatter used during record processing.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| ... | ... | Existing fields unchanged |
+| **prettify_field_keys** | **`bool`** | **New. Set to `!raw_fields && cfg.prettify_field_keys.unwrap_or(true)` during `build()`.** |
+
+## Modified Functions
+
+### KeyPrefix::push()
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| key | `&str` | Existing |
+| **prettify** | **`bool`** | **New. When true, applies `key_prettify`; when false, copies key bytes verbatim.** |
+
+## Config File (TOML)
+
+```toml
+[formatting]
+prettify-field-keys = true   # New field, default true
+```
+
+## State Transitions
+
+N/A — This is a stateless boolean flag. No lifecycle transitions.
+
+## Validation Rules
+
+- `prettify-field-keys` in TOML must be a boolean (`true` or `false`)
+- Invalid values cause a deserialization error (handled by serde)