@rigour-labs/core 6.5.0 → 6.5.1

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export { reviewChange, toReviewFinding, type ReviewInput, type ReviewResult, typ
 export { splitByChangedLines, type ChangedLineSplit } from './review/changed-lines.js';
 export { dismissFinding, dismissedKeys, findingKey, isProven, quietSplit, DISMISSED_FILE } from './review/quiet.js';
 export { isGeneratedFile } from './review/generated-files.js';
+export { countUsage, durationBucket, flushDailyUsage, isTelemetryEnabled, readTelemetryState, setTelemetryEnabled, shouldAskTelemetry, telemetryToken, trackUsage } from './telemetry/telemetry.js';
 export { buildReviewTask, type ReviewTask, type ReviewTaskItem } from './review/review-task.js';
 export { acknowledgeReview, type ReviewAck, type AckResult } from './review/review-ack.js';
 export { exportReviewed, readLedger, reviewedKeys, isReviewed, recordReview, REVIEWED_FILE, type LedgerEntry, type ReviewedKey, type ReviewVerdict } from './review/ledger.js';

package/dist/index.js

@@ -15,6 +15,7 @@ export { reviewChange, toReviewFinding } from './review/review.js';
 export { splitByChangedLines } from './review/changed-lines.js';
 export { dismissFinding, dismissedKeys, findingKey, isProven, quietSplit, DISMISSED_FILE } from './review/quiet.js';
 export { isGeneratedFile } from './review/generated-files.js';
+export { countUsage, durationBucket, flushDailyUsage, isTelemetryEnabled, readTelemetryState, setTelemetryEnabled, shouldAskTelemetry, telemetryToken, trackUsage } from './telemetry/telemetry.js';
 export { buildReviewTask } from './review/review-task.js';
 export { acknowledgeReview } from './review/review-ack.js';
 export { exportReviewed, readLedger, reviewedKeys, isReviewed, recordReview, REVIEWED_FILE } from './review/ledger.js';

package/dist/review/quiet.d.ts

@@ -7,6 +7,8 @@ export interface QuietSplit {
     speaking: Failure[];
     advisory: Failure[];
     dismissed: number;
+    /** Which gates the dismissed findings came from: where Rigour is wrong for this team. */
+    dismissedByGate: Record<string, number>;
 }
 export declare function quietSplit(cwd: string, findings: Failure[], includeHeuristics?: boolean): QuietSplit;
 export declare function dismissedKeys(cwd: string): Set<string>;

package/dist/review/quiet.js

@@ -27,10 +27,12 @@ export function findingKey(failure) {
 }
 export function quietSplit(cwd, findings, includeHeuristics = false) {
     const dismissed = dismissedKeys(cwd);
-    const split = { speaking: [], advisory: [], dismissed: 0 };
+    const split = { speaking: [], advisory: [], dismissed: 0, dismissedByGate: {} };
     for (const finding of findings) {
-        if (dismissed.has(findingKey(finding)))
+        if (dismissed.has(findingKey(finding))) {
             split.dismissed++;
+            split.dismissedByGate[finding.id] = (split.dismissedByGate[finding.id] ?? 0) + 1;
+        }
         else if (includeHeuristics || isProven(finding))
             split.speaking.push(finding);
         else

package/dist/review/quiet.test.js

@@ -20,7 +20,7 @@ describe('quiet by default', () => {
         expect(dismissFinding(dir, findingKey(leak), 'test fixture token, never deployed')).toBe(true);
         expect(dismissFinding(dir, findingKey(leak), 'again')).toBe(true); // idempotent
         const moved = { ...leak, line: 40 };
-        expect(quietSplit(dir, [moved, finding('semantic-bugs')])).toMatchObject({ dismissed: 1, speaking: [expect.objectContaining({ id: 'semantic-bugs' })] });
+        expect(quietSplit(dir, [moved, finding('semantic-bugs')])).toMatchObject({ dismissed: 1, dismissedByGate: { 'security-patterns': 1 }, speaking: [expect.objectContaining({ id: 'semantic-bugs' })] });
         expect(JSON.parse(fs.readFileSync(path.join(dir, '.rigour/dismissed.json'), 'utf8')).entries).toHaveLength(1);
         expect(dismissFinding(dir, 'not-a-key', 'x')).toBe(false);
     });

package/dist/review/review.d.ts

@@ -21,8 +21,9 @@ export interface ReviewResult {
     contextFindings: Failure[];
     /** Heuristic findings on changed lines: returned on request, never deciding the verdict (quiet.ts). */
     advisory: Failure[];
-    /** Findings a person dismissed as not a bug. */
+    /** Findings a person dismissed as not a bug, and the gates they came from. */
     dismissed: number;
+    dismissedByGate: Record<string, number>;
     unlocated: number;
     excludedOutsideChangedLines: number;
     changedLines: Record<string, Set<number>>;

package/dist/review/review.js

@@ -21,7 +21,7 @@ export async function reviewChange(input) {
     const changedLines = withoutGenerated(input.cwd, parseDiff(diff));
     const targets = input.files?.length ? input.files : Object.keys(changedLines);
     if (targets.length === 0) {
-        return { status: 'PASS', findings: [], fileFindings: [], contextFindings: [], advisory: [], dismissed: 0, unlocated: 0, excludedOutsideChangedLines: 0, changedLines, report: null };
+        return { status: 'PASS', findings: [], fileFindings: [], contextFindings: [], advisory: [], dismissed: 0, dismissedByGate: {}, unlocated: 0, excludedOutsideChangedLines: 0, changedLines, report: null };
     }
     const deep = input.deep ? { ...input.deep, focusLines: changedLinesByFile(changedLines), removedLines: removedByFile(diff), diff } : undefined;
     const report = await new GateRunner(input.config).run(input.cwd, await normalizeScopePatterns(input.cwd, targets), deep);
@@ -35,6 +35,7 @@ export async function reviewChange(input) {
         findings: quiet.speaking,
         advisory: quiet.advisory,
         dismissed: quiet.dismissed,
+        dismissedByGate: quiet.dismissedByGate,
         fileFindings: split.fileFindings,
         contextFindings: split.contextFindings,
         unlocated: split.unlocated,

package/dist/telemetry/telemetry.d.ts

@@ -0,0 +1,28 @@
+type Env = Record<string, string | undefined>;
+type Fetch = (url: string, init?: any) => Promise<unknown>;
+export interface TelemetryState {
+    /** undefined until the person has been asked. */
+    enabled?: boolean;
+    installId: string;
+}
+export interface TelemetryDeps {
+    env?: Env;
+    home?: string;
+    fetch?: Fetch;
+    version?: string;
+    now?: number;
+}
+export declare function telemetryToken(env?: Env): string;
+export declare function readTelemetryState(home?: string): TelemetryState;
+export declare function setTelemetryEnabled(enabled: boolean, home?: string): TelemetryState;
+export declare function isTelemetryEnabled(deps?: TelemetryDeps): boolean;
+/** Ask only once, only a person at a terminal, only when sending would be possible at all. */
+export declare function shouldAskTelemetry(isTty: boolean, deps?: TelemetryDeps): boolean;
+export declare function trackUsage(event: string, properties: Record<string, unknown>, deps?: TelemetryDeps): Promise<void>;
+/** Count something an agent does on a hot path (a hook check, an MCP tool call). Local only; no network. */
+export declare function countUsage(name: string, by?: number, deps?: TelemetryDeps): void;
+/** Send the day's counters as one `daily_usage` event once they are a day old, then start a new day. */
+export declare function flushDailyUsage(deps?: TelemetryDeps): Promise<boolean>;
+/** A duration as a coarse bucket, so timing never identifies a run. */
+export declare function durationBucket(ms: number): string;
+export {};

package/dist/telemetry/telemetry.js

@@ -0,0 +1,152 @@
+/**
+ * Anonymous, opt-in usage telemetry: how Rigour is used and where it is wrong,
+ * so the next release fixes what people actually hit. Every field is listed in
+ * TELEMETRY.md.
+ *
+ * Never sent: code, file or repository names, paths, git remotes, finding
+ * text, emails, keys, IP addresses (Mixpanel is told not to record them). The
+ * only identity is a random install id. Nothing is sent unless the person said
+ * yes, a token is built in (release builds only), and neither DO_NOT_TRACK nor
+ * RIGOUR_TELEMETRY=0 is set. CI never sends unless RIGOUR_TELEMETRY=1. A send
+ * that fails or is slow is dropped: telemetry never fails or slows a command.
+ *
+ * Two shapes: an event per CLI command or review (`trackUsage`), and, for the
+ * hot paths an agent drives on every edit (hooks, MCP tools), local counters
+ * (`countUsage`, no network) sent as one `daily_usage` event a day.
+ */
+import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { MIXPANEL_TOKEN } from './token.js';
+const ENDPOINT = 'https://api.mixpanel.com/track?ip=0';
+const TIMEOUT_MS = 2000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+export function telemetryToken(env = process.env) {
+    return env.RIGOUR_MIXPANEL_TOKEN?.trim() || MIXPANEL_TOKEN;
+}
+function file(home, name) {
+    return path.join(home, '.rigour', name);
+}
+export function readTelemetryState(home = os.homedir()) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file(home, 'telemetry.json'), 'utf8'));
+        if (typeof parsed?.installId === 'string')
+            return { installId: parsed.installId, enabled: typeof parsed.enabled === 'boolean' ? parsed.enabled : undefined };
+    }
+    catch {
+        // Not asked yet.
+    }
+    return { installId: crypto.randomUUID() };
+}
+export function setTelemetryEnabled(enabled, home = os.homedir()) {
+    const state = { ...readTelemetryState(home), enabled };
+    writeJson(file(home, 'telemetry.json'), state);
+    return state;
+}
+function isCi(env) {
+    return !!(env.CI || env.GITHUB_ACTIONS || env.BUILDKITE || env.GITLAB_CI || env.CIRCLECI);
+}
+/** Opted out by the environment, whatever the stored answer. */
+function vetoed(env) {
+    return (!!env.DO_NOT_TRACK && env.DO_NOT_TRACK !== '0') || env.RIGOUR_TELEMETRY === '0' || !telemetryToken(env);
+}
+export function isTelemetryEnabled(deps = {}) {
+    const env = deps.env ?? process.env;
+    if (vetoed(env))
+        return false;
+    if (env.RIGOUR_TELEMETRY === '1')
+        return true;
+    if (isCi(env))
+        return false;
+    return readTelemetryState(deps.home).enabled === true;
+}
+/** Ask only once, only a person at a terminal, only when sending would be possible at all. */
+export function shouldAskTelemetry(isTty, deps = {}) {
+    const env = deps.env ?? process.env;
+    return isTty && !isCi(env) && !vetoed(env) && env.RIGOUR_TELEMETRY === undefined && readTelemetryState(deps.home).enabled === undefined;
+}
+export async function trackUsage(event, properties, deps = {}) {
+    if (!isTelemetryEnabled(deps))
+        return;
+    const env = deps.env ?? process.env;
+    const body = [{
+            event,
+            properties: {
+                token: telemetryToken(env),
+                distinct_id: readTelemetryState(deps.home).installId,
+                time: Math.floor((deps.now ?? Date.now()) / 1000),
+                $insert_id: crypto.randomUUID(),
+                version: deps.version,
+                os: process.platform,
+                node_major: Number(process.versions.node.split('.')[0]),
+                ci: isCi(env),
+                ...properties,
+            },
+        }];
+    try {
+        await (deps.fetch ?? fetch)(ENDPOINT, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Accept: 'text/plain' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+    }
+    catch {
+        // Dropped: telemetry never affects the command.
+    }
+}
+/** Count something an agent does on a hot path (a hook check, an MCP tool call). Local only; no network. */
+export function countUsage(name, by = 1, deps = {}) {
+    if (!isTelemetryEnabled(deps))
+        return;
+    try {
+        const home = deps.home ?? os.homedir();
+        const counters = readCounters(home, deps.now ?? Date.now());
+        counters.counts[name] = (counters.counts[name] ?? 0) + by;
+        writeJson(file(home, 'telemetry-counters.json'), counters);
+    }
+    catch {
+        // Counting never affects the agent.
+    }
+}
+/** Send the day's counters as one `daily_usage` event once they are a day old, then start a new day. */
+export async function flushDailyUsage(deps = {}) {
+    if (!isTelemetryEnabled(deps))
+        return false;
+    const home = deps.home ?? os.homedir();
+    const now = deps.now ?? Date.now();
+    const counters = readCounters(home, now);
+    if (now - counters.since < DAY_MS || Object.keys(counters.counts).length === 0)
+        return false;
+    writeJson(file(home, 'telemetry-counters.json'), { since: now, counts: {} });
+    await trackUsage('daily_usage', { ...counters.counts }, deps);
+    return true;
+}
+function readCounters(home, now) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file(home, 'telemetry-counters.json'), 'utf8'));
+        if (typeof parsed?.since === 'number' && parsed.counts && typeof parsed.counts === 'object')
+            return parsed;
+    }
+    catch {
+        // First count.
+    }
+    return { since: now, counts: {} };
+}
+function writeJson(target, value) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, JSON.stringify(value, null, 2) + '\n');
+}
+/** A duration as a coarse bucket, so timing never identifies a run. */
+export function durationBucket(ms) {
+    if (ms < 1000)
+        return '<1s';
+    if (ms < 5000)
+        return '1-5s';
+    if (ms < 30000)
+        return '5-30s';
+    if (ms < 120000)
+        return '30s-2m';
+    return '>2m';
+}

