kostria 0.2.0__py3-none-any.whl

kostria/__init__.py

@@ -0,0 +1,3 @@
+"""Kostria: auditoria local de custo de IA por projeto, feature e conta."""
+
+__version__ = "0.1.0"

kostria/analysis.py

@@ -0,0 +1,312 @@
+"""Sinais acionaveis: o que fazer com o numero depois de apura-lo.
+
+Um total de gasto nao muda decisao nenhuma. Estes sinais mudam:
+
+- **reprocessamento**: quanto do custo e releitura de contexto em vez de
+  producao de codigo. Cache read barato em unidade, caro em volume.
+- **retrabalho**: arquivos reescritos muitas vezes na mesma sessao, sinal de
+  tentativa e erro cara.
+- **eficiencia por modelo**: custo por edicao entregue, que e o que permite
+  comparar modelo caro com modelo barato de forma honesta.
+- **exploracao**: sessoes que nao produziram edicao nenhuma.
+- **contas ociosas**: conta paga sem uso recente.
+"""
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from datetime import datetime, timedelta, timezone
+
+
+def _dt(iso):
+    if not iso:
+        return None
+    try:
+        return datetime.fromisoformat(str(iso).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def token_mix(sessions):
+    """Composicao do consumo. Precisa dos models por sessao, entao aproxima
+    pelo agregado de tokens quando o detalhe nao existe."""
+    mix = Counter()
+    for s in sessions:
+        for kind, n in (s.token_mix or {}).items():
+            mix[kind] += n
+    total = sum(mix.values()) or 1
+    return {k: {"tokens": v, "share": v / total} for k, v in mix.most_common()}
+
+
+def rework(sessions, resolver, top=12):
+    """Arquivos reescritos varias vezes dentro da mesma sessao."""
+    counts: dict[str, int] = defaultdict(int)
+    sess_hits: dict[str, int] = defaultdict(int)
+    cost_of: dict[str, float] = defaultdict(float)
+
+    for s in sessions:
+        if not s.edits:
+            continue
+        per = Counter(e.path for e in s.edits)
+        share = s.usd / len(s.edits) if s.edits else 0.0
+        for path, n in per.items():
+            if n >= 3:                       # 1-2 escritas e trabalho normal
+                counts[path] += n
+                sess_hits[path] += 1
+                cost_of[path] += share * n
+    out = []
+    for path, n in sorted(counts.items(), key=lambda kv: -cost_of[kv[0]])[:top]:
+        out.append({"path": path, "writes": n, "sessions": sess_hits[path],
+                    "cost": cost_of[path],
+                    "project": resolver.of_path(path)})
+    return out
+
+
+def model_efficiency(sessions):
+    """Custo por edicao entregue, por modelo.
+
+    Comparar modelos por preco de token e enganoso: o modelo caro pode
+    precisar de menos tentativas. O que importa e o custo do resultado.
+    """
+    cost: dict[str, float] = defaultdict(float)
+    edits: dict[str, int] = defaultdict(int)
+    tokens: dict[str, int] = defaultdict(int)
+
+    for s in sessions:
+        if not s.models:
+            continue
+        total = sum(c for c, _t in s.models.values()) or 0.0
+        for model, (c, t) in s.models.items():
+            cost[model] += c
+            tokens[model] += t
+            if total > 0 and s.edits:
+                edits[model] += round(len(s.edits) * (c / total))
+
+    out = []
+    for m in cost:
+        e = edits[m]
+        out.append({"model": m, "cost": cost[m], "tokens": tokens[m],
+                    "edits": e,
+                    "cost_per_edit": (cost[m] / e) if e else None})
+    return sorted(out, key=lambda x: -x["cost"])
+
+
+def exploration_share(sessions):
+    """Custo em sessoes que nao editaram arquivo nenhum."""
+    explo = sum(s.usd for s in sessions if not s.edits)
+    total = sum(s.usd for s in sessions) or 1
+    return {"cost": explo, "share": explo / total}
+
+
+def idle_accounts(sessions, days=14):
+    """Contas sem atividade recente: candidatas a revisao de assento."""
+    last: dict[str, datetime] = {}
+    cost: dict[str, float] = defaultdict(float)
+    for s in sessions:
+        cost[s.account] += s.usd
+        d = _dt(s.started_at)
+        if d and (s.account not in last or d > last[s.account]):
+            last[s.account] = d
+    now = datetime.now(timezone.utc)
+    out = []
+    for acct, c in cost.items():
+        d = last.get(acct)
+        idle = (now - d).days if d else None
+        out.append({"account": acct, "cost": c,
+                    "last_seen": d.isoformat(timespec="seconds") if d else None,
+                    "idle_days": idle,
+                    "idle": bool(idle is not None and idle >= days)})
+    return sorted(out, key=lambda x: -x["cost"])
+
+
+def daily_series(sessions):
+    """Custo por dia, para tendencia e projecao."""
+    by_day: dict[str, float] = defaultdict(float)
+    for s in sessions:
+        d = _dt(s.started_at)
+        if d:
+            by_day[d.date().isoformat()] += s.usd
+    return dict(sorted(by_day.items()))
+
+
+def projection(sessions, window=7):
+    """Projecao mensal a partir da media dos ultimos dias com atividade."""
+    series = daily_series(sessions)
+    if not series:
+        return None
+    days = sorted(series)[-window:]
+    if not days:
+        return None
+    avg = sum(series[d] for d in days) / len(days)
+    return {"daily_avg": avg, "monthly": avg * 30, "window_days": len(days),
+            "from": days[0], "to": days[-1]}
+
+
+def anomalies(sessions, sigma: float = 2.0, min_days: int = 7):
+    """Dias cujo custo foge do padrao do proprio periodo.
+
+    Media simples nao serve de alarme: um dia 4x acima da media pode ser
+    normal numa serie muito irregular. O corte usa desvio padrao da propria
+    serie, e so opina quando ha dias suficientes para o desvio significar algo.
+    """
+    serie = daily_series(sessions)
+    if len(serie) < min_days:
+        return {"enough_data": False, "days": len(serie), "items": []}
+
+    valores = list(serie.values())
+    media = sum(valores) / len(valores)
+    var = sum((v - media) ** 2 for v in valores) / len(valores)
+    desvio = var ** 0.5
+    corte = media + sigma * desvio
+
+    itens = [{"day": d, "cost": v, "times_avg": (v / media) if media else None,
+              "excess": v - media}
+             for d, v in serie.items() if v > corte]
+    itens.sort(key=lambda x: -x["cost"])
+    return {"enough_data": True, "days": len(serie), "avg": media,
+            "stdev": desvio, "threshold": corte, "sigma": sigma,
+            "items": itens}
+
+
+def top_sessions(sessions, top: int = 10, resolver=None):
+    """Sessoes mais caras, uma por uma.
+
+    O agregado por projeto esconde o caso individual: uma sessao que entrou em
+    loop pode responder sozinha por uma fatia grande do mes, e e nela que se
+    age. Traz o projeto, o volume e o que a sessao produziu, para separar
+    trabalho pesado de desperdicio.
+    """
+    total = sum(s.usd for s in sessions) or 1
+    out = []
+    for s in sessions:
+        if not s.usd:
+            continue
+        projeto = None
+        if resolver is not None:
+            alvo = (s.edits or [None])[0] or (getattr(s, "reads", None) or [None])[0]
+            projeto = resolver.of_path(alvo.path if alvo else s.cwd)
+        mix = s.token_mix or {}
+        reread = mix.get("cache_read", 0)
+        out.append({
+            "cost": s.usd, "tokens": s.tokens, "share": s.usd / total,
+            "project": projeto, "tool": s.tool, "account": s.account,
+            "started_at": s.started_at,
+            "edits": len(s.edits or []), "reads": len(getattr(s, "reads", None) or []),
+            "reread_share": (reread / s.tokens) if s.tokens else None,
+            "source": s.source,
+        })
+    out.sort(key=lambda r: -r["cost"])
+    return out[:top]
+
+
+def end_of_month_forecast(sessions):
+    """Previsao de fechamento do mes corrente, nao um generico "por mes".
+
+    A projecao existente (media movel x30) responde "nesse ritmo, quanto por
+    mes". Esta responde a pergunta que fecha orcamento de verdade: "quanto eu
+    vou ter gasto no dia 1 do mes que vem". Soma o que ja foi gasto desde o
+    dia 1 do mes atual com a media recente extrapolada pelos dias que faltam
+    no CALENDARIO, nao numa janela movel generica.
+    """
+    import calendar
+
+    serie = daily_series(sessions)
+    if not serie:
+        return None
+    hoje = datetime.now(timezone.utc).date()
+    inicio_mes = hoje.replace(day=1)
+    dias_no_mes = calendar.monthrange(hoje.year, hoje.month)[1]
+    dias_passados = (hoje - inicio_mes).days + 1
+    dias_restantes = dias_no_mes - dias_passados
+
+    ini_iso, hoje_iso = inicio_mes.isoformat(), hoje.isoformat()
+    mtd = sum(v for d, v in serie.items() if ini_iso <= d <= hoje_iso)
+
+    proj = projection(sessions)
+    media_recente = proj["daily_avg"] if proj else 0.0
+
+    return {
+        "month": ini_iso[:7], "today": hoje_iso, "month_to_date": mtd,
+        "days_elapsed": dias_passados, "days_remaining": dias_restantes,
+        "days_in_month": dias_no_mes, "recent_daily_avg": media_recente,
+        "forecast_total": mtd + media_recente * dias_restantes,
+    }
+
+
+def _cost_tokens_by_model(sessions):
+    cost: dict[str, float] = defaultdict(float)
+    tokens: dict[str, int] = defaultdict(int)
+    for s in sessions:
+        for model, (c, t) in (s.models or {}).items():
+            cost[model] += c
+            tokens[model] += t
+    return cost, tokens
+
+
+def _downgrade_estimate(sessions, alternative_of, alt_price_of, min_cost):
+    """Nucleo comum de model_downgrade_opportunities/opencode_downgrade_
+    opportunities: agrega custo/tokens por modelo, acha a alternativa via
+    `alternative_of(model)` e escala o custo pela razao de preco de input.
+
+    Aproximacao: `Session.models` so guarda custo e tokens TOTAIS por
+    modelo, sem quebra input/output/cache — nao da pra recalcular o custo
+    exato com a tabela da alternativa. Em vez disso escala o custo real
+    pela RAZAO entre os precos de input dos dois modelos, assumindo que a
+    mistura de tipo de token e parecida entre ambos (razoavel: e o mesmo
+    tipo de sessao). Numero e ESTIMATIVA DE PRECO, nunca diz se o resultado
+    teria a mesma qualidade.
+    """
+    from . import pricing
+
+    cost, tokens = _cost_tokens_by_model(sessions)
+    out = []
+    for model, c in cost.items():
+        if c < min_cost:
+            continue
+        alt = alternative_of(model)
+        if not alt:
+            continue
+        preco_atual, preco_alt = pricing.lookup_any(model), alt_price_of(alt)
+        if not preco_atual or not preco_alt:
+            continue
+        fator = preco_alt[0] / preco_atual[0]
+        estimado = c * fator
+        out.append({
+            "model": model, "alternative": alt,
+            "cost": c, "tokens": tokens[model],
+            "estimated_cost_with_alternative": estimado,
+            "estimated_savings": c - estimado,
+            "savings_pct": 1 - fator,
+        })
+    return sorted(out, key=lambda x: -x["estimated_savings"])
+
+
+def model_downgrade_opportunities(sessions, min_cost: float = 1.0):
+    """Economia estimada trocando cada modelo usado pelo mais barato do
+    MESMO fornecedor (pricing.cheaper_alternative) — ver _downgrade_estimate
+    para a metodologia de estimativa."""
+    from . import pricing
+    return _downgrade_estimate(
+        sessions, pricing.cheaper_alternative, pricing.lookup_any, min_cost)
+
+
+def opencode_downgrade_opportunities(sessions, min_cost: float = 1.0):
+    """Economia estimada trocando cada modelo usado por um modelo ABERTO
+    do catalogo pago OpenCode Zen (pricing.opencode_alternative) —
+    CROSS-fornecedor, ver _downgrade_estimate para a metodologia."""
+    from . import pricing
+    return _downgrade_estimate(
+        sessions, pricing.opencode_alternative,
+        lambda m: pricing.OPENCODE_ZEN.get(m), min_cost)
+
+
+def weekday_profile(sessions):
+    """Custo por dia da semana: revela se o gasto vaza no fim de semana."""
+    nomes = ["segunda", "terca", "quarta", "quinta", "sexta", "sabado", "domingo"]
+    acc = defaultdict(float)
+    for s in sessions:
+        d = _dt(s.started_at)
+        if d:
+            acc[nomes[d.weekday()]] += s.usd
+    total = sum(acc.values()) or 1
+    return {n: {"cost": acc.get(n, 0.0), "share": acc.get(n, 0.0) / total}
+            for n in nomes}

kostria/attribution.py

@@ -0,0 +1,359 @@
+"""Atribuicao: de onde o dinheiro saiu, de verdade.
+
+Tres descobertas sustentam este modulo:
+
+1. **O diretorio da sessao mente.** O agente edita varios repositorios a partir
+   de um cwd so (working dirs adicionais, worktrees, pastas temporarias). Medir
+   por cwd joga o custo no projeto errado. A atribuicao segue os ARQUIVOS
+   efetivamente editados.
+2. **Worktree nao e outro projeto.** `git rev-parse --git-common-dir` aponta o
+   repositorio principal, o que resolve worktrees sem depender de convencao de
+   nome.
+3. **O PR e uma unidade grosseira.** Um PR de consolidacao carrega varias
+   frentes e uma feature grande atravessa varios PRs. A unidade fina e o
+   commit, classificado por area (escopo do commit) e por item do board.
+"""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from bisect import bisect_left
+from collections import defaultdict
+from datetime import datetime
+from pathlib import Path
+
+TICKET_RE = re.compile(r"\b[A-Z][A-Z0-9]+-\d+\b")
+SCOPE_RE = re.compile(
+    r"^(?:feat|fix|perf|refactor|chore|docs|test|build|ci|style)\(([^)]+)\)")
+RS, US = "\x1e", "\x1f"
+
+# pastas que nao representam um projeto de verdade
+SCRATCH = {"scratchpad", "tmp", "temp", "out", "dist", "build", "node_modules",
+           "__pycache__", ".cache", "bench", "retro"}
+TMPNAME_RE = re.compile(r"w[a-z]*[A-Z0-9]?\.[A-Za-z0-9]{5,8}")
+UUID_RE = re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", re.I)
+
+
+def _git(args, cwd=None):
+    try:
+        r = subprocess.run(["git", *args], cwd=cwd, capture_output=True,
+                           text=True, errors="ignore", timeout=30)
+        return r.stdout.strip() if r.returncode == 0 else None
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+
+class ProjectResolver:
+    """Mapeia um caminho para o nome do projeto, com cache."""
+
+    def __init__(self, workspaces=None):
+        self._cache: dict[str, str] = {}
+        self.workspaces = [str(w) for w in (workspaces or
+                                            [Path.home() / "Documentos" / "VS"])]
+        self.notes: dict[str, str] = {}
+        self._known_cache = None
+        self._worktrees = self._index_worktrees()
+
+    def _index_worktrees(self) -> dict[str, str]:
+        """prefixo de worktree -> repo principal.
+
+        Worktree apagado nao responde a `git rev-parse`, entao o indice e
+        montado a partir dos repos vivos e serve tambem para caminhos mortos.
+        """
+        idx: dict[str, str] = {}
+        for ws in self.workspaces:
+            base = Path(ws)
+            if not base.is_dir():
+                continue
+            for repo in base.iterdir():
+                if not (repo / ".git").exists():
+                    continue
+                out = _git(["worktree", "list", "--porcelain"], cwd=repo)
+                for line in (out or "").splitlines():
+                    if line.startswith("worktree "):
+                        wt = line.split(" ", 1)[1].strip()
+                        if Path(wt).resolve() != repo.resolve():
+                            idx[wt] = repo.name
+                # convencao comum: <repo>-wt/<branch> guarda os worktrees
+                sibling = base / f"{repo.name}-wt"
+                if sibling.is_dir():
+                    idx[str(sibling)] = repo.name
+        return idx
+
+    def _encoded_origin(self, d: str) -> str | None:
+        """Projeto codificado num segmento do caminho (`-home-user-code-app`).
+
+        O scratch por sessao guarda o cwd de origem no proprio nome da pasta.
+        Sem isso, todo esse custo cai num balde generico e some do projeto que
+        de fato o gerou.
+
+        A codificacao troca TODA barra por hifen, o que e ambiguo: o segmento
+        `-home-user-code-obsidian-vault` tanto pode ser `.../obsidian/vault`
+        quanto `.../obsidian-vault`. Decodificar ao contrario chuta errado,
+        entao o casamento e feito contra os nomes de projeto que existem de
+        verdade no workspace, do mais longo para o mais curto.
+        """
+        for seg in d.split("/"):
+            if not seg.startswith("-") or len(seg) < 8:
+                continue
+            for name in self._known_projects:
+                if seg.endswith("-" + name.replace("/", "-")):
+                    return name
+        return None
+
+    @property
+    def _known_projects(self):
+        if self._known_cache is None:
+            names = []
+            for ws in self.workspaces:
+                base = Path(ws)
+                if base.is_dir():
+                    names += [p.name for p in base.iterdir() if p.is_dir()]
+            # mais longo primeiro: 'obsidian-vault' antes de 'vault'
+            self._known_cache = sorted(set(names), key=len, reverse=True)
+        return self._known_cache
+
+    def _from_worktree_index(self, d: str) -> str | None:
+        for wt, repo in self._worktrees.items():
+            if d == wt or d.startswith(wt.rstrip("/") + "/"):
+                return repo
+        return None
+
+    def of_path(self, path: str | None) -> str | None:
+        if not path:
+            return None
+        d = path if os.path.isdir(path) else os.path.dirname(path)
+        if not d:
+            return None
+        if d in self._cache:
+            return self._cache[d]
+        name = self._resolve(d)
+        self._cache[d] = name
+        return name
+
+    def _resolve(self, d: str) -> str:
+        # worktree (vivo ou ja apagado) pertence ao repo principal
+        wt = self._from_worktree_index(d)
+        if wt:
+            self.notes[d] = "worktree do repo principal"
+            return self._post(wt)
+        # scratch de sessao carrega o projeto de origem codificado no caminho:
+        # /tmp/claude-1000/-home-user-code-app/<sessao>/scratchpad/...
+        enc = self._encoded_origin(d)
+        if enc:
+            self.notes[d] = "scratch de sessao, projeto lido do caminho"
+            return self._post(enc)
+        if os.path.isdir(d):
+            # git-common-dir aponta o repo principal mesmo dentro de worktree
+            common = _git(["rev-parse", "--git-common-dir"], cwd=d)
+            if common:
+                # git devolve caminho relativo ao cwd (".git", "../../.git"):
+                # sem normalizar, o nome do projeto vira ".."
+                raw = common if os.path.isabs(common) else os.path.join(d, common)
+                p = Path(os.path.normpath(raw))
+                if p.name == ".git":
+                    self.notes[d] = "raiz git"
+                    return self._post(p.parent.name)
+        for ws in self.workspaces:
+            if d.startswith(ws + "/"):
+                self.notes[d] = "primeiro nivel do workspace"
+                return self._post(d[len(ws) + 1:].split("/")[0])
+        self.notes[d] = "nome da pasta (sem repo identificavel)"
+        return self._post(os.path.basename(d.rstrip("/")) or d)
+
+    @staticmethod
+    def _post(name: str) -> str:
+        if UUID_RE.fullmatch(name or ""):
+            return "(worktree temporario removido)"
+        if name in SCRATCH or TMPNAME_RE.fullmatch(name or ""):
+            return "(scratch / temporario)"
+        return name or "(nao atribuido)"
+
+
+#: como o custo de uma sessao foi ligado a um projeto, do mais forte ao mais
+#: fraco. A distincao importa: "editou" e prova de entrega, "leu" e prova de
+#: contexto, e "diretorio" e so o que a ferramenta declarou — e o diretorio
+#: mente, porque o agente edita fora dele o tempo todo.
+ATTRIBUTION = {
+    "edited": "arquivos escritos na sessao",
+    "read": "arquivos lidos na sessao (investigacao, sem entrega)",
+    "cwd": "diretorio declarado, sem nenhum arquivo tocado",
+}
+
+
+def split_session_cost(session, resolver: ProjectResolver):
+    """Rateia o custo da sessao entre os projetos, em cascata de evidencia.
+
+    Devolve (custo_por_projeto, tokens_por_projeto, metodo), onde metodo diz
+    QUAL evidencia sustentou a atribuicao. Tratar tudo como equivalente
+    esconderia que parte do numero repousa em prova fraca.
+    """
+    def _rateio(paths):
+        projetos = [p for p in (resolver.of_path(x) for x in paths) if p]
+        if not projetos:
+            return None
+        custo: dict[str, float] = defaultdict(float)
+        toks: dict[str, int] = defaultdict(int)
+        n = len(projetos)
+        for p in projetos:
+            custo[p] += session.usd / n
+            toks[p] += session.tokens // n
+        return custo, toks
+
+    got = _rateio([e.path for e in (getattr(session, "edits", None) or [])])
+    if got:
+        return got[0], got[1], "edited"
+
+    got = _rateio([e.path for e in (getattr(session, "reads", None) or [])])
+    if got:
+        return got[0], got[1], "read"
+
+    proj = resolver.of_path(session.cwd) or session.cwd or "(sem projeto)"
+    return ({proj: session.usd}, {proj: session.tokens}, "cwd")
+
+
+class RepoHistory:
+    """Historico de um repositorio: arquivo -> commits que o tocaram."""
+
+    def __init__(self, repo: Path, ref: str | None = None):
+        self.repo = Path(repo)
+        self.ref = ref or self._default_ref()
+        self.by_file: dict[str, list] = defaultdict(list)
+        self._ts: dict[str, list] = {}
+        self.commits = 0
+        self._load()
+
+    def _default_ref(self) -> str:
+        for ref in ("origin/dev", "origin/main", "origin/master", "HEAD"):
+            if _git(["rev-parse", "--verify", ref], cwd=self.repo):
+                return ref
+        return "HEAD"
+
+    def _load(self):
+        out = _git(["log", self.ref,
+                    f"--pretty=format:{RS}%H{US}%ct{US}%s{US}%b{US}",
+                    "--name-only"], cwd=self.repo)
+        if not out:
+            return
+        for rec in out.split(RS):
+            if not rec.strip():
+                continue
+            parts = rec.split(US)
+            if len(parts) < 5:
+                continue
+            sha, cts, subject, body = parts[0], parts[1], parts[2], parts[3]
+            try:
+                ts = int(cts)
+            except ValueError:
+                continue
+            self.commits += 1
+            tickets = tuple(sorted(set(TICKET_RE.findall(f"{subject}\n{body}"))))
+            m = SCOPE_RE.match(subject.strip())
+            entry = (ts, tickets, m.group(1) if m else None, subject.strip(), sha)
+            for path in (x for x in parts[4].splitlines() if x.strip()):
+                self.by_file[path].append(entry)
+        for path, lst in self.by_file.items():
+            lst.sort(key=lambda x: x[0])
+            self._ts[path] = [x[0] for x in lst]
+
+    def relpath(self, abs_path: str) -> str | None:
+        """Maior sufixo do caminho que exista no historico do repo."""
+        parts = abs_path.strip("/").split("/")
+        for i in range(len(parts) - 1):
+            cand = "/".join(parts[i:])
+            if cand in self.by_file:
+                # sufixo curto demais colide entre repos
+                if cand.count("/") >= 1 or len(parts) - i > 1:
+                    return cand
+        return None
+
+    def commit_for(self, relpath: str, when_iso: str | None):
+        """Primeiro commit posterior a edicao que tocou aquele arquivo."""
+        if not when_iso or relpath not in self._ts:
+            return None
+        try:
+            ts = int(datetime.fromisoformat(
+                when_iso.replace("Z", "+00:00")).timestamp())
+        except ValueError:
+            return None
+        i = bisect_left(self._ts[relpath], ts)
+        lst = self.by_file[relpath]
+        return lst[i] if i < len(lst) else None
+
+
+def _dia_de(iso_ts):
+    """`2026-07-28T13:45:00Z` -> `2026-07-28`. None se a data nao presta.
+
+    Mesma conversao do `report._day_of`. Fica repetida aqui de proposito: o
+    report importa este modulo, entao importar de volta fecharia um ciclo por
+    causa de cinco linhas.
+    """
+    if not iso_ts:
+        return None
+    try:
+        return datetime.fromisoformat(
+            str(iso_ts).replace("Z", "+00:00")).date().isoformat()
+    except ValueError:
+        return None
+
+
+def features_for_repo(sessions, repo: Path, resolver: ProjectResolver,
+                      ref: str | None = None):
+    """Custo por area do produto e por item do board, dentro de um repo."""
+    if not _git(["rev-parse", "--git-dir"], cwd=repo):
+        return {"error": f"{repo} nao e um repositorio git"}
+    hist = RepoHistory(repo, ref)
+    if not hist.commits:
+        return {"error": f"repositorio sem commits alcancaveis em {repo}"}
+
+    # `days` guarda o custo do escopo POR DIA. A data ja existe (`e.ts`, usada
+    # logo abaixo para achar o commit), entao isto nao inventa distribuicao:
+    # so para de jogar fora uma quebra que o motor ja tinha em maos. Sem ela o
+    # sync so consegue mandar um escopo por projeto, e o board mostra o custo
+    # inteiro do projeto colado no escopo dominante.
+    by_scope: dict[str, dict] = defaultdict(
+        lambda: {"cost": 0.0, "edits": 0, "days": defaultdict(float)})
+    by_ticket: dict[str, dict] = defaultdict(
+        lambda: {"cost": 0.0, "edits": 0, "subject": "", "days": defaultdict(float)})
+    matched = unmatched = 0.0
+
+    for s in sessions:
+        if not s.edits or not s.usd:
+            continue
+        share = s.usd / len(s.edits)
+        for e in s.edits:
+            rel = hist.relpath(e.path)
+            if not rel:
+                continue
+            c = hist.commit_for(rel, e.ts)
+            if not c:
+                unmatched += share
+                continue
+            _ts, tickets, scope, subject, _sha = c
+            matched += share
+            key = scope or "(sem escopo)"
+            by_scope[key]["cost"] += share
+            by_scope[key]["edits"] += 1
+            dia = _dia_de(e.ts)
+            if dia:                       # edicao sem data nao vira linha de dia
+                by_scope[key]["days"][dia] += share
+            if tickets:
+                for t in tickets:                 # commit com N itens: 1/N
+                    by_ticket[t]["cost"] += share / len(tickets)
+                    by_ticket[t]["edits"] += 1
+                    by_ticket[t]["subject"] = by_ticket[t]["subject"] or subject
+                    if dia:
+                        by_ticket[t]["days"][dia] += share / len(tickets)
+            else:
+                by_ticket["(sem item)"]["cost"] += share
+                by_ticket["(sem item)"]["edits"] += 1
+                if dia:
+                    by_ticket["(sem item)"]["days"][dia] += share
+
+    return {"by_scope": {k: {**v, "days": dict(v["days"])}
+                        for k, v in by_scope.items()},
+            "by_ticket": {k: {**v, "days": dict(v["days"])}
+                          for k, v in by_ticket.items()},
+            "matched": matched, "unmatched": unmatched,
+            "ref": hist.ref, "commits": hist.commits}