@setsquare/review-sdk 0.0.1

package/dist/checks/rule-pack.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Setsquare's in-page axe rule pack: AAA checks axe does not ship.
+ *
+ * Registered via `axe.configure()` on OUR instance (never `window.axe`)
+ * immediately after axe is injected, so the rules flow through the same
+ * results shape, the same tags→WCAG mapping, and the same sanitisation as
+ * axe's own. Every rule carries an AAA version tag, which is what scopes it:
+ * `runOnly` selects by tag, so the pack only ever runs when a scan targets
+ * AAA — exactly like axe's own three AAA rules.
+ *
+ * **Clean-room rule (licensing):** these checks are implemented from the WCAG
+ * 2.2 Understanding documents cited on each rule, never from axe's own rule
+ * source (MPL — a close rewrite is a derivative) and never from GPL tools.
+ *
+ * **Honesty rule:** violation only where the geometry is deterministic and the
+ * SC's exceptions have been ruled out; everything judgment-shaped returns
+ * `undefined`, axe's needs-review outcome. 2.5.5's exceptions are Equivalent /
+ * Inline / User-agent / Essential — note there is NO spacing exception at AAA
+ * (that is 2.5.8's escape hatch, and importing it here would assess the wrong
+ * criterion).
+ *
+ * The pack is a source string because check `evaluate` functions must live in
+ * the page; a function shipped from Node does not survive the evaluate
+ * boundary. Version every behavioural change via SETSQUARE_RULE_PACK_VERSION — it
+ * feeds the ruleset digest.
+ */
+export declare const SETSQUARE_RULE_PACK_VERSION = "setsquare-rules@1";
+export declare const SETSQUARE_RULE_IDS: readonly ["setsquare-target-size-aaa", "setsquare-visual-presentation", "setsquare-link-purpose"];
+/**
+ * An IIFE taking the axe instance. Interpolated values are limited to the
+ * help URLs from links.ts — everything else is static source.
+ */
+export declare function rulePackSource(): string;
+//# sourceMappingURL=rule-pack.d.ts.map

package/dist/checks/rule-pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-pack.d.ts","sourceRoot":"","sources":["../../src/checks/rule-pack.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,eAAO,MAAM,2BAA2B,sBAAsB,CAAC;AAE/D,eAAO,MAAM,kBAAkB,mGAIrB,CAAC;AAEX;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAuOvC"}

package/dist/checks/rule-pack.js

