feat(cli): migrate from argparse to Typer

[jychp]

Type of change

• New feature (non-breaking change that adds functionality)
• Refactoring (no functional changes)
• Documentation update

Summary

Migrate the Cartography CLI from argparse to Typer for improved user experience.

Key improvements:

• Organized help panels: 100+ CLI options are now grouped by category (Core, Neo4j, AWS, Azure, GitHub, etc.) instead of one overwhelming list
• Dynamic contextual help: cartography --selected-modules aws --help shows only AWS-related options, making it easier to discover relevant parameters
• Shell autocompletion: Built-in support for bash, zsh, fish, and PowerShell via --install-completion
• 100% backward compatible: All existing CLI arguments work unchanged

Implementation details:

• Pre-parses --selected-modules from argv before building the Typer app to enable dynamic help filtering
• Uses hidden=True on options whose panels aren't relevant to selected modules
• Maintains class-based CLI structure for dependency injection and testing with mock Sync objects

Related issues or links

• Addresses user feedback about overwhelming --help output
• Aligns with cartography-rules which already uses Typer
• Closes Improve configuration and secrets management #1072
• Replace refactor: using dynaconf for settings management #1449

Note: typer allow configuration from var env that we will be able to enable in a following PR.

How was this tested?

• All lint checks pass (make test_lint)
• Integration test tests/integration/cartography/test_cli.py passes
• Manual testing:

  # Full help shows all panels
  cartography --help
  
  # Dynamic help shows only relevant panels
  cartography --selected-modules aws --help
  cartography --selected-modules aws,github --help
  
  # Shell completion works
  cartography --install-completion

Checklist

General

• I have read the contributing guidelines.
• The linter passes locally (make lint).
• I have added/updated tests that prove my fix is effective or my feature works.

Proof of functionality

• New or updated unit/integration tests.

Notes for reviewers

This is a large diff due to the migration from argparse to Typer, but the logic is straightforward:

1. Each option is now defined using typer.Option() with rich_help_panel for grouping
2. The hidden parameter enables dynamic help filtering based on --selected-modules
3. The credential resolution logic (reading env vars, etc.) is unchanged

The contributor documentation has been updated to show the new Typer patterns for adding CLI options.

[jychp]

[cubic-dev-ai]

2 issues found across 8 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="docs/agents/create-module.md">

<violation number="1" location="docs/agents/create-module.md:543">
P2: The new guidance passes the API key value into Config, but the later validation snippet still treats `config.your_service_api_key` as an environment variable name. Update one of these sections so the docs are internally consistent (e.g., use `config.your_service_api_key` directly in validation or keep Config storing the env var name).</violation>
</file>

<file name="docs/root/usage/index.md">

<violation number="1" location="docs/root/usage/index.md:4">
P2: The new `cli` toctree entry points to a missing document. Add the corresponding `docs/root/usage/cli.*` file (or adjust the toctree entry to the correct path) so the Sphinx build doesn’t fail with a missing document.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="tests/integration/cartography/intel/aws/iam/test_iam.py">

<violation number="1" location="tests/integration/cartography/intel/aws/iam/test_iam.py:51">
P1: Rule violated: **Tests and documentation quality**

Integration tests must validate graph outcomes and should not mock Cartography internals. This test mocks cartography.sync.run_with_config (an internal function) and asserts parameters passed to the mock instead of checking graph data, violating the “Mock only external APIs” and “Test outcomes, not implementation” clauses.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[kunaals]

looks almost good to go! i just see one issue: spacelift_ec2_ownership_aws_profile is missing from Config: the CLI option is defined but the value is never passed to the Config object

im not going to stamp just yet i think @achantavy should probably stamp this one

[achantavy]

minor things but this is super exciting.

just on sync.py we can update the typehints and imports to clean up a bit now that things are simplified and explicit

[achantavy]

very cool

[achantavy]

nit: new annotation style e.g. str | None

[achantavy]

Previously we were taking the raw argparse Namespace object and passing that to sync.py's run_with_config. Now that we're explicitly creating a more type-safe Config object, we can update sync.py to remove the argparse.Namespace import and simplify the type hints.