Add regex command implementation

This commit is contained in:
Rogee
2025-10-31 10:12:02 +08:00
parent a0d7084c28
commit d436970848
55 changed files with 2115 additions and 9 deletions

92
internal/regex/apply.go Normal file
View File

@@ -0,0 +1,92 @@
package regex
import (
"context"
"errors"
"fmt"
"os"
"path/filepath"
"sort"
"github.com/rogeecn/renamer/internal/history"
)
// Apply executes the planned regex renames and writes a ledger entry.
func Apply(ctx context.Context, req Request, planned []PlannedRename, summary Summary) (history.Entry, error) {
reqCopy := req
if err := reqCopy.Validate(); err != nil {
return history.Entry{}, err
}
entry := history.Entry{Command: "regex"}
if len(planned) == 0 {
return entry, nil
}
sort.SliceStable(planned, func(i, j int) bool {
return planned[i].Depth > planned[j].Depth
})
done := make([]history.Operation, 0, len(planned))
groupsMeta := make(map[string][]string, len(planned))
revert := func() error {
for i := len(done) - 1; i >= 0; i-- {
op := done[i]
source := filepath.Join(reqCopy.WorkingDir, filepath.FromSlash(op.To))
destination := filepath.Join(reqCopy.WorkingDir, filepath.FromSlash(op.From))
if err := os.Rename(source, destination); err != nil && !errors.Is(err, os.ErrNotExist) {
return err
}
}
return nil
}
for _, plan := range planned {
if err := ctx.Err(); err != nil {
_ = revert()
return history.Entry{}, err
}
if err := os.MkdirAll(filepath.Dir(plan.TargetAbsolute), 0o755); err != nil {
_ = revert()
return history.Entry{}, fmt.Errorf("prepare target directory: %w", err)
}
if err := os.Rename(plan.SourceAbsolute, plan.TargetAbsolute); err != nil {
_ = revert()
return history.Entry{}, err
}
relFrom := filepath.ToSlash(plan.SourceRelative)
relTo := filepath.ToSlash(plan.TargetRelative)
done = append(done, history.Operation{From: relFrom, To: relTo})
if len(plan.MatchGroups) > 0 {
groupsMeta[relFrom] = append([]string(nil), plan.MatchGroups...)
}
}
if len(done) == 0 {
return entry, nil
}
entry.Operations = done
metadata := map[string]any{
"pattern": reqCopy.Pattern,
"template": reqCopy.Template,
"matched": summary.Matched,
"changed": summary.Changed,
}
if len(groupsMeta) > 0 {
metadata["matchGroups"] = groupsMeta
}
entry.Metadata = metadata
if err := history.Append(reqCopy.WorkingDir, entry); err != nil {
_ = revert()
return history.Entry{}, err
}
return entry, nil
}

4
internal/regex/doc.go Normal file
View File

@@ -0,0 +1,4 @@
// Package regex provides the request, preview summary, and supporting types for the
// `renamer regex` command. The concrete planning and execution logic will be added as the
// feature progresses through later phases.
package regex

69
internal/regex/engine.go Normal file
View File

@@ -0,0 +1,69 @@
package regex
import (
"fmt"
"regexp"
)
// Engine encapsulates a compiled regex pattern and parsed template for reuse across candidates.
type Engine struct {
re *regexp.Regexp
tmpl template
groups int
}
// NewEngine compiles the regex pattern and template into a reusable Engine instance.
func NewEngine(pattern, tmpl string) (*Engine, error) {
re, err := regexp.Compile(pattern)
if err != nil {
return nil, err
}
parsed, maxGroup, err := parseTemplate(tmpl)
if err != nil {
return nil, err
}
if maxGroup > re.NumSubexp() {
return nil, ErrTemplateGroupOutOfRange{Group: maxGroup, Available: re.NumSubexp()}
}
return &Engine{
re: re,
tmpl: parsed,
groups: re.NumSubexp(),
}, nil
}
// Apply evaluates the regex against input and renders the replacement when it matches.
// When no match occurs, matched is false without error.
func (e *Engine) Apply(input string) (output string, matchGroups []string, matched bool, err error) {
submatches := e.re.FindStringSubmatch(input)
if submatches == nil {
return "", nil, false, nil
}
rendered, err := e.tmpl.render(submatches)
if err != nil {
return "", nil, false, err
}
// Exclude the full match from the recorded match group slice.
groups := make([]string, 0, len(submatches)-1)
if len(submatches) > 1 {
groups = append(groups, submatches[1:]...)
}
return rendered, groups, true, nil
}
// ErrTemplateGroupOutOfRange indicates that the template references a capture group that the regex
// does not provide.
type ErrTemplateGroupOutOfRange struct {
Group int
Available int
}
func (e ErrTemplateGroupOutOfRange) Error() string {
return fmt.Sprintf("template references @%d but pattern only defines %d groups", e.Group, e.Available)
}