@@ -0,0 +1,270 @@
+import { LINK_PURPOSE_LINK_ONLY_HELP_URL, TARGET_SIZE_ENHANCED_HELP_URL, VISUAL_PRESENTATION_HELP_URL, } from '../links.js';
+/**
+ * Setsquare's in-page axe rule pack: AAA checks axe does not ship.
+ *
+ * Registered via `axe.configure()` on OUR instance (never `window.axe`)
+ * immediately after axe is injected, so the rules flow through the same
+ * results shape, the same tags→WCAG mapping, and the same sanitisation as
+ * axe's own. Every rule carries an AAA version tag, which is what scopes it:
+ * `runOnly` selects by tag, so the pack only ever runs when a scan targets
+ * AAA — exactly like axe's own three AAA rules.
+ *
+ * **Clean-room rule (licensing):** these checks are implemented from the WCAG
+ * 2.2 Understanding documents cited on each rule, never from axe's own rule
+ * source (MPL — a close rewrite is a derivative) and never from GPL tools.
+ *
+ * **Honesty rule:** violation only where the geometry is deterministic and the
+ * SC's exceptions have been ruled out; everything judgment-shaped returns
+ * `undefined`, axe's needs-review outcome. 2.5.5's exceptions are Equivalent /
+ * Inline / User-agent / Essential — note there is NO spacing exception at AAA
+ * (that is 2.5.8's escape hatch, and importing it here would assess the wrong
+ * criterion).
+ *
+ * The pack is a source string because check `evaluate` functions must live in
+ * the page; a function shipped from Node does not survive the evaluate
+ * boundary. Version every behavioural change via SETSQUARE_RULE_PACK_VERSION — it
+ * feeds the ruleset digest.
+ */
+export const SETSQUARE_RULE_PACK_VERSION = 'setsquare-rules@1';
+export const SETSQUARE_RULE_IDS = [
+    'setsquare-target-size-aaa',
+    'setsquare-visual-presentation',
+    'setsquare-link-purpose',
+];
+/**
+ * An IIFE taking the axe instance. Interpolated values are limited to the
+ * help URLs from links.ts — everything else is static source.
+ */
+export function rulePackSource() {
+    return `(function (axe) {
+  'use strict';
+
+  axe.configure({
+    checks: [
+      {
+        // WCAG 2.5.5 Target Size (Enhanced), AAA. Implemented from the W3C
+        // Understanding document for 2.5.5 (linked as this rule's helpUrl).
+        id: 'setsquare-target-size-44',
+        evaluate: function (node) {
+          var rect = node.getBoundingClientRect();
+          var width = Math.round(rect.width);
+          var height = Math.round(rect.height);
+          // No accessible name here, deliberately (D13). For this rule the label
+          // is decoration around a measurement — the finding is 32x32 against a
+          // 44x44 requirement, and it reads the same without the page's own text.
+          // The link-purpose rule below is where the name IS the finding, and it
+          // is the only rule in this pack that may carry one.
+          //
+          // Note for anyone editing this file: it is one long template literal,
+          // so a backtick in a comment ends the string and the parse error lands
+          // three checks away from the character that caused it.
+          // Path only. A query string and a fragment are where reset tokens,
+          // email addresses and session ids live, and none of them is evidence
+          // about a target's size. Stripped here so the value never enters the
+          // check's data at all; the contract strips it again on the way out,
+          // because a rule author's care is not a boundary (D13).
+          var href = (node.getAttribute('href') || '').split('#')[0].split('?')[0];
+
+          this.data({
+            width: width,
+            height: height,
+            href: href,
+          });
+
+          if (width >= 44 && height >= 44) return true;
+
+          // Inline exception: a target in a sentence or line of text is exempt.
+          var display = window.getComputedStyle(node).display;
+          if (display === 'inline' || display === 'inline-block') {
+            var parent = node.parentElement;
+            if (parent) {
+              for (var i = 0; i < parent.childNodes.length; i += 1) {
+                var sibling = parent.childNodes[i];
+                if (sibling.nodeType === 3 && sibling.textContent && sibling.textContent.trim()) {
+                  // Sits amongst text: the inline exception may apply — a person decides.
+                  return undefined;
+                }
+              }
+            }
+          }
+
+          // User-agent exception: unstyled native checkboxes/radios are the
+          // browser's own size, which the SC exempts.
+          if (
+            node.tagName === 'INPUT' &&
+            (node.type === 'checkbox' || node.type === 'radio')
+          ) {
+            return undefined;
+          }
+
+          // Deterministically small; the Equivalent exception is ruled out (or
+          // not) across the whole page in the after() phase.
+          return false;
+        },
+        after: function (results) {
+          // Equivalent exception: another target with the same function
+          // (approximated by accessible name / destination) that IS large
+          // enough. Cannot be decided per-node, so it is decided here, and it
+          // downgrades a failure to needs-review rather than deleting it — the
+          // heuristic sees a name match, not a genuine functional equivalent.
+          var bigEnough = {};
+          results.forEach(function (result) {
+            if (result.result === true && result.data) {
+              var key = result.data.href || result.data.name;
+              if (key) bigEnough[key] = true;
+            }
+          });
+          results.forEach(function (result) {
+            if (result.result === false && result.data) {
+              var key = result.data.href || result.data.name;
+              if (key && bigEnough[key]) result.result = undefined;
+            }
+          });
+          return results;
+        },
+        metadata: {
+          impact: 'moderate',
+          messages: {
+            pass: 'Target is at least 44 by 44 CSS pixels',
+            fail: 'Target is smaller than 44 by 44 CSS pixels and no exception applies',
+            incomplete:
+              'Target is smaller than 44 by 44 CSS pixels; an exception (inline, user-agent default, or an equivalent control) may apply — needs a person',
+          },
+        },
+      },
+      {
+        // WCAG 1.4.8 Visual Presentation, AAA. Implemented from the W3C
+        // Understanding document for 1.4.8 (linked as this rule's helpUrl).
+        // Scoped to the prongs an author actively defeats: justified text,
+        // fixed line-height below 1.5, and measures past 80 characters
+        // (40 for CJK). Always needs-review — the SC requires a MECHANISM be
+        // available, so a conflicting default is a signal, never a verdict.
+        id: 'setsquare-visual-presentation-defaults',
+        evaluate: function (node) {
+          var style = window.getComputedStyle(node);
+          var problems = [];
+
+          if (style.textAlign === 'justify') problems.push('justified');
+
+          var fontSize = parseFloat(style.fontSize);
+          var lineHeight = parseFloat(style.lineHeight);
+          if (
+            style.lineHeight !== 'normal' &&
+            isFinite(lineHeight) &&
+            isFinite(fontSize) &&
+            fontSize > 0 &&
+            lineHeight / fontSize < 1.5
+          ) {
+            problems.push('line-height ' + (Math.round((lineHeight / fontSize) * 100) / 100));
+          }
+
+          var lang = (node.closest('[lang]') || document.documentElement)
+            .getAttribute('lang');
+          var cjk = /^(ja|zh|ko)/i.test(lang || '');
+          var width = node.getBoundingClientRect().width;
+          // Approximate rendered measure: CJK glyphs are square (one em); Latin
+          // averages about half an em.
+          var chars = cjk ? width / fontSize : width / (fontSize * 0.5);
+          var limit = cjk ? 40 : 80;
+          if (isFinite(chars) && chars > limit) {
+            problems.push('measure ~' + Math.round(chars) + ' chars (limit ' + limit + ')');
+          }
+
+          if (problems.length === 0) return true;
+          this.data({ problems: problems.join('; ') });
+          return undefined;
+        },
+        metadata: {
+          impact: 'minor',
+          messages: {
+            pass: 'Text block defaults do not conflict with 1.4.8',
+            fail: 'Text block presentation fails 1.4.8',
+            incomplete:
+              'Defaults conflict with 1.4.8; a user mechanism may still satisfy it — needs a person',
+          },
+        },
+      },
+      {
+        // WCAG 2.4.9 Link Purpose (Link Only), AAA. Implemented from the W3C
+        // Understanding document for 2.4.9 (linked as this rule's helpUrl).
+        id: 'setsquare-link-purpose-text',
+        evaluate: function (node) {
+          var name = (
+            node.getAttribute('aria-label') ||
+            node.textContent ||
+            node.getAttribute('title') ||
+            ''
+          )
+            .trim()
+            .toLowerCase()
+            .replace(/\\s+/g, ' ');
+
+          if (!name) return true; // Nameless links are axe's link-name rule, not ours.
+
+          var vague = [
+            'click here', 'click', 'here', 'read more', 'more', 'learn more',
+            'details', 'more details', 'this page', 'continue', 'link', 'go',
+          ];
+          var isVague = vague.indexOf(name) !== -1 || /^https?:\\/\\//.test(name);
+
+          if (!isVague) return true;
+          this.data({ name: name.slice(0, 80) });
+          return undefined;
+        },
+        metadata: {
+          impact: 'minor',
+          messages: {
+            pass: 'Link text describes its purpose',
+            fail: 'Link text does not describe its purpose',
+            incomplete:
+              'Link text alone may not describe its purpose ("click here", "read more", a bare URL) — needs a person',
+          },
+        },
+      },
+    ],
+    rules: [
+      {
+        id: 'setsquare-target-size-aaa',
+        selector:
+          'a[href], button, input:not([type=hidden]), select, textarea, ' +
+          '[role=button], [role=link], [role=checkbox], [role=radio], [role=tab], [role=menuitem]',
+        excludeHidden: true,
+        // 2.5.5 arrived in WCAG 2.1; the criterion tag is what toWcag() maps.
+        tags: ['wcag21aaa', 'wcag255'],
+        all: ['setsquare-target-size-44'],
+        metadata: {
+          description: 'Targets should be at least 44 by 44 CSS pixels (WCAG 2.5.5, AAA)',
+          help: 'Target size (enhanced)',
+          helpUrl: '${TARGET_SIZE_ENHANCED_HELP_URL}',
+        },
+      },
+      {
+        id: 'setsquare-visual-presentation',
+        selector: 'p',
+        excludeHidden: true,
+        tags: ['wcag2aaa', 'wcag148'],
+        all: ['setsquare-visual-presentation-defaults'],
+        metadata: {
+          description:
+            'Text block presentation should not conflict with WCAG 1.4.8 defaults (AAA)',
+          help: 'Visual presentation',
+          helpUrl: '${VISUAL_PRESENTATION_HELP_URL}',
+        },
+      },
+      {
+        id: 'setsquare-link-purpose',
+        selector: 'a[href]',
+        excludeHidden: true,
+        tags: ['wcag2aaa', 'wcag249'],
+        all: ['setsquare-link-purpose-text'],
+        metadata: {
+          description: 'Link purpose should be clear from the link text alone (WCAG 2.4.9, AAA)',
+          help: 'Link purpose (link only)',
+          helpUrl: '${LINK_PURPOSE_LINK_ONLY_HELP_URL}',
+        },
+      },
+    ],
+  });
+})`;
+}
+//# sourceMappingURL=rule-pack.js.map

