renamer/specs/006-add-regex-command/spec.md

Feature Specification: Regex Command for Pattern-Based Renaming

Feature Branch: 006-add-regex-command
Created: 2025-10-30
Status: Draft
Input: User description: "实现 regex 命令，用于使用正则获取指定位置内容后再重新命名，示例 renamer regexp @1-@2 实现了获取正则的第一、二位的匹配数据，并进行重新命名"

User Scenarios & Testing (mandatory)

User Story 1 - Rename Files Using Captured Groups (Priority: P1)

As a power user organizing datasets, I want to rename files by extracting portions of their names via regular expressions so that I can normalize naming schemes without writing custom scripts.

Why this priority: Provides the core value—regex-driven renaming to rearrange captured data quickly across large batches.

Independent Test: In a directory with files named 2025-01_report.txt and 2025-02_report.txt, run renamer regex "^(\\d{4})-(\\d{2})_report" "Q@2-@1" --dry-run and verify the preview shows Q01-2025.txt and Q02-2025.txt. Re-run with --yes to confirm filesystem updates and ledger entry.

Acceptance Scenarios:

1. Given files alpha-123.log and beta-456.log, When the user runs renamer regex "^(\\w+)-(\\d+)" "@2_@1" --dry-run, Then the preview lists 123_alpha.log and 456_beta.log as proposed names.
2. Given files that do not match the pattern, When the command runs in preview mode, Then unmatched files are listed with a "skipped" status and no filesystem changes occur on apply.

---

User Story 2 - Automation-Friendly Regex Renames (Priority: P2)

As a DevOps engineer automating release artifact naming, I need deterministic exit codes, ledger metadata, and undo support for regex-based renames so CI pipelines remain auditable and reversible.

Why this priority: Ensures the new command can be safely adopted in automation without risking opaque failures.

Independent Test: Execute renamer regex "^build_(\\d+)_(.*)$" "release-@1-@2" --yes --path ./fixtures, verify exit code 0, inspect .renamer for recorded pattern, replacement template, and affected files, then run renamer undo to restore originals.

Acceptance Scenarios:

1. Given a non-interactive run with --yes, When all matches succeed without conflicts, Then exit code is 0 and the ledger entry records the regex pattern, replacement template, and matching groups per file.
2. Given a ledger entry produced by renamer regex, When renamer undo executes, Then filenames revert to their previous values even if the original files contained Unicode characters or were renamed by automation.

---

User Story 3 - Validate Patterns, Placeholders, and Conflicts (Priority: P3)

As a user experimenting with regex templates, I want clear validation and preview feedback for invalid patterns, missing capture groups, or resulting conflicts so I can adjust commands before committing changes.

Why this priority: Prevents accidental data loss and reduces trial-and-error when constructing regex commands.

Independent Test: Run renamer regex "^(.*)$" "@2" --dry-run and confirm the command exits with a descriptive error because placeholder @2 is undefined; run a scenario where multiple files would map to the same name and ensure apply is blocked.

Acceptance Scenarios:

1. Given a replacement template referencing an undefined capture group, When the command runs, Then it exits non-zero with a message explaining the missing group and no files change.
2. Given two files whose matches produce identical targets, When preview executes, Then conflicts are listed and apply refuses to proceed until resolved.

---

Edge Cases

• How does the command behave when the regex pattern is invalid or cannot compile?
• What is the outcome when no files match the pattern (preview and apply)?
• How are nested or optional groups handled when placeholders reference non-matching groups?
• What happens if the replacement template results in empty filenames or removes extensions?
• How are directories or hidden files treated when scope flags include/exclude them?
• What feedback is provided when resulting names differ only by case on case-insensitive filesystems?

Requirements (mandatory)

Functional Requirements

• FR-001: CLI MUST provide a regex subcommand that accepts a required regex pattern and replacement template arguments (e.g., renamer regex <pattern> <template>).
• FR-002: Replacement templates MUST support numbered capture placeholders (@1, @2, etc.) corresponding to the regex groups; referencing undefined groups MUST produce a validation error.
• FR-003: Pattern matching MUST operate on the filename stem by default while preserving extensions unless the template explicitly alters them.
• FR-004: Preview MUST display original names, proposed names, and highlight skipped entries (unmatched, invalid template) prior to apply; apply MUST be blocked when conflicts or validation errors exist.
• FR-005: Execution MUST respect shared scope flags (--path, --recursive, --include-dirs, --hidden, --extensions, --dry-run, --yes) consistent with other commands.
• FR-006: Ledger entries MUST capture the regex pattern, replacement template, and affected files so undo can restore originals deterministically.
• FR-007: The command MUST emit deterministic exit codes: 0 for successful apply or no matches, non-zero for validation failures or conflicts.
• FR-008: Help output MUST document pattern syntax expectations, placeholder usage, escaping rules, and examples for both files and directories.

Key Entities

• RegexRequest: Working directory, regex pattern, replacement template, scope flags, dry-run/apply settings.
• RegexSummary: Counts of matched files, skipped entries, conflicts, warnings, and preview entries with status (changed, skipped, no_change).

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Users rename 500 files via regex (preview + apply) in under 2 minutes end-to-end.
• SC-002: 95% of beta testers correctly apply a regex rename after reading renamer regex --help without additional guidance.
• SC-003: Automated regression tests confirm regex rename + undo cycles leave the filesystem unchanged in 100% of scripted scenarios.
• SC-004: Support tickets related to custom regex renaming scripts drop by 30% within the first release cycle post-launch.

Clarifications

Session 2025-10-30

• Q: How should literal @ characters be escaped in templates? → A: Use @@ to emit a literal @ while keeping numbered placeholders intact.

Assumptions

• Regex evaluation uses the runtime’s built-in engine with RE2-compatible syntax; no backtracking-specific constructs (e.g., look-behind) are supported.
• Matching applies to filename stems by default; users can reconstruct extensions via placeholders if required.
• Unmatched files are skipped gracefully and reported in preview; apply exits 0 when all files are skipped.
• Templates treat @0 as the entire match if referenced; placeholders are case-sensitive and must be preceded by @. Use @@ to emit a literal @ character.

Dependencies & Risks

• Requires extending existing traversal, preview, and ledger infrastructure to accommodate regex replacement logic.
• Complex regex patterns may produce unexpected duplicates; conflict detection must guard against accidental overwrites.
• Users may expect advanced regex features (named groups, non-ASCII classes); documentation must clarify supported syntax to prevent confusion.