settld 0.1.2 → 0.2.0

package/scripts/ci/flake-budget-guard.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+const ROOT = process.cwd();
+const WORKFLOW_PATH = path.join(ROOT, ".github", "workflows", "tests.yml");
+const POLICY_DOC_PATH = path.join(ROOT, "docs", "ops", "CI_FLAKE_BUDGET.md");
+
+function fail(msg) {
+  process.stderr.write(`[flake-budget-guard] ${msg}\n`);
+  process.exit(1);
+}
+
+function requirePattern({ text, pattern, label }) {
+  if (!pattern.test(text)) {
+    fail(`missing required policy marker: ${label}`);
+  }
+}
+
+function forbidPattern({ text, pattern, label }) {
+  if (pattern.test(text)) {
+    fail(`forbidden flaky tolerance detected: ${label}`);
+  }
+}
+
+async function main() {
+  const [workflowText, policyText] = await Promise.all([
+    readFile(WORKFLOW_PATH, "utf8"),
+    readFile(POLICY_DOC_PATH, "utf8")
+  ]);
+
+  // Guard against silent flake debt by forbidding retry/continue-on-error patterns
+  // in the canonical tests workflow.
+  forbidPattern({
+    text: workflowText,
+    pattern: /\bcontinue-on-error\s*:\s*true\b/i,
+    label: "continue-on-error: true"
+  });
+  forbidPattern({
+    text: workflowText,
+    pattern: /\b--retries?\b/i,
+    label: "explicit retry flag"
+  });
+
+  // Keep policy explicit and discoverable.
+  requirePattern({
+    text: policyText,
+    pattern: /^#\s*CI Flake Budget/m,
+    label: "CI Flake Budget heading"
+  });
+  requirePattern({
+    text: policyText,
+    pattern: /\bBudget:\s*0\b/i,
+    label: "Budget: 0 policy"
+  });
+  requirePattern({
+    text: policyText,
+    pattern: /\bEscalation\b/i,
+    label: "Escalation section"
+  });
+
+  process.stdout.write("[flake-budget-guard] ok\n");
+}
+
+main().catch((err) => {
+  fail(err?.message ?? String(err ?? ""));
+});

package/scripts/ci/generate-error-codes.mjs

@@ -0,0 +1,54 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+async function walk(dir) {
+  const out = [];
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const fp = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      // eslint-disable-next-line no-await-in-loop
+      out.push(...(await walk(fp)));
+    } else if (e.isFile() && fp.endsWith(".js")) out.push(fp);
+  }
+  return out;
+}
+
+function stableSortStrings(list) {
+  return [...list].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+function extractErrorCodesFromJsSource(source) {
+  const codes = new Set();
+  const re = /\berror\s*:\s*"([^"]+)"/g;
+  let m;
+  while ((m = re.exec(source)) !== null) {
+    codes.add(m[1]);
+  }
+  // CLI-specific "errors[]" code (not an `error:` field).
+  if (source.includes('code: "FAIL_ON_WARNINGS"')) codes.add("FAIL_ON_WARNINGS");
+  // Defensive fallback used by CLI when no `result.error` exists.
+  if (source.includes('"FAILED"')) codes.add("FAILED");
+  return codes;
+}
+
+async function main() {
+  const repoRoot = process.cwd();
+  const srcFiles = await walk(path.join(repoRoot, "packages", "artifact-verify", "src"));
+  const cliFile = path.join(repoRoot, "packages", "artifact-verify", "bin", "settld-verify.js");
+  const files = [...srcFiles, cliFile];
+
+  const codes = new Set();
+  for (const fp of files) {
+    // eslint-disable-next-line no-await-in-loop
+    const text = await fs.readFile(fp, "utf8");
+    for (const c of extractErrorCodesFromJsSource(text)) codes.add(c);
+  }
+
+  const outPath = path.join(repoRoot, "docs", "spec", "error-codes.v1.txt");
+  const lines = stableSortStrings(codes);
+  await fs.writeFile(outPath, lines.join("\n") + "\n", "utf8");
+}
+
+await main();
+

package/scripts/ci/lib/lighthouse-tracker.mjs

