codex-skill-analytics 0.1.0

package/src/codex_skill_analytics/cli.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sqlite3
+from collections.abc import Iterable, Mapping, Sequence
+from pathlib import Path
+
+from .database import AnalyticsDB
+from .graph import build_graph_data, write_graph_html
+from .sync import sync_history
+from .web import serve_dashboard
+
+DEFAULT_DB = Path.home() / ".local" / "share" / "codex-skill-analytics" / "analytics.sqlite3"
+
+
+def _rows_as_dicts(rows: Iterable[sqlite3.Row]) -> list[dict[str, object]]:
+    return [dict(row) for row in rows]
+
+
+def _print_table(rows: Sequence[Mapping[str, object]]) -> None:
+    if not rows:
+        print("No data.")
+        return
+    columns = list(rows[0].keys())
+    widths = {
+        column: max(len(column), *(len(str(row[column] if row[column] is not None else "")) for row in rows))
+        for column in columns
+    }
+    print("  ".join(column.ljust(widths[column]) for column in columns))
+    print("  ".join("-" * widths[column] for column in columns))
+    for row in rows:
+        print(
+            "  ".join(
+                str(row[column] if row[column] is not None else "").ljust(widths[column])
+                for column in columns
+            )
+        )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="codex-skill-analytics",
+        description="Local deterministic analytics for Codex Skill usage.",
+    )
+    parser.add_argument("--db", type=Path, default=DEFAULT_DB)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    sync_parser = subparsers.add_parser("sync", help="Incrementally import Codex rollout JSONL files")
+    sync_parser.add_argument("--codex-home", type=Path, default=Path.home() / ".codex")
+
+    summary_parser = subparsers.add_parser("summary", help="Show Skill usage totals")
+    summary_parser.add_argument("--days", type=int, default=30)
+    summary_parser.add_argument("--json", action="store_true")
+
+    events_parser = subparsers.add_parser("events", help="Show when individual Skills were invoked")
+    events_parser.add_argument("--days", type=int, default=30)
+    events_parser.add_argument("--limit", type=int, default=100)
+    events_parser.add_argument("--json", action="store_true")
+
+    trend_parser = subparsers.add_parser("trend", help="Show daily Skill invocation counts")
+    trend_parser.add_argument("--days", type=int, default=30)
+    trend_parser.add_argument("--json", action="store_true")
+
+    relation_parser = subparsers.add_parser("relations", help="Show Skill relationship weights")
+    relation_parser.add_argument("--days", type=int, default=30)
+    relation_parser.add_argument(
+        "--type", choices=("same-turn", "sequence", "next-in-thread"), default="same-turn"
+    )
+    relation_parser.add_argument("--json", action="store_true")
+
+    graph_parser = subparsers.add_parser(
+        "graph", help="Generate a standalone interactive Skill dependency graph"
+    )
+    graph_parser.add_argument("--days", type=int, default=30)
+    graph_parser.add_argument(
+        "--type", choices=("same-turn", "sequence", "next-in-thread"), default="sequence"
+    )
+    graph_parser.add_argument("--min-weight", type=int, default=2)
+    graph_parser.add_argument("--limit", type=int, default=100, help="Maximum number of edges")
+    graph_parser.add_argument(
+        "--output", type=Path, default=Path("skill-dependency-graph.html")
+    )
+
+    serve_parser = subparsers.add_parser("serve", help="Run the local two-page analytics Web")
+    serve_parser.add_argument("--codex-home", type=Path, default=Path.home() / ".codex")
+    serve_parser.add_argument("--host", default="127.0.0.1")
+    serve_parser.add_argument("--port", type=int, default=8765)
+    serve_parser.add_argument("--open", action="store_true", help="Open the Web in a browser")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "serve":
+        serve_dashboard(args.db, args.codex_home, args.host, args.port, args.open)
+        return 0
+    with AnalyticsDB(args.db) as db:
+        if args.command == "sync":
+            stats = sync_history(args.codex_home, db)
+            print(json.dumps(stats.__dict__, ensure_ascii=False, indent=2))
+            return 0
+        if args.command == "graph":
+            data = build_graph_data(
+                db,
+                days=max(1, args.days),
+                relation_type=args.type,
+                min_weight=max(1, args.min_weight),
+                limit=max(1, args.limit),
+            )
+            output = write_graph_html(data, args.output)
+            print(output)
+            return 0
+        if args.command == "summary":
+            rows = _rows_as_dicts(db.summary(args.days))
+        elif args.command == "events":
+            rows = _rows_as_dicts(db.events(args.days, args.limit))
+        elif args.command == "trend":
+            rows = _rows_as_dicts(db.trend(args.days))
+        else:
+            rows = _rows_as_dicts(db.relations(args.days, args.type))
+        if args.json:
+            print(json.dumps(rows, ensure_ascii=False, indent=2))
+        else:
+            _print_table(rows)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/codex_skill_analytics/database.py