190
internal/regex/preview.go Normal file
View File

@@ -0,0 +1,190 @@
package regex
import (
"context"
"fmt"
"io"
"os"
"path/filepath"
"strings"
)
// PlannedRename represents a proposed rename resulting from preview.
type PlannedRename struct {
SourceRelative string
SourceAbsolute string
TargetRelative string
TargetAbsolute string
MatchGroups []string
Depth int
}
// Preview evaluates the regex rename request and returns a summary plus the planned operations.
func Preview(ctx context.Context, req Request, out io.Writer) (Summary, []PlannedRename, error) {
reqCopy := req
if err := reqCopy.Validate(); err != nil {
return Summary{}, nil, err
}
engine, err := NewEngine(reqCopy.Pattern, reqCopy.Template)
if err != nil {
return Summary{}, nil, err
}
summary := Summary{
LedgerMetadata: map[string]any{
"pattern": reqCopy.Pattern,
"template": reqCopy.Template,
},
Entries: make([]PreviewEntry, 0),
}
planned := make([]PlannedRename, 0)
plannedTargets := make(map[string]string)
plannedTargetsFold := make(map[string]string)
err = TraverseCandidates(ctx, &reqCopy, func(candidate Candidate) error {
summary.TotalCandidates++
rendered, groups, matched, err := engine.Apply(candidate.Stem)
if err != nil {
summary.Warnings = append(summary.Warnings, err.Error())
summary.Skipped++
summary.Entries = append(summary.Entries, PreviewEntry{
OriginalPath: candidate.RelativePath,
ProposedPath: candidate.RelativePath,
Status: EntrySkipped,
})
return nil
}
if !matched {
summary.Skipped++
summary.Entries = append(summary.Entries, PreviewEntry{
OriginalPath: candidate.RelativePath,
ProposedPath: candidate.RelativePath,
Status: EntrySkipped,
})
return nil
}
summary.Matched++
proposedName := rendered
if !candidate.IsDir && candidate.Extension != "" {
proposedName += candidate.Extension
}
dir := filepath.Dir(candidate.RelativePath)
if dir == "." {
dir = ""
}
var proposedRelative string
if dir != "" {
proposedRelative = filepath.ToSlash(filepath.Join(dir, proposedName))
} else {
proposedRelative = filepath.ToSlash(proposedName)
}
matchEntry := PreviewEntry{
OriginalPath: candidate.RelativePath,
ProposedPath: proposedRelative,
MatchGroups: groups,
}
if proposedRelative == candidate.RelativePath {
summary.Entries = append(summary.Entries, PreviewEntry{
OriginalPath: candidate.RelativePath,
ProposedPath: candidate.RelativePath,
Status: EntryNoChange,
MatchGroups: groups,
})
return nil
}
if proposedName == "" || proposedRelative == "" {
summary.Conflicts = append(summary.Conflicts, Conflict{
OriginalPath: candidate.RelativePath,
ProposedPath: proposedRelative,
Reason: ConflictInvalidTemplate,
})
summary.Skipped++
matchEntry.Status = EntrySkipped
summary.Entries = append(summary.Entries, matchEntry)
return nil
}
if existing, ok := plannedTargets[proposedRelative]; ok && existing != candidate.RelativePath {
summary.Conflicts = append(summary.Conflicts, Conflict{
OriginalPath: candidate.RelativePath,
ProposedPath: proposedRelative,
Reason: ConflictDuplicateTarget,
})
summary.Skipped++
matchEntry.Status = EntrySkipped
summary.Entries = append(summary.Entries, matchEntry)
return nil
}
casefoldKey := strings.ToLower(proposedRelative)
if existing, ok := plannedTargetsFold[casefoldKey]; ok && existing != candidate.RelativePath {
summary.Conflicts = append(summary.Conflicts, Conflict{
OriginalPath: candidate.RelativePath,
ProposedPath: proposedRelative,
Reason: ConflictDuplicateTarget,
})
summary.Skipped++
matchEntry.Status = EntrySkipped
summary.Entries = append(summary.Entries, matchEntry)
return nil
}
targetAbsolute := filepath.Join(reqCopy.WorkingDir, filepath.FromSlash(proposedRelative))
if info, statErr := os.Stat(targetAbsolute); statErr == nil {
origInfo, origErr := os.Stat(candidate.OriginalPath)
if origErr != nil || !os.SameFile(info, origInfo) {
reason := ConflictExistingFile
if info.IsDir() {
reason = ConflictExistingDir
}
summary.Conflicts = append(summary.Conflicts, Conflict{
OriginalPath: candidate.RelativePath,
ProposedPath: proposedRelative,
Reason: reason,
})
summary.Skipped++
matchEntry.Status = EntrySkipped
summary.Entries = append(summary.Entries, matchEntry)
return nil
}
}
plannedTargets[proposedRelative] = candidate.RelativePath
plannedTargetsFold[casefoldKey] = candidate.RelativePath
matchEntry.Status = EntryChanged
summary.Entries = append(summary.Entries, matchEntry)
summary.Changed++
planned = append(planned, PlannedRename{
SourceRelative: candidate.RelativePath,
SourceAbsolute: candidate.OriginalPath,
TargetRelative: proposedRelative,
TargetAbsolute: targetAbsolute,
MatchGroups: groups,
Depth: candidate.Depth,
})
if out != nil {
fmt.Fprintf(out, "%s -> %s\n", candidate.RelativePath, proposedRelative)
}
return nil
})
if err != nil {
return Summary{}, nil, err
}
return summary, planned, nil
}

