redlinegate 0.0.1

package/dist/enforce/ladder.js

@@ -0,0 +1,148 @@
+// The enforcement ladder.
+//
+// Enforcement was binary: advisory by default, blocking with `--blocking`.
+// Neither end works across hundreds of repositories. Rolling blocking to all of
+// them in one step is not achievable; leaving everything advisory means the
+// organisation can never state a guarantee about any of them.
+//
+// Four rungs, and a repository climbs on recorded evidence rather than on
+// assertion. Two decisions the roadmap left open are settled here, and both are
+// settled toward the same principle: **the safe direction never needs permission.**
+export const RUNGS = ['observe', 'warn', 'block-blocker', 'block-high'];
+export const RUNG_INDEX = {
+    observe: 0,
+    warn: 1,
+    'block-blocker': 2,
+    'block-high': 3,
+};
+export const isRung = (value) => typeof value === 'string' && RUNGS.includes(value);
+export const BEHAVIOUR = {
+    observe: {
+        blocks: false,
+        description: 'Findings are reported and recorded. Nothing is blocked, including a BLOCKER.',
+    },
+    warn: {
+        blocks: false,
+        description: 'Findings are reported as warnings on the pull request. Still nothing is blocked, but the check is visible in the merge box rather than buried in a log.',
+    },
+    'block-blocker': {
+        blocks: 'BLOCKER',
+        description: 'A BLOCKER finding stops the merge. HIGH and SUGGESTION are reported.',
+    },
+    'block-high': {
+        blocks: 'HIGH',
+        description: 'A BLOCKER or a HIGH stops the merge. The strictest rung, and the one that needs the most trust in the rule set.',
+    },
+};
+export const REQUIREMENTS = {
+    // Nothing to earn: observe is where a repository starts.
+    observe: { minSeedRecall: null, minActedOnRate: null, minSampleSize: 0, maxFalsePositives: null },
+    // Warning costs nobody a merge, so it asks only that the reviewer is running.
+    warn: { minSeedRecall: null, minActedOnRate: null, minSampleSize: 5, maxFalsePositives: null },
+    // The first rung that can stop a merge, and the first that needs proof the
+    // reviewer both catches real defects and is not flagging correct code.
+    'block-blocker': {
+        minSeedRecall: 1,
+        minActedOnRate: 0.6,
+        minSampleSize: 20,
+        maxFalsePositives: 0,
+    },
+    // Blocking on HIGH means blocking on judgement calls, so the bar for people
+    // actually agreeing with the findings is materially higher.
+    'block-high': {
+        minSeedRecall: 1,
+        minActedOnRate: 0.8,
+        minSampleSize: 50,
+        maxFalsePositives: 0,
+    },
+};
+export function nextRung(current) {
+    return RUNGS[RUNG_INDEX[current] + 1] ?? null;
+}
+/**
+ * May this repository move to `to`?
+ *
+ * **Demotion never needs evidence.** Moving down is always allowed and always
+ * immediate: a repository whose gate is misfiring at 3am must be able to step
+ * back without waiting for anyone, and a ladder that made the safe direction hard
+ * would be switched off entirely rather than stepped down.
+ *
+ * **A market floor may raise a repository's minimum, never lower it below its
+ * own choice.** Markets have different regulators and different appetites, so the
+ * ladder is per repository with a per-market floor — a market may insist on more
+ * than a repository wants, and may not force one below where it has already got to.
+ */
+export function canPromote(from, to, evidence, marketFloor = 'observe') {
+    const blockers = [];
+    if (RUNG_INDEX[to] < RUNG_INDEX[from]) {
+        if (RUNG_INDEX[to] < RUNG_INDEX[marketFloor]) {
+            return {
+                to,
+                eligible: false,
+                blockers: [
+                    `this market's floor is "${marketFloor}" — a repository may not go below it. ` +
+                        'Raise it with the market owner, not here.',
+                ],
+            };
+        }
+        // Down, and at or above the floor. Always allowed, no evidence asked for.
+        return { to, eligible: true, blockers: [] };
+    }
+    if (to === from)
+        return { to, eligible: true, blockers: [] };
+    // One rung at a time. Jumping observe to block-high skips the rung where the
+    // evidence for blocking is actually gathered.
+    if (RUNG_INDEX[to] > RUNG_INDEX[from] + 1) {
+        blockers.push(`"${from}" cannot jump to "${to}" — promote one rung at a time, through "${nextRung(from)}", ` +
+            'which is where the evidence for the next one is gathered');
+    }
+    const need = REQUIREMENTS[to];
+    if (evidence.sampleSize < need.minSampleSize) {
+        blockers.push(`${need.minSampleSize} reviewed pull requests are needed and ${evidence.sampleSize} have been recorded — ` +
+            'a perfect rate over a handful is a coincidence, not evidence');
+    }
+    if (need.minSeedRecall !== null) {
+        if (evidence.seedRecall === null) {
+            blockers.push('the seeded corpus has never been scored for this stack, so there is no evidence the reviewer ' +
+                'catches known defects at all');
+        }
+        else if (evidence.seedRecall < need.minSeedRecall) {
+            blockers.push(`seed BLOCKER recall is ${(evidence.seedRecall * 100).toFixed(0)}% and ` +
+                `${(need.minSeedRecall * 100).toFixed(0)}% is required — a reviewer that misses known defects ` +
+                'must not be given a veto');
+        }
+    }
+    if (need.maxFalsePositives !== null) {
+        if (evidence.falsePositives === null) {
+            blockers.push('the clean corpus has never been scored, so nothing shows the reviewer stays quiet on correct code');
+        }
+        else if (evidence.falsePositives > need.maxFalsePositives) {
+            blockers.push(`${evidence.falsePositives} false positive(s) on the clean corpus — a reviewer that flags correct ` +
+                'code cannot be given a veto, whatever its recall');
+        }
+    }
+    if (need.minActedOnRate !== null) {
+        if (evidence.actedOnRate === null) {
+            blockers.push('too few findings have fired to compute an acted-on rate');
+        }
+        else if (evidence.actedOnRate < need.minActedOnRate) {
+            blockers.push(`acted-on rate is ${(evidence.actedOnRate * 100).toFixed(0)}% and ` +
+                `${(need.minActedOnRate * 100).toFixed(0)}% is required — blocking on findings people already ` +
+                'ignore turns the gate into an obstacle rather than a control');
+        }
+    }
+    return { to, eligible: blockers.length === 0, blockers };
+}
+/** The highest rung this repository could move to today, and why not higher. */
+export function ladderStatus(current, evidence, marketFloor = 'observe') {
+    const next = nextRung(current);
+    return {
+        current,
+        next,
+        promotion: next ? canPromote(current, next, evidence, marketFloor) : null,
+        // A repository under its market's floor is not drifting, it is out of policy,
+        // and the difference matters to whoever has to act.
+        belowFloor: RUNG_INDEX[current] < RUNG_INDEX[marketFloor],
+    };
+}
+//# sourceMappingURL=ladder.js.map