package/dist/checks/rule-pack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-pack.js","sourceRoot":"","sources":["../../src/checks/rule-pack.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,+BAA+B,EAC/B,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAC;AAE/D,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,2BAA2B;IAC3B,+BAA+B;IAC/B,wBAAwB;CAChB,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAuMa,6BAA6B;;;;;;;;;;;;;sBAa7B,4BAA4B;;;;;;;;;;;;sBAY5B,+BAA+B;;;;;GAKlD,CAAC;AACJ,CAAC"}

package/dist/checks/versions.d.ts

@@ -0,0 +1,28 @@
+import type { RulePolicy } from '../rules.js';
+/**
+ * The Setsquare checks a run is CONFIGURED with, for the ruleset digest.
+ *
+ * Policy-level, deliberately, and identical for every scan in a run: the
+ * digest pins the configuration evidence is relative to, exactly as the tag
+ * list does — a quiet auto-scan that never found a safe moment for the
+ * dynamic checks still ran under the same configuration, the same way an
+ * inapplicable axe rule is still part of the ruleset. Making this per-scan
+ * (only the scans that executed a check) split one run across two digests
+ * and set off the multi-ruleset drift warning on every run, which would
+ * teach people to ignore the warning that exists to catch real drift.
+ */
+export declare function setsquareCheckVersions(policy: RulePolicy): string[];
+/**
+ * Which criteria Setsquare's OWN checks map to — the setsquare half of the
+ * criterion → rules coverage map. Without this, a setsquare-covered criterion with
+ * no rows in a run renders as "no automated check in this engine", which is
+ * false the moment the check exists: 3.3.1 and 4.1.3 sat in that list on the
+ * first real Eos run while setsquare-status-messages was right there, idle only
+ * because no error state was scanned.
+ *
+ * Lists every check that EXISTS in this build, enabled or not — the ledger's
+ * "checks that did not run here" is exactly the right label for a check that
+ * exists but was gated off (reading level at an AA target, the AAA pack at AA).
+ */
+export declare const SETSQUARE_CHECK_CRITERIA: ReadonlyMap<string, readonly string[]>;
+//# sourceMappingURL=versions.d.ts.map