@@ -0,0 +1,90 @@
+import { readFile } from "node:fs/promises";
+
+export const LIGHTHOUSE_ACTIVE_STATUSES = Object.freeze([
+  "paid_production_settlement_confirmed",
+  "production_active"
+]);
+
+function asNonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+
+function isIsoTimestamp(value) {
+  if (typeof value !== "string" || value.trim() === "") return false;
+  return Number.isFinite(Date.parse(value));
+}
+
+export function evaluateLighthouseTracker(parsed) {
+  const accounts = Array.isArray(parsed?.accounts) ? parsed.accounts : [];
+  const requiredActiveAccounts =
+    Number.isSafeInteger(Number(parsed?.requiredActiveAccounts)) && Number(parsed.requiredActiveAccounts) > 0
+      ? Number(parsed.requiredActiveAccounts)
+      : 3;
+  const activeStatuses = new Set(LIGHTHOUSE_ACTIVE_STATUSES);
+  const duplicateAccountIds = [];
+  const seenAccountIds = new Set();
+
+  const accountChecks = accounts.map((row, index) => {
+    const accountId = asNonEmptyString(row?.accountId) ?? `unknown_${index + 1}`;
+    if (seenAccountIds.has(accountId)) duplicateAccountIds.push(accountId);
+    seenAccountIds.add(accountId);
+
+    const status = String(row?.status ?? "").toLowerCase();
+    const isActive = activeStatuses.has(status);
+    const signedAt = asNonEmptyString(row?.signedAt);
+    const goLiveAt = asNonEmptyString(row?.goLiveAt);
+    const settlementRef = asNonEmptyString(row?.productionSettlementRef);
+    const missing = [];
+    const errors = [];
+
+    if (isActive) {
+      if (!signedAt) missing.push("signedAt");
+      if (!goLiveAt) missing.push("goLiveAt");
+      if (!settlementRef) missing.push("productionSettlementRef");
+      if (signedAt && !isIsoTimestamp(signedAt)) errors.push("signedAt_invalid_iso");
+      if (goLiveAt && !isIsoTimestamp(goLiveAt)) errors.push("goLiveAt_invalid_iso");
+      if (signedAt && goLiveAt && isIsoTimestamp(signedAt) && isIsoTimestamp(goLiveAt)) {
+        const signedAtMs = Date.parse(signedAt);
+        const goLiveAtMs = Date.parse(goLiveAt);
+        if (goLiveAtMs < signedAtMs) errors.push("goLiveAt_before_signedAt");
+      }
+    }
+
+    return {
+      accountId,
+      status,
+      isActive,
+      ready: isActive && missing.length === 0 && errors.length === 0,
+      missing,
+      errors
+    };
+  });
+
+  const readyActive = accountChecks.filter((row) => row.ready);
+  const incompleteActive = accountChecks.filter((row) => row.isActive && row.ready !== true);
+  const trackerErrors = [];
+  if (duplicateAccountIds.length) {
+    trackerErrors.push({
+      code: "duplicate_account_id",
+      accountIds: Array.from(new Set(duplicateAccountIds)).sort()
+    });
+  }
+  const integrityOk = trackerErrors.length === 0;
+
+  return {
+    ok: readyActive.length >= requiredActiveAccounts && integrityOk,
+    totalAccounts: accounts.length,
+    activeAccounts: readyActive.length,
+    requiredActiveAccounts,
+    eligibleStatuses: Array.from(activeStatuses),
+    incompleteActiveAccounts: incompleteActive,
+    errors: trackerErrors,
+    accounts: accountChecks
+  };
+}
+
+export async function loadLighthouseTrackerFromPath(pathname) {
+  const raw = await readFile(pathname, "utf8");
+  const parsed = JSON.parse(raw);
+  return evaluateLighthouseTracker(parsed);
+}

package/scripts/ci/lib/self-serve-launch-gate.mjs

