Skip to content

Add verbose cache miss diagnostics #614

@mattiasgronlund

Description

@mattiasgronlund

Problem or motivation

When rumdl cache lookups miss, verbose output currently does not explain why. This makes cache behavior difficult to debug, especially when users are trying to confirm that repeated runs are benefiting from the cache or understand why a supposedly unchanged file is being linted again.

Useful cache miss causes include:

  • cache disabled
  • missing cache entry
  • unreadable cache entry
  • invalid cache entry JSON
  • file content hash changed
  • configuration hash changed
  • enabled rules hash changed
  • rumdl version changed
  • cache lock unavailable

Without these diagnostics, users and maintainers have to infer cache behavior indirectly from timings or manually inspect .rumdl_cache.

Proposed solution

Add structured cache miss reasons and print them in verbose mode.

  • Add a CacheMissReason enum in src/cache.rs.
  • Add LintCache::get_with_reason(...) -> Result<Vec<LintWarning>, CacheMissReason>.
  • Preserve existing cache hit behavior while returning precise miss reasons.
  • Update file processing to print messages like Cache miss for path/to/file.md: configuration hash changed when --verbose is active and output is not quiet/silent.
  • Add tests for representative miss reasons such as missing cache entries and config changes.

Alternatives considered

Keep the current Option<Vec<LintWarning>> cache API and only log generic misses. That is simpler, but it does not solve the diagnostic problem because all miss causes collapse to None.

Feature category

Performance

Example markdown

Contribution

  • I would be willing to submit a PR to implement this feature

Additional context

No response

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions