@m0saic/templates 0.2.0

package/dist/m0saic/github/week-math.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Pure calendar arithmetic for the GitHub connector — ISO-8601 weeks and
+ * Monday-start week windows.
+ *
+ * DETERMINISM CONTRACT: every function here is a pure integer computation over
+ * `"YYYY-MM-DD"` strings — NO `Date` construction, NO wall-clock. This is what
+ * lets the core-tier `weekly-pulse-adapter` (and the beats) stay deterministic
+ * while still doing week math, and it extends the `parseISODate` idiom already
+ * in `hero/ffmpeg-pulse/_shared/pulse-data.ts`. Shared by: the client (window →
+ * since/until), the adapter (weekNumber, trailing-8 grid), and — later — the
+ * Jobs window tokens (F5 Phase 5), which import these instead of re-deriving.
+ *
+ * The engine (proleptic Gregorian) day-count is Howard Hinnant's
+ * `days_from_civil` / `civil_from_days` — exact for all in-range dates, integer
+ * throughout.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseISODate = parseISODate;
+exports.formatISODate = formatISODate;
+exports.daysFromCivil = daysFromCivil;
+exports.civilFromDays = civilFromDays;
+exports.addDaysISO = addDaysISO;
+exports.isoDayOfWeek = isoDayOfWeek;
+exports.mondayOfISO = mondayOfISO;
+exports.isoWeekNumber = isoWeekNumber;
+exports.lastFullWeek = lastFullWeek;
+/** Parse `"YYYY-MM-DD"` (optionally with a trailing time) into integer parts. */
+function parseISODate(iso) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(iso);
+    if (!m)
+        throw new Error(`week-math: not an ISO date: ${JSON.stringify(iso)}`);
+    return { y: Number(m[1]), m: Number(m[2]), d: Number(m[3]) };
+}
+/** Format integer parts back to `"YYYY-MM-DD"` (zero-padded). */
+function formatISODate({ y, m, d }) {
+    const p = (n, w) => String(n).padStart(w, "0");
+    return `${p(y, 4)}-${p(m, 2)}-${p(d, 2)}`;
+}
+/** Days since 1970-01-01 for a civil date. Pure integer (Hinnant). */
+function daysFromCivil(y, m, d) {
+    const yy = y - (m <= 2 ? 1 : 0);
+    const era = Math.floor((yy >= 0 ? yy : yy - 399) / 400);
+    const yoe = yy - era * 400; // [0, 399]
+    const doy = Math.floor((153 * (m + (m > 2 ? -3 : 9)) + 2) / 5) + d - 1; // [0, 365]
+    const doe = yoe * 365 + Math.floor(yoe / 4) - Math.floor(yoe / 100) + doy; // [0, 146096]
+    return era * 146097 + doe - 719468;
+}
+/** Civil date from a 1970-epoch day-count. Inverse of {@link daysFromCivil}. */
+function civilFromDays(z) {
+    const zz = z + 719468;
+    const era = Math.floor((zz >= 0 ? zz : zz - 146096) / 146097);
+    const doe = zz - era * 146097; // [0, 146096]
+    const yoe = Math.floor((doe - Math.floor(doe / 1460) + Math.floor(doe / 36524) - Math.floor(doe / 146096)) / 365); // [0, 399]
+    const y = yoe + era * 400;
+    const doy = doe - (365 * yoe + Math.floor(yoe / 4) - Math.floor(yoe / 100)); // [0, 365]
+    const mp = Math.floor((5 * doy + 2) / 153); // [0, 11]
+    const d = doy - Math.floor((153 * mp + 2) / 5) + 1; // [1, 31]
+    const m = mp + (mp < 10 ? 3 : -9); // [1, 12]
+    return { y: y + (m <= 2 ? 1 : 0), m, d };
+}
+const dayCount = (iso) => { const { y, m, d } = parseISODate(iso); return daysFromCivil(y, m, d); };
+/** Add `n` days (may be negative) to an ISO date, returning a new ISO date. */
+function addDaysISO(iso, n) {
+    return formatISODate(civilFromDays(dayCount(iso) + n));
+}
+/** ISO day-of-week: 0 = Monday … 6 = Sunday. */
+function isoDayOfWeek(iso) {
+    // 1970-01-01 (day 0) is a Thursday → Sunday-indexed weekday = (z + 4) mod 7.
+    const sun = (((dayCount(iso) + 4) % 7) + 7) % 7; // 0 = Sunday
+    return (sun + 6) % 7; // 0 = Monday
+}
+/** The Monday (`"YYYY-MM-DD"`) of the ISO week containing `iso`. */
+function mondayOfISO(iso) {
+    return addDaysISO(iso, -isoDayOfWeek(iso));
+}
+/** ISO-8601 week number (1–53) of the week containing `iso`. */
+function isoWeekNumber(iso) {
+    const z = dayCount(iso);
+    const thursday = z - isoDayOfWeek(iso) + 3; // Thursday fixes the ISO week-year
+    const { y } = civilFromDays(thursday);
+    const jan1 = daysFromCivil(y, 1, 1);
+    return Math.floor((thursday - jan1) / 7) + 1;
+}
+/**
+ * The most recent COMPLETE Monday..Sunday week STRICTLY before `todayISO`.
+ *
+ * The week containing `todayISO` is never complete before its own Sunday
+ * elapses, so the last guaranteed-complete week is always the one before it —
+ * `[thisMonday - 7d, thisMonday - 1d]` — regardless of which weekday `today` is.
+ * This is the window the Jobs `{{lastFullWeek*}}` tokens resolve to (F5 P5).
+ */
+function lastFullWeek(todayISO) {
+    const thisMonday = mondayOfISO(todayISO);
+    return { startISO: addDaysISO(thisMonday, -7), endISO: addDaysISO(thisMonday, -1) };
+}