@@ -0,0 +1,359 @@
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Self
+
+from .parser import Invocation, SessionMeta, SkillRef
+
+SCHEMA = """
+PRAGMA journal_mode=WAL;
+PRAGMA foreign_keys=ON;
+
+CREATE TABLE IF NOT EXISTS sources (
+    path TEXT PRIMARY KEY,
+    byte_offset INTEGER NOT NULL DEFAULT 0,
+    line_number INTEGER NOT NULL DEFAULT 0,
+    file_size INTEGER NOT NULL DEFAULT 0,
+    mtime_ns INTEGER NOT NULL DEFAULT 0,
+    last_synced_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+    thread_id TEXT PRIMARY KEY,
+    source_path TEXT NOT NULL,
+    started_at TEXT NOT NULL,
+    cwd TEXT NOT NULL,
+    cli_version TEXT NOT NULL,
+    parent_thread_id TEXT,
+    archived INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS skills (
+    skill_key TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    path TEXT NOT NULL,
+    scope TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS invocations (
+    invocation_id TEXT PRIMARY KEY,
+    thread_id TEXT NOT NULL,
+    turn_id TEXT NOT NULL,
+    invoked_at TEXT NOT NULL,
+    skill_key TEXT NOT NULL,
+    skill_name TEXT NOT NULL,
+    skill_scope TEXT NOT NULL,
+    invoke_type TEXT NOT NULL,
+    first_evidence_type TEXT NOT NULL,
+    source_path TEXT NOT NULL,
+    source_line INTEGER NOT NULL,
+    source_order INTEGER NOT NULL DEFAULT 0,
+    FOREIGN KEY(thread_id) REFERENCES sessions(thread_id),
+    FOREIGN KEY(skill_key) REFERENCES skills(skill_key)
+);
+
+CREATE TABLE IF NOT EXISTS accesses (
+    access_id TEXT PRIMARY KEY,
+    invocation_id TEXT NOT NULL,
+    accessed_at TEXT NOT NULL,
+    evidence_type TEXT NOT NULL,
+    source_path TEXT NOT NULL,
+    source_line INTEGER NOT NULL,
+    call_id TEXT,
+    FOREIGN KEY(invocation_id) REFERENCES invocations(invocation_id)
+);
+
+CREATE INDEX IF NOT EXISTS invocations_time_idx ON invocations(invoked_at);
+CREATE INDEX IF NOT EXISTS invocations_turn_idx ON invocations(turn_id, invoked_at);
+CREATE INDEX IF NOT EXISTS invocations_skill_idx ON invocations(skill_key, invoked_at);
+CREATE INDEX IF NOT EXISTS accesses_invocation_idx ON accesses(invocation_id);
+"""
+
+
+class AnalyticsDB:
+    def __init__(self, path: Path) -> None:
+        self.path = path.expanduser().resolve()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.connection = sqlite3.connect(self.path)
+        self.connection.row_factory = sqlite3.Row
+        self.connection.executescript(SCHEMA)
+        self._migrate_columns()
+
+    def _migrate_columns(self) -> None:
+        columns = {
+            row["name"] for row in self.connection.execute("PRAGMA table_info(invocations)")
+        }
+        additions = {
+            "skill_name": "TEXT NOT NULL DEFAULT ''",
+            "skill_scope": "TEXT NOT NULL DEFAULT ''",
+            "source_order": "INTEGER NOT NULL DEFAULT 0",
+        }
+        for name, declaration in additions.items():
+            if name not in columns:
+                self.connection.execute(
+                    f"ALTER TABLE invocations ADD COLUMN {name} {declaration}"
+                )
+        self.connection.execute(
+            """
+            UPDATE invocations
+            SET skill_name=COALESCE(NULLIF(skill_name, ''),
+                (SELECT name FROM skills WHERE skills.skill_key=invocations.skill_key)),
+                skill_scope=COALESCE(NULLIF(skill_scope, ''),
+                (SELECT scope FROM skills WHERE skills.skill_key=invocations.skill_key))
+            WHERE skill_name='' OR skill_scope=''
+            """
+        )
+        self.connection.commit()
+
+    def close(self) -> None:
+        self.connection.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.close()
+
+    def checkpoint(self, path: str) -> sqlite3.Row | None:
+        return self.connection.execute("SELECT * FROM sources WHERE path = ?", (path,)).fetchone()
+
+    def save_checkpoint(
+        self, path: str, *, byte_offset: int, line_number: int, file_size: int, mtime_ns: int
+    ) -> None:
+        self.connection.execute(
+            """
+            INSERT INTO sources(path, byte_offset, line_number, file_size, mtime_ns)
+            VALUES (?, ?, ?, ?, ?)
+            ON CONFLICT(path) DO UPDATE SET
+                byte_offset=excluded.byte_offset,
+                line_number=excluded.line_number,
+                file_size=excluded.file_size,
+                mtime_ns=excluded.mtime_ns,
+                last_synced_at=CURRENT_TIMESTAMP
+            """,
+            (path, byte_offset, line_number, file_size, mtime_ns),
+        )
+
+    def upsert_session(self, session: SessionMeta, source_path: str, archived: bool) -> None:
+        self.connection.execute(
+            """
+            INSERT INTO sessions(thread_id, source_path, started_at, cwd, cli_version, parent_thread_id, archived)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(thread_id) DO UPDATE SET
+                source_path=excluded.source_path,
+                cwd=excluded.cwd,
+                cli_version=excluded.cli_version,
+                parent_thread_id=excluded.parent_thread_id,
+                archived=excluded.archived
+            """,
+            (
+                session.thread_id,
+                source_path,
+                session.started_at,
+                session.cwd,
+                session.cli_version,
+                session.parent_thread_id,
+                int(archived),
+            ),
+        )
+
+    def upsert_skill(self, skill: SkillRef) -> None:
+        self.connection.execute(
+            """
+            INSERT INTO skills(skill_key, name, path, scope) VALUES (?, ?, ?, ?)
+            ON CONFLICT(skill_key) DO UPDATE SET
+                name=excluded.name, path=excluded.path, scope=excluded.scope
+            """,
+            (skill.key, skill.name, skill.path, skill.scope),
+        )
+
+    def add_invocation(self, invocation: Invocation) -> tuple[bool, bool]:
+        self.upsert_skill(invocation.skill)
+        before = self.connection.total_changes
+        self.connection.execute(
+            """
+            INSERT OR IGNORE INTO invocations(
+                invocation_id, thread_id, turn_id, invoked_at, skill_key, skill_name, skill_scope, invoke_type,
+                first_evidence_type, source_path, source_line, source_order
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                invocation.invocation_id,
+                invocation.thread_id,
+                invocation.turn_id,
+                invocation.timestamp,
+                invocation.skill.key,
+                invocation.skill.name,
+                invocation.skill.scope,
+                invocation.invoke_type,
+                invocation.evidence_type,
+                invocation.source_path,
+                invocation.source_line,
+                invocation.source_order,
+            ),
+        )
+        invocation_added = self.connection.total_changes > before
+        before = self.connection.total_changes
+        self.connection.execute(
+            """
+            INSERT OR IGNORE INTO accesses(
+                access_id, invocation_id, accessed_at, evidence_type, source_path, source_line, call_id
+            ) VALUES (?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                invocation.access_id,
+                invocation.invocation_id,
+                invocation.timestamp,
+                invocation.evidence_type,
+                invocation.source_path,
+                invocation.source_line,
+                invocation.call_id,
+            ),
+        )
+        return invocation_added, self.connection.total_changes > before
+
+    def commit(self) -> None:
+        self.connection.commit()
+
+    def summary(self, days: int) -> list[sqlite3.Row]:
+        return self.connection.execute(
+            """
+            SELECT i.skill_name AS name, i.skill_scope AS scope,
+                   COUNT(*) AS invocations,
+                   COUNT(DISTINCT i.thread_id) AS threads,
+                   COUNT(DISTINCT i.turn_id) AS turns,
+                   SUM((SELECT COUNT(*) FROM accesses a WHERE a.invocation_id=i.invocation_id)) AS accesses,
+                   MIN(i.invoked_at) AS first_used_at,
+                   MAX(i.invoked_at) AS last_used_at
+            FROM invocations i
+            WHERE datetime(i.invoked_at) >= datetime('now', ?)
+            GROUP BY i.skill_name, i.skill_scope
+            ORDER BY invocations DESC, accesses DESC, name
+            """,
+            (f"-{max(1, days)} days",),
+        ).fetchall()
+
+    def volume_totals(self, days: int) -> sqlite3.Row:
+        row = self.connection.execute(
+            """
+            SELECT COUNT(*) AS invocations,
+                   COUNT(DISTINCT skill_scope || ':' || skill_name) AS skills,
+                   COUNT(DISTINCT thread_id) AS threads,
+                   COUNT(DISTINCT turn_id) AS turns,
+                   COALESCE(SUM((SELECT COUNT(*) FROM accesses a
+                                 WHERE a.invocation_id=i.invocation_id)), 0) AS accesses,
+                   MIN(invoked_at) AS first_used_at,
+                   MAX(invoked_at) AS last_used_at
+            FROM invocations i
+            WHERE datetime(invoked_at) >= datetime('now', ?)
+            """,
+            (f"-{max(1, days)} days",),
+        ).fetchone()
+        assert row is not None
+        return row
+
+    def volume_by_scope(self, days: int) -> list[sqlite3.Row]:
+        return self.connection.execute(
+            """
+            SELECT skill_scope AS scope,
+                   COUNT(*) AS invocations,
+                   COUNT(DISTINCT skill_name) AS skills,
+                   COUNT(DISTINCT thread_id) AS threads,
+                   COUNT(DISTINCT turn_id) AS turns,
+                   COALESCE(SUM((SELECT COUNT(*) FROM accesses a
+                                 WHERE a.invocation_id=i.invocation_id)), 0) AS accesses
+            FROM invocations i
+            WHERE datetime(invoked_at) >= datetime('now', ?)
+            GROUP BY skill_scope
+            ORDER BY invocations DESC, scope
+            """,
+            (f"-{max(1, days)} days",),
+        ).fetchall()
+
+    def relations(self, days: int, relation_type: str) -> list[sqlite3.Row]:
+        modifier = f"-{max(1, days)} days"
+        if relation_type == "same-turn":
+            return self.connection.execute(
+                """
+                WITH pairs AS (
+                    SELECT
+                        CASE WHEN (a.skill_scope || ':' || a.skill_name) < (b.skill_scope || ':' || b.skill_name)
+                             THEN a.skill_name ELSE b.skill_name END AS source,
+                        CASE WHEN (a.skill_scope || ':' || a.skill_name) < (b.skill_scope || ':' || b.skill_name)
+                             THEN a.skill_scope ELSE b.skill_scope END AS source_scope,
+                        CASE WHEN (a.skill_scope || ':' || a.skill_name) < (b.skill_scope || ':' || b.skill_name)
+                             THEN b.skill_name ELSE a.skill_name END AS target,
+                        CASE WHEN (a.skill_scope || ':' || a.skill_name) < (b.skill_scope || ':' || b.skill_name)
+                             THEN b.skill_scope ELSE a.skill_scope END AS target_scope,
+                        a.turn_id,
+                        a.thread_id
+                    FROM invocations a
+                    JOIN invocations b ON b.turn_id=a.turn_id AND b.invocation_id>a.invocation_id
+                    WHERE datetime(a.invoked_at) >= datetime('now', ?)
+                      AND (a.skill_name<>b.skill_name OR a.skill_scope<>b.skill_scope)
+                )
+                SELECT source, source_scope, target, target_scope,
+                       COUNT(DISTINCT turn_id) AS weight,
+                       COUNT(DISTINCT thread_id) AS threads
+                FROM pairs
+                GROUP BY source, source_scope, target, target_scope
+                ORDER BY weight DESC, source, target
+                """,
+                (modifier,),
+            ).fetchall()
+        partition = "thread_id, turn_id" if relation_type == "sequence" else "thread_id"
+        return self.connection.execute(
+            f"""
+            WITH ordered AS (
+                SELECT thread_id, turn_id, skill_key, skill_name, skill_scope, invoked_at,
+                       LEAD(skill_name) OVER (
+                           PARTITION BY {partition}
+                           ORDER BY invoked_at, source_line, source_order, invocation_id
+                       ) AS next_skill,
+                       LEAD(skill_scope) OVER (
+                           PARTITION BY {partition}
+                           ORDER BY invoked_at, source_line, source_order, invocation_id
+                       ) AS next_scope
+                FROM invocations
+                WHERE datetime(invoked_at) >= datetime('now', ?)
+            )
+            SELECT skill_name AS source, skill_scope AS source_scope,
+                   next_skill AS target, next_scope AS target_scope,
+                   COUNT(*) AS weight,
+                   COUNT(DISTINCT ordered.thread_id) AS threads
+            FROM ordered
+            WHERE ordered.next_skill IS NOT NULL
+              AND (skill_name<>next_skill OR skill_scope<>next_scope)
+            GROUP BY skill_name, skill_scope, next_skill, next_scope
+            ORDER BY weight DESC, source, target
+            """,
+            (modifier,),
+        ).fetchall()
+
+    def events(self, days: int, limit: int) -> list[sqlite3.Row]:
+        return self.connection.execute(
+            """
+            SELECT i.invoked_at, i.skill_name AS skill, i.skill_scope AS scope, i.invoke_type,
+                   i.first_evidence_type AS evidence, i.thread_id, i.turn_id,
+                   i.source_path, i.source_line
+            FROM invocations i
+            WHERE datetime(i.invoked_at) >= datetime('now', ?)
+            ORDER BY i.invoked_at DESC, i.source_line DESC, i.source_order DESC
+            LIMIT ?
+            """,
+            (f"-{max(1, days)} days", max(1, limit)),
+        ).fetchall()
+
+    def trend(self, days: int) -> list[sqlite3.Row]:
+        return self.connection.execute(
+            """
+            SELECT date(i.invoked_at) AS day, i.skill_name AS skill,
+                   i.skill_scope AS scope, COUNT(*) AS invocations
+            FROM invocations i
+            WHERE datetime(i.invoked_at) >= datetime('now', ?)
+            GROUP BY date(i.invoked_at), i.skill_name, i.skill_scope
+            ORDER BY day DESC, invocations DESC, skill
+            """,
+            (f"-{max(1, days)} days",),
+        ).fetchall()