69
internal/regex/request.go Normal file
View File

@@ -0,0 +1,69 @@
package regex
import (
"errors"
"fmt"
"os"
"path/filepath"
"time"
)
// Request captures the inputs required to evaluate regex-based rename operations.
type Request struct {
WorkingDir string
Pattern string
Template string
IncludeDirectories bool
Recursive bool
IncludeHidden bool
Extensions []string
DryRun bool
AutoConfirm bool
Timestamp time.Time
}
// NewRequest constructs a Request with the supplied working directory and defaults the
// timestamp to the current UTC time. Additional fields should be set by the caller.
func NewRequest(workingDir string) Request {
return Request{
WorkingDir: workingDir,
Timestamp: time.Now().UTC(),
}
}
// Validate ensures the request has usable defaults and a resolvable working directory.
func (r *Request) Validate() error {
if r == nil {
return errors.New("regex request cannot be nil")
}
if r.Pattern == "" {
return errors.New("regex pattern is required")
}
if r.WorkingDir == "" {
cwd, err := os.Getwd()
if err != nil {
return fmt.Errorf("determine working directory: %w", err)
}
r.WorkingDir = cwd
}
if !filepath.IsAbs(r.WorkingDir) {
abs, err := filepath.Abs(r.WorkingDir)
if err != nil {
return fmt.Errorf("resolve working directory: %w", err)
}
r.WorkingDir = abs
}
info, err := os.Stat(r.WorkingDir)
if err != nil {
return fmt.Errorf("stat working directory: %w", err)
}
if !info.IsDir() {
return fmt.Errorf("working directory %q is not a directory", r.WorkingDir)
}
return nil
}

47
internal/regex/summary.go Normal file
View File

@@ -0,0 +1,47 @@
package regex
// Summary describes the outcome of previewing or applying a regex rename request.
type Summary struct {
TotalCandidates int
Matched int
Changed int
Skipped int
Conflicts []Conflict
Warnings []string
Entries []PreviewEntry
LedgerMetadata map[string]any
}
// ConflictReason enumerates reasons a proposed rename cannot proceed.
type ConflictReason string
const (
ConflictDuplicateTarget ConflictReason = "duplicate_target"
ConflictExistingFile ConflictReason = "existing_file"
ConflictExistingDir ConflictReason = "existing_directory"
ConflictInvalidTemplate ConflictReason = "invalid_template"
)
// Conflict reports a blocked rename candidate to the CLI and callers.
type Conflict struct {
OriginalPath string
ProposedPath string
Reason ConflictReason
}
// EntryStatus captures the preview disposition for a candidate path.
type EntryStatus string
const (
EntryChanged EntryStatus = "changed"
EntryNoChange EntryStatus = "no_change"
EntrySkipped EntryStatus = "skipped"
)
// PreviewEntry documents a single rename candidate and the proposed output.
type PreviewEntry struct {
OriginalPath string
ProposedPath string
Status EntryStatus
MatchGroups []string
}

109
internal/regex/template.go Normal file
View File