package/dist/m0saic/github/weekly-pulse/index.d.ts

@@ -0,0 +1 @@
+export * from "./v1/weekly-pulse";

package/dist/m0saic/github/weekly-pulse/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./v1/weekly-pulse"), exports);

package/dist/m0saic/github/weekly-pulse/v1/weekly-pulse.d.ts

@@ -0,0 +1,51 @@
+import type { MosaicTemplate } from "@m0saic/types";
+import type { GithubRepoFacts } from "../../repo-facts-fetcher/v1/facts";
+/**
+ * `@m0saic/github/weekly-pulse/v1` — the ONE self-contained, app-runnable Weekly
+ * Pulse. Capability-tier: it fetches a repo's week itself from prop input (repo +
+ * window + token), derives the WeeklyPulse sheet, and renders all 8 beats — no
+ * `.mosaicx` pipeline, no upstream wiring. The app counterpart to the fetcher →
+ * adapter → runner chain the Jobs cron uses.
+ *
+ * NETWORK DISCIPLINE (renderLite): editor previews / prop changes call
+ * `renderLite`, which does NOT fetch — it shows a friendly "ready" card so
+ * tweaking props never hammers the API. The live fetch happens only on an
+ * explicit Make (`render`). Power users can set `livePreview:true` to fetch on
+ * every preview and geometrically inspect the real data — an intentional opt-in.
+ *
+ * WINDOW: live mode defaults to the last COMPLETE Mon..Sun week (UTC, computed
+ * at render time — this capability template is inherently non-deterministic, so
+ * it reads the clock; core templates never do). Set `window` to pin a week. The
+ * fully deterministic path is the cron `.mosaicx` (`{{lastFullWeek*}}` tokens).
+ */
+export type GithubWeeklyPulseProps = {
+    /** `replay` (embedded sample, no network — default) or `live` (fetch `repo`). */
+    source?: "replay" | "live";
+    /** Replay payload. Default: the embedded sample. */
+    facts?: GithubRepoFacts;
+    /** `owner/name` (live). */
+    repo?: string;
+    /** UTC Monday..Sunday inclusive (live). Omit → the last complete week. */
+    window?: {
+        startISO: string;
+        endISO: string;
+    };
+    /** Connection id for the base URL + keychain token (live). */
+    connectionId?: string;
+    /** Explicit SecretRef escape hatch (e.g. `env:GITHUB_TOKEN`); falls through to the connection when unresolvable. */
+    tokenRef?: string;
+    commitDetails?: "auto" | "full" | "none";
+    maxCommits?: number;
+    callBudget?: number;
+    /** Power-user opt-in: fetch + render real data on EVERY editor preview (not just Make). Off by default. */
+    livePreview?: boolean;
+    kpiKeys?: string[];
+    notableCount?: number;
+    areaDepth?: number;
+    topContributors?: number;
+    timings?: Record<string, number>;
+    crossfadeMs?: number;
+    renderMode?: "premium" | "light";
+};
+export declare const GithubWeeklyPulse: MosaicTemplate<GithubWeeklyPulseProps>;
+export default GithubWeeklyPulse;