package/dist/enforce/ladder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ladder.js","sourceRoot":"","sources":["../../cli/enforce/ladder.ts"],"names":[],"mappings":"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"}

package/dist/exempt/parse.js

@@ -0,0 +1,86 @@
+// A structured exemption: who accepted a failing process check, why, and until when.
+//
+// The bare `redline-exempt` label recorded none of that. It downgraded process
+// checks to warnings and left the estate unable to answer the two questions that
+// matter about an exemption — is anyone still standing behind it, and was it ever
+// meant to be permanent. An exemption nobody has to justify and nobody revisits
+// is not an exemption, it is an opt-out.
+export const EXEMPTION_HEADING = '## Redline exemption';
+// Ninety days. Long enough for real remediation work to be scheduled, short
+// enough that "temporary" has to be renewed by someone who still believes it.
+export const MAX_DAYS = 90;
+export const MIN_REASON_LENGTH = 20;
+// HTML comments are guidance, not content.
+//
+// The shipped pull request template explains each field with a commented block
+// that necessarily contains the words `reason:`, `until:` and `scope:` — so a
+// parser reading the first match found the instructions instead of the author's
+// answer, and rejected every correctly filled exemption. The template cannot
+// stop describing its own fields, so the parser has to know what a comment is.
+const withoutComments = (text) => text.replace(/<!--[\s\S]*?-->/g, '');
+const field = (block, name) => {
+    const match = new RegExp(`^\\s*[-*]?\\s*${name}\\s*:\\s*(.+)$`, 'im').exec(block);
+    return match?.[1]?.trim() ?? null;
+};
+/**
+ * Parse the exemption block out of a pull request body.
+ *
+ * `now` is injected rather than read from the clock so the expiry rules are
+ * testable and so a gate run and a later audit of the same pull request can
+ * reach the same verdict about the same text.
+ */
+export function parseExemption(body, now) {
+    const problems = [];
+    const fail = (problem, detail) => {
+        problems.push({ problem, detail });
+        return { exemption: null, problems };
+    };
+    const searchable = withoutComments(body);
+    const start = searchable.toLowerCase().indexOf(EXEMPTION_HEADING.toLowerCase());
+    if (start === -1) {
+        return fail('no-block', `the pull request has no "${EXEMPTION_HEADING}" section — a label alone no longer exempts anything`);
+    }
+    // Everything until the next heading of the same or higher level. A reason that
+    // runs into the next section would otherwise swallow the rest of the body.
+    const rest = searchable.slice(start + EXEMPTION_HEADING.length);
+    const next = /^#{1,2}\s/m.exec(rest);
+    const block = next ? rest.slice(0, next.index) : rest;
+    const reason = field(block, 'reason');
+    if (!reason) {
+        return fail('no-reason', 'the exemption block has no `reason:` — say what is being accepted and why');
+    }
+    if (reason.length < MIN_REASON_LENGTH) {
+        return fail('reason-too-short', `the reason is ${reason.length} characters; at least ${MIN_REASON_LENGTH} are required — "needed for release" tells a later reader nothing`);
+    }
+    const until = field(block, 'until');
+    if (!until) {
+        return fail('no-until', 'the exemption block has no `until:` — an exemption with no end is a permanent one nobody chose');
+    }
+    const parsed = new Date(`${until}T23:59:59.999Z`);
+    if (Number.isNaN(parsed.getTime())) {
+        return fail('until-unparseable', `\`until: ${until}\` is not a YYYY-MM-DD date`);
+    }
+    if (parsed.getTime() < now.getTime()) {
+        return fail('until-past', `this exemption expired on ${until} — renew it deliberately or fix the finding`);
+    }
+    // Ceil, not the raw fraction: `until` is a whole day and is inclusive to its
+    // end, so a date exactly MAX_DAYS out measures as slightly over and was
+    // refused as "91 days away" for asking for 90.
+    const days = Math.ceil((parsed.getTime() - now.getTime()) / 86400000 - 1);
+    if (days > MAX_DAYS) {
+        return fail('until-too-far', `\`until: ${until}\` is ${Math.round(days)} days away; the maximum is ${MAX_DAYS} — a longer exemption is a standards change, not an exemption`);
+    }
+    const scopeField = field(block, 'scope');
+    const scope = scopeField
+        ? scopeField
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s !== '')
+        : ['*'];
+    return { exemption: { reason, until, scope }, problems };
+}
+/** Whether an exemption covers a named check or rule id. */
+export function covers(exemption, check) {
+    return exemption.scope.includes('*') || exemption.scope.includes(check);
+}
+//# sourceMappingURL=parse.js.map

