[FIX] Audit command return non zero exit code on missing keys and handling plural and gender

[JavedNicolas]

Following the issues : https://github.com/aissat/easy_localization/issues/766, i've updated the audit command to return a non zero exit code (1) if there is missing keys.

Summary by CodeRabbit

• Documentation

  • Audit docs updated: clearer headings, arguments table, error-code reference, and expanded Logger usage guidance.

• New Features

  • Improved audit key detection for more reliable discovery in source and translation files.

• Bug Fixes

  • Audit command now returns a non-zero exit when missing non-variable translation keys are found.

• Chores

  • Raised minimum Dart SDK requirement.

• Examples

  • Added iOS LLDB helper/import to aid debugging in example projects.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai[bot]]

Walkthrough

Adds a KeyParser to extract translation keys from JSON and Dart sources, updates the audit CLI with a new --show-warnings flag and exit behavior for non-variable missing keys, expands README audit/logger docs, adds iOS LLDB helper/init files, and raises the Dart SDK lower bound.

Changes

Cohort / File(s)	Summary
Audit CLI & Parser bin/audit/audit_command.dart, bin/audit/key_parser.dart, bin/audit.dart	Introduces KeyParser to parse translation JSON and scan Dart sources with multiple regex patterns; replaces previous inline loading/scanning logic; AuditCommand.run and its reporter now accept showWarnings (exposed as --show-warnings) and the CLI exits(1) when non-variable missing keys are found.
Documentation README.md	Reworks Audit section (promotes header), adds Arguments and Errors tables, and expands Logger guidance (custom Easy Logger usage, filtering, disabling, and custom printer) with references.
iOS LLDB helpers (example) example/ios/Flutter/ephemeral/flutter_lldb_helper.py, example/ios/Flutter/ephemeral/flutter_lldbinit	Adds LLDB Python helper that handles NOTIFY_DEBUGGER_ABOUT_RX_PAGES and an init file to import the helper.
Package config pubspec.yaml	Bumps Dart SDK lower bound in environment from >=2.12.0 to >=2.17.0.

Sequence Diagram(s)

sequenceDiagram
    participant CLI as Audit CLI
    participant Parser as KeyParser
    participant FS as File System
    participant Reporter as Reporter/Console

    CLI->>Parser: parseKeysInTranslationsDir(translationsDir)
    Parser->>FS: read JSON files & resolve linked refs
    FS-->>Parser: file contents
    Parser-->>CLI: map<lang, keys>

    CLI->>Parser: parseKeysInSourceDir(sourceDir)
    Parser->>FS: read Dart files
    FS-->>Parser: source contents
    Parser-->>CLI: used keys set

    CLI->>Reporter: compare translations vs used keys (with showWarnings)
    alt missing non-variable keys found
        Reporter->>CLI: print missing keys
        CLI->>CLI: exit(1)
    else
        Reporter->>CLI: print report (may include warnings)
    end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

• Focus areas:
  • bin/audit/key_parser.dart — regex coverage, keyword suffix handling, LocaleKeys normalization, comment-stripping and false-positive risk.
  • JSON linked-file resolution and _flatten correctness across nested structures.
  • Missing-key classification (variables-only vs non-variable) and exit(1) decision path.
  • CLI flag parsing and propagation; update/add tests for --show-warnings.
  • pubspec.yaml SDK bump implications and CI compatibility.
  • Safety and comments in example/ios/... LLDB script.

Possibly related issues

• aissat/easy_localization#766 — Adds optional non-zero exit on missing keys and aligns with the new --show-warnings/exit(1) behavior in this PR.

Possibly related PRs

• aissat/easy_localization#763 — Refactors the audit command and parsing logic; strongly related to the KeyParser and CLI changes in this PR.

Suggested reviewers

• aissat
• a1ssat

Poem

🐰 I hop through JSON nests and code,
I sniff the keys that ebbed and flowed.
I flag the gaps and softly drum,
"Report!" I cry — then nibble some. 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main objective of the PR - implementing non-zero exit codes for missing keys in the audit command, and adds support for plural and gender handling.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[JavedNicolas]

Ignoring nitpick as it will remove valuable information from the console log if we exit the command at the first missing key.

[JavedNicolas]

Right now the audit command does not ignore when the lines are commented, i need to handle this case before this PR is ready to be merged, especially if there is a non-zero exit code that can make a pipeline fail !