cctally 1.11.1 → 1.13.0

package/bin/_cctally_config.py

@@ -46,6 +46,7 @@ import json
 import os
 import secrets
 import sys
+from pathlib import Path
 from typing import Any
 
 
@@ -162,17 +163,60 @@ def config_writer_lock():
         fh.close()
 
 
-def load_config() -> dict[str, Any]:
+def _load_config_from_explicit_path(path: "str | Path") -> dict[str, Any]:
+    """Read config from an explicit per-invocation override path (issue #88).
+
+    Contract differs from the default ``load_config()``:
+      - Missing file → ``SystemExit(2)`` with a clear stderr message.
+      - Unreadable / malformed JSON / non-object root → ``SystemExit(2)``
+        with a clear stderr message.
+      - Never writes, never acquires ``config_writer_lock``, never
+        creates the on-disk default config — the override is read-only
+        for this invocation.
+
+    Used by the ccusage drop-in ``--config <path>`` flag wired onto the
+    10 Claude reporting commands (spec §3 T1.6 / issue #86 Session A).
+    """
+    p = Path(path)
+    if not p.exists():
+        eprint(f"cctally: --config: file not found: {p}")
+        raise SystemExit(2)
+    try:
+        raw = p.read_text(encoding="utf-8")
+    except OSError as exc:
+        eprint(f"cctally: --config: read failed for {p}: {exc}")
+        raise SystemExit(2) from exc
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        eprint(f"cctally: --config: invalid JSON in {p}: {exc}")
+        raise SystemExit(2) from exc
+    if not isinstance(data, dict):
+        eprint(
+            f"cctally: --config: {p} top-level must be a JSON object"
+        )
+        raise SystemExit(2)
+    return data
+
+
+def load_config(path: "str | Path | None" = None) -> dict[str, Any]:
     """Read config.json, falling back to in-memory defaults on corruption.
 
-    Concurrent-safety: readers see either the pre-rename or post-rename
-    contents thanks to save_config's atomic os.replace. On corrupt or
-    non-object JSON, emits a one-shot stderr warning and returns
-    in-memory defaults WITHOUT re-saving — the next legitimate
-    save_config call (under config_writer_lock) will overwrite the bad
-    bytes atomically. On first run (file missing), creates the file
-    with a fresh collector token under the writer lock so two parallel
-    first-run processes don't clobber each other.
+    When ``path`` is None (default): reads the persisted user config at
+    ``_cctally_core.CONFIG_PATH``, creating it on first run with a fresh
+    collector token under the writer lock. Concurrent-safety: readers see
+    either the pre-rename or post-rename contents thanks to save_config's
+    atomic os.replace. On corrupt or non-object JSON, emits a one-shot
+    stderr warning and returns in-memory defaults WITHOUT re-saving — the
+    next legitimate save_config call (under config_writer_lock) will
+    overwrite the bad bytes atomically.
+
+    When ``path`` is set (issue #88 ccusage drop-in ``--config <path>``):
+    reads from the explicit override path and bypasses the default-path
+    branch entirely. Missing / unreadable / malformed paths surface as
+    ``SystemExit(2)`` with a clear stderr message — see
+    ``_load_config_from_explicit_path``. No writes, no first-run create,
+    no mutation of the on-disk default config.
 
     DEADLOCK NOTE: `fcntl.flock` is per-fd even within the same
     process. Callers that already hold config_writer_lock MUST use
@@ -180,6 +224,8 @@ def load_config() -> dict[str, Any]:
     inside an outer lock would block forever (verified during issue
     #17 fix).
     """
+    if path is not None:
+        return _load_config_from_explicit_path(path)
     c = _cctally()
     ensure_dirs()
     parsed = _try_read_config()

package/bin/_cctally_core.py

@@ -67,6 +67,7 @@ def _init_paths_from_env() -> None:
     global UPDATE_STATE_PATH, UPDATE_SUPPRESS_PATH
     global UPDATE_LOCK_PATH, UPDATE_LOG_PATH, UPDATE_LOG_ROTATED_PATH
     global UPDATE_CHECK_LAST_FETCH_PATH, CLAUDE_SETTINGS_PATH
+    global CLAUDE_PROJECTS_DIR
 
     home = pathlib.Path.home()
     APP_DIR = home / ".local" / "share" / "cctally"
@@ -108,10 +109,60 @@ def _init_paths_from_env() -> None:
 
     CLAUDE_SETTINGS_PATH = home / ".claude" / "settings.json"
 
+    # Claude session JSONL root. Production path is `~/.claude/projects`;
+    # exposed as a module-level constant so cross-DB migrations (e.g.
+    # stats migration 008) and the dispatcher's empty-disk fallback can
+    # honor a fixture override via tests' `monkeypatch.setattr(
+    # _cctally_core, "CLAUDE_PROJECTS_DIR", tmp_path / "...")`. The
+    # `_get_claude_data_dirs()` helper in bin/cctally remains the
+    # authoritative resolver for ad-hoc reads (multi-root + env-aware);
+    # this constant is the single-rooted production default that 99% of
+    # callers want. For multi-root, env-aware resolution (mirroring
+    # `_get_claude_data_dirs`), use `_resolve_claude_projects_dirs()`.
+    CLAUDE_PROJECTS_DIR = home / ".claude" / "projects"
+
 
 _init_paths_from_env()
 
 
+def _resolve_claude_projects_dirs() -> list[pathlib.Path]:
+    """Return Claude Code projects dirs that exist on disk, env-aware.
+
+    Mirrors `_get_claude_data_dirs()` in bin/cctally but returns the
+    `projects/` subdir directly (since cross-DB migrations only care
+    about the JSONL root, not the parent Claude data dir). Honors
+    ``CLAUDE_CONFIG_DIR`` (comma-separated multi-root) and falls back
+    to ``~/.config/claude`` then ``~/.claude``.
+
+    Used by stats migration 008's gate helper to avoid falsely
+    short-circuiting Layer C's empty-disk fallback when the user has
+    ``CLAUDE_CONFIG_DIR=/other/path`` set AND no ``~/.claude/projects``
+    dir on disk: the gate would otherwise see zero JSONL files at the
+    hardcoded ``CLAUDE_PROJECTS_DIR`` and "pass" the gate, then run the
+    recompute as a no-op against an empty cache.
+
+    Tests can also feed an explicit list to the gate helper directly,
+    skipping this resolver.
+    """
+    env_val = os.environ.get("CLAUDE_CONFIG_DIR", "").strip()
+    if env_val:
+        candidates = [pathlib.Path(p.strip()) for p in env_val.split(",") if p.strip()]
+        result = [
+            d / "projects"
+            for d in candidates
+            if d.is_dir() and (d / "projects").is_dir()
+        ]
+        if result:
+            return result
+
+    home = pathlib.Path.home()
+    defaults = [
+        home / ".config" / "claude",
+        home / ".claude",
+    ]
+    return [d / "projects" for d in defaults if d.is_dir() and (d / "projects").is_dir()]
+
+
 # === Logging =========================================================