@pugi/cli 0.1.0-beta.92 → 0.1.0-beta.94

package/dist/core/retro/metrics.js

@@ -0,0 +1,342 @@
+/**
+ * Metric aggregator for `pugi retro`.
+ *
+ * Pure functions over a RawCommit[] window — no I/O, no git calls.
+ * Same input shape goes through the same code path whether we are
+ * computing the current window or the prior compare window.
+ *
+ * All ratio fields default to 0 when undefined (never NaN). The
+ * renderer never has to guard against NaN.
+ */
+/** Session detection threshold — `pugi retro` mirrors the gstack-retro
+ * convention of 45 minutes between consecutive commits as the session
+ * boundary. Sessions are per-author so cross-author commits in the
+ * same time window do NOT merge into one session.
+ */
+const SESSION_GAP_MS = 45 * 60 * 1000;
+/** Conventional-commits subject pattern: `<type>(scope)!?: subject`. */
+const CONVENTIONAL_RE = /^(feat|fix|refactor|test|chore|docs)(\([^)]+\))?!?:/i;
+const COMMIT_TYPES = ['feat', 'fix', 'refactor', 'test', 'chore', 'docs', 'other'];
+function emptyCommitTypeTable() {
+    const out = {};
+    for (const t of COMMIT_TYPES)
+        out[t] = 0;
+    return out;
+}
+export function classifyCommitType(subject, files) {
+    const match = CONVENTIONAL_RE.exec(subject);
+    if (match) {
+        const tag = (match[1] ?? '').toLowerCase();
+        if (COMMIT_TYPES.includes(tag))
+            return tag;
+    }
+    // Heuristic fallback: a commit that only touches test files is test.
+    // A commit that only touches docs is docs. Otherwise "other".
+    if (files.length > 0) {
+        const allTest = files.every((f) => /(^|\/)(test|tests|spec|__tests__)\//i.test(f) || /\.(spec|test)\./i.test(f));
+        if (allTest)
+            return 'test';
+        const allDocs = files.every((f) => /\.(md|mdx|rst|txt)$/i.test(f) || /(^|\/)docs?\//i.test(f));
+        if (allDocs)
+            return 'docs';
+    }
+    return 'other';
+}
+/** Top-level directory of a file path. Returns `<root>` for files at
+ * the repo root so the focus-score reporter has a non-empty bucket.
+ */
+export function topLevelDir(path) {
+    const idx = path.indexOf('/');
+    if (idx === -1)
+        return '<root>';
+    return path.slice(0, idx);
+}
+export function aggregateAuthors(commits, currentUserName, currentUserEmail) {
+    const byKey = new Map();
+    for (const c of commits) {
+        const key = c.authorEmail || c.author;
+        const existing = byKey.get(key);
+        if (existing) {
+            existing.commits += 1;
+            existing.insertions += c.stats.insertions;
+            existing.deletions += c.stats.deletions;
+        }
+        else {
+            const isYou = matchesUser(c, currentUserName, currentUserEmail);
+            byKey.set(key, {
+                name: c.author,
+                email: c.authorEmail,
+                commits: 1,
+                insertions: c.stats.insertions,
+                deletions: c.stats.deletions,
+                isYou,
+            });
+        }
+    }
+    const arr = Array.from(byKey.values());
+    // Sort: you first, then by commits desc, then by name asc for stable order.
+    arr.sort((a, b) => {
+        if (a.isYou !== b.isYou)
+            return a.isYou ? -1 : 1;
+        if (b.commits !== a.commits)
+            return b.commits - a.commits;
+        return a.name.localeCompare(b.name);
+    });
+    return arr;
+}
+function matchesUser(commit, name, email) {
+    if (email && commit.authorEmail && commit.authorEmail.toLowerCase() === email.toLowerCase()) {
+        return true;
+    }
+    if (name && commit.author === name)
+        return true;
+    return false;
+}
+export function hotspots(commits, limit = 10) {
+    const byPath = new Map();
+    for (const c of commits) {
+        for (const f of c.files) {
+            const existing = byPath.get(f);
+            if (existing) {
+                existing.touches += 1;
+                // numstat doesn't split per-file insertions here; we already
+                // rolled the per-commit total. For hotspot LOC we accumulate
+                // the per-commit total against every file it touched, which
+                // overcounts but preserves the "files touching big commits"
+                // ranking signal. Renderer labels this honestly.
+                existing.insertions += c.stats.insertions;
+                existing.deletions += c.stats.deletions;
+            }
+            else {
+                byPath.set(f, {
+                    path: f,
+                    touches: 1,
+                    insertions: c.stats.insertions,
+                    deletions: c.stats.deletions,
+                });
+            }
+        }
+    }
+    const arr = Array.from(byPath.values());
+    arr.sort((a, b) => {
+        if (b.touches !== a.touches)
+            return b.touches - a.touches;
+        return a.path.localeCompare(b.path);
+    });
+    return arr.slice(0, limit);
+}
+export function detectSessions(commits) {
+    const byAuthor = new Map();
+    for (const c of commits) {
+        const key = c.authorEmail || c.author;
+        const bucket = byAuthor.get(key);
+        if (bucket)
+            bucket.push(c);
+        else
+            byAuthor.set(key, [c]);
+    }
+    const sessions = [];
+    for (const [, list] of byAuthor) {
+        const sorted = [...list].sort((a, b) => a.epochSeconds - b.epochSeconds);
+        let cur;
+        for (const c of sorted) {
+            if (!cur) {
+                cur = { start: c, end: c, commits: 1 };
+                continue;
+            }
+            const gapMs = (c.epochSeconds - cur.end.epochSeconds) * 1000;
+            if (gapMs > SESSION_GAP_MS) {
+                sessions.push(toSession(cur));
+                cur = { start: c, end: c, commits: 1 };
+            }
+            else {
+                cur.end = c;
+                cur.commits += 1;
+            }
+        }
+        if (cur)
+            sessions.push(toSession(cur));
+    }
+    sessions.sort((a, b) => a.start.localeCompare(b.start));
+    return sessions;
+}
+function toSession(s) {
+    const durationMinutes = Math.max(0, Math.round((s.end.epochSeconds - s.start.epochSeconds) / 60));
+    return {
+        start: s.start.timestamp,
+        end: s.end.timestamp,
+        commits: s.commits,
+        durationMinutes,
+        author: s.start.author,
+    };
+}
+export function classifySessions(sessions) {
+    let deep = 0;
+    let medium = 0;
+    let micro = 0;
+    let totalMinutes = 0;
+    for (const s of sessions) {
+        totalMinutes += s.durationMinutes;
+        if (s.durationMinutes >= 50)
+            deep += 1;
+        else if (s.durationMinutes >= 20)
+            medium += 1;
+        else
+            micro += 1;
+    }
+    const averageMinutes = sessions.length === 0 ? 0 : Math.round(totalMinutes / sessions.length);
+    return { deep, medium, micro, totalMinutes, averageMinutes };
+}
+export function hourlyHistogram(commits) {
+    const buckets = new Array(24).fill(0);
+    for (const c of commits) {
+        const d = new Date(c.epochSeconds * 1000);
+        const hour = d.getHours();
+        const bucket = buckets[hour] ?? 0;
+        buckets[hour] = bucket + 1;
+    }
+    return buckets;
+}
+export function countActiveDays(commits) {
+    const days = new Set();
+    for (const c of commits) {
+        const d = new Date(c.epochSeconds * 1000);
+        const key = `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}`;
+        days.add(key);
+    }
+    return days.size;
+}
+export function shipOfTheWeek(commits) {
+    let best;
+    for (const c of commits) {
+        const net = c.stats.insertions + c.stats.deletions;
+        if (!best || net > best.net) {
+            best = {
+                sha: c.sha,
+                subject: c.subject,
+                author: c.author,
+                insertions: c.stats.insertions,
+                deletions: c.stats.deletions,
+                net,
+            };
+        }
+    }
+    return best;
+}
+export function computeFocusScore(commits) {
+    if (commits.length === 0)
+        return { topDir: undefined, score: 0 };
+    const byDir = new Map();
+    for (const c of commits) {
+        const dirsTouched = new Set();
+        for (const f of c.files)
+            dirsTouched.add(topLevelDir(f));
+        for (const dir of dirsTouched) {
+            byDir.set(dir, (byDir.get(dir) ?? 0) + 1);
+        }
+    }
+    let topDir;
+    let topCount = 0;
+    for (const [dir, count] of byDir) {
+        if (count > topCount) {
+            topDir = dir;
+            topCount = count;
+        }
+    }
+    const score = Math.round((topCount / commits.length) * 100);
+    return { topDir, score };
+}
+/** Per-author + per-team consecutive-day streak ending today.
+ *
+ * The streak is counted backwards from `now` (the window upper bound).
+ * If neither the user nor the team shipped today, the streak for that
+ * scope is 0 (today is not yet a contribution day). The function is
+ * intentionally lenient about timezone — it bucket-keys by the local
+ * day boundary so a commit at 23:59 today is the same calendar day as
+ * any other commit today.
+ */
+export function computeStreaks(commits, now, currentUserName, currentUserEmail) {
+    const personalDays = new Set();
+    const teamDays = new Set();
+    for (const c of commits) {
+        const d = new Date(c.epochSeconds * 1000);
+        const key = dayKey(d);
+        teamDays.add(key);
+        if (matchesUser(c, currentUserName, currentUserEmail)) {
+            personalDays.add(key);
+        }
+    }
+    return {
+        personalDays: walkStreak(personalDays, now),
+        teamDays: walkStreak(teamDays, now),
+    };
+}
+function dayKey(d) {
+    return `${d.getFullYear()}-${d.getMonth() + 1}-${d.getDate()}`;
+}
+function walkStreak(days, now) {
+    let cursor = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    let streak = 0;
+    // Guard: we only walk inside the bounded window — the metric is
+    // never larger than the window length itself.
+    for (let i = 0; i < 366; i += 1) {
+        const key = dayKey(cursor);
+        if (days.has(key)) {
+            streak += 1;
+            cursor = new Date(cursor.getFullYear(), cursor.getMonth(), cursor.getDate() - 1);
+        }
+        else {
+            break;
+        }
+    }
+    return streak;
+}
+export function computeMetrics(args) {
+    const { window, commits, currentUserName, currentUserEmail } = args;
+    const insertions = commits.reduce((acc, c) => acc + c.stats.insertions, 0);
+    const deletions = commits.reduce((acc, c) => acc + c.stats.deletions, 0);
+    const testInsertions = commits.reduce((acc, c) => acc + c.stats.testInsertions, 0);
+    const testDeletions = commits.reduce((acc, c) => acc + c.stats.testDeletions, 0);
+    const totalLoc = insertions + deletions;
+    const totalTestLoc = testInsertions + testDeletions;
+    const testRatio = totalLoc === 0 ? 0 : Math.min(1, totalTestLoc / totalLoc);
+    const commitTypes = emptyCommitTypeTable();
+    for (const c of commits) {
+        const tag = classifyCommitType(c.subject, c.files);
+        commitTypes[tag] += 1;
+    }
+    const sessions = detectSessions(commits);
+    const sessionStats = classifySessions(sessions);
+    const focus = computeFocusScore(commits);
+    const streak = computeStreaks(commits, window.until, currentUserName, currentUserEmail);
+    return {
+        window: {
+            since: window.since.toISOString(),
+            until: window.until.toISOString(),
+            label: window.label,
+            days: window.days,
+        },
+        branch: { current: args.currentBranch, base: args.baseBranch },
+        commits: { total: commits.length, toBaseHead: args.toBaseHeadCount },
+        authors: aggregateAuthors(commits, currentUserName, currentUserEmail),
+        loc: { insertions, deletions, net: insertions - deletions },
+        testLoc: { insertions: testInsertions, deletions: testDeletions, ratio: testRatio },
+        activeDays: countActiveDays(commits),
+        sessions: {
+            total: sessions.length,
+            deep: sessionStats.deep,
+            medium: sessionStats.medium,
+            micro: sessionStats.micro,
+            totalMinutes: sessionStats.totalMinutes,
+            averageMinutes: sessionStats.averageMinutes,
+            detected: sessions,
+        },
+        hourly: hourlyHistogram(commits),
+        commitTypes,
+        hotspots: hotspots(commits, 10),
+        focus,
+        shipOfTheWeek: shipOfTheWeek(commits),
+        streak,
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/core/retro/narrative.js

@@ -0,0 +1,249 @@
+/**
+ * Markdown narrative + JSON snapshot writer for `pugi retro`.
+ *
+ * The markdown body is the operator-facing artifact (committed to
+ * `.pugi/retros/` and optionally posted to Plane). The JSON snapshot is
+ * the machine-readable mirror for downstream tooling (e.g. a future
+ * trend dashboard). Both are written atomically (tmp + rename) so a
+ * concurrent reader never sees a half-written file.
+ *
+ * Output convention:
+ *  - One header per major section.
+ *  - Numbers right-aligned in tables when meaningful.
+ *  - Empty sections collapse to a single italicised hint instead of
+ *    rendering an empty table.
+ */
+import { existsSync, mkdirSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const RETRO_DIR_REL = '.pugi/retros';
+export function ensureRetroDir(root) {
+    const dir = join(root, RETRO_DIR_REL);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/** Discover the next sequence number for `<date>-<seq>.md` filenames.
+ * Multiple retros on the same day get monotonically increasing seq
+ * numbers; the first one of a new day starts at 1.
+ */
+export function nextSequence(dir, dateLabel) {
+    if (!existsSync(dir))
+        return 1;
+    let max = 0;
+    const re = new RegExp(`^${escapeRegExp(dateLabel)}-(\\d+)\\.md$`);
+    for (const name of readdirSync(dir)) {
+        const m = re.exec(name);
+        if (!m)
+            continue;
+        const n = Number.parseInt(m[1] ?? '0', 10);
+        if (Number.isFinite(n) && n > max)
+            max = n;
+    }
+    return max + 1;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function localDateLabel(d) {
+    const pad = (n) => n.toString().padStart(2, '0');
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+export function planOutputPaths(root, now) {
+    const dir = ensureRetroDir(root);
+    const dateLabel = localDateLabel(now);
+    const sequence = nextSequence(dir, dateLabel);
+    return {
+        dir,
+        markdownPath: join(dir, `${dateLabel}-${sequence}.md`),
+        jsonPath: join(dir, `${dateLabel}-${sequence}.json`),
+        sequence,
+        dateLabel,
+    };
+}
+/** Atomic write — tmp file in the same directory, then rename so a
+ * watcher (or a concurrent `pugi retro` run) never sees a partial body.
+ */
+export function atomicWriteFile(path, body) {
+    const tmpPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmpPath, body, 'utf8');
+    renameSync(tmpPath, path);
+}
+export function renderMarkdown(input) {
+    const { metrics, plane, compare, generatedAt, sequence } = input;
+    const lines = [];
+    lines.push(`# Retro ${localDateLabel(generatedAt)} (seq ${sequence})`);
+    lines.push('');
+    lines.push(`Window: ${metrics.window.label} (${metrics.window.days} day${metrics.window.days === 1 ? '' : 's'})`);
+    lines.push(`Branch: \`${metrics.branch.current}\` over \`${metrics.branch.base}\``);
+    lines.push(`Generated: ${generatedAt.toISOString()}`);
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push('| Metric | Value |');
+    lines.push('| --- | ---: |');
+    lines.push(`| Commits | ${metrics.commits.total} |`);
+    lines.push(`| Commits ahead of \`${metrics.branch.base}\` | ${metrics.commits.toBaseHead} |`);
+    lines.push(`| Lines added | ${metrics.loc.insertions} |`);
+    lines.push(`| Lines removed | ${metrics.loc.deletions} |`);
+    lines.push(`| Net LOC | ${metrics.loc.net} |`);
+    lines.push(`| Test LOC ratio | ${(metrics.testLoc.ratio * 100).toFixed(1)}% |`);
+    lines.push(`| Active days | ${metrics.activeDays} |`);
+    lines.push(`| Sessions | ${metrics.sessions.total} (deep ${metrics.sessions.deep}, medium ${metrics.sessions.medium}, micro ${metrics.sessions.micro}) |`);
+    lines.push(`| Total session time | ${formatMinutes(metrics.sessions.totalMinutes)} |`);
+    lines.push(`| Focus score | ${metrics.focus.score}% on \`${metrics.focus.topDir ?? 'n/a'}\` |`);
+    lines.push(`| Personal streak | ${metrics.streak.personalDays} day${metrics.streak.personalDays === 1 ? '' : 's'} |`);
+    lines.push(`| Team streak | ${metrics.streak.teamDays} day${metrics.streak.teamDays === 1 ? '' : 's'} |`);
+    lines.push('');
+    if (compare) {
+        lines.push('## Compare vs prior window');
+        lines.push('');
+        lines.push('| Metric | Current | Prior | Delta |');
+        lines.push('| --- | ---: | ---: | ---: |');
+        const c = compare.current;
+        const p = compare.prior;
+        lines.push(`| Commits | ${c.commits.total} | ${p.commits.total} | ${signed(c.commits.total - p.commits.total)} |`);
+        lines.push(`| Net LOC | ${c.loc.net} | ${p.loc.net} | ${signed(c.loc.net - p.loc.net)} |`);
+        lines.push(`| Active days | ${c.activeDays} | ${p.activeDays} | ${signed(c.activeDays - p.activeDays)} |`);
+        lines.push(`| Sessions | ${c.sessions.total} | ${p.sessions.total} | ${signed(c.sessions.total - p.sessions.total)} |`);
+        lines.push(`| Test ratio | ${(c.testLoc.ratio * 100).toFixed(1)}% | ${(p.testLoc.ratio * 100).toFixed(1)}% | ${signed(Math.round((c.testLoc.ratio - p.testLoc.ratio) * 100))}pp |`);
+        lines.push('');
+    }
+    lines.push('## Authors');
+    lines.push('');
+    if (metrics.authors.length === 0) {
+        lines.push('_No commits in this window._');
+        lines.push('');
+    }
+    else {
+        lines.push('| Author | Commits | + | - |');
+        lines.push('| --- | ---: | ---: | ---: |');
+        for (const a of metrics.authors) {
+            const label = a.isYou ? `You (${a.name})` : a.name;
+            lines.push(`| ${label} | ${a.commits} | ${a.insertions} | ${a.deletions} |`);
+        }
+        lines.push('');
+    }
+    lines.push('## Commit types');
+    lines.push('');
+    lines.push('| Type | Count |');
+    lines.push('| --- | ---: |');
+    for (const [type, count] of Object.entries(metrics.commitTypes)) {
+        lines.push(`| ${type} | ${count} |`);
+    }
+    lines.push('');
+    lines.push('## Hourly histogram (local time)');
+    lines.push('');
+    lines.push('```');
+    for (let h = 0; h < 24; h += 1) {
+        const count = metrics.hourly[h] ?? 0;
+        const bar = '#'.repeat(Math.min(40, count));
+        lines.push(`${h.toString().padStart(2, '0')} | ${bar} ${count}`);
+    }
+    lines.push('```');
+    lines.push('');
+    lines.push('## Hotspots (top 10 files)');
+    lines.push('');
+    if (metrics.hotspots.length === 0) {
+        lines.push('_No file activity in this window._');
+        lines.push('');
+    }
+    else {
+        lines.push('| File | Touches |');
+        lines.push('| --- | ---: |');
+        for (const h of metrics.hotspots) {
+            lines.push(`| \`${h.path}\` | ${h.touches} |`);
+        }
+        lines.push('');
+    }
+    if (metrics.shipOfTheWeek) {
+        lines.push('## Ship of the week');
+        lines.push('');
+        lines.push(`\`${metrics.shipOfTheWeek.sha.slice(0, 8)}\` ${metrics.shipOfTheWeek.subject}`);
+        lines.push('');
+        lines.push(`Author: ${metrics.shipOfTheWeek.author} · +${metrics.shipOfTheWeek.insertions} -${metrics.shipOfTheWeek.deletions}`);
+        lines.push('');
+    }
+    if (plane) {
+        lines.push('## Plane');
+        lines.push('');
+        lines.push(`Closed: ${plane.closedIssues.length} · Created: ${plane.createdIssues.length} · Net: ${signed(plane.sprintVelocity.netDelta)}`);
+        lines.push('');
+        if (plane.activeCycle) {
+            lines.push(`Active cycle: \`${plane.activeCycle.name}\` (${plane.activeCycle.progressPercent}% complete)`);
+            lines.push('');
+        }
+        if (plane.oversizedModules.length > 0) {
+            lines.push('### Oversized modules');
+            lines.push('');
+            lines.push('Modules with more than 60 issues are flagged because the Plane web UI');
+            lines.push('starts to break above the 200-issue cap (see Pugi incident 2026-05-30).');
+            lines.push('');
+            for (const m of plane.oversizedModules) {
+                lines.push(`- \`${m.name}\` — ${m.issueCount} issues`);
+            }
+            lines.push('');
+        }
+        if (plane.prToIssueLinks.length > 0) {
+            lines.push('### PR ↔ issue links');
+            lines.push('');
+            for (const link of plane.prToIssueLinks) {
+                const issueLabel = link.planeIssue ? `${link.issueRef} — ${link.planeIssue.name}` : link.issueRef;
+                lines.push(`- \`${link.prSha.slice(0, 8)}\` ${link.prSubject}  ↔  ${issueLabel}`);
+            }
+            lines.push('');
+        }
+    }
+    lines.push('---');
+    lines.push('');
+    lines.push('_Generated by `pugi retro`._');
+    lines.push('');
+    return lines.join('\n');
+}
+function formatMinutes(total) {
+    if (total < 60)
+        return `${total}m`;
+    const h = Math.floor(total / 60);
+    const m = total % 60;
+    return m === 0 ? `${h}h` : `${h}h ${m}m`;
+}
+function signed(n) {
+    if (n > 0)
+        return `+${n}`;
+    return `${n}`;
+}
+export function snapshotFromMetrics(args) {
+    return {
+        schema: 1,
+        generatedAt: args.generatedAt.toISOString(),
+        sequence: args.sequence,
+        window: args.metrics.window,
+        metrics: args.metrics,
+        plane: args.plane,
+    };
+}
+export function persistRetro(args) {
+    const paths = planOutputPaths(args.root, args.now);
+    const markdown = renderMarkdown({
+        metrics: args.metrics,
+        plane: args.plane,
+        compare: args.compare,
+        generatedAt: args.now,
+        sequence: paths.sequence,
+    });
+    const snapshot = snapshotFromMetrics({
+        metrics: args.metrics,
+        plane: args.plane,
+        generatedAt: args.now,
+        sequence: paths.sequence,
+    });
+    atomicWriteFile(paths.markdownPath, markdown);
+    atomicWriteFile(paths.jsonPath, `${JSON.stringify(snapshot, null, 2)}\n`);
+    return {
+        markdownPath: paths.markdownPath,
+        jsonPath: paths.jsonPath,
+        sequence: paths.sequence,
+        dateLabel: paths.dateLabel,
+        markdown,
+        snapshot,
+    };
+}
+//# sourceMappingURL=narrative.js.map