package/dist/checks/versions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/checks/versions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAO9C;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAKnE;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAO1E,CAAC"}

package/dist/checks/versions.js

@@ -0,0 +1,45 @@
+import { readingLevelEnabled } from '../runtime.js';
+import { SETSQUARE_DYNAMIC_CHECKS_VERSION } from './dynamic.js';
+import { SETSQUARE_RULE_PACK_VERSION } from './rule-pack.js';
+import { READING_LEVEL_CHECK_VERSION } from '../reading-level.js';
+/**
+ * The Setsquare checks a run is CONFIGURED with, for the ruleset digest.
+ *
+ * Policy-level, deliberately, and identical for every scan in a run: the
+ * digest pins the configuration evidence is relative to, exactly as the tag
+ * list does — a quiet auto-scan that never found a safe moment for the
+ * dynamic checks still ran under the same configuration, the same way an
+ * inapplicable axe rule is still part of the ruleset. Making this per-scan
+ * (only the scans that executed a check) split one run across two digests
+ * and set off the multi-ruleset drift warning on every run, which would
+ * teach people to ignore the warning that exists to catch real drift.
+ */
+export function setsquareCheckVersions(policy) {
+    const versions = [SETSQUARE_DYNAMIC_CHECKS_VERSION];
+    if (policy.target === 'AAA')
+        versions.push(SETSQUARE_RULE_PACK_VERSION);
+    if (readingLevelEnabled())
+        versions.push(READING_LEVEL_CHECK_VERSION);
+    return versions;
+}
+/**
+ * Which criteria Setsquare's OWN checks map to — the setsquare half of the
+ * criterion → rules coverage map. Without this, a setsquare-covered criterion with
+ * no rows in a run renders as "no automated check in this engine", which is
+ * false the moment the check exists: 3.3.1 and 4.1.3 sat in that list on the
+ * first real Eos run while setsquare-status-messages was right there, idle only
+ * because no error state was scanned.
+ *
+ * Lists every check that EXISTS in this build, enabled or not — the ledger's
+ * "checks that did not run here" is exactly the right label for a check that
+ * exists but was gated off (reading level at an AA target, the AAA pack at AA).
+ */
+export const SETSQUARE_CHECK_CRITERIA = new Map([
+    ['setsquare-text-spacing', ['1.4.12']],
+    ['setsquare-status-messages', ['3.3.1', '4.1.3']],
+    ['setsquare-reading-level', ['3.1.5']],
+    ['setsquare-target-size-aaa', ['2.5.5']],
+    ['setsquare-visual-presentation', ['1.4.8']],
+    ['setsquare-link-purpose', ['2.4.9']],
+]);
+//# sourceMappingURL=versions.js.map

