feat(doctor-core): add --push mode with privacy-stripped findings

Adds a new push module that strips Diagnostic[] down to the 6 fields the
SaaS receives (file, line, col, ruleId, severity, category) and POSTs the
payload with Content-Type: application/json and x-api-key headers.

Privacy boundary is enforced in stripFindings itself (defense in depth):
the SaaS schema also rejects extras, but the CLI never sends them.

The category is looked up from the existing RULE_REGISTRY, not derived
from the ruleId prefix. Unknown ruleIds get category='unknown'.

CI fields (commitSha, branch, prNumber) are read from GITHUB_SHA,
GITHUB_REF_NAME, and GITHUB_PR_NUMBER env vars and only included when
set.

pushFindings never throws: HTTP 5xx, network errors, and abort timeouts
all return { ok: false, error } so the audit's exit code is unaffected
by SaaS downtime. A 5s AbortController timeout guards against hanging
servers.

20 unit tests in tests/push.test.ts cover strip, fetch URL+headers+body
shape, missing registry entries, 1MB codeSnippet non-leakage, 5xx, network
error, non-Error throwables, and timeout behavior.

Signed-off-by: Vinayak Kulkarni <19776877+vinayakkulkarni@users.noreply.github.com>

Author: vinayakkulkarni

packages/doctor-core/src/index.ts

@@ -103,6 +103,16 @@ export {
 } from './rule-registry.js';
 export { scoreDiagnostics } from './score.js';
 export type { ScoreBreakdownEntry, ScoreConfig, ScoreResult } from './score.js';
+export {
+  buildPushPayload,
+  pushFindings,
+  stripFindings,
+  type PushOptions,
+  type PushPayload,
+  type PushPayloadInput,
+  type PushResult,
+  type PushedFinding,
+} from './push.js';
 export type {
   Capability,
   Framework,

packages/doctor-core/src/push.ts

@@ -0,0 +1,162 @@
+import { RULE_REGISTRY } from './rule-registry.js';
+import type { Diagnostic, Severity } from './types.js';
+
+/**
+ * The 6 fields the SaaS receives for each finding.
+ * Everything else (message, codeSnippet, recommendation, etc.) is privacy-sensitive
+ * and MUST be stripped before transmission.
+ */
+export interface PushedFinding {
+  file: string;
+  line: number;
+  col: number;
+  ruleId: string;
+  severity: Severity;
+  category: string;
+}
+
+export interface PushPayloadInput {
+  project: string;
+  score: number;
+  errorCount: number;
+  warnCount: number;
+  infoCount: number;
+  findings: PushedFinding[];
+}
+
+export interface PushPayload extends PushPayloadInput {
+  commitSha?: string;
+  branch?: string;
+  prNumber?: number;
+}
+
+export interface PushOptions {
+  project: string;
+  score: number;
+  errorCount: number;
+  warnCount: number;
+  infoCount: number;
+  diagnostics: Diagnostic[];
+  url: string;
+  apiKey: string;
+  fetchImpl?: typeof fetch;
+  /** Overrides for the request timeout (ms). Defaults to 5000. Test-only. */
+  timeoutMs?: number;
+}
+
+export type PushResult =
+  | { ok: true; status?: number; error?: undefined }
+  | { ok: false; status?: number; error: string };
+
+const PUSH_TIMEOUT_MS = 5000;
+
+const categoryByRuleId: ReadonlyMap<string, string> = new Map(
+  RULE_REGISTRY.map((r) => [r.id, r.category]),
+);
+
+function lookupCategory(ruleId: string): string {
+  return categoryByRuleId.get(ruleId) ?? 'unknown';
+}
+
+/**
+ * Strip a list of Diagnostics down to the 6 allowed push fields.
+ * Privacy boundary: this function is the single point of enforcement.
+ * If you add a new privacy-sensitive field to Diagnostic, add it to the deny list here.
+ */
+export function stripFindings(diagnostics: Diagnostic[]): PushedFinding[] {
+  const out: PushedFinding[] = new Array(diagnostics.length);
+  for (let i = 0; i < diagnostics.length; i++) {
+    const d = diagnostics[i]!;
+    out[i] = {
+      file: d.file,
+      line: d.line,
+      col: d.column,
+      ruleId: d.ruleId,
+      severity: d.severity,
+      category: lookupCategory(d.ruleId),
+    };
+  }
+  return out;
+}
+
+function readOptionalEnv(name: string): string | undefined {
+  const v = process.env[name];
+  return v === undefined || v === '' ? undefined : v;
+}
+
+function readPrNumber(): number | undefined {
+  const raw = readOptionalEnv('GITHUB_PR_NUMBER');
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/**
+ * Build the top-level POST body. CI fields (commitSha, branch, prNumber) are
+ * included ONLY when the matching GITHUB_* env var is set.
+ */
+export function buildPushPayload(input: PushPayloadInput): PushPayload {
+  const payload: PushPayload = {
+    project: input.project,
+    score: input.score,
+    errorCount: input.errorCount,
+    warnCount: input.warnCount,
+    infoCount: input.infoCount,
+    findings: input.findings,
+  };
+  const commitSha = readOptionalEnv('GITHUB_SHA');
+  const branch = readOptionalEnv('GITHUB_REF_NAME');
+  const prNumber = readPrNumber();
+  if (commitSha !== undefined) payload.commitSha = commitSha;
+  if (branch !== undefined) payload.branch = branch;
+  if (prNumber !== undefined) payload.prNumber = prNumber;
+  return payload;
+}
+
+/**
+ * Strip + POST findings to a SaaS endpoint. Never throws — returns
+ * `{ ok: false, error }` on any HTTP / network failure so the audit's
+ * exit code is not affected by SaaS downtime.
+ */
+export async function pushFindings(opts: PushOptions): Promise<PushResult> {
+  const findings = stripFindings(opts.diagnostics);
+  const payload = buildPushPayload({
+    project: opts.project,
+    score: opts.score,
+    errorCount: opts.errorCount,
+    warnCount: opts.warnCount,
+    infoCount: opts.infoCount,
+    findings,
+  });
+
+  const fetchImpl: typeof fetch = opts.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timeoutMs = opts.timeoutMs ?? PUSH_TIMEOUT_MS;
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  timer.unref?.();
+
+  try {
+    const res = await fetchImpl(opts.url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': opts.apiKey,
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+    if (res.ok) {
+      return { ok: true, status: res.status };
+    }
+    return {
+      ok: false,
+      status: res.status,
+      error: `HTTP ${res.status} ${res.statusText}`.trim(),
+    };
+  } catch (err) {
+    clearTimeout(timer);
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: message };
+  }
+}