Ownership map

Arguments: $ARGUMENTS

Turn git history into a picture of who maintains what.

Collect the facts

bash "${CLAUDE_PLUGIN_ROOT}/scripts/ownership-scan.sh" <window> <path>

<window> is 1m, 3m, 6m, 12m or all (default 3m). Upstream offered exactly these four windows; all is added because "who has ever touched this" is a different and useful question.

The script is read-only and always exits 0. Check its output before drawing:

• git no - not a git repository, or git is missing. Stop. Tell the user ownership cannot be derived without history; there is nothing to guess from.
• total_commits 0 - the window is empty. Offer a wider one instead of drawing an all-grey diagram.
• error - report it verbatim.

Classify maintenance level

Upstream colour-codes nodes green / orange / yellow / uncoloured for actively / moderately / lightly / unmaintained, but publishes no thresholds. These bands are this plugin's own definition. Because they are invented, they must be printed with the diagram so a reader can disagree with them:

Scale the commit counts to the repo. On a repo whose busiest directory has 6 commits in three months, a 10-commit threshold marks everything unmaintained and the diagram says nothing. When the top directory is under ~10 commits, divide the thresholds proportionally and say that you rescaled, and to what.

CODEOWNERS beats blame

When the scan reports a CODEOWNERS file, it is the declared owner and outranks commit counts, which only show who happened to touch the code. Show both when they disagree - that gap is often the most interesting thing on the diagram:

src/payments is owned by @payments-team but 80% of recent commits are from @alice.

Draw it

flowchart with one node per directory, a classDef per band, and top contributors as a node sub-label. Hand off to the core /mermaid loop to render.

This diagram carries real contributor names from git log. Rendering through the bundled server sends them to mcp.mermaid.ai. On a private repo, say so before rendering and offer the local mmdc path instead.

---
config:
  theme: base
---
flowchart TD
  classDef active   fill:#d5e8d4,stroke:#82b366,color:#333
  classDef moderate fill:#ffe6cc,stroke:#d79b00,color:#333
  classDef light    fill:#fff2cc,stroke:#d6b656,color:#333
  classDef unmaint  fill:#eeeeee,stroke:#999999,color:#333

  api["src/api<br/>45 commits · 3 authors<br/>alice(30) bob(10)"]
  web["src/web<br/>12 commits · 2 authors<br/>carol(9) alice(3)"]
  legacy["src/legacy<br/>0 commits<br/>last touched 2024-03-11"]

  api --> web
  api --> legacy

  class api active
  class web moderate
  class legacy unmaint

Edges are optional. Draw them only where a real relationship exists (a directory hierarchy, or an import edge you actually verified). Do not invent edges to make the diagram look connected - a plain set of coloured boxes is a legitimate ownership map.

Always print with the diagram

1. The window and the date it resolves to.
2. The total commit count the classification rests on.
3. The thresholds used, including any rescaling.
4. Whether CODEOWNERS was found.
5. Merge commits are excluded (--no-merges), so counts reflect authored work.

Without these the colours look like objective measurements. They are a heuristic, and the user should be able to see the heuristic.

Honesty rules

• Never guess at ownership. No history means no answer.
• Author names come from git and may be inconsistent - the same person can appear under several names and emails. If two entries look like the same human, say so rather than silently merging them.
• A high commit count is not expertise, and low is not neglect. A stable, finished module correctly has no recent commits. Mention this when a directory reads as "unmaintained" but looks intentionally complete.
• Bus factor is a claim worth being careful with. One author in the window may mean concentrated knowledge, or it may mean a small window. Say which.