package/dist/exempt/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../cli/exempt/parse.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,EAAE;AACF,+EAA+E;AAC/E,iFAAiF;AACjF,kFAAkF;AAClF,gFAAgF;AAChF,yCAAyC;AAyBzC,MAAM,CAAC,MAAM,iBAAiB,GAAG,sBAAsB,CAAC;AAExD,4EAA4E;AAC5E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,CAAC;AAC3B,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAEpC,2CAA2C;AAC3C,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,gFAAgF;AAChF,6EAA6E;AAC7E,+EAA+E;AAC/E,MAAM,eAAe,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;AAEvF,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,IAAY,EAAiB,EAAE;IAC3D,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,iBAAiB,IAAI,gBAAgB,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClF,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;AACpC,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,GAAS;IACpD,MAAM,QAAQ,GAAgC,EAAE,CAAC;IACjD,MAAM,IAAI,GAAG,CAAC,OAAyB,EAAE,MAAc,EAAmB,EAAE;QAC1E,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QACnC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACvC,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,iBAAiB,CAAC,WAAW,EAAE,CAAC,CAAC;IAChF,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;QACjB,OAAO,IAAI,CACT,UAAU,EACV,4BAA4B,iBAAiB,sDAAsD,CACpG,CAAC;IACJ,CAAC;IAED,+EAA+E;IAC/E,2EAA2E;IAC3E,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAChE,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEtD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC,WAAW,EAAE,2EAA2E,CAAC,CAAC;IACxG,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACtC,OAAO,IAAI,CACT,kBAAkB,EAClB,iBAAiB,MAAM,CAAC,MAAM,yBAAyB,iBAAiB,mEAAmE,CAC5I,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC,UAAU,EAAE,gGAAgG,CAAC,CAAC;IAC5H,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,GAAG,KAAK,gBAAgB,CAAC,CAAC;IAClD,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC,mBAAmB,EAAE,YAAY,KAAK,6BAA6B,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC,YAAY,EAAE,6BAA6B,KAAK,6CAA6C,CAAC,CAAC;IAC7G,CAAC;IACD,6EAA6E;IAC7E,wEAAwE;IACxE,+CAA+C;IAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC;IAC1E,IAAI,IAAI,GAAG,QAAQ,EAAE,CAAC;QACpB,OAAO,IAAI,CACT,eAAe,EACf,YAAY,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,8BAA8B,QAAQ,+DAA+D,CAChJ,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU;QACtB,CAAC,CAAC,UAAU;aACP,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;QAC5B,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAEV,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,CAAC;AAC3D,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,MAAM,CAAC,SAAoB,EAAE,KAAa;IACxD,OAAO,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC1E,CAAC"}

