Refactor: Use private fields and dynamic versioning

[mudcube]

Summary

This PR refactors the codebase to improve encapsulation and maintainability by converting private properties to private fields (using # syntax) and implementing dynamic version management for cache invalidation.

Key Changes

Private Fields Migration

• Converted all private properties to private fields (#) in:
  • GenericGenerator - improved encapsulation of config and internal methods
  • CircuitBreaker - better protection of state management
  • CliExecutor - secured command validation and parsing logic
• Updated all internal method calls to use the new private field syntax
• This provides true privacy at the language level rather than just convention

Dynamic Versioning

• Added getVersion() utility function to read version from package.json
• Replaced hardcoded cache versions ('1.0.0' and '1.0') with dynamic getVersion() calls in:
  • generate-symbols.ts
  • packages/docs-engine-cli/src/index.ts
• Updated documentation examples to show best practice of using getVersion() for cache invalidation

Type Definitions

• Added new src/lib/mdast.d.ts module augmentation file for proper TypeScript support of:
  • remark-math nodes (InlineMath, Math)
  • remark-directive nodes (ContainerDirective, LeafDirective, TextDirective)
• Removed duplicate inline type definitions from plugin files
• Imported types from centralized definition file in:
  • katex.ts and katex.test.ts
  • collapse.ts
  • reference.ts and reference.test.ts

Code Quality Improvements

• Removed redundant comments and improved code clarity
• Simplified variable naming in loops (e.g., items → categoryItems for clarity)
• Fixed type assertions in mutation operations for better type safety
• Improved test helper functions with proper type annotations
• Removed unnecessary as unknown type casts where proper types are now available

Minor Fixes

• Fixed optional chaining in image-optimization.test.ts for safer property access
• Improved error handling in openapi-formatter.ts with proper type annotations
• Cleaned up unused imports and type definitions

Benefits

• Better Encapsulation: Private fields prevent accidental external access
• Automatic Cache Invalidation: Version changes automatically invalidate caches
• Improved Type Safety: Centralized type definitions reduce duplication and errors
• Cleaner Code: Removed redundant comments and improved readability

https://claude.ai/code/session_01McEbidFvENrWTdVduD4AKN