package/dist/checks/versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../src/checks/versions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAE7D,OAAO,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAkB;IACvD,MAAM,QAAQ,GAAG,CAAC,gCAAgC,CAAC,CAAC;IACpD,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK;QAAE,QAAQ,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACxE,IAAI,mBAAmB,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACtE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAA2C,IAAI,GAAG,CAAC;IACtF,CAAC,wBAAwB,EAAE,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC,2BAA2B,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC,yBAAyB,EAAE,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC,2BAA2B,EAAE,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC,+BAA+B,EAAE,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC,wBAAwB,EAAE,CAAC,OAAO,CAAC,CAAC;CACtC,CAAC,CAAC"}

package/dist/ci.d.ts

@@ -0,0 +1,37 @@
+import type { RunIngestRequest } from '@setsquare/schema';
+/**
+ * Where this run came from.
+ *
+ * `runSource` and `branch` are not decoration. P2's canonical-run machinery
+ * decides which runs drive trend and regression claims, and it decides on these
+ * fields — so a run that misreports its branch attaches itself to a history it was
+ * never part of, and every "this regressed" claim built on that history is
+ * quietly wrong. That is why the rule here is absolute: **detection failures
+ * degrade to an explicit "unknown", never to a plausible guess.**
+ *
+ * "unknown" is unjoinable, which is precisely what makes it safe. A run that
+ * cannot say where it came from simply does not participate.
+ */
+export declare const UNKNOWN = "unknown";
+export interface RunOrigin {
+    runSource: 'ci' | 'local';
+    branch: string;
+    commit: string;
+    ci?: NonNullable<RunIngestRequest['source']['ci']>;
+    /** Which fields could not be determined. Surfaced in the run's own output. */
+    unknowns: string[];
+}
+type Env = Record<string, string | undefined>;
+/**
+ * Detect the run's origin from the environment, falling back to git.
+ *
+ * Providers are checked most-specific-first. A GitHub Actions runner also sets
+ * the generic `CI=true`, so an ordering that tested the generic case first would
+ * report every GitHub run as an unidentified CI with no branch — the fields are
+ * there, and we would have thrown them away.
+ */
+export declare function detectOrigin(env?: Env, cwd?: string): RunOrigin;
+export declare function gitBranch(cwd?: string): string;
+export declare function gitCommit(cwd?: string): string;
+export {};
+//# sourceMappingURL=ci.d.ts.map

package/dist/ci.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci.d.ts","sourceRoot":"","sources":["../src/ci.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,OAAO,YAAY,CAAC;AAEjC,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,IAAI,GAAG,OAAO,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,WAAW,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACnD,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE9C;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,GAAE,GAAiB,EAAE,GAAG,GAAE,MAAsB,GAAG,SAAS,CAkB3F;AAuJD,wBAAgB,SAAS,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,CAW7D;AAED,wBAAgB,SAAS,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,CAE7D"}

