fix(cli): add version flags, restore -h, and speed up --help

[jychp]

Type of change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Refactoring (no functional changes)
• Documentation update
• Other (please describe):

Summary

• Adds --version output to the main CLI.
• Keeps -v/--verbose behavior and adds -d/--debug as an alias to the same option.
• Marks --verbose as deprecated in help text (planned removal in v1.0.0).
• Restores short help flag -h alongside --help.
• Fixes slow cartography --help startup by lazy-loading heavy sync/validation imports and deferring default sync construction until command execution.

Related issues or links

• Fixes cartography -v [--version] #2358
• Fixes Regression: cartography -h no longer works after PR #2333 #2364
• Fixes cartography --help is very slow #2365

Breaking changes

None.

How was this tested?

• UV_CACHE_DIR=/tmp/uv-cache uv run pytest -q tests/integration/cartography/test_cli.py
• UV_CACHE_DIR=/tmp/uv-cache uv run pytest -q tests/integration/cartography/intel/aws/iam/test_iam.py::test_permission_relationships_file_cli
• Manual timing check:
  • time UV_CACHE_DIR=/tmp/uv-cache uv run cartography --help

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

• Screenshot showing the graph before and after changes.
• New or updated unit/integration tests.

If you are adding or modifying a synced entity

• Included Cartography sync logs from a real environment demonstrating successful synchronization of the new/modified entity. Logs should show:
  • The sync job starting and completing without errors
  • The number of nodes/relationships created or updated
  • Example:

    INFO:cartography.intel.aws.ec2:Loading 42 EC2 instances for region us-east-1
    INFO:cartography.intel.aws.ec2:Synced EC2 instances in 3.21 seconds
    

If you are changing a node or relationship

• Updated the schema documentation.
• Updated the schema README.

If you are implementing a new intel module

• Used the NodeSchema data model.

Notes for reviewers

• This PR intentionally avoids the larger sync registry refactor. A follow-up issue will track that (lazy module registry / import-on-demand in cartography/sync.py).

[cubic-dev-ai]

1 issue found across 6 files (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/unit/cartography/graph/test_matchlink.py">

<violation number="1" location="tests/unit/cartography/graph/test_matchlink.py:19">
P2: Rule violated: **Tests and documentation quality**

This test mocks an internal Cartography function (get_cartography_version), which violates the rule to mock only external APIs. Update the test to avoid patching internal helpers and instead assert against the real version value or another non-mocked mechanism.</violation>
</file>

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

[cubic-dev-ai]

3 issues found across 4 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="cartography/cli.py">

<violation number="1" location="cartography/cli.py:119">
P2: `--version` raises `typer.Exit`, but with `standalone_mode=False` Click doesn’t translate it into `SystemExit`, so it falls into the generic exception handler and returns `STATUS_FAILURE`. That makes `cartography --version` exit with a failure code. Consider raising `SystemExit(0)` here (or handle `typer.Exit` explicitly in `main`).</violation>
</file>

<file name="tests/integration/cartography/test_cli.py">

<violation number="1" location="tests/integration/cartography/test_cli.py:24">
P2: Rule violated: **Tests and documentation quality**

These new integration tests assert mock call counts on `sync.run`, which violates the "Test outcomes, not implementation" requirement that tests verify graph data (via check_nodes/check_rels) rather than mock interactions. Update these tests to validate resulting graph state (or other real outcomes) instead of mock call assertions.</violation>
</file>

<file name="cartography/version.py">

<violation number="1" location="cartography/version.py:20">
P1: Rule violated: **General coding rules**

Do not swallow PackageNotFoundError with a fallback return. The general coding rule requires letting exceptions bubble up instead of masking them with defaults.</violation>
</file>

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

[cubic-dev-ai]

3 issues found across 4 files (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="cartography/version.py">

<violation number="1" location="cartography/version.py:10">
P2: Returning package metadata without handling PackageNotFoundError will crash in source/dev environments where metadata is missing. Reintroduce the fallback so version lookup failure doesn’t abort the CLI.</violation>
</file>

<file name="tests/integration/cartography/test_cli.py">

<violation number="1" location="tests/integration/cartography/test_cli.py:55">
P2: Rule violated: **Tests and documentation quality**

Avoid mocking Cartography’s internal functions in tests. This test patches the internal `_build_app` method, which violates the “Mock only external APIs” requirement. Use the real CLI app behavior (e.g., invoke a real Typer app path that exits) or restructure the test so only external API calls are mocked.</violation>
</file>

<file name="tests/unit/cartography/graph/test_matchlink.py">

<violation number="1" location="tests/unit/cartography/graph/test_matchlink.py:18">
P1: Rule violated: **Tests and documentation quality**

Avoid mocking Cartography internal functions in tests; only external API calls should be mocked per “Mock only external APIs.” Replace this with a test that exercises the real `get_cartography_version` behavior (or refactor the test to avoid patching internal helpers).</violation>
</file>

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

[cubic-dev-ai]

2 issues found across 2 files (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="cartography/version.py">

<violation number="1" location="cartography/version.py:22">
P1: Rule violated: **General coding rules**

Do not suppress PackageNotFoundError here. The rule requires errors to bubble up rather than being caught and replaced with fallback values.</violation>
</file>

<file name="tests/unit/cartography/test_version.py">

<violation number="1" location="tests/unit/cartography/test_version.py:10">
P1: Rule violated: **Tests and documentation quality**

Mocking Cartography’s internal `get_release_version_and_commit_revision` violates the “Mock only external APIs” clause in Tests and documentation quality. Rewrite this test to avoid mocking internal helpers (e.g., assert against real version behavior or only mock external API calls).</violation>
</file>

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

[achantavy]

@jychp - How long does time cartography -h take to run with this change on?