diff --git a/README.md b/README.md index ce0e8ef..cb9a397 100644 --- a/README.md +++ b/README.md @@ -70,13 +70,38 @@ both, so rows can add up to more than the total. With `--breakdown`, a **Per Session** column gives each tool / skill / command / agent count divided by the row's sessions. -Every period report, `session` included, ends with a **Skills** table: every +Every period report, `session` included, has a **Skills** table: every skill used in the range, by model and by user, with estimated tokens and cost, as in the summary. `--top` limits the breakdown sub-rows, not this list. +In table, Markdown and HTML output the overview comes first: skills, plugins, +usage limits and any `-a` / `-r` sections. The period table itself (*Usage per +session*, *per day*, ...) is at the bottom. CSV keeps the period table first. +Every report names the period its data covers, from the first to the last +activity within the filters, e.g. `Data: 2025-12-06 → 2026-11-04 (334 days)`. +It also appears as `coverage` in JSON. Below it are the headline figures: +sessions, prompts, tool calls, pull requests, tokens and estimated cost. In +HTML these are tiles, followed by a row of links to every section. Each table +keeps to the window width and scrolls sideways on its own. *Phase mix per +week* draws the phase shares as one stacked bar, and weeks with fewer than 3 +sessions are dimmed. HTML reports add a **How it's measured** +section above the period table. It describes the data read, the period and +time zone, and how sessions, tokens, cost, tools, usage limits, adoption phases, +session intent and recommendations are counted, covering only what the +report contains. The section starts collapsed. HTML also folds what is long: +the period report's Skills table shows its top 15 rows with a *Show all* +button, and the sort order is kept when it folds. Recommendations with low +impact or under $1 at stake sit under a "more" toggle. Table, Markdown and +CSV output keep everything open. + The `session` report names each session by its title (the first 8 characters of its id when it has none), cut to at most 35 characters with `…` in every -display format. JSON keeps the full title. +display format. JSON keeps the full title. Each session's **Intent**, +**Phase** (as in the adoption report) and **Prompts** follow *Last Activity*. +HTML and Markdown list the newest session first, and `--order asc|desc` +overrides that. With `--source all` a **Tool** +column names the AI tool each session ran in (Claude Code, GitHub Copilot or +Cursor); JSON rows always have it as `tool`. **Tokens per tool, skill and subagent.** Breakdown sub-rows fill the token columns like their parent row: *Output* (the tool input the model wrote), diff --git a/bin/ccreports.mjs b/bin/ccreports.mjs index 18cae69..d1fe28a 100644 --- a/bin/ccreports.mjs +++ b/bin/ccreports.mjs @@ -9,9 +9,10 @@ import { loadCursorRecords, defaultCursorDirs } from '../src/cursor.mjs'; import { defaultCursorUserDirs } from '../src/cursor-state.mjs'; import { aggregate, parseDateArg, toJSON, REPORTS } from '../src/aggregate.mjs'; import { buildPeriodReport, buildSummary } from '../src/report.mjs'; +import { coverage, methodSection } from '../src/method.mjs'; import { FORMATS, toTerminal, toMarkdown, toCsv, toHtml } from '../src/formats.mjs'; import { loadPricingTable, createPricer } from '../src/pricing.mjs'; -import { buildAdoption, buildIntents, parseIntents, PHASES, AUTONOMY_THRESHOLD } from '../src/adoption.mjs'; +import { buildAdoption, buildIntents, parseIntents, sessionStats, PHASES, AUTONOMY_THRESHOLD } from '../src/adoption.mjs'; import { INTENTS } from '../src/intent.mjs'; import { buildRecommendations } from '../src/recommendations.mjs'; import { openFile, FORMAT_EXTENSIONS } from '../src/open.mjs'; @@ -214,7 +215,9 @@ if (showCost) { } const result = aggregate(data, { report, since, until, project: opts.project, timeZone: opts.timezone, pricer }); -if (opts.order === 'desc') result.buckets.reverse(); +// Documents read top-down list the newest session first; --order overrides. +const newestFirst = !opts.order && report === 'session' && ['html', 'markdown'].includes(format); +if (opts.order === 'desc' || newestFirst) result.buckets.reverse(); // Warnings go to stderr so redirected output stays clean. if (showCost) { @@ -249,6 +252,8 @@ const docOpts = { plugins, product, intents, + // Session reports over several products name each session's tool. + toolColumn: source === 'all', // No token usage at all (Cursor alone): reports leave out the token columns. tokens: data.usage.length > 0, }; @@ -284,9 +289,25 @@ const usageLimits = ['adoption', 'recommendations'].includes(report) ? null : limitStats(data, { since, until, project: opts.project, timeZone: opts.timezone }); +// The period the data covers: first to last activity within the filters. +const range = coverage(result.totals, { timeZone: opts.timezone }); + +// Per-session phase, intent, prompts and PRs (the adoption assessment's stats): +// columns of the session table and figures in the headline. +const documentFormat = ['table', 'markdown', 'html'].includes(format); +const perSession = adoption?.stats ?? (documentFormat && result.totals.sessions.size ? sessionStats(data, docOpts) : null); +if (perSession && report === 'session') { + const phaseTitle = Object.fromEntries(PHASES.map((p) => [p.key, p.title.replace(/^Phase \d · /, '')])); + const intentTitle = Object.fromEntries(INTENTS.map((i) => [i.key, i.title])); + docOpts.sessionInfo = new Map( + perSession.map((s) => [s.id, { phase: phaseTitle[s.phase] ?? '', intent: intentTitle[s.intent] ?? '', prompts: s.prompts }]), + ); +} + let output; if (format === 'json') { const meta = { report, source, since, until, pricingSource, ccreportsVersion: VERSION }; + if (range) meta.coverage = { from: range.from, to: range.to, days: range.days }; const adoptionJson = adoption && { summary: adoption.summary, phases: PHASES, @@ -332,6 +353,29 @@ if (format === 'json') { if (!part || part === doc) continue; doc = { ...doc, summary: [...(doc.summary ?? []), ...part.summary], sections: [...doc.sections, ...part.sections] }; } + // A page to read: how it is measured, then the period table (per session, + // day, ...) at the bottom, below the overview sections. + const tail = []; + if (format === 'html') { + const has = { + claude: !!claudeData?.files, + copilot: !!copilotData?.files, + cursor: !!cursorData?.files, + cost: showCost, + breakdown: report === 'summary' || !!opts.breakdown, + shell: opts.shell, + adoption: !!adoption, + intentsByClaude: !!intents, + recommendations: !!advice, + }; + tail.push(methodSection(has, { since, until, project: opts.project, timeZone: opts.timezone, pricingSource, range })); + } + doc = { + ...doc, + kpis: headline(result.totals, perSession, { showCost, tokens: data.usage.length > 0 }), + coverage: range, + sections: [...doc.sections.filter((s) => !s.main), ...tail, ...doc.sections.filter((s) => s.main)], + }; output = { table: () => toTerminal(doc, { color: toTTY && !opts['no-color'] && !process.env.NO_COLOR, version: VERSION }) + '\n', markdown: () => toMarkdown(doc, { version: VERSION }), @@ -361,3 +405,16 @@ if (file) { } else { process.stdout.write(output); } + +/** The headline figures: sessions, prompts, tool calls, PRs, tokens and cost. */ +function headline(totals, perSession, { showCost, tokens }) { + const sum = (f) => perSession.reduce((n, s) => n + f(s), 0); + return [ + { label: 'sessions', value: totals.sessions.size }, + ...(perSession ? [{ label: 'prompts', value: sum((s) => s.prompts) }] : []), + { label: 'tool calls', value: totals.toolCalls }, + ...(perSession ? [{ label: 'pull requests', value: sum((s) => s.prs) }] : []), + ...(tokens ? [{ label: 'tokens', value: totals.totalTokens, compact: true }] : []), + ...(showCost ? [{ label: 'estimated cost', value: totals.costUSD, usd: true }] : []), + ]; +} diff --git a/skills/report/SKILL.md b/skills/report/SKILL.md index 0f2b228..d8bfec6 100644 --- a/skills/report/SKILL.md +++ b/skills/report/SKILL.md @@ -50,6 +50,9 @@ Useful options: `-s/--since` and `-u/--until` (`YYYYMMDD`), `-p/--project - For a page to view or share, write HTML to a file in the current working directory unless the user names another place, e.g. `-f html -o ccreports-adoption.html`, then give the user the full path. + HTML reports list the overview first, then a *How it's measured* section + and the period table (per session, day, ...) at the bottom; the header + names the period the data covers. When they ask to see or open it, add `--open`: the CLI launches the file in its associated app (browser for HTML, Excel for CSV). From your shell it does not open files unless `--open` is passed. diff --git a/src/adoption.mjs b/src/adoption.mjs index dc4d9ce..2325313 100644 --- a/src/adoption.mjs +++ b/src/adoption.mjs @@ -223,9 +223,9 @@ export function buildAdoption(data, opts) { const cohortColumns = [ left('Phase'), left('How'), - right('PRs per session'), + right('Of sessions'), right('Sessions'), - right('Share of sessions'), + right('PRs per session'), right('PRs'), right('Edits per session'), right('Median tool calls per prompt'), @@ -244,9 +244,9 @@ export function buildAdoption(data, opts) { cells: [ p.title, p.description.replace(/^Claude\b/, agentName), - average(prs, list.length), - list.length, share(list.length, stats.length), + list.length, + average(prs, list.length), prs, average(sum(list, (s) => s.edits), list.length), m == null ? '' : average(m, 1), @@ -272,6 +272,8 @@ export function buildAdoption(data, opts) { } const weeks = [...weekMap.values()].sort((a, b) => (a.key < b.key ? -1 : 1)); const weekRows = weeks.map((w) => ({ + // Weeks with only a session or two swing between 0% and 100%. + muted: w.total < 3, cells: [ w.key, w.total, @@ -327,7 +329,9 @@ export function buildAdoption(data, opts) { { title: 'Adoption cohorts', note: `sessions by how they used ${opts.product ?? 'Claude Code'}`, cards: true, columns: cohortColumns, rows: cohortRows }, { title: 'Phase mix per week', - note: 'by the week a session started', + note: 'by the week a session started; weeks with fewer than 3 sessions are dimmed', + // HTML draws the phase shares as one stacked bar. + stack: { start: 2, count: PHASES.length, title: 'Phase mix' }, columns: [ left('Week'), right('Sessions'), diff --git a/src/aggregate.mjs b/src/aggregate.mjs index 77966fa..ba741b5 100644 --- a/src/aggregate.mjs +++ b/src/aggregate.mjs @@ -97,6 +97,13 @@ function newBucket(key) { export const MAIN_AGENT = '(main session)'; +/** The AI tool a session ran in, from its entrypoint (copilot-cli, cursor-ide, cli, ...). */ +export function toolOf(entrypoint) { + if (entrypoint?.startsWith('copilot')) return 'GitHub Copilot'; + if (entrypoint?.startsWith('cursor')) return 'Cursor'; + return 'Claude Code'; +} + function agentEntry(bucket, type) { const key = type ?? MAIN_AGENT; if (!bucket.agents.has(key)) { @@ -327,7 +334,10 @@ export function aggregate(data, { report = 'summary', since, until, project, tim b.avgContextTokens = b.contextRequests ? Math.round(b.contextTokensSum / b.contextRequests) : 0; } if (report === 'session') { - for (const b of list) b.title = data.titles.get(b.key) ?? null; + for (const b of list) { + b.title = data.titles.get(b.key) ?? null; + b.tool = toolOf(data.sessions?.get(b.key)?.entrypoint); + } list.sort((a, b) => (a.lastActivity < b.lastActivity ? -1 : 1)); } else if (report === 'project') { list.sort((a, b) => a.totalTokens - b.totalTokens); diff --git a/src/formats.mjs b/src/formats.mjs index 7f2468d..1d08a9f 100644 --- a/src/formats.mjs +++ b/src/formats.mjs @@ -23,6 +23,8 @@ function cellText(cell, { csv = false } = {}) { if (cell.v == null) return csv ? '' : '-'; return csv ? (cell.v * 100).toFixed(2) : `${(cell.v * 100).toFixed(1)}%`; } + // Shares drawn as one stacked bar (HTML); as text: "Chat 40.0% · Assisted 20.0%". + if (cell.kind === 'stack') return cell.parts.map((p) => `${p.label} ${cellText({ kind: 'pct', v: p.v })}`).join(' · '); return String(cell); } @@ -81,10 +83,14 @@ function terminalTable({ columns, rows }, c) { export function toTerminal(doc, { color = false, version } = {}) { const c = paint(color); const out = [c.bold(doc.title)]; + if (doc.coverage) out.push(c.dim(`Data: ${doc.coverage.text}`)); + if (doc.kpis?.length) out.push(doc.kpis.map((k) => `${c.bold(kpiValue(k))} ${k.label}`).join(' · ')); if (doc.summary?.length) out.push(...doc.summary.map((l) => `• ${l}`), ''); doc.sections.forEach((s, i) => { if (s.title) out.push((i > 0 ? '\n' : '') + c.bold(s.title) + (s.note ? c.dim(` (${s.note})`) : '')); - if (s.items) { + if (s.notes) { + for (const note of s.notes) out.push('', `${c.bold(note.term)}: ${note.text}`); + } else if (s.items) { s.items.forEach((item, n) => { out.push('', `${n + 1}. ${c.bold(item.title)} ${c.dim(`[${itemImpact(item)}]`)}`); out.push(` ${c.dim('Evidence:')} ${item.evidence}`, ` ${c.cyan('→')} ${item.advice}`); @@ -118,10 +124,16 @@ const mdEscape = (s) => s.replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/ export function toMarkdown(doc, { version } = {}) { const out = [`# ${doc.title}`]; + if (doc.coverage) out.push('', `_Data: ${doc.coverage.text}_`); + if (doc.kpis?.length) out.push('', doc.kpis.map((k) => `**${kpiValue(k)}** ${k.label}`).join(' · ')); if (doc.summary?.length) out.push('', ...doc.summary.map((l) => `- ${l}`)); for (const s of doc.sections) { out.push(''); if (s.title) out.push(`## ${s.title}${s.note ? ` _(${s.note})_` : ''}`, ''); + if (s.notes) { + for (const note of s.notes) out.push(`- **${note.term}:** ${note.text}`); + continue; + } if (s.items) { s.items.forEach((item, n) => { out.push(`### ${n + 1}. ${item.title}`, '', `_${itemImpact(item)}_`, '', `**Evidence:** ${item.evidence}`, '', `**Do:** ${item.advice}`, ''); @@ -154,7 +166,7 @@ const csvField = (s) => (/[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s); */ export function toCsv(doc) { return ( - doc.sections + [...doc.sections.filter((s) => s.main), ...doc.sections.filter((s) => !s.main && !s.notes)] .map((section) => { const s = section.items ? itemsTable(section.items) : section; const lines = [s.columns.map((col) => csvField(col.title)).join(',')]; @@ -173,8 +185,13 @@ export function toCsv(doc) { const esc = (s) => String(s).replace(/[&<>"']/g, (ch) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[ch]); -function htmlTable({ columns, rows }) { +function htmlTable({ columns, rows, fold }) { const hasSubRows = rows.some((r) => r.style === 'sub'); + // Long tables show their first `fold` rows; a button opens the rest. Folding + // only pays off when it hides more than a couple of rows. + const bodyRows = rows.filter((r) => r.style !== 'total').length; + const folded = !hasSubRows && fold > 0 && bodyRows > fold + 2; + let shownRows = 0; const sortable = !hasSubRows; const head = columns .map((col) => `${esc(col.title)}`) @@ -202,6 +219,12 @@ function htmlTable({ columns, rows }) { ? '' : ''; // Clipped paths show in full on hover. + if (cell?.kind === 'stack') { + const segs = cell.parts + .map((p, n) => (p.v ? `` : '')) + .join(''); + return `
${segs}
`; + } const text = cellText(cell); const shown = clipStart(text, col, r); if (shown !== text) attrs.push(`title="${esc(text)}"`); @@ -209,7 +232,9 @@ function htmlTable({ columns, rows }) { }) .join(''); const rowAttrs = []; - if (r.style) rowAttrs.push(`class="${r.style}"`); + const rowClasses = [r.style, r.muted && 'muted'].filter(Boolean); + if (rowClasses.length) rowAttrs.push(`class="${rowClasses.join(' ')}"`); + if (folded && r.style !== 'total' && ++shownRows > fold) rowAttrs.push('hidden'); if (isSub) rowAttrs.push(`data-parent="${group}" hidden`); if (hasChildren) rowAttrs.push(`data-group="${group}"`); return `${cells}`; @@ -219,7 +244,10 @@ function htmlTable({ columns, rows }) { const controls = hasSubRows ? '
\n' : ''; - return `${controls}
\n${head}\n\n${body}\n
`; + const more = folded + ? `\n
` + : ''; + return `${controls}
\n${head}\n\n${body}\n
${more}`; } /** @@ -229,12 +257,22 @@ function htmlTable({ columns, rows }) { /** Escaped text with `inline code` as . */ const escCode = (s) => esc(s).replace(/`([^`]+)`/g, '$1'); +/** Low impact, or less than $1 at stake: listed under "more", folded. */ +export const minorItem = (item) => item.impact === 'low' || (item.atStakeUSD != null && item.atStakeUSD < 1); + function htmlItems(items) { - const list = items.map( - (item, n) => - `
  • ${n + 1}

    ${esc(item.title)}

    ${esc(itemImpact(item))}

    ${escCode(item.evidence)}

    ${escCode(item.advice)}

  • `, - ); - return `
      ${list.join('\n')}
    `; + const li = (item, n) => + `
  • ${n + 1}

    ${esc(item.title)}

    ${esc(itemImpact(item))}

    ${escCode(item.evidence)}

    ${escCode(item.advice)}

  • `; + // Items come most impact first, so the minor ones are a tail; at least one stays open. + let main = items.findIndex(minorItem); + if (main === -1) main = items.length; + if (main === 0) main = 1; + const open = items.slice(0, main).map((item, n) => li(item, n)); + const rest = items.slice(main).map((item, n) => li(item, main + n)); + const more = rest.length + ? `\n
    ${rest.length} more, with less at stake
      ${rest.join('\n')}
    ` + : ''; + return `
      ${open.join('\n')}
    ${more}`; } function htmlCards({ columns, rows }) { @@ -248,22 +286,86 @@ function htmlCards({ columns, rows }) { return `
    ${cards.join('\n')}
    `; } +const slug = (s) => + s + .toLowerCase() + .replace(/[^a-z0-9]+/g, '-') + .replace(/^-|-$/g, ''); + +/** A headline figure: 1,234 · $56.78 · 1.2B tokens. */ +export function kpiValue({ value, usd, compact }) { + if (usd) return cellText({ kind: 'usd', v: value }); + if (compact) { + for (const [n, unit] of [[1e9, 'B'], [1e6, 'M'], [1e3, 'k']]) { + if (value >= n) return `${(value / n).toLocaleString('en-US', { maximumFractionDigits: value >= n * 100 ? 0 : 1 })}${unit}`; + } + } + return value.toLocaleString('en-US'); +} + +/** + * A section whose columns start..start+count are shares of one whole (phases + * per week): those columns become one stacked bar, with a legend. + */ +function stackSection(s) { + const { start, count, title } = s.stack; + const labels = s.columns.slice(start, start + count).map((c) => c.title.replace(/^Phase \d · /, '')); + return { + ...s, + legend: labels, + columns: [...s.columns.slice(0, start), { title, align: 'left' }, ...s.columns.slice(start + count)], + rows: s.rows.map((r) => ({ + ...r, + cells: [ + ...r.cells.slice(0, start), + { kind: 'stack', parts: r.cells.slice(start, start + count).map((c, i) => ({ label: labels[i], v: c?.v ?? 0 })) }, + ...r.cells.slice(start + count), + ], + })), + }; +} + export function toHtml(doc, { generatedAt = new Date(), pricingSource, version, copilot = false } = {}) { const meta = [`Generated ${generatedAt.toLocaleString('sv-SE').slice(0, 16)}${version ? ` with ccreports ${version}` : ''}`]; if (copilot) meta.push('GitHub Copilot cost from its billed AI credits'); if (pricingSource) { meta.push(`${copilot ? 'other ' : ''}cost estimates at ${pricingSource === 'builtin' ? 'built-in ' : ''}Claude API list prices`); } + // Section ids for the table of contents. + const ids = new Map(); + const idOf = (s, n) => { + if (!ids.has(s)) ids.set(s, `s${n + 1}-${slug(s.title ?? '')}`); + return ids.get(s); + }; + const toc = + doc.sections.filter((s) => s.title).length > 3 + ? `\n` + : ''; const sections = doc.sections - .map((s) => { - const heading = s.title ? `

    ${esc(s.title)}${s.note ? ` ${esc(s.note)}` : ''}

    ` : ''; + .map((section, n) => { + const s = section.stack ? stackSection(section) : section; + const id = idOf(section, n); + const heading = s.title ? `

    ${esc(s.title)}${s.note ? ` ${esc(s.note)}` : ''}

    ` : ''; + // Reference material: collapsed, the heading opens it. + if (s.notes) + return `
    ${heading} +
    ${s.notes.map((n) => `
    ${esc(n.term)}
    ${escCode(n.text)}
    `).join('')}
    `; if (s.items) return `
    ${heading}\n${htmlItems(s.items)}
    `; - return s.cards ? `
    ${heading}\n${htmlCards(s)}
    ` : `
    ${heading}\n${htmlTable(s)}
    `; + if (s.cards) return `
    ${heading}\n${htmlCards(s)}
    `; + const legend = s.legend + ? `
    ${s.legend.map((label, i) => `${esc(label)}`).join('')}
    \n` + : ''; + return `
    ${heading}\n${legend}${htmlTable(s)}
    `; }) .join('\n'); const summary = doc.summary?.length ? `
      ${doc.summary.map((l) => `
    • ${esc(l)}
    • `).join('')}
    \n` : ''; + const kpis = doc.kpis?.length + ? `
    ${doc.kpis.map((k) => `
    ${esc(kpiValue(k))}${esc(k.label)}
    `).join('')}
    \n` + : ''; return ` @@ -278,10 +380,24 @@ export function toHtml(doc, { generatedAt = new Date(), pricingSource, version, } * { box-sizing:border-box; } body { margin:0; background:var(--bg); color:var(--fg); font:14px/1.45 system-ui,-apple-system,"Segoe UI",sans-serif; } -/* The page grows to its widest table: one horizontal scrollbar for the page, not one per table. */ -main { padding:24px 16px 48px; width:fit-content; min-width:100%; } -/* Text stays at window width when the page is wider. */ -.meta, .summary, section.plain { max-width:calc(100vw - 32px); } +/* Sections keep to the window; a table wider than its section scrolls on its own. */ +main { padding:24px 16px 48px; max-width:100%; } +.scroll { overflow-x:auto; } +.kpis { display:flex; flex-wrap:wrap; gap:10px; margin:0 0 16px; } +.kpi { background:var(--card); border:1px solid var(--line); border-radius:10px; padding:10px 16px; min-width:120px; } +.kpi b { display:block; font-size:22px; font-variant-numeric:tabular-nums; } +.kpi span { color:var(--muted); font-size:13px; } +.toc { display:flex; flex-wrap:wrap; gap:6px; margin:0 0 16px; } +.toc a { font-size:13px; color:var(--fg); text-decoration:none; border:1px solid var(--line); border-radius:999px; padding:2px 10px; background:var(--card); } +.toc a:hover { border-color:var(--accent); color:var(--accent); } +h2[id] { scroll-margin-top:12px; } +:root { --seg0:#9ca3af; --seg1:#93c5fd; --seg2:#3b82f6; --seg3:#7c3aed; } +.seg0 { background:var(--seg0); } .seg1 { background:var(--seg1); } .seg2 { background:var(--seg2); } .seg3 { background:var(--seg3); } +.stackcell { min-width:260px; width:40%; } +.stack { display:flex; height:14px; border-radius:4px; overflow:hidden; background:var(--line); } +.legend { display:flex; flex-wrap:wrap; gap:14px; margin:0 0 8px; font-size:13px; color:var(--muted); } +.legend i { display:inline-block; width:10px; height:10px; border-radius:2px; margin-right:6px; vertical-align:-1px; } +tr.muted td { opacity:.5; } h1 { font-size:22px; margin:0 0 4px; } .meta { color:var(--muted); margin:0 0 20px; } section { background:var(--card); border:1px solid var(--line); border-radius:10px; padding:14px 16px; margin:0 0 16px; } @@ -290,6 +406,10 @@ h2 { font-size:15px; margin:0 0 10px; } .summary { background:var(--card); border:1px solid var(--line); border-left:3px solid var(--accent); border-radius:10px; margin:0 0 16px; padding:12px 16px 12px 34px; } .summary li { margin:3px 0; } section.plain { background:none; border:0; padding:0; } +.meta strong { color:var(--fg); font-weight:600; } +section.method dl { display:grid; grid-template-columns:minmax(140px, max-content) 1fr; gap:8px 16px; margin:0; } +section.method dt { font-weight:600; } section.method dd { margin:0; color:var(--muted); } +@media (max-width:640px) { section.method dl { grid-template-columns:1fr; gap:2px; } section.method dd { margin-bottom:8px; } } .recs { list-style:none; margin:0; padding:0; display:grid; gap:10px; } .rec { background:var(--card); border:1px solid var(--line); border-left:4px solid var(--muted); border-radius:10px; padding:12px 16px; } .rec.high { border-left-color:#dc2626; } .rec.medium { border-left-color:#d97706; } .rec.low { border-left-color:var(--accent); } @@ -299,6 +419,13 @@ section.plain { background:none; border:0; padding:0; } .badge { margin-left:auto; font-size:12px; color:var(--muted); border:1px solid var(--line); border-radius:999px; padding:1px 8px; } .evidence { color:var(--muted); margin:6px 0 4px; } .advice { margin:0; } +details.more { margin-top:10px; } +details.more > summary, section.method summary { cursor:pointer; color:var(--muted); } +details.more > summary:hover, section.method summary:hover { color:var(--accent); } +details.more > .recs { margin-top:10px; } +section.method summary h2 { display:inline; margin:0; color:var(--fg); } +section.method details[open] > summary { margin-bottom:10px; } +.controls.fold { margin:10px 0 0; } code { font-family:ui-monospace,SFMono-Regular,Consolas,monospace; font-size:12.5px; background:var(--bar); border-radius:4px; padding:0 4px; } .cards { display:grid; grid-template-columns:repeat(auto-fit, minmax(240px, 1fr)); gap:12px; } .card { background:var(--card); border:1px solid var(--line); border-radius:10px; padding:14px 16px; } @@ -334,8 +461,8 @@ tbody tr:not(.total):hover td { background-color:var(--bar); }

    ${esc(doc.title)}

    -

    ${esc(meta.join(' · '))}

    -${summary}${sections} +

    ${doc.coverage ? `Data: ${esc(doc.coverage.text)} · ` : ''}${esc(meta.join(' · '))}

    +${kpis}${summary}${toc}${sections}
    diff --git a/src/method.mjs b/src/method.mjs new file mode 100644 index 0000000..b3d3e88 --- /dev/null +++ b/src/method.mjs @@ -0,0 +1,133 @@ +// "How it's measured": what a report is built from and how its figures are +// counted, limited to the sources and sections the report contains. + +import { AUTONOMY_THRESHOLD } from './adoption.mjs'; +import { dateFormatter } from './aggregate.mjs'; + +const DAY_MS = 86_400_000; + +/** + * The period a report's data covers: its first and last activity within the + * filters, as "2026-06-12 → 2026-11-04 (146 days)". Null without activity. + */ +export function coverage(totals, { timeZone } = {}) { + if (!totals.firstActivity || !totals.lastActivity) return null; + const date = dateFormatter(timeZone); + const from = date(totals.firstActivity); + const to = date(totals.lastActivity); + const days = Math.round((Date.parse(to) - Date.parse(from)) / DAY_MS) + 1; + return { from, to, days, text: `${from} → ${to} (${days.toLocaleString('en-US')} ${days === 1 ? 'day' : 'days'})` }; +} + +/** + * The section: { title, note, notes: [{ term, text }] }. + * `has` says what the report includes: claude / copilot / cursor (sources with + * sessions), cost, breakdown, shell, adoption, recommendations, intentsByClaude. + */ +export function methodSection(has, { since, until, project, timeZone, pricingSource, range } = {}) { + const notes = []; + const add = (term, text) => notes.push({ term, text }); + + const sources = [ + has.claude && 'Claude Code transcripts in ~/.claude/projects, subagent transcripts included and counted in their parent session', + has.copilot && 'GitHub Copilot CLI and VS Code agent sessions in ~/.copilot/session-state', + has.cursor && "Cursor agent transcripts in ~/.cursor/projects, with chat metadata (model, mode) from the editor's database", + ].filter(Boolean); + add( + 'Data', + `Read from your local logs only: ${listText(sources)}. Nothing is uploaded; the only network call fetches Anthropic's public pricing page.`, + ); + + const filters = [ + since && `from ${since}`, + until && `until ${until}`, + project && `projects matching "${project}"`, + ].filter(Boolean); + add( + 'Period', + `${range ? `The data runs from the first to the last activity found: ${range.text}` : 'No activity was found'}${ + filters.length ? `, filtered to ${listText(filters)}` : ', all logs that are still on disk' + }. Dates are in ${timeZone ?? 'your local time zone'}.`, + ); + + add( + 'Sessions and prompts', + 'A session is one conversation. Resumed sessions copy earlier history into a new log, so every message, tool call and response is counted once, by its id. Prompts are the messages you typed; tool results and messages the tool adds itself are not prompts.', + ); + + if (has.claude || has.copilot) { + add( + 'Tokens', + `Input, output, cache-write and cache-read tokens as each API response logged them, once per response.${ + has.copilot ? ' Older Copilot sessions only log totals per run at shutdown, and sessions that never shut down cleanly have none.' : '' + }${has.cursor ? ' Cursor keeps token usage on its servers, so its sessions count in activity only (prompts, tools, skills).' : ''} Context size is the main conversation's, without subagents.`, + ); + } else if (has.cursor) { + add('Tokens', 'Cursor keeps token usage on its servers, so this report shows activity only: sessions, prompts, tools, skills and commands.'); + } + + if (has.cost) { + add( + 'Cost', + `Estimated per request at Claude API list prices (${ + pricingSource === 'builtin' ? "a built-in copy of Anthropic's pricing page; it was unreachable" : "Anthropic's pricing page" + }), with each model's cache, long-context and fast-mode rates. On a subscription it shows what the usage would cost at API prices, not what you pay.${ + has.copilot ? ' For Copilot it is what Copilot billed in AI credits (1 AIU = $0.01); unbilled Claude models are priced at API rates.' : '' + } Models without a price count as $0.`, + ); + } + + add( + 'Tools, skills and commands', + `Every tool call in the logs; MCP tools are also rolled up per server. Skills count when the model calls one and when you type it as a slash command${ + has.cursor ? " (in Cursor, when the agent reads a skill's SKILL.md)" : '' + }. Slash commands include built-ins such as /clear and /model. Installed plugins come from the plugin settings on disk, with the use of their skills, commands, subagents, MCP servers and hooks.`, + ); + + if (has.breakdown || has.shell) { + add( + 'Tokens per tool, skill and subagent', + `Marked ~: reconstructed from how much each result grew the context, so they include re-reads of the result in later requests.${ + has.copilot ? " Copilot's are rougher: they are scaled down to at most what the session sent." : '' + } Subagent tokens are exact.${ + has.shell ? ' Shell commands are the programs each Bash or PowerShell call ran; a call running several counts for each.' : '' + }`, + ); + } + + add( + 'Usage limits', + `Counted when a plan's 5-hour, weekly or spend limit${has.copilot ? ", or Copilot's premium request quota or rate limit," : ''} stopped a request. Short capacity errors that are retried automatically do not count. The table only appears when a limit was hit.${ + has.cursor ? ' Cursor logs no errors.' : '' + }`, + ); + + if (has.adoption) { + add( + 'Adoption phases', + `Each session gets one phase. Chat: no code edits and no pull requests. Multi-agent: two or more subagent launches, background agents, worktrees or messages between agents. Agent-first: ${AUTONOMY_THRESHOLD} or more tool calls per prompt you typed. Assisted: the rest. Pull requests are those the agent created.`, + ); + add( + 'Session intent', + has.intentsByClaude + ? 'Classified by Claude from all prompts of each session; sessions it did not classify use the rules: weighted signals from commit and PR titles, the session title, branch names, prompts and the kinds of files changed. A best guess per session.' + : 'A best guess per session from weighted rules over commit and PR titles, the session title, branch names, prompts and the kinds of files changed (code, tests, docs, config, plans).', + ); + } + + if (has.recommendations) { + add( + 'Recommendations', + 'Checks against your own logs, most impact first, each with the evidence it is based on. The amounts at stake are estimates that overlap, so they do not add up.', + ); + } + + return { title: "How it's measured", notes }; +} + +/** "a, b and c"; items that contain commas are separated by semicolons. */ +function listText(items) { + if (items.length <= 1) return items.join(''); + const sep = items.some((i) => i.includes(',')) ? '; ' : ', '; + return `${items.slice(0, -1).join(sep)}${sep.trim()} and ${items.at(-1)}`; +} diff --git a/src/report.mjs b/src/report.mjs index e14dc47..9807794 100644 --- a/src/report.mjs +++ b/src/report.mjs @@ -145,11 +145,11 @@ function rangeText({ since, until }) { } const PERIOD = { - daily: { title: 'Date', name: 'daily' }, - weekly: { title: 'Week', name: 'weekly' }, - monthly: { title: 'Month', name: 'monthly' }, - session: { title: 'Session', name: 'per-session' }, - project: { title: 'Project', name: 'per-project' }, + daily: { title: 'Date', name: 'daily', rows: 'Usage per day' }, + weekly: { title: 'Week', name: 'weekly', rows: 'Usage per week' }, + monthly: { title: 'Month', name: 'monthly', rows: 'Usage per month' }, + session: { title: 'Session', name: 'per-session', rows: 'Usage per session' }, + project: { title: 'Project', name: 'per-project', rows: 'Usage per project' }, }; /** daily / weekly / monthly / session / project report. */ @@ -222,6 +222,14 @@ function estimateCells(usage, totals, opts) { ]; } +/** Intent, phase and prompts of a session, from the adoption assessment's per-session stats. */ +function sessionInfoCells(info) { + return info ? [info.intent, info.phase, info.prompts] : ['', '', '']; +} + +// Rows a long HTML table shows before "Show all". +const FOLD_ROWS = 15; + /** Every skill used, by who invoked it; `top` > 0 keeps the first rows. */ function skillSection(totals, opts, top = 0) { const entries = ranked(totals.skills, (s) => s.model + s.user); @@ -229,6 +237,8 @@ function skillSection(totals, opts, top = 0) { const shown = top > 0 ? entries.slice(0, top) : entries; return { title: 'Skills', + // HTML shows the first rows and a button for the rest. + fold: top > 0 ? undefined : FOLD_ROWS, note: shown.length < entries.length ? `top ${shown.length} of ${entries.length}` : undefined, columns: [left('Skill'), right('By model'), right('By user'), right('Total'), ...estimateColumns(opts)], rows: shown.map(([name, s]) => ({ @@ -242,7 +252,13 @@ export function buildPeriodReport(report, { buckets, totals }, opts) { const hasSubRows = breakdown || shell; const isSession = report === 'session'; const lead = isSession - ? [left('Session', SESSION_NAME_MAX), path('Project'), left('Last Activity')] + ? [ + left('Session', SESSION_NAME_MAX), + ...(opts.toolColumn ? [left('Tool')] : []), + path('Project'), + left('Last Activity'), + ...(opts.sessionInfo ? [left('Intent'), left('Phase'), right('Prompts')] : []), + ] : [report === 'project' ? path('Project') : left(PERIOD[report].title)]; // A session row is always one session, so the per-session columns only make // sense for the other reports. Per Session is filled on breakdown sub-rows. @@ -282,7 +298,13 @@ export function buildPeriodReport(report, { buckets, totals }, opts) { for (const b of buckets) { const models = ranked(b.models, (m) => m.totalTokens).map(([m]) => shortModel(m)); const leadCells = isSession - ? [sessionName(b.title ?? b.key.slice(0, 8)), [...b.projects][0] ?? '', localTime(b.lastActivity, timeZone)] + ? [ + sessionName(b.title ?? b.key.slice(0, 8)), + ...(opts.toolColumn ? [b.tool] : []), + [...b.projects][0] ?? '', + localTime(b.lastActivity, timeZone), + ...(opts.sessionInfo ? sessionInfoCells(opts.sessionInfo.get(b.key)) : []), + ] : [b.key]; rows.push({ cells: [ @@ -334,7 +356,13 @@ export function buildPeriodReport(report, { buckets, totals }, opts) { return { title: `${opts.product ?? 'Claude Code'} ${PERIOD[report].name} usage${rangeText(opts)}`, // All skills: --top limits the per-row breakdown, not this list. - sections: [{ columns, rows }, skillSection(totals, opts), ...(opts.plugins?.length ? [pluginSection(opts.plugins)] : [])].filter( + // The period table is the report's own (`main`): the CLI moves it below the + // other sections in documents, CSV keeps it first. + sections: [ + { title: PERIOD[report].rows, note: hasSubRows ? 'click a row for its breakdown' : undefined, main: true, columns, rows }, + skillSection(totals, opts), + ...(opts.plugins?.length ? [pluginSection(opts.plugins)] : []), + ].filter( Boolean, ), }; diff --git a/test/adoption.test.mjs b/test/adoption.test.mjs index aac8441..6dad49c 100644 --- a/test/adoption.test.mjs +++ b/test/adoption.test.mjs @@ -73,7 +73,8 @@ test('buildAdoption: cohorts, weekly mix, capabilities, surfaces and summary', ( assert.equal(cohorts.cards, true); const agentRow = cohorts.rows[2].cells; assert.equal(agentRow[0], 'Phase 2 · Agent-first'); - assert.deepEqual(agentRow[2], { kind: 'avg', v: 2 }); // PRs per session + assert.deepEqual(agentRow[2], { kind: 'pct', v: 0.25 }); // headline: share of sessions + assert.deepEqual(agentRow[cohorts.columns.findIndex((c) => c.title === 'PRs per session')], { kind: 'avg', v: 2 }); assert.equal(agentRow[3], 1); // sessions assert.deepEqual(agentRow[cohorts.columns.findIndex((c) => c.title === 'Plan mode')], { kind: 'pct', v: 1 }); assert.deepEqual(weekly.rows.map((r) => r.cells[0]), ['2026-09-28']); // Oct 1-4, 2026 is Thu-Sun of one week diff --git a/test/ccreports.test.mjs b/test/ccreports.test.mjs index a0afc04..240919b 100644 --- a/test/ccreports.test.mjs +++ b/test/ccreports.test.mjs @@ -365,6 +365,29 @@ test('session names are at most 35 characters in reports', async () => { assert.equal(doc.sections[0].rows[0].cells[0], 'A'.repeat(34) + '…'); }); +test('session report names the AI tool of each session with --source all', () => { + const rec = (sessionId) => ({ timestamp: '2026-10-01T10:00:00Z', sessionId, project: '/p', agent: null, name: 'Bash' }); + const data = { + usage: [], + tools: ['c1', 'g1', 'k1'].map(rec), + skills: [], + commands: [], + hooks: [], + titles: new Map(), + sessions: new Map([ + ['c1', { entrypoint: 'claude-vscode' }], + ['g1', { entrypoint: 'copilot-cli' }], + ['k1', { entrypoint: 'cursor-ide' }], + ]), + }; + const result = aggregate(data, { report: 'session' }); + assert.deepEqual(result.buckets.map((b) => [b.key, b.tool]), [['c1', 'Claude Code'], ['g1', 'GitHub Copilot'], ['k1', 'Cursor']]); + const { columns, rows } = buildPeriodReport('session', result, { toolColumn: true }).sections[0]; + assert.deepEqual(columns.slice(0, 3).map((c) => c.title), ['Session', 'Tool', 'Project']); + assert.deepEqual(rows.map((r) => r.cells[1]), ['Claude Code', 'GitHub Copilot', 'Cursor', '']); + assert.ok(!buildPeriodReport('session', result, {}).sections[0].columns.some((c) => c.title === 'Tool')); +}); + test('records the permission modes a session ran in', async () => { const root = await mkdtemp(path.join(tmpdir(), 'ccreports-')); try { @@ -386,3 +409,14 @@ test('records the permission modes a session ran in', async () => { await rm(root, { recursive: true, force: true }); } }); + +test('session report: intent, phase and prompts per session', () => { + const rec = { timestamp: '2026-10-01T10:00:00Z', sessionId: 's1', project: '/p', agent: null, name: 'Bash' }; + const data = { usage: [], tools: [rec], skills: [], commands: [], hooks: [], titles: new Map() }; + const sessionInfo = new Map([['s1', { intent: 'Bug fix', phase: 'Agent-first', prompts: 3 }]]); + const { columns, rows } = buildPeriodReport('session', aggregate(data, { report: 'session' }), { sessionInfo }).sections[0]; + const at = (t) => columns.findIndex((c) => c.title === t); + assert.deepEqual([at('Last Activity') + 1, at('Phase'), at('Prompts')], [at('Intent'), at('Intent') + 1, at('Intent') + 2]); + assert.deepEqual([rows[0].cells[at('Intent')], rows[0].cells[at('Phase')], rows[0].cells[at('Prompts')]], ['Bug fix', 'Agent-first', 3]); + assert.equal(rows.at(-1).cells[at('Intent')], ''); // totals row +}); diff --git a/test/method.test.mjs b/test/method.test.mjs new file mode 100644 index 0000000..e6045e7 --- /dev/null +++ b/test/method.test.mjs @@ -0,0 +1,113 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { coverage, methodSection } from '../src/method.mjs'; +import { toCsv, toHtml, toMarkdown } from '../src/formats.mjs'; + +test('coverage: first to last activity, in days', () => { + const range = coverage({ firstActivity: '2026-10-01T08:00:00Z', lastActivity: '2026-10-30T20:00:00Z' }, { timeZone: 'UTC' }); + assert.deepEqual(range, { from: '2026-10-01', to: '2026-10-30', days: 30, text: '2026-10-01 → 2026-10-30 (30 days)' }); + assert.equal(coverage({ firstActivity: '2026-10-01T08:00:00Z', lastActivity: '2026-10-01T09:00:00Z' }, { timeZone: 'UTC' }).text, '2026-10-01 → 2026-10-01 (1 day)'); + assert.equal(coverage({ firstActivity: null, lastActivity: null }), null); +}); + +test('methodSection: notes only for the sources and sections in the report', () => { + const range = { text: '2026-10-01 → 2026-10-30 (30 days)' }; + const claudeOnly = methodSection({ claude: true, cost: true }, { range, since: '2026-10-01', timeZone: 'UTC' }); + const terms = claudeOnly.notes.map((n) => n.term); + assert.ok(terms.includes('Cost') && terms.includes('Tokens')); + assert.ok(!terms.includes('Adoption phases') && !terms.includes('Recommendations') && !terms.includes('Tokens per tool, skill and subagent')); + const text = claudeOnly.notes.map((n) => n.text).join(' '); + assert.match(text, /2026-10-01 → 2026-10-30 \(30 days\), filtered to from 2026-10-01\. Dates are in UTC\./); + assert.doesNotMatch(text, /Copilot|Cursor/); + + const all = methodSection( + { claude: true, copilot: true, cursor: true, cost: true, breakdown: true, adoption: true, recommendations: true, intentsByClaude: true }, + { range }, + ); + const byTerm = Object.fromEntries(all.notes.map((n) => [n.term, n.text])); + assert.match(byTerm.Data, /~\/\.claude\/projects.*; ~?.*~\/\.copilot\/session-state; and Cursor/); + assert.match(byTerm['Session intent'], /Classified by Claude/); + assert.match(byTerm['Adoption phases'], /10 or more tool calls per prompt/); + assert.match(byTerm.Cost, /AI credits/); + + const cursorOnly = methodSection({ cursor: true }, { range }); + assert.match(cursorOnly.notes.find((n) => n.term === 'Tokens').text, /activity only/); + assert.ok(!cursorOnly.notes.some((n) => n.term === 'Cost')); +}); + +test('documents render the notes and the covered period; CSV keeps the period table first and skips the notes', () => { + const doc = { + title: 'x', + coverage: { text: '2026-10-01 → 2026-10-30 (30 days)' }, + sections: [ + { title: 'Skills', columns: [{ title: 'Skill' }], rows: [{ cells: ['plan'] }] }, + { title: "How it's measured", notes: [{ term: 'Data', text: 'local `logs`' }] }, + { title: 'Usage per session', main: true, columns: [{ title: 'Session' }], rows: [{ cells: ['s1'] }] }, + ], + }; + const html = toHtml(doc); + assert.match(html, /Data: 2026-10-01 → 2026-10-30 \(30 days\)<\/strong>/); + assert.match(html, /

    How it's measured<\/h2><\/summary>\n
    Data<\/dt>
    local logs<\/code><\/dd><\/dl>/); + assert.ok(html.indexOf('Skills') < html.indexOf('How it's measured') && html.indexOf('How it's measured') < html.indexOf('Usage per session')); + const md = toMarkdown(doc); + assert.doesNotMatch(md, /
    /); + assert.match(md, /_Data: 2026-10-01 → 2026-10-30 \(30 days\)_/); + assert.match(md, /- \*\*Data:\*\* local `logs`/); + assert.equal(toCsv(doc), 'Session\ns1\n\nSkill\nplan\n'); +}); + +test('HTML folds long tables and minor recommendations', () => { + const rows = Array.from({ length: 20 }, (_, i) => ({ cells: [`s${i}`] })); + const html = toHtml({ title: 'x', sections: [{ title: 'Skills', fold: 15, columns: [{ title: 'Skill' }], rows }] }); + assert.equal((html.match(//g) ?? []).length, 5); + assert.match(html, //); + assert.match(html, /data-fold-toggle[^>]*>Show all 20 ({ title, impact, atStakeUSD, evidence: 'e', advice: 'a' }); + const recs = toHtml({ + title: 'x', + sections: [{ title: 'R', items: [item('Big', 'high', 400), item('Cheap', 'medium', 0.2), item('Small', 'low')] }], + }); + const [open, more] = recs.split('
    '); + assert.match(open, /Big/); + assert.doesNotMatch(open, /Cheap|Small/); + assert.match(more, /^2 more, with less at stake<\/summary>
      .*Cheap.*Small/s); + // Only minor items: the first stays open. + const onlyLow = toHtml({ title: 'x', sections: [{ title: 'R', items: [item('Small', 'low')] }] }); + assert.doesNotMatch(onlyLow, /
      { + const doc = { + title: 'x', + kpis: [ + { label: 'sessions', value: 1234 }, + { label: 'tokens', value: 1_234_567_890, compact: true }, + { label: 'estimated cost', value: 56.789, usd: true }, + ], + sections: ['A', 'B', 'C'].map((title) => ({ title, columns: [{ title: 'k' }], rows: [{ cells: ['v'] }] })).concat({ + title: 'Phase mix per week', + stack: { start: 1, count: 2, title: 'Phase mix' }, + columns: [{ title: 'Week' }, { title: 'Chat' }, { title: 'Phase 1 · Assisted' }, { title: 'PRs' }], + rows: [ + { cells: ['2026-10-05', { kind: 'pct', v: 0.25 }, { kind: 'pct', v: 0.75 }, 3] }, + { muted: true, cells: ['2026-10-12', { kind: 'pct', v: 1 }, { kind: 'pct', v: 0 }, 0] }, + ], + }), + }; + const html = toHtml(doc); + assert.match(html, /
      1,234<\/b>sessions<\/span><\/div>
      1.2B<\/b>tokens<\/span><\/div>
    /); + assert.match(html, /
    <\/i>Chat<\/span><\/i>Assisted<\/span><\/div>/); + // Markdown keeps the share columns and gives the headline as one line. + const md = toMarkdown(doc); + assert.match(md, /\*\*1,234\*\* sessions · \*\*1.2B\*\* tokens · \*\*\$56.79\*\* estimated cost/); + assert.match(md, /\| Week \| Chat \| Phase 1 · Assisted \| PRs \|/); +});
    Phase mix<\/th>]*>PRs<\/th>/); + assert.match(html, /<\/span>/); + assert.match(html, /