huge amount of work on fixing issues with ambiguity and adding much smarter heuristics, updated docs

Author: ndbroadbent

README.md

@@ -46,7 +46,7 @@ See [MCP Server documentation](https://docspring.github.io/renamify/mcp/overview
 
 ## Features
 
-- **Smart Case Conversion**: Automatically detects and converts between different case styles (snake_case, kebab-case, camelCase, PascalCase, SCREAMING_SNAKE_CASE, Train-Case, Title Case, dot.case)
+- **Smart Case Conversion**: Automatically detects and converts between different case styles (snake_case, kebab-case, camelCase, PascalCase, SCREAMING_SNAKE_CASE, Train-Case, Title Case, dot.case, lowercase, UPPERCASE)
 - **Safe by default**: Plan → Review → Apply workflow prevents accidents
 - **Built-in undo/redo**: Full history tracking separate from git. No need to git stash or commit with `--no-verify` before renaming.
 - **File and directory renaming**: Rename everything in one atomic operation
@@ -73,6 +73,12 @@ renamify plan myProject betterName --preview diff
 # Exclude matches in comments and TODO lines
 renamify plan old_name new_name --exclude-matching-lines '^//'
 renamify plan old_name new_name --exclude-matching-lines '(TODO|FIXME)'
+
+# Skip renaming files and directories
+renamify plan old_name new_name --no-rename-paths
+
+# Ignore ambiguous/mixed-case identifiers
+renamify plan old_name new_name --ignore-ambiguous
 ```
 
 ## Demo
@@ -138,6 +144,7 @@ The MCP server and VS Code extension depend on the CLI and must maintain version
 - **Patch version**: Independent, can be any value
 
 #### Examples
+
 - CLI `2.3.1` → MCP `2.0.5` ✅ (major matches, minor 0 ≤ 3)
 - CLI `2.3.1` → MCP `2.3.9` ✅ (major matches, minor 3 ≤ 3)
 - CLI `2.3.1` → MCP `2.4.0` ❌ (minor 4 > 3, might use unavailable features)
@@ -146,6 +153,7 @@ The MCP server and VS Code extension depend on the CLI and must maintain version
 ### Version Check
 
 The CLI provides version information via:
+
 ```bash
 renamify version --output json
 # {"name":"renamify","version":"0.1.0"}
@@ -217,16 +225,10 @@ cargo clippy --all-targets --all-features
 git commit  # lefthook will run checks pre-commit
 ```
 
-## Help Wanted
+### Contributing
 
-- **Package Managers**: Help us get Renamify into Homebrew, AUR, Scoop, Chocolatey, etc.
-- **Language-Specific Features**: Contribute language-aware renaming (imports, modules, namespaces)
 - **Documentation**: Help improve our docs, add more examples, fix any inaccuracies
 - **Bug Reports**: Found an issue? Please [report it](https://github.com/DocSpring/renamify/issues)!
-
-### Contributing
-
-- Open an issue if you find a bug or have a feature request
 - PRs welcome! All checks must pass (formatting, linting, tests)
 - We use [lefthook](https://github.com/evilmartians/lefthook) for git hooks
 

docs/.vscode/launch.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.0",
+  "version": "0.1.0",
   "configurations": [
     {
       "command": "./node_modules/.bin/astro dev",

docs/astro.config.mjs

@@ -41,8 +41,8 @@ export default defineConfig({
             { label: "Self-Hosting Demo", slug: "self-hosting-demo" },
             { label: "Quick Start", slug: "quick-start" },
             {
-              label: "Why Not Search and Replace?",
-              slug: "why-not-search-and-replace",
+              label: "Rename vs. Replace",
+              slug: "rename-vs-replace",
             },
             { label: "FAQ", link: "/#frequently-asked-questions" },
           ],
@@ -71,6 +71,7 @@ export default defineConfig({
             },
             { label: "Safety Features", slug: "features/safety" },
             { label: "Filtering and Ignore Rules", slug: "features/filtering" },
+            { label: "Resolving Case Ambiguity", slug: "features/ambiguity-resolution" },
           ],
         },
         {
@@ -79,6 +80,7 @@ export default defineConfig({
             { label: "init", slug: "commands/init" },
             { label: "search", slug: "commands/search" },
             { label: "rename", slug: "commands/rename" },
+            { label: "replace", slug: "commands/replace" },
             { label: "plan", slug: "commands/plan" },
             { label: "apply", slug: "commands/apply" },
             { label: "dry-run", slug: "commands/dry-run" },

docs/src/content/docs/commands/plan.mdx

@@ -29,6 +29,7 @@ renamify plan <OLD> <NEW> [PATHS]... [OPTIONS]
 - `--exclude <PATTERNS>` - Skip files matching these glob patterns
 - `--no-rename-files` - Don't rename matching files
 - `--no-rename-dirs` - Don't rename matching directories
+- `--no-rename-paths` - Don't rename files or directories (equivalent to --no-rename-files --no-rename-dirs)
 
 ### Case Styles
 - `--exclude-styles <STYLES>` - Exclude specific case styles from the default set

docs/src/content/docs/commands/rename.mdx

@@ -30,6 +30,7 @@ renamify rename <OLD> <NEW> [PATHS]... [OPTIONS]
 - `--exclude <PATTERNS>` - Skip files matching these glob patterns
 - `--no-rename-files` - Don't rename matching files
 - `--no-rename-dirs` - Don't rename matching directories
+- `--no-rename-paths` - Don't rename files or directories (equivalent to --no-rename-files --no-rename-dirs)
 
 ### Root Directory
 - `--rename-root` - Allow renaming the root project directory (requires confirmation)
@@ -39,6 +40,7 @@ renamify rename <OLD> <NEW> [PATHS]... [OPTIONS]
 - `--exclude-styles <STYLES>` - Exclude specific case styles from the default set
 - `--include-styles <STYLES>` - Add additional case styles to the active set
 - `--only-styles <STYLES>` - Use only these case styles, ignoring defaults
+- `--ignore-ambiguous` - Ignore mixed-case/ambiguous identifiers that don't match standard patterns
 
 ### Match Control
 - `--exclude-match <PATTERNS>` - Skip specific matches (e.g., compound words to ignore)
@@ -118,6 +120,18 @@ renamify rename config settings \
   --exclude-match ConfigurationManager,ConfigService
 ```
 
+### Content-Only Rename (No Path Changes)
+```bash
+# Only modify file contents, don't rename files or directories
+renamify rename old_api new_api --no-rename-paths
+```
+
+### Ignore Ambiguous Identifiers
+```bash
+# Skip mixed-case identifiers that don't match standard patterns
+renamify rename userName user_name --ignore-ambiguous
+```
+
 ## Interactive Flow
 
 When you run `rename`, this is what happens:

docs/src/content/docs/commands/replace.mdx

@@ -0,0 +1,215 @@
+---
+title: renamify replace
+description: Simple regex or literal string replacement across your codebase
+---
+
+The `replace` command performs straightforward search-and-replace operations using regular expressions or literal strings. Unlike the `rename` command which handles case transformations, `replace` is for mechanical replacements where you control the exact pattern and replacement.
+
+## Usage
+
+```bash
+renamify replace <PATTERN> <REPLACEMENT> [PATHS]... [OPTIONS]
+```
+
+## Arguments
+
+- `<PATTERN>` - Search pattern (regex by default, literal with --no-regex)
+- `<REPLACEMENT>` - Replacement string (supports $1, $2 capture groups in regex mode)
+- `[PATHS]...` - Search paths (files or directories)
+
+## Options
+
+### Pattern Mode
+- `--no-regex` - Treat pattern as literal string instead of regex
+
+### Preview and Confirmation
+- `--preview <FORMAT>` - Show preview before confirmation (table, diff, json, none) [default: table]
+- `--dry-run` - Show preview only, don't apply changes
+- `--yes` / `-y` - Skip confirmation prompt and apply immediately
+- `--large` - Acknowledge large changes (>500 files or >100 renames)
+
+### File Processing
+- `--include <PATTERNS>` - Only process files matching these glob patterns
+- `--exclude <PATTERNS>` - Skip files matching these glob patterns
+- `--no-rename-files` - Don't rename matching files
+- `--no-rename-dirs` - Don't rename matching directories
+- `--no-rename-paths` - Don't rename files or directories
+
+### Line Filtering
+- `--exclude-matching-lines <REGEX>` - Skip matches on lines matching this regex pattern
+
+### Safety and Git
+- `--commit` - Create a git commit after applying changes
+- `--force-with-conflicts` - Force apply even with conflicts
+
+### Unrestricted Mode
+- `-u` - Disable .gitignore files
+- `-uu` - Disable all ignore files, include hidden files
+- `-uuu` - Disable all ignore files, include hidden files, process binary files
+
+## Examples
+
+### Basic Regex Replacement
+
+```bash
+# Update version numbers with regex
+renamify replace 'version: "(\d+)\.(\d+)\.(\d+)"' 'version: "$1.$2.4"'
+
+# Update import paths with capture groups
+renamify replace 'from "\./(.*)"' 'from "@local/$1"'
+
+# Fix method names
+renamify replace 'get([A-Z]\w+)ById' 'find$1ById'
+```
+
+### Literal String Mode
+
+```bash
+# Fix a typo without escaping special characters
+renamify replace --no-regex 'array[index]' 'array.at(index)'
+
+# Update exact strings
+renamify replace --no-regex 'Copyright (c) 2024' 'Copyright (c) 2025'
+
+# Replace configuration values
+renamify replace --no-regex 'localhost:3000' 'api.example.com'
+```
+
+### File Type Specific
+
+```bash
+# Only in JavaScript files
+renamify replace 'console\.log' 'logger.debug' --include "**/*.js"
+
+# Exclude test files
+renamify replace 'OLD_API' 'NEW_API' --exclude "**/*.test.*"
+```
+
+### With Line Filtering
+
+```bash
+# Skip commented lines
+renamify replace 'TODO' 'DONE' --exclude-matching-lines '^\s*//'
+
+# Only in import statements
+renamify replace '"lodash"' '"lodash-es"' --include "**/*.ts" \
+  --exclude-matching-lines '^(?!import)'
+```
+
+### Large Codebase
+
+```bash
+# Acknowledge large changes
+renamify replace 'OldComponent' 'NewComponent' --large
+
+# Dry run first to see scope
+renamify replace 'deprecated' 'legacy' --dry-run
+```
+
+## Regex Features
+
+The replace command uses Rust's regex crate, which supports:
+
+### Capture Groups
+
+```bash
+# Swap parameters
+renamify replace 'fn\((\w+), (\w+)\)' 'fn($2, $1)'
+
+# Extract and reformat
+renamify replace 'user_(\d+)_profile' 'profile/user/$1'
+```
+
+### Character Classes
+
+```bash
+# Match any whitespace
+renamify replace '\s+' ' '
+
+# Match word boundaries
+renamify replace '\btest\b' 'spec'
+```
+
+### Quantifiers
+
+```bash
+# Optional trailing comma
+renamify replace ',?\s*\]' ']'
+
+# One or more digits
+renamify replace 'id:\d+' 'id:REDACTED'
+```
+
+### Lookarounds
+
+```bash
+# Positive lookahead
+renamify replace '(\w+)(?=\()' 'async $1'
+
+# Negative lookbehind
+renamify replace '(?<!\\)n' '\\n'
+```
+
+## Important Notes
+
+### No Case Transformation
+
+Unlike `rename`, the `replace` command does NOT:
+- Transform between case styles (snake_case, camelCase, etc.)
+- Respect token boundaries
+- Handle acronyms specially
+- Generate style variants
+
+If you need these features, use the `rename` command instead.
+
+### File Renaming
+
+When pattern matches in filenames:
+- Files are renamed after content changes
+- Directories are renamed depth-first
+- Collisions are detected and reported
+
+### Escaping in Regex Mode
+
+Common patterns that need escaping:
+- Dots: `\.` for literal dot
+- Parentheses: `\(` and `\)` for literal
+- Square brackets: `\[` and `\]`
+- Special chars: `\$`, `\^`, `\*`, `\+`, `\?`
+
+Use `--no-regex` to avoid escaping entirely.
+
+## Comparison with rename
+
+| Task | Use `rename` | Use `replace` |
+|------|--------------|---------------|
+| Rename a variable across case styles | ✅ | ❌ |
+| Update version numbers | ❌ | ✅ |
+| Fix typos | ❌ | ✅ |
+| Refactor class names | ✅ | ❌ |
+| Update config values | ❌ | ✅ |
+| Change import paths | ❌ | ✅ |
+| Rename functions preserving style | ✅ | ❌ |
+
+## Interactive Flow
+
+Similar to `rename`, the replace command follows this flow:
+
+1. **Scanning**: Searches for pattern matches
+2. **Preview**: Shows planned changes in chosen format
+3. **Confirmation**: Prompts "Apply these changes? [y/N]:"
+4. **Apply**: Makes changes atomically
+5. **Results**: Shows operation ID for undo
+
+## Exit Codes
+
+- `0` - Success
+- `1` - Conflicts detected (use `--force-with-conflicts` to override)
+- `2` - Invalid input or arguments
+- `3` - Internal error or system issue
+
+## See Also
+
+- [rename](./rename) - Case-aware identifier renaming
+- [plan](./plan) - Create a replacement plan without applying
+- [undo](./undo) - Revert the last operation

docs/src/content/docs/commands/search.mdx

@@ -29,12 +29,22 @@ renamify search <term> [paths...] [options]
 - `--include-styles <styles>` - Include additional case styles (title, dot)
 - `--only-styles <styles>` - Use only these case styles (overrides defaults)
 
-Available styles: `original`, `snake`, `kebab`, `camel`, `pascal`, `screaming-snake`, `train`, `screaming-train`, `title`, `dot`
+Available styles: `snake`, `kebab`, `camel`, `pascal`, `screaming-snake`, `train`, `screaming-train`, `title`, `dot`, `lower`, `upper`
 
 ### Line Filtering
 
 - `--exclude-matching-lines <regex>` - Skip matches on lines matching this regex pattern
 
+### File and Directory Renaming
+
+- `--no-rename-files` - Don't include file renames in search results
+- `--no-rename-dirs` - Don't include directory renames in search results
+- `--no-rename-paths` - Don't include any file or directory renames (equivalent to --no-rename-files --no-rename-dirs)
+
+### Case Detection
+
+- `--ignore-ambiguous` - Ignore mixed-case/ambiguous identifiers that don't match standard patterns
+
 ### Output Control
 
 - `--preview <format>` - Preview format: `table`, `diff`, `matches`, `summary` (default: summary)
@@ -98,6 +108,18 @@ renamify search myIdentifier --only-styles snake,kebab
 renamify search importantFunction --exclude-matching-lines "^\\s*//"
 ```
 
+### Search Without File Renames
+
+```bash
+renamify search myFunction --no-rename-paths
+```
+
+### Ignore Ambiguous Identifiers
+
+```bash
+renamify search cleanName --ignore-ambiguous
+```
+
 ### JSON Output for Processing
 
 ```bash