package/dist/metrics/options.js

@@ -0,0 +1,257 @@
+import { RedlineError } from "../core/errors.js";
+const DATA = {
+    env: 'DATA_DIR',
+    type: 'path',
+    help: 'directory of collected telemetry',
+    default: 'data',
+};
+const ORG = { env: 'ORG', type: 'string', help: 'the GitHub organisation', required: true };
+const TOKEN = {
+    env: 'GH_TOKEN',
+    type: 'string',
+    help: 'a token with org read access (or set GH_TOKEN in the environment)',
+};
+export const METRICS_COMMANDS = {
+    collect: {
+        summary: 'pull review outcomes for merged pull requests across the org',
+        runsIn: 'the metrics repo, on a schedule',
+        script: 'scripts/collect-telemetry.mjs',
+        options: {
+            org: ORG,
+            token: TOKEN,
+            days: { env: 'DAYS', type: 'number', help: 'how far back to look', default: '8' },
+            since: { env: 'SINCE', type: 'string', help: 'YYYY-MM-DD, instead of --days' },
+            out: { env: 'OUT', type: 'path', help: 'where to write the monthly JSONL', default: 'data' },
+            'dry-run': { env: 'DRY_RUN', type: 'boolean', help: 'print a sample and write nothing' },
+            'skip-sarif': { env: 'SKIP_SARIF', type: 'boolean', help: 'do not ingest code-scanning alerts' },
+        },
+    },
+    dashboard: {
+        summary: 'build the telemetry dashboard page',
+        runsIn: 'the metrics repo, or any checkout of its data/',
+        script: 'scripts/build-dashboard.mjs',
+        options: {
+            org: ORG,
+            data: DATA,
+            days: { env: 'DAYS', type: 'number', help: 'window in days', default: '90' },
+            out: { env: 'OUT', type: 'path', help: 'output directory', default: 'dist' },
+            registry: { env: 'REGISTRY', type: 'path', help: 'the register, for coverage and the ladder', default: 'registry.json' },
+            onboarded: { env: 'ONBOARDED', type: 'number', help: 'onboarded repo count, if not read from the register' },
+            'seed-scores': { env: 'SEED_SCORES', type: 'path', help: 'seed score history', default: 'data/seed-scores.jsonl' },
+            'standards-version': { env: 'STANDARDS_VERSION', type: 'string', help: 'version to display' },
+        },
+    },
+    digest: {
+        summary: 'build the weekly stakeholder digest as an Adaptive Card',
+        runsIn: 'the metrics repo, weekly',
+        script: 'scripts/build-digest.mjs',
+        options: {
+            org: ORG,
+            data: DATA,
+            days: { env: 'DAYS', type: 'number', help: 'window in days', default: '7' },
+            out: { env: 'OUT', type: 'path', help: 'write the card here instead of stdout' },
+            'open-prs': { env: 'OPEN_PRS', type: 'number', help: 'open PR count, from the caller' },
+            'stale-prs': { env: 'STALE_PRS', type: 'number', help: 'stale PR count, from the caller' },
+            'seed-scores': { env: 'SEED_SCORES', type: 'path', help: 'seed score history, for the recall line' },
+            'dashboard-url': { env: 'DASHBOARD_URL', type: 'string', help: 'linked from the card' },
+        },
+    },
+    inbox: {
+        summary: 'build the org-wide prioritised pull request inbox',
+        runsIn: 'the source repo, on a schedule',
+        script: 'scripts/build-inbox.mjs',
+        options: {
+            org: ORG,
+            token: TOKEN,
+            out: { env: 'OUT', type: 'path', help: 'output directory', default: 'dist' },
+            'max-pages': { env: 'MAX_PAGES', type: 'number', help: 'search pages to walk', default: '10' },
+        },
+    },
+    baseline: {
+        summary: 'compute the baseline every roadmap phase is measured against',
+        runsIn: 'a maintainer terminal, once, with org credentials',
+        script: 'scripts/build-baseline.mjs',
+        options: {
+            data: DATA,
+            org: { env: 'ORG', type: 'string', help: 'the org, to survey Redline\'s own PRs and SARIF producers' },
+            token: TOKEN,
+            registry: { env: 'REGISTRY', type: 'path', help: 'the derived register', default: 'registry.json' },
+            days: { env: 'DAYS', type: 'number', help: 'window in days', default: '90' },
+            out: { env: 'OUT', type: 'path', help: 'where to write the JSON', default: 'baseline.json' },
+            'spend-total': { env: 'SPEND_TOTAL', type: 'number', help: 'AI spend, from the vendor\'s own usage reporting' },
+            'spend-currency': { env: 'SPEND_CURRENCY', type: 'string', help: 'currency of --spend-total', default: 'USD' },
+            'spend-grain': {
+                env: 'SPEND_GRAIN',
+                type: 'string',
+                help: 'whether the spend figure is per repo or org-wide',
+                default: 'org',
+                values: ['repo', 'org', 'unknown'],
+            },
+        },
+    },
+    roi: {
+        summary: 'build the page that says what review cost against what it caught',
+        runsIn: 'the metrics repo, or any checkout of its data/',
+        script: 'scripts/build-roi.mjs',
+        options: {
+            data: DATA,
+            days: { env: 'DAYS', type: 'number', help: 'window in days', default: '90' },
+            out: { env: 'OUT', type: 'path', help: 'JSON output', default: 'roi.json' },
+            html: { env: 'HTML', type: 'path', help: 'the readable page', default: 'roi.html' },
+            'spend-total': { env: 'SPEND_TOTAL', type: 'number', help: 'AI spend for the window' },
+            'spend-currency': { env: 'SPEND_CURRENCY', type: 'string', help: 'currency of --spend-total', default: 'USD' },
+            'spend-grain': {
+                env: 'SPEND_GRAIN',
+                type: 'string',
+                help: 'per repo or org-wide — an org figure will not answer a per-repo question',
+                default: 'org',
+                values: ['repo', 'org', 'unknown'],
+            },
+            'spend-source': { env: 'SPEND_SOURCE', type: 'string', help: 'where the figure came from, recorded with it' },
+        },
+    },
+    correlate: {
+        summary: 'research: whether ignoring a finding cost anything',
+        runsIn: 'the metrics repo. It is an experiment, not a loop',
+        script: 'scripts/build-correlation.mjs',
+        options: {
+            data: DATA,
+            days: { env: 'DAYS', type: 'number', help: 'how much history to read', default: '180' },
+            'window-days': { env: 'WINDOW_DAYS', type: 'number', help: 'how long after a merge a revert still counts', default: '30' },
+            'min-sample': {
+                env: 'MIN_SAMPLE',
+                type: 'number',
+                help: 'ignored findings a rule needs before any rate is reported',
+                default: '10',
+            },
+            out: { env: 'OUT', type: 'path', help: 'where to write the JSON', default: 'correlation.json' },
+        },
+    },
+    'score-seeds': {
+        summary: 'score an automated reviewer against the seeded corpus',
+        runsIn: 'anywhere, against a pull request that carries the corpus',
+        script: 'scripts/score-seeds.mjs',
+        argv: true,
+        options: {
+            repo: { env: 'REPO', type: 'string', help: 'owner/name of the pilot repository', required: true },
+            pr: { env: 'PR', type: 'number', help: 'the pull request number', required: true },
+            token: TOKEN,
+            json: { env: 'JSON_OUT', type: 'boolean', help: 'machine-readable output' },
+            window: { env: 'WINDOW', type: 'number', help: 'lines around a marker a finding may land on', default: '4' },
+            history: { env: 'HISTORY', type: 'path', help: 'append the score to this JSONL' },
+            baseline: { env: 'BASELINE', type: 'boolean', help: 'record as a baseline rather than a run' },
+        },
+    },
+    context: {
+        summary: 'measure what the skills render target saves, per profile',
+        runsIn: 'the source repo',
+        script: 'scripts/measure-context.mjs',
+        options: {
+            root: { env: 'ROOT', type: 'path', help: 'the repo to measure', default: '.' },
+            out: { env: 'OUT', type: 'path', help: 'also write the rows as JSON here' },
+        },
+    },
+};
+export const REGISTRY_COMMAND = {
+    summary: 'derive the register of onboarded repositories by walking the org',
+    runsIn: 'the source repo, nightly',
+    script: 'scripts/build-registry.mjs',
+    options: {
+        org: ORG,
+        token: TOKEN,
+        source: {
+            env: 'SOURCE',
+            type: 'string',
+            help: 'owner/name of this repo, recorded so a consumer knows which estate the register describes',
+            required: true,
+        },
+        out: { env: 'OUT', type: 'path', help: 'where to write it', default: 'registry.json' },
+    },
+};
+/**
+ * Turn parsed flags into the environment the runner reads.
+ *
+ * Every refusal here is one that used to be silent. An unset required option was
+ * a runner throwing halfway through; a non-numeric `--days` became `NaN` and
+ * produced an empty window; a mistyped `--spend-grain` became "unknown" and made
+ * the resulting number quietly less trustworthy than it looked.
+ */
+export function resolveEnv(spec, flags, env, name) {
+    const resolved = {};
+    for (const [flag, option] of Object.entries(spec.options)) {
+        const raw = flags[flag];
+        if (option.type === 'boolean') {
+            if (raw === true)
+                resolved[option.env] = '1';
+            continue;
+        }
+        // Precedence: the flag, then the environment, then the default. The
+        // environment stays honoured so a scheduled job can keep using a secret
+        // without putting a token on a command line, where it lands in shell history
+        // and in the process table.
+        const value = raw !== undefined ? String(raw) : (env[option.env] ?? option.default);
+        if (value === undefined || value === '') {
+            if (option.required) {
+                throw new RedlineError('usage', `redline ${name} needs --${flag} (${option.help})`, `or set ${option.env} in the environment`);
+            }
+            continue;
+        }
+        if (option.type === 'number' && !Number.isFinite(Number(value))) {
+            throw new RedlineError('usage', `--${flag} must be a number, not "${value}"`);
+        }
+        if (option.values && !option.values.includes(value)) {
+            throw new RedlineError('usage', `--${flag} must be one of ${option.values.join(', ')}, not "${value}"`);
+        }
+        resolved[option.env] = value;
+    }
+    return resolved;
+}
+/** The help for one command, generated from the same table that validates it. */
+export function helpFor(name, spec) {
+    const left = (flag, option) => `  --${flag}${option.type === 'boolean' ? '' : ` <${option.type}>`}`;
+    // Sized to the widest flag in THIS command, not to a constant: a fixed column
+    // collides the moment a longer flag is added, and a help screen whose columns
+    // run together reads as unmaintained.
+    const width = Math.max(...Object.entries(spec.options).map(([f, o]) => left(f, o).length)) + 2;
+    const flags = Object.entries(spec.options).map(([flag, option]) => {
+        const suffix = option.required
+            ? '  (required)'
+            : option.default
+                ? `  (default: ${option.default})`
+                : '';
+        return left(flag, option).padEnd(width) + `${option.help}${suffix}`;
+    });
+    return [
+        `redline ${name} — ${spec.summary}`,
+        '',
+        `Runs in: ${spec.runsIn}.`,
+        '',
+        ...flags,
+        '',
+        'Every option can also be set as an environment variable — see the names in the docs.',
+    ].join('\n');
+}
+/**
+ * The same validated flags, as argv, for a runner that parses its own.
+ *
+ * `--token` is deliberately never forwarded: it is a credential, and a command
+ * line is visible in the process table and lands in shell history. It travels as
+ * an environment variable, which is where the runner reads it from anyway.
+ */
+export function resolveArgv(spec, flags, env, name) {
+    const resolvedEnv = resolveEnv(spec, flags, env, name);
+    const argv = [];
+    for (const [flag, option] of Object.entries(spec.options)) {
+        if (option.env === 'GH_TOKEN')
+            continue;
+        const value = resolvedEnv[option.env];
+        if (value === undefined)
+            continue;
+        if (option.type === 'boolean')
+            argv.push(`--${flag}`);
+        else
+            argv.push(`--${flag}`, value);
+    }
+    return argv;
+}
+//# sourceMappingURL=options.js.map