@@ -0,0 +1,89 @@
+import { readFile } from "node:fs/promises";
+
+export const DEFAULT_SELF_SERVE_REQUIRED_METRICS = Object.freeze([
+  "mvsvUsd",
+  "signups",
+  "teamsFirstLiveSettlement",
+  "payingCustomers",
+  "medianTimeToFirstSettlementMinutes",
+  "arbitrationMedianResolutionHours"
+]);
+
+function asFiniteNumber(value) {
+  const num = Number(value);
+  return Number.isFinite(num) ? num : null;
+}
+
+function evaluateMetric({ key, definition }) {
+  const row = definition && typeof definition === "object" && !Array.isArray(definition) ? definition : {};
+  const value = asFiniteNumber(row.value);
+  const targetMin = row.targetMin === undefined || row.targetMin === null ? null : asFiniteNumber(row.targetMin);
+  const targetMax = row.targetMax === undefined || row.targetMax === null ? null : asFiniteNumber(row.targetMax);
+  const targetMaxExclusive =
+    row.targetMaxExclusive === undefined || row.targetMaxExclusive === null ? null : asFiniteNumber(row.targetMaxExclusive);
+  const errors = [];
+
+  if (value === null) errors.push("value_missing_or_invalid");
+  if (row.targetMin !== undefined && row.targetMin !== null && targetMin === null) errors.push("targetMin_invalid");
+  if (row.targetMax !== undefined && row.targetMax !== null && targetMax === null) errors.push("targetMax_invalid");
+  if (row.targetMaxExclusive !== undefined && row.targetMaxExclusive !== null && targetMaxExclusive === null) errors.push("targetMaxExclusive_invalid");
+  if (targetMax !== null && targetMaxExclusive !== null) errors.push("targetMax_and_targetMaxExclusive_conflict");
+
+  let ok = errors.length === 0;
+  if (ok && targetMin !== null && value < targetMin) ok = false;
+  if (ok && targetMax !== null && value > targetMax) ok = false;
+  if (ok && targetMaxExclusive !== null && value >= targetMaxExclusive) ok = false;
+
+  return {
+    key,
+    label: typeof row.label === "string" && row.label.trim() !== "" ? row.label.trim() : key,
+    value,
+    targetMin,
+    targetMax,
+    targetMaxExclusive,
+    unit: typeof row.unit === "string" && row.unit.trim() !== "" ? row.unit.trim() : null,
+    ok,
+    errors
+  };
+}
+
+export function evaluateSelfServeLaunchTracker(parsed) {
+  const tracker = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  const metrics = tracker.metrics && typeof tracker.metrics === "object" && !Array.isArray(tracker.metrics) ? tracker.metrics : {};
+  const requiredRaw = Array.isArray(tracker.requiredMetrics) ? tracker.requiredMetrics : DEFAULT_SELF_SERVE_REQUIRED_METRICS;
+  const requiredMetrics = Array.from(
+    new Set(
+      requiredRaw
+        .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+        .filter(Boolean)
+    )
+  );
+
+  const metricResults = requiredMetrics.map((key) => evaluateMetric({ key, definition: metrics[key] ?? null }));
+  const missingMetrics = metricResults.filter((metric) => metric.value === null).map((metric) => metric.key);
+  const failedMetrics = metricResults.filter((metric) => metric.ok !== true).map((metric) => metric.key);
+  const ok = failedMetrics.length === 0;
+
+  return {
+    ok,
+    evaluatedAt: new Date().toISOString(),
+    schemaVersion: "SelfServeLaunchGateEvaluation.v1",
+    trackerSchemaVersion: typeof tracker.schemaVersion === "string" ? tracker.schemaVersion : null,
+    window: tracker.window && typeof tracker.window === "object" && !Array.isArray(tracker.window) ? tracker.window : null,
+    requiredMetrics,
+    missingMetrics,
+    failedMetrics,
+    metrics: metricResults,
+    summary: {
+      requiredCount: requiredMetrics.length,
+      passedCount: metricResults.filter((metric) => metric.ok).length,
+      failedCount: failedMetrics.length
+    }
+  };
+}
+
+export async function loadSelfServeLaunchTrackerFromPath(pathname) {
+  const raw = await readFile(pathname, "utf8");
+  const parsed = JSON.parse(raw);
+  return evaluateSelfServeLaunchTracker(parsed);
+}