package/dist/telemetry/telemetry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/telemetry/telemetry.test.js

@@ -0,0 +1,59 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { countUsage, durationBucket, flushDailyUsage, isTelemetryEnabled, readTelemetryState, setTelemetryEnabled, shouldAskTelemetry, trackUsage } from './telemetry.js';
+let home;
+const env = { RIGOUR_MIXPANEL_TOKEN: 'tok' };
+beforeEach(() => { home = fs.mkdtempSync(path.join(os.tmpdir(), 'telemetry-')); });
+afterEach(() => { fs.rmSync(home, { recursive: true, force: true }); });
+describe('telemetry consent', () => {
+    it('sends nothing until the person says yes, and the environment always wins', () => {
+        expect(isTelemetryEnabled({ env, home })).toBe(false);
+        expect(shouldAskTelemetry(true, { env, home })).toBe(true);
+        setTelemetryEnabled(true, home);
+        expect(isTelemetryEnabled({ env, home })).toBe(true);
+        expect(shouldAskTelemetry(true, { env, home })).toBe(false); // asked once
+        expect(isTelemetryEnabled({ env: { ...env, DO_NOT_TRACK: '1' }, home })).toBe(false);
+        expect(isTelemetryEnabled({ env: { ...env, RIGOUR_TELEMETRY: '0' }, home })).toBe(false);
+        expect(isTelemetryEnabled({ env: { ...env, CI: 'true' }, home })).toBe(false);
+        expect(isTelemetryEnabled({ env: {}, home })).toBe(false); // a build without a token never sends
+    });
+    it('never asks in CI or without a terminal, and keeps one random install id', () => {
+        expect(shouldAskTelemetry(false, { env, home })).toBe(false);
+        expect(shouldAskTelemetry(true, { env: { ...env, GITHUB_ACTIONS: 'true' }, home })).toBe(false);
+        const first = setTelemetryEnabled(false, home).installId;
+        expect(readTelemetryState(home).installId).toBe(first);
+        expect(first).toMatch(/^[0-9a-f-]{36}$/);
+    });
+});
+describe('telemetry sending', () => {
+    it('sends one event with the install id and no IP, and swallows a failing network', async () => {
+        setTelemetryEnabled(true, home);
+        const fetch = vi.fn().mockResolvedValue({ ok: true });
+        await trackUsage('review_completed', { status: 'PASS', findings_by_gate: { 'semantic-bugs': 1 } }, { env, home, fetch, version: '6.5.0' });
+        const [url, init] = fetch.mock.calls[0];
+        expect(url).toBe('https://api.mixpanel.com/track?ip=0');
+        const [event] = JSON.parse(init.body);
+        expect(event.event).toBe('review_completed');
+        expect(event.properties).toMatchObject({ token: 'tok', distinct_id: readTelemetryState(home).installId, version: '6.5.0', status: 'PASS' });
+        expect(JSON.stringify(event)).not.toContain(home);
+        await expect(trackUsage('x', {}, { env, home, fetch: vi.fn().mockRejectedValue(new Error('offline')) })).resolves.toBeUndefined();
+    });
+    it('counts hot-path activity locally and sends it as one daily event', async () => {
+        setTelemetryEnabled(true, home);
+        const fetch = vi.fn().mockResolvedValue({ ok: true });
+        const day = 24 * 60 * 60 * 1000;
+        countUsage('hook_check', 1, { env, home, now: 0 });
+        countUsage('hook_check', 1, { env, home, now: 1000 });
+        countUsage('mcp:rigour_review', 1, { env, home, now: 2000 });
+        expect(await flushDailyUsage({ env, home, fetch, now: 5000 })).toBe(false); // not a day yet
+        expect(await flushDailyUsage({ env, home, fetch, now: day + 1 })).toBe(true);
+        const [event] = JSON.parse(fetch.mock.calls[0][1].body);
+        expect(event).toMatchObject({ event: 'daily_usage', properties: { hook_check: 2, 'mcp:rigour_review': 1 } });
+        expect(await flushDailyUsage({ env, home, fetch, now: 2 * day + 2 })).toBe(false); // counters reset
+    });
+    it('buckets durations so timing never identifies a run', () => {
+        expect([500, 3000, 20000, 60000, 600000].map(durationBucket)).toEqual(['<1s', '1-5s', '5-30s', '30s-2m', '>2m']);
+    });
+});