package/dist/metrics/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../cli/metrics/options.ts"],"names":[],"mappings":"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"}

package/dist/metrics/run.js

@@ -0,0 +1,72 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isRedlineError, RedlineError } from "../core/errors.js";
+import { METRICS_COMMANDS, REGISTRY_COMMAND, resolveArgv, resolveEnv } from "./options.js";
+export function specFor(name) {
+    if (name === 'registry')
+        return REGISTRY_COMMAND;
+    const spec = METRICS_COMMANDS[name];
+    if (!spec) {
+        throw new RedlineError('usage', `unknown metrics command "${name}"`, `known: ${Object.keys(METRICS_COMMANDS).join(', ')}`);
+    }
+    return spec;
+}
+/**
+ * Validate the flags, then run the runner in this process.
+ *
+ * The runner reads its configuration from the environment, which is the contract
+ * it already documents. This layer is its front door: it decides what is valid,
+ * says so in `--help`, and refuses before anything runs — rather than letting a
+ * missing token surface as a 401 halfway through an org walk.
+ */
+export async function runMetrics(name, opts) {
+    const spec = specFor(name);
+    const env = opts.env ?? process.env;
+    const label = name === 'registry' ? 'registry' : `metrics ${name}`;
+    // Both paths validate through the same table. Which one a runner takes is a
+    // fact about that runner, never a difference in what the user may type.
+    const resolved = resolveEnv(spec, opts.flags, env, label);
+    const argv = spec.argv ? resolveArgv(spec, opts.flags, env, label) : null;
+    const script = join(opts.root, spec.script);
+    if (!existsSync(script) && !opts.load) {
+        throw new RedlineError('failed', `${spec.script} is missing from this installation`, 'reinstall redlinegate — the runners ship inside the package');
+    }
+    // Applied to the real environment because the runner reads process.env
+    // directly. Scoped to this process, which lives for exactly one command.
+    for (const [key, value] of Object.entries(resolved))
+        process.env[key] = value;
+    // A runner that parses its own argv reads process.argv, so it is set the way
+    // node would have: [execPath, script, ...flags].
+    const savedArgv = process.argv;
+    if (argv)
+        process.argv = [process.argv[0] ?? 'node', script, ...argv];
+    try {
+        const load = opts.load ?? ((path) => import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
+        await load(script);
+    }
+    catch (error) {
+        if (isRedlineError(error))
+            throw error;
+        // A runner that throws is reporting a real failure of the work — a bad
+        // credential, an unreachable host, a malformed data file. Letting it reach
+        // the CLI's catch-all would print "redline failed unexpectedly", which tells
+        // a reader the tool is broken when the token is.
+        const message = error instanceof Error ? error.message : String(error);
+        throw new RedlineError('host', `redline ${name} failed: ${message.split('\n')[0]}`, /401|403|bad credentials/i.test(message)
+            ? 'check the token — most of these commands need org read access'
+            : undefined);
+    }
+    finally {
+        process.argv = savedArgv;
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/metrics/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../cli/metrics/run.ts"],"names":[],"mappings":"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"}