@@ -0,0 +1,109 @@
package regex
import (
"fmt"
"strconv"
"strings"
)
type templateSegment struct {
literal string
group int
}
const literalSegment = -1
// template represents a parsed replacement template with capture placeholders.
type template struct {
segments []templateSegment
}
// parseTemplate converts a string containing literal text, numbered placeholders (@0, @1, ...),
// and escaped @@ sequences into a template structure. It returns the template, the highest
// placeholder index encountered, or an error when syntax is invalid.
func parseTemplate(input string) (template, int, error) {
segments := make([]templateSegment, 0)
var literal strings.Builder
maxGroup := 0
i := 0
for i < len(input) {
ch := input[i]
if ch != '@' {
literal.WriteByte(ch)
i++
continue
}
// Flush any buffered literal before handling placeholder/escape.
flushLiteral := func() {
if literal.Len() == 0 {
return
}
segments = append(segments, templateSegment{literal: literal.String(), group: literalSegment})
literal.Reset()
}
if i+1 >= len(input) {
return template{}, 0, fmt.Errorf("dangling @ at end of template")
}
next := input[i+1]
if next == '@' {
flushLiteral()
literal.WriteByte('@')
i += 2
continue
}
j := i + 1
for j < len(input) && input[j] >= '0' && input[j] <= '9' {
j++
}
if j == i+1 {
return template{}, 0, fmt.Errorf("invalid placeholder at offset %d", i)
}
indexStr := input[i+1 : j]
index, err := strconv.Atoi(indexStr)
if err != nil {
return template{}, 0, fmt.Errorf("invalid placeholder index @%s", indexStr)
}
flushLiteral()
segments = append(segments, templateSegment{group: index})
if index > maxGroup {
maxGroup = index
}
i = j
}
if literal.Len() > 0 {
segments = append(segments, templateSegment{literal: literal.String(), group: literalSegment})
}
return template{segments: segments}, maxGroup, nil
}
// render produces the output string for a given set of submatches. The slice must contain the
// full match at index 0 followed by capture groups. Missing groups (e.g., optional matches)
// expand to empty strings. Referencing a group index beyond the available matches returns an error.
func (t template) render(submatches []string) (string, error) {
var builder strings.Builder
for _, segment := range t.segments {
if segment.group == literalSegment {
builder.WriteString(segment.literal)
continue
}
if segment.group >= len(submatches) {
return "", ErrUndefinedPlaceholder{Index: segment.group}
}
builder.WriteString(submatches[segment.group])
}
return builder.String(), nil
}

View File

@@ -0,0 +1,86 @@
package regex
import (
"context"
"io/fs"
"path/filepath"
"strings"
"github.com/rogeecn/renamer/internal/traversal"
)
// Candidate represents a file or directory subject to regex evaluation.
type Candidate struct {
RelativePath string
OriginalPath string
BaseName string
Stem string
Extension string
IsDir bool
Depth int
}
// TraverseCandidates walks the working directory and invokes fn for each eligible candidate.
func TraverseCandidates(ctx context.Context, req *Request, fn func(Candidate) error) error {
if err := req.Validate(); err != nil {
return err
}
extensions := make(map[string]struct{}, len(req.Extensions))
for _, ext := range req.Extensions {
lower := strings.ToLower(ext)
extensions[lower] = struct{}{}
}
walker := traversal.NewWalker()
return walker.Walk(
req.WorkingDir,
req.Recursive,
req.IncludeDirectories,
req.IncludeHidden,
0,
func(relPath string, entry fs.DirEntry, depth int) error {
select {
case <-ctx.Done():
return ctx.Err()
default:
}
isDir := entry.IsDir()
name := entry.Name()
stem := name
ext := ""
if !isDir {
if dot := strings.IndexRune(name, '.'); dot > 0 {
ext = name[dot:]
stem = name[:dot]
}
if len(extensions) > 0 {
lower := strings.ToLower(ext)
if _, ok := extensions[lower]; !ok {
return nil
}
}
}
rel := filepath.ToSlash(relPath)
if rel == "." {
return nil
}
candidate := Candidate{
RelativePath: rel,
OriginalPath: filepath.Join(req.WorkingDir, relPath),
BaseName: name,
Stem: stem,
Extension: ext,
IsDir: isDir,
Depth: depth,
}
return fn(candidate)
},
)
}

View File

@@ -0,0 +1,30 @@
package regex
import "fmt"
// ValidateTemplate ensures the parsed template does not reference capture groups beyond the
// pattern's capabilities and returns a descriptive error for CLI presentation.
func ValidateTemplate(engine *Engine, tmpl template) error {
if engine == nil {
return fmt.Errorf("internal error: regex engine not initialized")
}
max := 0
for _, segment := range tmpl.segments {
if segment.group > max {
max = segment.group
}
}
if max > engine.groups {
return ErrTemplateGroupOutOfRange{Group: max, Available: engine.groups}
}
return nil
}
// ErrUndefinedPlaceholder indicates that the template references a group with no match result.
type ErrUndefinedPlaceholder struct {
Index int
}
func (e ErrUndefinedPlaceholder) Error() string {
return fmt.Sprintf("template references @%d but the pattern did not produce that group", e.Index)
}