renamer/specs/006-add-regex-command/data-model.md

Data Model – Regex Command

Entity: RegexRequest

• Fields
  • WorkingDir string — Absolute path derived from CLI --path or current directory.
  • Pattern string — User-supplied regular expression.
  • Template string — Replacement string with @n placeholders.
  • IncludeDirs bool — Mirrors --include-dirs flag.
  • Recursive bool — Mirrors --recursive flag.
  • IncludeHidden bool — True only when --hidden is supplied.
  • ExtensionFilter []string — Filter tokens from --extensions.
  • DryRun bool — Preview-only execution state.
  • AutoConfirm bool — Captures --yes for non-interactive runs.
  • Timestamp time.Time — Invocation timestamp for ledger correlation.
• Validation Rules
  • Regex must compile; invalid patterns produce errors.
  • Template may reference @0 (full match) and numbered groups; referencing undefined groups is invalid.
  • Prohibit control characters and path separators in resulting names.
• Relationships
  • Consumed by regex engine to build rename plan.
  • Serialized into ledger metadata alongside summary output.

Entity: RegexSummary

• Fields
  • TotalCandidates int — Items inspected after scope filtering.
  • Matched int — Files whose names matched the regex.
  • Changed int — Entries that will change after template substitution.
  • Skipped int — Non-matching or invalid-template entries.
  • Conflicts []Conflict — Rename collisions or generated duplicates.
  • Warnings []string — Validation notices (unused groups, truncated templates).
  • Entries []PreviewEntry — Original/proposed mappings with status.
  • LedgerMetadata map[string]any — Snapshot persisted with ledger entry (pattern, template, scope flags).
• Validation Rules
  • Conflicts must be empty before apply.
  • Matched = Changed + (matched entries with no change) for consistency.
• Relationships
  • Drives preview rendering.
  • Input for ledger writer and undo verification.

Entity: Conflict

• Fields
  • OriginalPath string
  • ProposedPath string
  • Reason string — (duplicate_target, existing_file, invalid_template).
• Validation Rules
  • ProposedPath unique among planned operations.
  • Reason drawn from known enum for consistent messaging.
• Relationships
  • Reported in preview output and blocks apply.

Entity: PreviewEntry

• Fields
  • OriginalPath string
  • ProposedPath string
  • Status string — changed, no_change, skipped.
  • MatchGroups []string — Captured groups applied to template.
• Validation Rules
  • ProposedPath equals OriginalPath when Status == "no_change".
  • MatchGroups length must equal number of captured groups.
• Relationships
  • Displayed in preview output.
  • Persisted alongside ledger metadata for undo.