package/dist/telemetry/token.d.ts

@@ -0,0 +1 @@
+export declare const MIXPANEL_TOKEN = "53ab28669fd4bf80e2dbe5605eabacc5";

package/dist/telemetry/token.js

@@ -0,0 +1 @@
+export const MIXPANEL_TOKEN = '53ab28669fd4bf80e2dbe5605eabacc5';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "6.5.0",
+  "version": "6.5.1",
   "description": "AI-native quality gate engine with local Bayesian learning. AST analysis, drift detection, Fix Packet generation, and agent self-healing across TypeScript, JavaScript, Python, Go, Ruby, and C#.",
   "engines": {
     "node": ">=22"
@@ -70,11 +70,11 @@
     "pg": "^8.16.3",
     "sqlite3": "^5.1.7",
     "openai": "^4.104.0",
-    "@rigour-labs/brain-darwin-arm64": "6.5.0",
-    "@rigour-labs/brain-linux-arm64": "6.5.0",
-    "@rigour-labs/brain-darwin-x64": "6.5.0",
-    "@rigour-labs/brain-linux-x64": "6.5.0",
-    "@rigour-labs/brain-win-x64": "6.5.0"
+    "@rigour-labs/brain-darwin-arm64": "6.5.1",
+    "@rigour-labs/brain-linux-arm64": "6.5.1",
+    "@rigour-labs/brain-darwin-x64": "6.5.1",
+    "@rigour-labs/brain-linux-x64": "6.5.1",
+    "@rigour-labs/brain-win-x64": "6.5.1"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",