package/dist/ci.js

@@ -0,0 +1,199 @@
+import { spawnSync } from 'node:child_process';
+/**
+ * Where this run came from.
+ *
+ * `runSource` and `branch` are not decoration. P2's canonical-run machinery
+ * decides which runs drive trend and regression claims, and it decides on these
+ * fields — so a run that misreports its branch attaches itself to a history it was
+ * never part of, and every "this regressed" claim built on that history is
+ * quietly wrong. That is why the rule here is absolute: **detection failures
+ * degrade to an explicit "unknown", never to a plausible guess.**
+ *
+ * "unknown" is unjoinable, which is precisely what makes it safe. A run that
+ * cannot say where it came from simply does not participate.
+ */
+export const UNKNOWN = 'unknown';
+/**
+ * Detect the run's origin from the environment, falling back to git.
+ *
+ * Providers are checked most-specific-first. A GitHub Actions runner also sets
+ * the generic `CI=true`, so an ordering that tested the generic case first would
+ * report every GitHub run as an unidentified CI with no branch — the fields are
+ * there, and we would have thrown them away.
+ */
+export function detectOrigin(env = process.env, cwd = process.cwd()) {
+    const detected = githubActions(env) ?? gitlabCi(env) ?? circleCi(env) ?? genericCi(env);
+    if (detected)
+        return withUnknowns(detected);
+    /*
+     * Not CI. Read git, because the local envelope is a product in its own right
+     * and "which branch was this?" is the first thing anyone asks of a saved run.
+     *
+     * Shelling out is a deliberate, bounded choice: one short-lived process, a
+     * timeout, and silence on any failure. It is not a network call, and it is what
+     * every other developer tool in this space already does.
+     */
+    return withUnknowns({
+        runSource: 'local',
+        branch: gitBranch(cwd),
+        commit: gitCommit(cwd),
+    });
+}
+function withUnknowns(origin) {
+    const unknowns = [];
+    if (origin.branch === UNKNOWN)
+        unknowns.push('branch');
+    if (origin.commit === UNKNOWN)
+        unknowns.push('commit');
+    return { ...origin, unknowns };
+}
+/** Non-empty, or nothing. An empty environment variable is not a value. */
+function value(raw) {
+    const trimmed = raw?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
+function githubActions(env) {
+    if (value(env['GITHUB_ACTIONS']) !== 'true')
+        return undefined;
+    /*
+     * On a `pull_request` event GitHub checks out a MERGE commit that exists
+     * nowhere in the repository, and sets:
+     *
+     *   GITHUB_REF_NAME = "123/merge"     — not a branch
+     *   GITHUB_SHA      = <merge commit>  — not the commit anyone pushed
+     *   GITHUB_HEAD_REF = <source branch> — the thing a human would name
+     *
+     * Reporting the first two would file every PR run against a branch called
+     * "123/merge" and a commit nobody can check out. P2 joins branch lineage across
+     * runs, so that is not cosmetic — it would orphan every PR from its own branch's
+     * history.
+     */
+    const isPullRequest = value(env['GITHUB_EVENT_NAME'])?.startsWith('pull_request') === true;
+    const headRef = value(env['GITHUB_HEAD_REF']);
+    const branch = (isPullRequest ? headRef : undefined) ?? value(env['GITHUB_REF_NAME']) ?? UNKNOWN;
+    const commit = value(env['GITHUB_SHA']) ?? UNKNOWN;
+    const ci = { provider: 'github-actions' };
+    const server = value(env['GITHUB_SERVER_URL']);
+    const repository = value(env['GITHUB_REPOSITORY']);
+    const runId = value(env['GITHUB_RUN_ID']);
+    if (server && repository && runId)
+        ci.buildUrl = `${server}/${repository}/actions/runs/${runId}`;
+    // `refs/pull/123/merge` -> `123`.
+    const pullRequest = /refs\/pull\/(\d+)\//.exec(value(env['GITHUB_REF']) ?? '')?.[1];
+    if (pullRequest)
+        ci.pullRequest = pullRequest;
+    return { runSource: 'ci', branch, commit, ci };
+}
+/**
+ * GitLab, detected but not supported.
+ *
+ * The distinction matters and is deliberate: real GitLab *support* (merge-request
+ * comments, pipeline status) is a P7 adapter behind P5's provider interface. What
+ * belongs here is recognising the environment so the run is honestly labelled
+ * `ci` with a real branch, rather than being mistaken for someone's laptop and
+ * quietly excluded from every trend claim.
+ */
+function gitlabCi(env) {
+    if (value(env['GITLAB_CI']) !== 'true')
+        return undefined;
+    const ci = { provider: 'gitlab-ci' };
+    const buildUrl = value(env['CI_PIPELINE_URL']);
+    if (buildUrl)
+        ci.buildUrl = buildUrl;
+    const mergeRequest = value(env['CI_MERGE_REQUEST_IID']);
+    if (mergeRequest)
+        ci.pullRequest = mergeRequest;
+    return {
+        runSource: 'ci',
+        // `CI_COMMIT_REF_NAME` is the branch on a branch pipeline and the source
+        // branch on a merge-request pipeline, which is the same distinction GitHub
+        // needs `GITHUB_HEAD_REF` for.
+        branch: value(env['CI_COMMIT_REF_NAME']) ?? UNKNOWN,
+        commit: value(env['CI_COMMIT_SHA']) ?? UNKNOWN,
+        ci,
+    };
+}
+/** CircleCI, on the same detected-not-supported basis as GitLab. */
+function circleCi(env) {
+    if (value(env['CIRCLECI']) !== 'true')
+        return undefined;
+    const ci = { provider: 'circleci' };
+    const buildUrl = value(env['CIRCLE_BUILD_URL']);
+    if (buildUrl)
+        ci.buildUrl = buildUrl;
+    const pullRequest = value(env['CIRCLE_PR_NUMBER']);
+    if (pullRequest)
+        ci.pullRequest = pullRequest;
+    return {
+        runSource: 'ci',
+        branch: value(env['CIRCLE_BRANCH']) ?? UNKNOWN,
+        commit: value(env['CIRCLE_SHA1']) ?? UNKNOWN,
+        ci,
+    };
+}
+/**
+ * Some CI we do not recognise.
+ *
+ * Nearly every CI system sets `CI=true`, so this catches Jenkins, Buildkite,
+ * Azure Pipelines, TeamCity and whatever comes next. It reports `runSource: ci`
+ * honestly — that much is certain — and declines to invent a branch, because the
+ * variable holding it differs per provider and guessing wrong is worse than
+ * admitting ignorance.
+ *
+ * Git still answers, and usually correctly: most CI systems check out a real
+ * branch. Where they check out a detached HEAD, `gitBranch` returns unknown
+ * rather than the literal string "HEAD".
+ */
+function genericCi(env) {
+    const ci = value(env['CI']);
+    if (ci !== 'true' && ci !== '1')
+        return undefined;
+    return {
+        runSource: 'ci',
+        branch: gitBranch(),
+        commit: gitCommit(),
+        ci: { provider: UNKNOWN },
+    };
+}
+/**
+ * Run a git command, or give up quietly.
+ *
+ * Bounded on purpose: no shell, a short timeout, and any failure — not a repo, no
+ * git installed, a repository so large the call is slow — resolves to nothing.
+ * The SDK must never be the reason a suite hangs, and this runs on every single
+ * run.
+ */
+function git(args, cwd) {
+    try {
+        const result = spawnSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            timeout: 2000,
+            // No shell: the arguments are fixed, and a shell would be an injection
+            // surface for a directory name.
+            shell: false,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        if (result.status !== 0)
+            return undefined;
+        return value(result.stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function gitBranch(cwd = process.cwd()) {
+    const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+    /*
+     * A detached HEAD reports the literal string "HEAD", which is not a branch and
+     * would collide across every such run in the history. CI systems that check out
+     * a commit rather than a branch do this constantly.
+     */
+    if (!branch || branch === 'HEAD')
+        return UNKNOWN;
+    return branch;
+}
+export function gitCommit(cwd = process.cwd()) {
+    return git(['rev-parse', 'HEAD'], cwd) ?? UNKNOWN;
+}
+//# sourceMappingURL=ci.js.map

package/dist/ci.js.map

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