Make Delta Reporting Git-Aware Instead of Cache-Aware

[rohaquinlop]

The current delta display is useful, but it is anchored to the last local complexipy execution, not to the actual code changes being prepared in git.

Today, the delta text shown in the CLI is derived from .complexipy_cache and compares the current function complexity against the previous cached run for the same target set. That means:

• the reported delta depends on whether complexipy was executed before,
• the baseline is local and ephemeral rather than tied to repository history,
• the numbers can drift from the code that is actually being reviewed or committed,
• staged changes are not treated as a first-class comparison target.

This works as a lightweight local hint, but it is not the best model for understanding the complexity impact of the current change set.

Proposed Follow-up

Add git-aware delta reporting so complexipy can compare the current analysis against repository state instead of only against the last cached execution.

The main use case should be:

• compare the current staged changes against HEAD, or
• compare the current working tree against a git reference / index state.

In practice, the most useful default may be something like:

complexipy . --delta-staged

or a more general interface such as:

complexipy . --delta-against HEAD
complexipy . --delta-against --cached

The goal is for delta output to answer: "What complexity changed in the code I am about to commit?" rather than "What changed since the last time I ran complexipy locally?"

Why This Is Better

• Git provides a stable, reviewable baseline.
• The result matches the developer workflow around staging, diffing, and committing.
• Delta output becomes reproducible across runs and machines.
• The feature becomes much more useful in pre-commit hooks and CI.

Important Constraints

• Do not break the existing cache-based behavior abruptly if users already rely on it.
• Decide whether git-aware deltas should replace the current default or live behind a new flag first.
• Handle files that are:
  • newly added,
  • deleted,
  • renamed,
  • partially staged.
• Be explicit about the comparison source:
  • working tree vs HEAD,
  • index/staged changes vs HEAD,
  • working tree vs index,
  • explicit git ref vs current tree.
• Keep behavior predictable outside a git repository.

Suggested Implementation Direction

1. Separate "delta source" from the current cache implementation.
2. Introduce a git-backed delta mode that reads file contents from HEAD and/or the index.
3. Reuse the existing function-level diff model where possible so the output stays familiar.
4. Support staged-only comparison as a first-class workflow.
5. Keep the current cache-based delta as a fallback or legacy mode until the new behavior settles.

Recommended Decisions

• Staged deltas should be the primary workflow, but not the implicit default on every run. A dedicated flag such as --delta-staged is clearer and avoids surprising users who expect today's plain analysis output.
• The current cache-based delta should remain available, but only as an explicit legacy/local-history mode. It is still useful as a lightweight personal comparison, but it should no longer be presented as the main interpretation of "what changed".
• This should converge with --diff <git-ref> rather than becoming a completely separate feature. Conceptually both are the same capability: compare current complexity results against another git-backed baseline. The interface should evolve toward one comparison model with multiple sources such as HEAD, another ref, or the index.
• Delta output should show only changed functions by default. That keeps the signal focused on regressions, improvements, additions, and removals. If broader context is useful later, it can be added as an opt-in verbose mode.

Proposed UX Direction

Treat comparison as one feature with different baseline selectors. For example:

complexipy . --diff HEAD
complexipy . --diff main
complexipy . --diff --staged
complexipy . --diff --cached

or, if the current --diff <git-ref> shape is too limiting, introduce a single new comparison interface and map the old flag into it as a compatibility layer.

The key product decision is:

• normal complexipy . keeps its current analysis behavior,
• git-aware comparison is explicitly requested,
• staged comparison becomes the preferred workflow for "what am I about to commit?",
• cache-based deltas become secondary and explicit.