package/dist/m0saic/github/weekly-pulse/v1/weekly-pulse.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GithubWeeklyPulse = void 0;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+const client_1 = require("../../client");
+const week_math_1 = require("../../week-math");
+const build_facts_1 = require("../../repo-facts-fetcher/v1/build-facts");
+const repo_facts_fetcher_1 = require("../../repo-facts-fetcher/v1/repo-facts-fetcher");
+const sample_facts_1 = require("../../repo-facts-fetcher/v1/sample-facts");
+const derive_pulse_1 = require("../../weekly-pulse-adapter/v1/derive-pulse");
+const runner_1 = require("../../../hero/ffmpeg-pulse/runner/v1/runner");
+const connection_1 = require("../../connection");
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    source: { type: "string", required: false, description: "replay = embedded sample, no network (default); live = fetch `repo` over `window`.", meta: { constraints: { oneOf: ["replay", "live"] }, ui: { label: "Source", order: 1 } } },
+    facts: { type: "json", required: false, description: "Replay payload (a GithubRepoFacts sheet). Defaults to the embedded sample.", meta: { ui: { label: "Facts (replay)", order: 2, consumer: "agent" } } },
+    repo: { type: "string", required: false, description: 'Repository "owner/name" (live).', meta: { ui: { label: "Repository", order: 3 } } },
+    window: { type: "json", required: false, description: "UTC { startISO, endISO } — Monday..Sunday. Omit → the last complete week (live).", meta: { ui: { label: "Window", order: 4, consumer: "agent" } } },
+    connectionId: { type: "string", required: false, description: "Host connection id for the base URL + keychain token (live).", meta: { ui: { label: "Connection", order: 5 } } },
+    tokenRef: { type: "string", required: false, description: "Explicit SecretRef (e.g. env:GITHUB_TOKEN). Falls through to the connection token when unresolvable.", meta: { ui: { label: "Token ref", order: 6 } } },
+    commitDetails: { type: "string", required: false, description: "auto (full when authenticated, none anonymous), full, or none.", meta: { constraints: { oneOf: ["auto", "full", "none"] }, ui: { label: "Commit details", order: 7 } } },
+    maxCommits: { type: "number", required: false, description: "Per-window commit cap.", meta: { constraints: { min: 1, max: 5000 }, ui: { label: "Max commits", order: 8 } } },
+    callBudget: { type: "number", required: false, description: "Hard cap on API calls per render.", meta: { constraints: { min: 1, max: 5000 }, ui: { label: "Call budget", order: 9 } } },
+    livePreview: { type: "boolean", required: false, description: "Fetch + render real data on every editor preview (not just Make). Off by default so prop changes don't hammer the API.", meta: { ui: { label: "Live preview (fetch on preview)", order: 10 } } },
+    kpiKeys: { type: "string[]", required: false, description: "Override the adaptive KPI selection (ordered keys).", meta: { ui: { label: "KPI keys", order: 11, consumer: "agent" } } },
+    notableCount: { type: "number", required: false, description: "Notable-commit feed length.", meta: { constraints: { min: 1, max: 12 }, ui: { label: "Notable count", order: 12 } } },
+    areaDepth: { type: "number", required: false, description: "Path segments defining a changed area.", meta: { constraints: { min: 1, max: 4 }, ui: { label: "Area depth", order: 13 } } },
+    topContributors: { type: "number", required: false, description: "Top-N contributors.", meta: { constraints: { min: 1, max: 12 }, ui: { label: "Top contributors", order: 14 } } },
+    timings: { type: "group", required: false, description: "Per-beat durations in ms.", meta: { ui: { label: "Beat timings", collapsedByDefault: true, consumer: "agent" } } },
+    crossfadeMs: { type: "number", required: false, description: "Cross-fade between beats (ms). 0 = hard cut.", meta: { constraints: { min: 0, max: 2000 }, ui: { label: "Cross-fade" } } },
+    renderMode: { type: "string", required: false, description: '"premium" (default) alpha-fade reveals; "light" geq-free pops.', meta: { constraints: { oneOf: ["light", "premium"] }, ui: { label: "Render mode" } } },
+});
+/** Live window: the explicit prop, else the last complete Mon..Sun week (UTC).
+ *  Capability-tier + inherently non-deterministic, so it reads the clock here. */
+function effectiveWindow(props) {
+    var _a;
+    return (_a = props.window) !== null && _a !== void 0 ? _a : (0, week_math_1.lastFullWeek)(new Date().toISOString().slice(0, 10));
+}
+/** The full fetch/replay → derive → render, shared by `render` (Make) and
+ *  `renderLite` when the user opted into a live preview. */
+async function renderPulse(props, ctx) {
+    var _a, _b, _c, _d, _e, _f;
+    const source = (_a = props.source) !== null && _a !== void 0 ? _a : "replay";
+    if (source !== "replay" && source !== "live") {
+        throw new Error(`github/weekly-pulse: source must be "replay" or "live", got ${JSON.stringify(source)}.`);
+    }
+    let facts;
+    if (source === "replay") {
+        const f = (_b = props.facts) !== null && _b !== void 0 ? _b : sample_facts_1.SAMPLE_FACTS;
+        if (f === null || typeof f !== "object" || Array.isArray(f)) {
+            throw new Error("github/weekly-pulse: replay `facts` must be a GithubRepoFacts object.");
+        }
+        facts = f;
+    }
+    else {
+        const repo = (_c = props.repo) !== null && _c !== void 0 ? _c : "FFmpeg/FFmpeg";
+        if (!/^[^/\s]+\/[^/\s]+$/.test(repo)) {
+            throw new Error(`github/weekly-pulse: repo must be "owner/name", got ${JSON.stringify(repo)}.`);
+        }
+        const window = effectiveWindow(props);
+        const commitDetails = (_d = props.commitDetails) !== null && _d !== void 0 ? _d : "auto";
+        const maxCommits = (_e = props.maxCommits) !== null && _e !== void 0 ? _e : 500;
+        const callBudget = (_f = props.callBudget) !== null && _f !== void 0 ? _f : 300;
+        try {
+            const { token, baseUrl } = await (0, repo_facts_fetcher_1.resolveGithubAccess)({ tokenRef: props.tokenRef, connectionId: props.connectionId }, ctx);
+            const client = new client_1.GithubClient({ baseUrl, token, callBudget });
+            facts = await (0, build_facts_1.buildRepoFacts)(client, { repo, window, commitDetails, maxCommits });
+        }
+        catch (e) {
+            return (0, template_utils_1.makeErrorMosaic)(`GitHub Weekly Pulse: fetch failed for ${repo} (${window.startISO}..${window.endISO}): ${e instanceof Error ? e.message : String(e)}`, { width: Math.max(1, Math.round(ctx.target.width)), height: Math.max(1, Math.round(ctx.target.height)), title: "GitHub Weekly Pulse", errorCode: "GITHUB_FETCH_FAILED", backgroundColor: "#000000" });
+        }
+    }
+    const pulse = (0, derive_pulse_1.deriveWeeklyPulse)(facts, {
+        kpiKeys: props.kpiKeys,
+        notableCount: props.notableCount,
+        areaDepth: props.areaDepth,
+        topContributors: props.topContributors,
+    });
+    return (0, runner_1.buildPulsePipeline)(pulse, { timings: props.timings, crossfadeMs: props.crossfadeMs, renderMode: props.renderMode }, ctx);
+}
+/** The network-free "ready" card shown on editor previews (renderLite). Themed,
+ *  friendly, and honest about what a Make will do — NO fetch, NO side effects. */
+function readyCard(props, ctx) {
+    var _a, _b;
+    const W = Math.max(1, Math.round(ctx.target.width));
+    const source = (_a = props.source) !== null && _a !== void 0 ? _a : "replay";
+    const repo = (_b = props.repo) !== null && _b !== void 0 ? _b : "FFmpeg/FFmpeg";
+    const ew = effectiveWindow(props);
+    const win = props.window ? `${ew.startISO} - ${ew.endISO}` : `${ew.startISO} - ${ew.endISO} (auto)`;
+    const body = source === "live"
+        ? [`Live - fetches ${repo} on render`, `Window: ${win}`, "Press Render to build the full pulse.", "Set livePreview to fetch + preview real data here."]
+        : ["Replay - the embedded sample", "Press Render to build the full pulse.", "Switch source to 'live' + set a repo to fetch real data."];
+    const titleFont = Math.max(18, Math.min(52, Math.round(W / 20)));
+    const bodyFont = Math.max(12, Math.min(24, Math.round(W / 44)));
+    const layers = [
+        { content: { kind: "literal", text: "GITHUB WEEKLY PULSE" }, style: { fontSize: titleFont, fontColor: "#2ea043" }, placement: { hAlign: "left", vAlign: "top", xExpr: "w*0.07", yExpr: "h*0.16" } },
+        { content: { kind: "literal", text: "ready" }, style: { fontSize: bodyFont, fontColor: "#8b949e" }, placement: { hAlign: "left", vAlign: "top", xExpr: "w*0.07", yExpr: "h*0.30" } },
+        ...body.map((text, i) => ({
+            content: { kind: "literal", text },
+            style: { fontSize: bodyFont, fontColor: "#c9d1d9" },
+            placement: { hAlign: "left", vAlign: "top", xExpr: "w*0.07", yExpr: `h*${(0.44 + i * 0.11).toFixed(2)}` },
+        })),
+    ];
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        m0: (0, dsl_stdlib_1.toM0String)("F", "weeklyPulseReady"),
+        assets: {},
+        sources: [{ type: "text", visual: { backgroundColor: "#0d1117" }, layers }],
+    };
+}
+// Plain-object template (like the pulse runner): it returns a duration-follows-
+// timings pipeline, so it opts out of defineMosaicTemplate's fixed-duration
+// timing assertion. Capability-tier — the host threads secrets/connections onto
+// ctx, which renderPulse passes straight to resolveGithubAccess.
+exports.GithubWeeklyPulse = {
+    id: (0, types_1.asTemplateId)("@m0saic/github/weekly-pulse/v1"),
+    label: "GitHub Weekly Pulse",
+    version: 1,
+    description: "Self-contained, app-runnable Weekly Pulse: fetches a GitHub repo's week from prop input (repo + window + token), derives the pulse sheet, and renders all 8 beats — one capability-tier template, no pipeline wiring. Replay mode (default) is network-free; live mode fetches over the GitHub REST API and degrades to an error frame on failure. Editor previews use a network-free renderLite card.",
+    capabilities: { tier: "capability", caps: { net: { fetch: true } } },
+    tags: ["data-viz", "github", "ffmpeg-pulse", "pulse", "live", "animated", "developers", "analysts", "weekly", "report"],
+    outputHints: { format: { kind: "video", container: "mp4" }, width: 1920, height: 1080, fps: 30, durationMs: 38000, note: "The full 8-beat weekly pulse. Live mode fetches GitHub; replay uses the embedded sample; previews show a renderLite card." },
+    propsSchema,
+    defaultProps: {
+        source: "replay",
+        facts: sample_facts_1.SAMPLE_FACTS,
+        repo: "FFmpeg/FFmpeg",
+        connectionId: String(connection_1.GITHUB_CONNECTION_ID),
+        tokenRef: "",
+        commitDetails: "auto",
+        maxCommits: 500,
+        callBudget: 300,
+        livePreview: false,
+        notableCount: 5,
+        areaDepth: 1,
+        topContributors: 5,
+        crossfadeMs: 350,
+        renderMode: "premium",
+    },
+    async render(props, ctx) {
+        return renderPulse(props, ctx);
+    },
+    /** Preview / design hot path — NO network unless the user opted into livePreview. */
+    async renderLite(props, ctx) {
+        if (props.livePreview)
+            return renderPulse(props, ctx); // power-user opt-in: fetch + preview real data
+        return readyCard(props, ctx);
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.GithubWeeklyPulse);
+exports.default = exports.GithubWeeklyPulse;

package/dist/m0saic/github/weekly-pulse-adapter/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./v1/weekly-pulse-adapter";
+export * from "./v1/derive-pulse";

package/dist/m0saic/github/weekly-pulse-adapter/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./v1/weekly-pulse-adapter"), exports);
+__exportStar(require("./v1/derive-pulse"), exports);

package/dist/m0saic/github/weekly-pulse-adapter/v1/derive-pulse.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `deriveWeeklyPulse` — the PURE core of the weekly-pulse-adapter (F5 Seam C).
+ *
+ * A deterministic function of `GithubRepoFacts` + preview props → a `WeeklyPulse`
+ * sheet. NO clock, NO network, NO randomness. Every derivation below is the
+ * determinism contract; the adapter's snapshot tests lock the exact output.
+ *
+ * Coverage-aware by design: a mirror repo (no PR/issue KPIs) or an anonymous
+ * fetch (`commitDetails:"none"` → commit-basis donut, 0 additions/deletions)
+ * degrades honestly — the basis is labeled, never faked.
+ */
+import type { WeeklyPulse } from "../../../hero/ffmpeg-pulse/_shared/pulse-data";
+import type { GithubRepoFacts } from "../../repo-facts-fetcher/v1/facts";
+export type DeriveWeeklyPulseProps = {
+    /** Override the adaptive KPI selection (ordered keys). */
+    kpiKeys?: string[];
+    /** Number of notable commits (default 5). */
+    notableCount?: number;
+    /** Path segments that define a "changed area" (default 1). */
+    areaDepth?: number;
+    /** Top-N contributors (default 5). */
+    topContributors?: number;
+};
+export declare function deriveWeeklyPulse(facts: GithubRepoFacts, props?: DeriveWeeklyPulseProps): WeeklyPulse;

package/dist/m0saic/github/weekly-pulse-adapter/v1/derive-pulse.js

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * `deriveWeeklyPulse` — the PURE core of the weekly-pulse-adapter (F5 Seam C).
+ *
+ * A deterministic function of `GithubRepoFacts` + preview props → a `WeeklyPulse`
+ * sheet. NO clock, NO network, NO randomness. Every derivation below is the
+ * determinism contract; the adapter's snapshot tests lock the exact output.
+ *
+ * Coverage-aware by design: a mirror repo (no PR/issue KPIs) or an anonymous
+ * fetch (`commitDetails:"none"` → commit-basis donut, 0 additions/deletions)
+ * degrades honestly — the basis is labeled, never faked.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveWeeklyPulse = deriveWeeklyPulse;
+const pulse_data_1 = require("../../../hero/ffmpeg-pulse/_shared/pulse-data");
+const week_math_1 = require("../../week-math");
+const DAY_LABELS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+/** Notable-commit keyword table — case-insensitive, FIRST match wins; both
+ *  classifies `kind` and sets `signal` + a score boost (F5 Seam C). */
+const KEYWORD_RULES = [
+    { re: /security|cve|overflow/i, kind: "fix", signal: "warn", boost: 6 },
+    { re: /revert|regression/i, kind: "fix", signal: "warn", boost: 4 },
+    { re: /fix|leak|crash/i, kind: "fix", signal: "win", boost: 2 },
+    { re: /\b(add|support|new|implement)/i, kind: "feat", signal: "neutral", boost: 2 },
+    { re: /faster|optimi|simd|speed/i, kind: "perf", signal: "win", boost: 3 },
+    { re: /docs?\b/i, kind: "docs", signal: "neutral", boost: 0 },
+    { re: /test|fate/i, kind: "test", signal: "neutral", boost: 0 },
+];
+function classify(headline) {
+    for (const r of KEYWORD_RULES)
+        if (r.re.test(headline))
+            return r;
+    return { kind: "chore", signal: "neutral", boost: 0 };
+}
+/** `area: description` prefix of a commit subject, capped to `areaDepth` segments. */
+function messagePrefix(headline, areaDepth) {
+    const m = /^([\w/,.-]+):/.exec(headline);
+    return m ? m[1].split("/").slice(0, areaDepth).join("/") : undefined;
+}
+/** The dominant changed directory of a commit (fallback: message prefix). */
+function topChangedDir(commit, areaDepth) {
+    var _a, _b;
+    const counts = new Map();
+    for (const f of (_a = commit.files) !== null && _a !== void 0 ? _a : []) {
+        const seg = f.path.split("/").slice(0, areaDepth).join("/");
+        counts.set(seg, ((_b = counts.get(seg)) !== null && _b !== void 0 ? _b : 0) + 1);
+    }
+    if (counts.size) {
+        return [...counts.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))[0][0];
+    }
+    return messagePrefix(commit.headline, areaDepth);
+}
+/** Top-6 areas + an aggregated `other`, colored from the shared PULSE_AREA ramp. */
+function buildByArea(areas) {
+    const out = areas.slice(0, 6).map((a, i) => ({ area: a.area, files: a.files, color: (0, pulse_data_1.PULSE_AREA)(i) }));
+    const otherFiles = areas.slice(6).reduce((s, a) => s + a.files, 0);
+    if (otherFiles > 0)
+        out.push({ area: "other", files: otherFiles, color: (0, pulse_data_1.PULSE_AREA)(5) });
+    return out;
+}
+/** direction (from the sign) + deltaPct (omitted when the base is 0 / unknown). */
+function deltaFields(cur, prev) {
+    if (cur === undefined || prev === undefined)
+        return {};
+    const diff = cur - prev;
+    const out = { direction: diff > 0 ? "up" : diff < 0 ? "down" : "flat" };
+    if (prev !== 0)
+        out.deltaPct = Math.round((diff / prev) * 1000) / 10;
+    return out;
+}
+function deriveWeeklyPulse(facts, props = {}) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    const areaDepth = Math.max(1, Math.floor((_a = props.areaDepth) !== null && _a !== void 0 ? _a : 1));
+    const notableCount = Math.max(1, Math.floor((_b = props.notableCount) !== null && _b !== void 0 ? _b : 5));
+    const topContributors = Math.max(1, Math.floor((_c = props.topContributors) !== null && _c !== void 0 ? _c : 5));
+    const cov = facts.coverage;
+    const hasDetails = cov.commitDetails === "full";
+    const windowCommits = facts.commits;
+    const windowMonday = (0, week_math_1.mondayOfISO)(facts.window.startISO);
+    const prevMonday = (0, week_math_1.addDaysISO)(windowMonday, -7);
+    const haveTrailing = facts.trailing8WeekCommitsLite.length > 0;
+    // ── period ─────────────────────────────────────────────────────
+    const period = { weekNumber: (0, week_math_1.isoWeekNumber)(facts.window.startISO), startISO: facts.window.startISO, endISO: facts.window.endISO };
+    // ── activity.days + peak (committer-date bucketed, Mon..Sun) ────
+    const dayCounts = [0, 0, 0, 0, 0, 0, 0];
+    for (const c of windowCommits)
+        dayCounts[(0, week_math_1.isoDayOfWeek)(c.committedISO)]++;
+    const days = DAY_LABELS.map((label, i) => ({ label, commits: dayCounts[i] }));
+    let peakIdx = 0;
+    for (let i = 1; i < 7; i++)
+        if (dayCounts[i] > dayCounts[peakIdx])
+            peakIdx = i; // tie → earliest
+    const peakDateISO = (0, week_math_1.addDaysISO)(windowMonday, peakIdx);
+    const peak = { dayLabel: DAY_LABELS[peakIdx], dateISO: peakDateISO, commits: dayCounts[peakIdx] };
+    // ── activity.grid (trailing 8 Mon-weeks, entirely from the lite list) ──
+    const weekStarts = [];
+    for (let w = 7; w >= 0; w--)
+        weekStarts.push((0, week_math_1.addDaysISO)(windowMonday, -7 * w));
+    const gridCounts = DAY_LABELS.map(() => weekStarts.map(() => 0));
+    for (const c of facts.trailing8WeekCommitsLite) {
+        const col = weekStarts.indexOf((0, week_math_1.mondayOfISO)(c.committedISO));
+        if (col >= 0)
+            gridCounts[(0, week_math_1.isoDayOfWeek)(c.committedISO)][col]++;
+    }
+    const grid = {
+        weekLabels: weekStarts.map((ws) => "W" + (0, week_math_1.isoWeekNumber)(ws)),
+        rows: DAY_LABELS.map((label, r) => ({ label, values: gridCounts[r] })),
+    };
+    // ── contributors (window commits grouped by login ?? name) ─────
+    const groups = new Map();
+    for (const c of windowCommits) {
+        const key = (_d = c.authorLogin) !== null && _d !== void 0 ? _d : c.authorName;
+        let g = groups.get(key);
+        if (!g) {
+            g = { login: (_e = c.authorLogin) !== null && _e !== void 0 ? _e : "", name: c.authorName, avatarUrl: c.avatarUrl, commits: 0, additions: 0, deletions: 0 };
+            groups.set(key, g);
+        }
+        g.commits++;
+        if (hasDetails) {
+            g.additions += (_f = c.additions) !== null && _f !== void 0 ? _f : 0;
+            g.deletions += (_g = c.deletions) !== null && _g !== void 0 ? _g : 0;
+        }
+    }
+    const contribRows = [...groups.entries()]
+        .map(([key, g]) => ({ key, g }))
+        .sort((a, b) => b.g.commits - a.g.commits || b.g.additions - a.g.additions || (a.key < b.key ? -1 : 1))
+        .slice(0, topContributors)
+        .map(({ g }, i) => ({ rank: i + 1, login: g.login, name: g.name, ...(g.avatarUrl ? { avatarUrl: g.avatarUrl } : {}), commits: g.commits, additions: g.additions, deletions: g.deletions }));
+    const contributorsThis = groups.size;
+    const prevAuthors = new Set();
+    let prevWeekCommits = 0;
+    for (const c of facts.trailing8WeekCommitsLite) {
+        if ((0, week_math_1.mondayOfISO)(c.committedISO) === prevMonday) {
+            prevWeekCommits++;
+            prevAuthors.add((_h = c.authorLogin) !== null && _h !== void 0 ? _h : c.authorName);
+        }
+    }
+    const prevCommitsArg = haveTrailing ? prevWeekCommits : undefined;
+    const prevContribArg = haveTrailing ? prevAuthors.size : undefined;
+    // ── scalar aggregates ──────────────────────────────────────────
+    const totalCommits = windowCommits.length;
+    const sumAdds = hasDetails ? windowCommits.reduce((s, c) => { var _a; return s + ((_a = c.additions) !== null && _a !== void 0 ? _a : 0); }, 0) : undefined;
+    const sumDels = hasDetails ? windowCommits.reduce((s, c) => { var _a; return s + ((_a = c.deletions) !== null && _a !== void 0 ? _a : 0); }, 0) : undefined;
+    const wcf = facts.weeklyCodeFrequency;
+    const cfCur = wcf && wcf.length ? wcf[wcf.length - 1] : undefined;
+    const cfPrev = wcf && wcf.length >= 2 ? wcf[wcf.length - 2] : undefined;
+    // ── changes (full = distinct changed paths by area; degraded = message-prefix commit counts) ──
+    let totalFiles;
+    let byArea;
+    if (hasDetails) {
+        const distinct = new Set();
+        const areaSets = new Map();
+        for (const c of windowCommits)
+            for (const f of (_j = c.files) !== null && _j !== void 0 ? _j : []) {
+                distinct.add(f.path);
+                const seg = f.path.split("/").slice(0, areaDepth).join("/");
+                let set = areaSets.get(seg);
+                if (!set) {
+                    set = new Set();
+                    areaSets.set(seg, set);
+                }
+                set.add(f.path);
+            }
+        totalFiles = distinct.size;
+        byArea = buildByArea([...areaSets.entries()].map(([area, set]) => ({ area, files: set.size })).sort((a, b) => b.files - a.files || (a.area < b.area ? -1 : 1)));
+    }
+    else {
+        const areaCounts = new Map();
+        for (const c of windowCommits) {
+            const seg = (_k = messagePrefix(c.headline, areaDepth)) !== null && _k !== void 0 ? _k : "other";
+            areaCounts.set(seg, ((_l = areaCounts.get(seg)) !== null && _l !== void 0 ? _l : 0) + 1);
+        }
+        totalFiles = windowCommits.length; // basis = commits, not files (labeled in the rail)
+        byArea = buildByArea([...areaCounts.entries()].map(([area, files]) => ({ area, files })).sort((a, b) => b.files - a.files || (a.area < b.area ? -1 : 1)));
+    }
+    // ── KPI pool (each entry present only when its inputs exist) ────
+    const pool = {};
+    const addKpi = (k) => { pool[k.key] = k; };
+    addKpi({ key: "commits", label: "Commits", value: totalCommits, sublabel: "vs last week", ...deltaFields(totalCommits, prevCommitsArg) });
+    addKpi({ key: "totalCommits", label: "Total Commits", value: totalCommits, sublabel: "vs last week", ...deltaFields(totalCommits, prevCommitsArg) });
+    addKpi({ key: "contributors", label: "Contributors", value: contributorsThis, sublabel: "vs last week", ...deltaFields(contributorsThis, prevContribArg) });
+    if (sumAdds !== undefined)
+        addKpi({ key: "additions", label: "Additions", value: sumAdds, sublabel: "vs last week", ...deltaFields(cfCur === null || cfCur === void 0 ? void 0 : cfCur.additions, cfPrev === null || cfPrev === void 0 ? void 0 : cfPrev.additions) });
+    if (sumDels !== undefined)
+        addKpi({ key: "deletions", label: "Deletions", value: sumDels, sublabel: "vs last week", ...deltaFields(cfCur ? Math.abs(cfCur.deletions) : undefined, cfPrev ? Math.abs(cfPrev.deletions) : undefined) });
+    if (sumAdds !== undefined && sumDels !== undefined)
+        addKpi({ key: "netChanges", label: "Net Changes", value: sumAdds - sumDels, display: (sumAdds - sumDels >= 0 ? "+" : "") + (sumAdds - sumDels).toLocaleString("en-US") });
+    if (hasDetails) {
+        addKpi({ key: "totalFiles", label: "Total Files Changed", value: totalFiles });
+        addKpi({ key: "filesChanged", label: "Files Changed", value: totalFiles });
+    }
+    if (cov.starDeltas && ((_m = facts.stars) === null || _m === void 0 ? void 0 : _m.deltaInWindow) !== undefined) {
+        addKpi({ key: "starsDelta", label: "Stars Δ", value: facts.stars.deltaInWindow, display: "+" + facts.stars.deltaInWindow, sublabel: "vs last week", ...deltaFields(facts.stars.deltaInWindow, facts.stars.deltaPrevWindow) });
+    }
+    if (cov.pulls && facts.pulls) {
+        addKpi({ key: "pullRequests", label: "Pull Requests", value: facts.pulls.openedInWindow });
+        addKpi({ key: "mergedPrs", label: "Merged PRs", value: facts.pulls.mergedInWindow });
+    }
+    if (cov.issues && facts.issues)
+        addKpi({ key: "openIssues", label: "Open Issues", value: facts.issues.open });
+    const activeDays = dayCounts.filter((c) => c > 0).length;
+    const avg = totalCommits / 7;
+    addKpi({ key: "peakDay", label: "Peak Day", value: peak.commits, sublabel: `${(0, pulse_data_1.monthDay)(peakDateISO)}, ${(0, week_math_1.parseISODate)(peakDateISO).y}` });
+    addKpi({ key: "dailyAvg", label: "Daily Avg", value: Math.round(avg), display: avg.toFixed(1) });
+    addKpi({ key: "activeDays", label: "Active Days", value: activeDays, display: `${activeDays}/7`, sublabel: `${Math.round((activeDays / 7) * 100)}% of week` });
+    const reviewed = windowCommits.filter((c) => { var _a, _b, _c; return ((_c = (_b = (_a = c.trailers) === null || _a === void 0 ? void 0 : _a["Reviewed-by"]) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0) > 0; }).length;
+    const reviewPct = totalCommits ? Math.round((reviewed / totalCommits) * 100) : 0;
+    addKpi({ key: "reviewCoverage", label: "Review Coverage", value: reviewPct, display: `${reviewPct}%`, sublabel: "of commits" });
+    // ── adaptive kpi selection (cap 8) ─────────────────────────────
+    const KPI_PRIORITY = ["commits", "contributors", "additions", "deletions", "filesChanged", "starsDelta", "pullRequests", "mergedPrs", "openIssues"];
+    const order = props.kpiKeys && props.kpiKeys.length ? props.kpiKeys : KPI_PRIORITY;
+    const kpis = order.map((k) => pool[k]).filter((k) => Boolean(k)).slice(0, 8);
+    // ── notable (deterministic score → top N, ties by sha asc) ─────
+    const notableItems = windowCommits
+        .map((c) => {
+        var _a, _b, _c, _d;
+        const cls = classify(c.headline);
+        const score = 2 * Math.log(1 + ((_a = c.additions) !== null && _a !== void 0 ? _a : 0) + ((_b = c.deletions) !== null && _b !== void 0 ? _b : 0)) + 0.5 * ((_d = (_c = c.files) === null || _c === void 0 ? void 0 : _c.length) !== null && _d !== void 0 ? _d : 0) + cls.boost;
+        return { c, cls, score };
+    })
+        .sort((a, b) => b.score - a.score || (a.c.sha < b.c.sha ? -1 : 1))
+        .slice(0, notableCount)
+        .map(({ c, cls }) => {
+        var _a, _b;
+        const reviewers = [...new Set((_b = (_a = c.trailers) === null || _a === void 0 ? void 0 : _a["Reviewed-by"]) !== null && _b !== void 0 ? _b : [])].slice(0, 2);
+        const area = topChangedDir(c, areaDepth);
+        return {
+            kind: cls.kind,
+            title: c.headline,
+            hash: c.sha,
+            author: c.authorName,
+            dateISO: c.committedISO.slice(0, 10),
+            ...(area ? { area } : {}),
+            signal: cls.signal,
+            ...(reviewers.length ? { reviewers } : {}),
+            // `pr` intentionally omitted — the facts sheet carries no commit→PR mapping.
+        };
+    });
+    // ── rails (fixed key-lists filtered to the available pool) ─────
+    const railFrom = (keys) => keys.map((k) => pool[k]).filter((k) => Boolean(k));
+    return {
+        repo: { name: facts.repo.name, fullName: facts.repo.fullName },
+        period,
+        kpis,
+        activity: { days, peak, grid, rail: railFrom(["totalCommits", "peakDay", "dailyAvg", "activeDays"]) },
+        contributors: { rows: contribRows, rail: railFrom(["totalCommits", "contributors", "additions", "deletions", "starsDelta"]) },
+        changes: { totalFiles, byArea, rail: hasDetails ? railFrom(["totalFiles", "additions", "deletions", "netChanges"]) : railFrom(["totalCommits", "contributors"]) },
+        notable: { items: notableItems, rail: railFrom(["mergedPrs", "reviewCoverage", "openIssues", "contributors"]) },
+        fin: {
+            headline: "THANK YOU!",
+            subhead: "ANOTHER WEEK OF PROGRESS.",
+            kpiStrip: railFrom(["commits", "contributors", "filesChanged", "starsDelta"]),
+            qr: { url: "https://www.m0saic.io", caption: "Make your own — m0saic.io" },
+            footer: "Built with m0saic",
+        },
+    };
+}