codex-usage-analyzer 0.1.0 → 0.2.0

package/src/parser/session-jsonl.js

@@ -1,231 +0,0 @@
-import { createReadStream } from "node:fs";
-import { access, readdir } from "node:fs/promises";
-import { constants } from "node:fs";
-import { createInterface } from "node:readline";
-import { join } from "node:path";
-
-export async function discoverSessionJsonlFiles(codexHome) {
-  const sessionsDir = join(codexHome, "sessions");
-  const diagnostics = [];
-
-  try {
-    await access(sessionsDir, constants.R_OK);
-  } catch {
-    return {
-      files: [],
-      diagnostics: [{
-        code: "sessions_unavailable",
-        severity: "info"
-      }]
-    };
-  }
-
-  const files = [];
-  await collectJsonlFiles(sessionsDir, files, diagnostics);
-
-  return {
-    files: files.sort(),
-    diagnostics
-  };
-}
-
-export async function* readSessionJsonlEntries(files) {
-  for (const file of files) {
-    let lineNumber = 0;
-
-    let lines;
-    try {
-      lines = createInterface({
-        crlfDelay: Infinity,
-        input: createReadStream(file, { encoding: "utf8" })
-      });
-    } catch {
-      yield { kind: "file_error" };
-      continue;
-    }
-
-    try {
-      for await (const line of lines) {
-        lineNumber += 1;
-
-        if (line.trim().length === 0) {
-          continue;
-        }
-
-        try {
-          yield {
-            file,
-            kind: "event",
-            event: JSON.parse(line)
-          };
-        } catch {
-          yield {
-            file,
-            kind: "malformed_line",
-            lineNumber
-          };
-        }
-      }
-    } catch {
-      yield { kind: "file_error" };
-    }
-  }
-}
-
-export function normalizeSessionTokenCountEvent(event) {
-  if (!isRecord(event) || event.type !== "event_msg") {
-    return null;
-  }
-
-  const payload = event.payload;
-  if (!isRecord(payload) || payload.type !== "token_count") {
-    return null;
-  }
-
-  const info = isRecord(payload.info) ? payload.info : null;
-
-  return {
-    durationMs: payload.duration_ms,
-    effort: payload.effort,
-    lastTokenUsage: readRecordAlias(payload, info, "last_token_usage"),
-    mode: payload.mode,
-    model: extractSessionModel(event),
-    timestamp: event.timestamp,
-    totalTokenUsage: readRecordAlias(payload, info, "total_token_usage")
-  };
-}
-
-export function normalizeSessionToolCatalogEvent(event) {
-  if (!isRecord(event) || event.type !== "session_meta") {
-    return null;
-  }
-
-  const payload = isRecord(event.payload) ? event.payload : null;
-  if (payload === null || !Array.isArray(payload.dynamic_tools)) {
-    return null;
-  }
-
-  const items = [];
-  for (const item of payload.dynamic_tools) {
-    if (!isRecord(item)) {
-      continue;
-    }
-
-    const name = readStringAlias(item.name);
-    if (name === null) {
-      continue;
-    }
-
-    items.push({
-      name,
-      namespace: readStringAlias(item.namespace)
-    });
-  }
-
-  return items.length > 0 ? { items } : null;
-}
-
-export function normalizeSessionToolInvocationEvent(event) {
-  if (!isRecord(event)) {
-    return null;
-  }
-
-  const payload = isRecord(event.payload) ? event.payload : null;
-  if (payload === null) {
-    return null;
-  }
-
-  if (
-    event.type === "response_item"
-    && (payload.type === "function_call" || payload.type === "custom_tool_call")
-  ) {
-    const name = readStringAlias(payload.name);
-    return name === null ? null : {
-      kind: "named_call",
-      name,
-      namespace: null
-    };
-  }
-
-  if (event.type === "event_msg" && payload.type === "dynamic_tool_call_request") {
-    const name = readStringAlias(payload.tool);
-    return name === null ? null : {
-      kind: "dynamic_request",
-      name,
-      namespace: readStringAlias(payload.namespace)
-    };
-  }
-
-  return null;
-}
-
-export function extractSessionModel(event) {
-  if (!isRecord(event)) {
-    return null;
-  }
-
-  const payload = isRecord(event.payload) ? event.payload : null;
-  if (payload === null) {
-    return null;
-  }
-
-  const info = isRecord(payload.info) ? payload.info : null;
-  const modelInfo = isRecord(payload.model_info) ? payload.model_info : null;
-
-  return readStringAlias(
-    modelInfo?.slug,
-    payload.model,
-    payload.model_name,
-    info?.model,
-    info?.model_name
-  );
-}
-
-async function collectJsonlFiles(directory, files, diagnostics) {
-  let entries;
-  try {
-    entries = await readdir(directory, { withFileTypes: true });
-  } catch {
-    diagnostics.push({
-      code: "session_directory_unreadable",
-      severity: "warning"
-    });
-    return;
-  }
-
-  for (const entry of entries) {
-    const entryPath = join(directory, entry.name);
-
-    if (entry.isDirectory()) {
-      await collectJsonlFiles(entryPath, files, diagnostics);
-    } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
-      files.push(entryPath);
-    }
-  }
-}
-
-function isRecord(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-function readRecordAlias(primary, secondary, key) {
-  if (isRecord(primary[key])) {
-    return primary[key];
-  }
-
-  if (isRecord(secondary?.[key])) {
-    return secondary[key];
-  }
-
-  return null;
-}
-
-function readStringAlias(...values) {
-  for (const value of values) {
-    if (typeof value === "string" && value.trim().length > 0) {
-      return value;
-    }
-  }
-
-  return null;
-}

package/src/parser/skill-plugin-aggregate.js

@@ -1,228 +0,0 @@
-import { resolveCodexHome } from "./codex-home.js";
-import {
-  discoverSessionJsonlFiles,
-  normalizeSessionToolCatalogEvent,
-  normalizeSessionToolInvocationEvent,
-  readSessionJsonlEntries
-} from "./session-jsonl.js";
-
-const TOP_LIMIT = 10;
-
-export async function aggregateSkillPluginUsageFromCodexHome(options = {}) {
-  const { codexHome, source } = resolveCodexHome(options);
-  const discovery = await discoverSessionJsonlFiles(codexHome);
-  const aggregate = await aggregateSkillPluginUsageFromSessionFiles(discovery.files);
-
-  aggregate.diagnostics.source = source;
-  aggregate.diagnostics.discovery = summarizeDiscovery(discovery.diagnostics);
-
-  if (discovery.files.length === 0) {
-    aggregate.diagnostics.status = "unavailable";
-    aggregate.diagnostics.reason = "session_jsonl_not_found";
-  }
-
-  return aggregate;
-}
-
-export async function aggregateSkillPluginUsageFromSessionFiles(files) {
-  const state = createAggregateState();
-
-  for await (const entry of readSessionJsonlEntries(files)) {
-    updateFileContext(state, entry);
-    state.diagnostics.entriesScanned += 1;
-
-    if (entry.kind === "malformed_line") {
-      state.diagnostics.malformedLines += 1;
-      continue;
-    }
-
-    if (entry.kind === "file_error") {
-      state.diagnostics.fileErrors += 1;
-      continue;
-    }
-
-    const catalog = normalizeSessionToolCatalogEvent(entry.event);
-    if (catalog !== null) {
-      state.diagnostics.catalogEvents += 1;
-      applyCatalogEvent(state, catalog);
-      continue;
-    }
-
-    const invocation = normalizeSessionToolInvocationEvent(entry.event);
-    if (invocation === null) {
-      state.diagnostics.ignoredEvents += 1;
-      continue;
-    }
-
-    applyInvocationEvent(state, invocation);
-  }
-
-  return finalizeAggregate(files.length, state);
-}
-
-function createAggregateState() {
-  return {
-    currentCatalog: new Map(),
-    currentFile: null,
-    diagnostics: {
-      status: "unavailable",
-      reason: "no_skill_plugin_invocations",
-      source: "session_jsonl",
-      filesScanned: 0,
-      entriesScanned: 0,
-      ignoredEvents: 0,
-      catalogEvents: 0,
-      catalogItems: 0,
-      actualInvocationEvents: 0,
-      classifiedSkillInvocations: 0,
-      classifiedPluginInvocations: 0,
-      unclassifiedInvocations: 0,
-      malformedLines: 0,
-      fileErrors: 0,
-      topLimit: TOP_LIMIT,
-      classificationBasis: "actual_invocation_with_session_catalog",
-      discovery: []
-    },
-    plugins: new Map(),
-    skills: new Map()
-  };
-}
-
-function updateFileContext(state, entry) {
-  if (entry.file === undefined || entry.file === state.currentFile) {
-    return;
-  }
-
-  state.currentCatalog = new Map();
-  state.currentFile = entry.file;
-}
-
-function applyCatalogEvent(state, catalog) {
-  for (const item of catalog.items) {
-    const kind = item.namespace === null ? "skill" : "plugin";
-    state.currentCatalog.set(item.name, {
-      id: createRankingId(kind, item.name, item.namespace),
-      kind,
-      name: item.name
-    });
-    state.diagnostics.catalogItems += 1;
-  }
-}
-
-function applyInvocationEvent(state, invocation) {
-  state.diagnostics.actualInvocationEvents += 1;
-
-  const catalogItem = state.currentCatalog.get(invocation.name);
-  const classified = catalogItem ?? classifyStandaloneInvocation(invocation);
-  if (classified === null) {
-    state.diagnostics.unclassifiedInvocations += 1;
-    return;
-  }
-
-  const target = classified.kind === "skill" ? state.skills : state.plugins;
-  const item = getRankingState(target, classified);
-  item.usageCount += 1;
-
-  if (classified.kind === "skill") {
-    state.diagnostics.classifiedSkillInvocations += 1;
-  } else {
-    state.diagnostics.classifiedPluginInvocations += 1;
-  }
-}
-
-function classifyStandaloneInvocation(invocation) {
-  if (invocation.kind !== "dynamic_request" || invocation.namespace === null) {
-    return null;
-  }
-
-  return {
-    id: createRankingId("plugin", invocation.name, invocation.namespace),
-    kind: "plugin",
-    name: invocation.name
-  };
-}
-
-function createRankingId(kind, name, namespace) {
-  if (kind === "plugin" && namespace !== null) {
-    return `${namespace}/${name}`;
-  }
-
-  return name;
-}
-
-function getRankingState(items, classified) {
-  const existing = items.get(classified.id);
-  if (existing !== undefined) {
-    return existing;
-  }
-
-  const item = {
-    displayName: classified.name,
-    id: classified.id,
-    name: classified.name,
-    usageCount: 0
-  };
-  items.set(item.id, item);
-  return item;
-}
-
-function finalizeAggregate(filesScanned, state) {
-  const topSkills = finalizeRanking(state.skills);
-  const topPlugins = finalizeRanking(state.plugins);
-  const hasClassifiedInvocations = topSkills.length > 0 || topPlugins.length > 0;
-
-  state.diagnostics.filesScanned = filesScanned;
-  state.diagnostics.status = hasClassifiedInvocations ? "ok" : state.diagnostics.status;
-  state.diagnostics.reason = hasClassifiedInvocations ? null : state.diagnostics.reason;
-
-  return {
-    diagnostics: state.diagnostics,
-    skills: {
-      exploredCount: hasClassifiedInvocations ? state.skills.size : null,
-      totalUsed: hasClassifiedInvocations ? state.diagnostics.classifiedSkillInvocations : null,
-      topSkills
-    },
-    plugins: {
-      topPlugins
-    }
-  };
-}
-
-function finalizeRanking(items) {
-  return Array.from(items.values())
-    .sort(compareRankingItem)
-    .slice(0, TOP_LIMIT)
-    .map((item) => ({
-      id: item.id,
-      name: item.name,
-      displayName: item.displayName,
-      usageCount: item.usageCount
-    }));
-}
-
-function compareRankingItem(left, right) {
-  const countDiff = right.usageCount - left.usageCount;
-  if (countDiff !== 0) return countDiff;
-
-  const displayNameDiff = compareNullableString(left.displayName, right.displayName);
-  if (displayNameDiff !== 0) return displayNameDiff;
-
-  const nameDiff = compareNullableString(left.name, right.name);
-  if (nameDiff !== 0) return nameDiff;
-
-  return left.id.localeCompare(right.id);
-}
-
-function compareNullableString(left, right) {
-  if (left === null && right === null) return 0;
-  if (left === null) return 1;
-  if (right === null) return -1;
-  return left.localeCompare(right);
-}
-
-function summarizeDiscovery(diagnostics) {
-  return diagnostics.map((diagnostic) => ({
-    code: diagnostic.code,
-    severity: diagnostic.severity
-  }));
-}

package/src/parser/token-aggregate.js

@@ -1,229 +0,0 @@
-import { resolveCodexHome } from "./codex-home.js";
-import {
-  discoverSessionJsonlFiles,
-  normalizeSessionTokenCountEvent,
-  readSessionJsonlEntries
-} from "./session-jsonl.js";
-
-const TOKEN_FIELDS = [
-  ["inputTokens", "input_tokens"],
-  ["outputTokens", "output_tokens"],
-  ["cacheReadTokens", "cached_input_tokens", "cache_read_input_tokens"],
-  ["cacheWriteTokens", "cache_write_input_tokens", "cache_write_tokens"],
-  ["reasoningTokens", "reasoning_output_tokens"]
-];
-
-export async function aggregateTokenUsageFromCodexHome(options = {}) {
-  const { codexHome, source } = resolveCodexHome(options);
-  const discovery = await discoverSessionJsonlFiles(codexHome);
-  const aggregate = await aggregateTokenUsageFromSessionFiles(discovery.files);
-
-  aggregate.diagnostics.source = source;
-  aggregate.diagnostics.discovery = summarizeDiscovery(discovery.diagnostics);
-
-  if (discovery.files.length === 0) {
-    aggregate.diagnostics.status = "unavailable";
-    aggregate.diagnostics.reason = "session_jsonl_not_found";
-  }
-
-  return aggregate;
-}
-
-export async function aggregateTokenUsageFromSessionFiles(files) {
-  const state = createAggregateState();
-
-  for await (const entry of readSessionJsonlEntries(files)) {
-    state.diagnostics.entriesScanned += 1;
-
-    if (entry.kind === "malformed_line") {
-      state.diagnostics.malformedLines += 1;
-      continue;
-    }
-
-    if (entry.kind === "file_error") {
-      state.diagnostics.fileErrors += 1;
-      continue;
-    }
-
-    const tokenEvent = normalizeSessionTokenCountEvent(entry.event);
-    if (tokenEvent === null) {
-      state.diagnostics.ignoredEvents += 1;
-      continue;
-    }
-
-    state.diagnostics.tokenEvents += 1;
-
-    if (tokenEvent.lastTokenUsage === null) {
-      state.diagnostics.tokenEventsWithoutLastUsage += 1;
-      continue;
-    }
-
-    applyTokenEvent(state, tokenEvent);
-  }
-
-  return finalizeAggregate(files.length, state);
-}
-
-function createAggregateState() {
-  return {
-    breakdown: createNullableTokenBreakdownState(),
-    daily: new Map(),
-    diagnostics: {
-      status: "unavailable",
-      reason: "no_token_events",
-      source: "session_jsonl",
-      filesScanned: 0,
-      entriesScanned: 0,
-      ignoredEvents: 0,
-      tokenEvents: 0,
-      tokenEventsWithUsage: 0,
-      tokenEventsWithoutLastUsage: 0,
-      malformedLines: 0,
-      fileErrors: 0,
-      discovery: []
-    },
-    totalTokens: 0
-  };
-}
-
-function applyTokenEvent(state, tokenEvent) {
-  const totalTokens = getTokenUsageTotal(tokenEvent.lastTokenUsage);
-  if (totalTokens === null) {
-    state.diagnostics.tokenEventsWithoutLastUsage += 1;
-    return;
-  }
-
-  state.totalTokens += totalTokens;
-  state.diagnostics.tokenEventsWithUsage += 1;
-  addTokenUsageBreakdown(state.breakdown, tokenEvent.lastTokenUsage);
-
-  const date = getUtcDate(tokenEvent.timestamp);
-  if (date !== null) {
-    const daily = getDailyBucket(state.daily, date);
-    daily.totalTokens += totalTokens;
-    addTokenUsageBreakdown(daily.breakdown, tokenEvent.lastTokenUsage);
-  }
-}
-
-function finalizeAggregate(filesScanned, state) {
-  const daily = Array.from(state.daily.entries())
-    .sort(([left], [right]) => left.localeCompare(right))
-    .map(([date, bucket]) => ({
-      date,
-      totalTokens: bucket.totalTokens,
-      ...finalizeTokenBreakdown(bucket.breakdown)
-    }));
-
-  const peakDailyTokens = daily.length > 0
-    ? Math.max(...daily.map((bucket) => bucket.totalTokens))
-    : null;
-
-  const hasUsage = state.diagnostics.tokenEventsWithUsage > 0;
-  state.diagnostics.filesScanned = filesScanned;
-  state.diagnostics.status = hasUsage ? "ok" : state.diagnostics.status;
-  state.diagnostics.reason = hasUsage ? null : state.diagnostics.reason;
-
-  return {
-    diagnostics: state.diagnostics,
-    usage: {
-      totalTokens: state.totalTokens,
-      peakDailyTokens,
-      tokenBreakdown: finalizeTokenBreakdown(state.breakdown),
-      daily
-    }
-  };
-}
-
-export function getTokenUsageTotal(usage) {
-  const explicitTotal = readNonNegativeInteger(usage.total_tokens);
-  if (explicitTotal !== null) {
-    return explicitTotal;
-  }
-
-  let total = 0;
-  let hasAnyField = false;
-  for (const [, ...sourceKeys] of TOKEN_FIELDS) {
-    const value = readFirstNonNegativeInteger(usage, sourceKeys);
-    if (value !== null) {
-      total += value;
-      hasAnyField = true;
-    }
-  }
-
-  return hasAnyField ? total : null;
-}
-
-export function addTokenUsageBreakdown(target, usage) {
-  for (const [targetKey, ...sourceKeys] of TOKEN_FIELDS) {
-    const value = readFirstNonNegativeInteger(usage, sourceKeys);
-    if (value !== null) {
-      target[targetKey].seen = true;
-      target[targetKey].value += value;
-    }
-  }
-}
-
-export function createNullableTokenBreakdownState() {
-  return {
-    inputTokens: { seen: false, value: 0 },
-    outputTokens: { seen: false, value: 0 },
-    cacheReadTokens: { seen: false, value: 0 },
-    cacheWriteTokens: { seen: false, value: 0 },
-    reasoningTokens: { seen: false, value: 0 }
-  };
-}
-
-export function finalizeTokenBreakdown(state) {
-  return Object.fromEntries(Object.entries(state).map(([key, entry]) => {
-    return [key, entry.seen ? entry.value : null];
-  }));
-}
-
-function getDailyBucket(buckets, date) {
-  const existing = buckets.get(date);
-  if (existing !== undefined) {
-    return existing;
-  }
-
-  const bucket = {
-    breakdown: createNullableTokenBreakdownState(),
-    totalTokens: 0
-  };
-  buckets.set(date, bucket);
-  return bucket;
-}
-
-export function getUtcDate(value) {
-  if (typeof value !== "string") {
-    return null;
-  }
-
-  const date = new Date(value);
-  if (Number.isNaN(date.getTime())) {
-    return null;
-  }
-
-  return date.toISOString().slice(0, 10);
-}
-
-function readFirstNonNegativeInteger(record, keys) {
-  for (const key of keys) {
-    const value = readNonNegativeInteger(record[key]);
-    if (value !== null) {
-      return value;
-    }
-  }
-
-  return null;
-}
-
-function readNonNegativeInteger(value) {
-  return Number.isInteger(value) && value >= 0 ? value : null;
-}
-
-function summarizeDiscovery(diagnostics) {
-  return diagnostics.map((diagnostic) => ({
-    code: diagnostic.code,
-    severity: diagnostic.severity
-  }));
-}

package/src/snapshot/index.js

@@ -1,6 +0,0 @@
-export {
-  USAGE_SNAPSHOT_V2_SCHEMA_VERSION,
-  assertUsageSnapshotV2,
-  isUsageSnapshotV2,
-  validateUsageSnapshotV2
-} from "./v2-schema.js";