Release: update style of prompts for consistency

[cawpea]

No description provided.

[github-actions]

PR Review: Release - Update Style of Prompts for Consistency

Summary

This PR introduces a centralized message formatting system to standardize CLI output across the validate and fix commands. The changes significantly improve user experience through consistent color schemes, emoji usage, and structured output formatting.

Code Quality & Best Practices ✅

Strengths

1. Excellent Separation of Concerns: The new message-formatter.ts provides a clean abstraction for all CLI messaging, following the Single Responsibility Principle.

2. Consistent API Design: The msg convenience export provides a clean, functional API that's easy to use throughout the codebase.

3. Well-Tested: The addition of 382 lines of comprehensive tests for message-formatter.test.ts shows strong commitment to quality (48 test cases covering edge cases, special characters, and various message types).

4. Good Documentation: JSDoc comments are thorough and helpful, explaining parameters and return values clearly.

5. Internationalization: Translation of Japanese comments to English in backup.ts improves maintainability for international contributors.

6. Color Scheme Consistency: Using centralized COLOR_SCHEMES export ensures colors are consistent across different output utilities (diff-display.ts, styles.ts).

Code Style Adherence ✅

The code follows all standards from CLAUDE.md:

• ✅ 2-space indentation
• ✅ Semicolons enabled
• ✅ Single quotes
• ✅ Type imports used appropriately
• ✅ 100 character line width respected

Potential Issues & Concerns

1. Static State in MessageFormatter (Minor)

Location: src/utils/message-formatter.ts:49

export class MessageFormatter {
  private static verboseMode = false;

Issue: Using static state for verboseMode could cause issues in testing or if the module is used in multiple contexts. While this is likely fine for a CLI tool, it's worth noting.

Suggestion: Consider passing verbose mode as a parameter to methods that need it, or document that this is intentional for CLI usage.

2. Missing Type Safety for Emojis (Minor)

Location: src/utils/message-formatter.ts:32-43

The EMOJIS object is not exported, which is fine, but some emojis defined aren't used by any public methods (e.g., skip, backup have dedicated methods, but search, fix, file, stats are only used internally).

Suggestion: This is actually well-designed as-is. No action needed.

3. Regex Efficiency in formatCodeLine (Minor)

Location: src/utils/styles.ts:176-198

The function creates multiple regex instances on every line formatting call:

keywords.forEach((keyword) => {
  const regex = new RegExp(`\\b(${keyword})\\b`, 'g');
  formattedLine = formattedLine.replace(regex, chalk.cyan('$1'));
});

Impact: Low - this is for CLI output which is not performance-critical.

Suggestion: For micro-optimization, pre-compile regexes as constants outside the function.

4. Code Duplication in Preview Display (Minor)

Location: src/utils/prompt.ts:113-186

The displayFixPreview function has grown quite large with multiple switch cases. Some logic could be extracted into helper functions.

Suggestion: Consider extracting helpers like displayInsertionPreview(), displayReplacementPreview(), etc. for better maintainability.

Performance Concerns

✅ No significant performance concerns. All changes are in CLI output formatting which is inherently I/O bound and not performance-critical.

Security Concerns

✅ No security issues identified. The changes are primarily cosmetic and don't introduce:

• User input handling vulnerabilities
• File system security issues
• Injection vulnerabilities

The code properly escapes special characters in regex patterns and uses chalk for safe terminal output.

Test Coverage

Strengths ✅

1. Comprehensive Coverage: 48 test cases added for message-formatter.ts covering:

   • Basic formatting (error, warning, info, success, neutral)
   • Verbose mode toggle
   • Error details with locations
   • Summary formatting
   • Edge cases (empty strings, special characters, HTML, Unicode)

2. Updated Existing Tests: Tests in diff-display.test.ts updated to handle colored output.

Gaps ⚠️

1. Integration Testing: No integration tests verifying the actual CLI output in validate and fix commands with the new formatter.

2. Visual Testing: No snapshot tests to ensure formatting remains consistent across changes.

Recommendation: Consider adding snapshot tests for full CLI output examples to catch unintended formatting changes.

Documentation

Strengths ✅

1. Updated docs/user-guide/cli-usage.md to document the new color-coded output.
2. Clear commit messages following Conventional Commits standard.

Missing ⚠️

1. Migration Guide: No documentation about the changes for existing users (though this is cosmetic and shouldn't break anything).

2. Color Scheme Reference: Consider documenting the full color scheme somewhere for reference:

   • Red: Errors
   • Yellow: Warnings
   • Green: Success
   • Cyan: Info
   • Gray: Debug/Dim

Recommendation: Add a section to the CLI usage guide showing the color scheme or include it in README.

Architectural Considerations

Strengths ✅

1. Centralization: Moving from scattered ANSI codes to a centralized formatter is a significant architectural improvement.

2. Extensibility: The design makes it easy to add new message types or change color schemes globally.

3. Backwards Compatibility: Changes are internal-only and don't affect the public API.

Observations

1. Diff Display Grouping: The change to group diff changes by type (commit 3f891eb) improves readability significantly. The implementation correctly buffers removed/added lines and flushes them in the right order.

Specific Code Review Comments

src/utils/message-formatter.ts

Line 226-237: The msg convenience export is well-designed, but consider adding a type definition:

export interface MessageFormatterAPI {
  error: (text: string) => string;
  warning: (text: string) => string;
  // ... etc
}

export const msg: MessageFormatterAPI = { /* ... */ };

This would provide better autocomplete and type safety.

src/utils/diff-display.ts

Line 46-61: The change buffering logic is clever:

if (removedLines.length > 0 || addedLines.length > 0) {
  flushChanges();
}

However, this could be extracted to a helper method for clarity:

private flushBufferedChanges() {
  if (this.removedLines.length > 0 || this.addedLines.length > 0) {
    this.flushChanges();
  }
}

src/cli/fix.ts

Line 90: Good addition of verbose mode support:

msg.setVerbose(options.verbose);

Line 217: The verbose check is correct:

if (lineDelta !== 0 && options.verbose) {

However, since msg.debug() already checks verbose mode internally, this could be simplified to:

if (lineDelta !== 0) {
  console.log(msg.debug(`   Line delta: ${lineDelta > 0 ? '+' : ''}${lineDelta}`));
}

Overall Assessment

✅ Approve with Minor Suggestions

This is a high-quality PR that significantly improves the user experience of the CLI tool. The changes are:

1. Well-architected and maintainable
2. Thoroughly tested
3. Properly documented
4. Follow coding standards
5. Don't introduce security vulnerabilities
6. Have no significant performance impact

Priority Recommendations

Before Merge (Optional but Recommended):

1. Add snapshot tests for CLI output examples
2. Document the color scheme in user-facing docs

Post-Merge (Nice to Have):

1. Consider extracting large switch statements in displayFixPreview to helper functions
2. Pre-compile regex patterns in formatCodeLine for micro-optimization
3. Add type interface for msg export

Testing Recommendation

Before merging, please verify:

1. ✅ All unit tests pass: npm test
2. ✅ Linting passes: npm run lint
3. ✅ Type checking passes: npm run type-check
4. ✅ Demo validation works: npm run demo:validate:invalid (should show colored output)

---

Great work on improving the developer experience! The centralized formatting system will make future maintenance much easier. 🎉

[github-actions]

🎉 This PR is included in version 0.4.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