connections-architect 0.2.0

package/src/checks/hosted/db-justify-existence.mjs

@@ -0,0 +1,113 @@
+// HOSTED check — the generic justify-existence governor for a live Postgres DB, distilled from daggar.
+// Runs ONLY through the MCP vault (domain:"hosted" → skipped standalone). Judges every table on the
+// 3-axis model (DATA rows × external APP-CODE refs × internal DB refs) against the user's spine, and
+// emits the 5 verdicts + a review-only remediation block. READ-ONLY — it never mutates the DB.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createFinding } from "../../core/finding.mjs";
+import { walkFiles } from "../../core/fs-walk.mjs";
+import { loadSpine, resolveClaim } from "../../core/hosted/spine.mjs";
+import { judgeObject, verdictSeverity, VERDICT_RANK } from "../../core/hosted/judge.mjs";
+import { vaultRdsQuery } from "../../core/hosted/vault-exec.mjs";
+
+const TABLES_SQL = "select relname as name, n_live_tup as rows from pg_stat_user_tables";
+const INTERNAL_SRC_SQL =
+  "select prosrc as src from pg_proc where pronamespace = 'public'::regnamespace " +
+  "union all select definition as src from pg_views where schemaname = 'public'";
+
+const CODE_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".rs", ".go", ".rb", ".java", ".php", ".sql"]);
+
+export const audit = {
+  id: "db-justify-existence",
+  title: "Database — justify existence (hosted)",
+  category: "governance",
+  domain: "hosted",
+  requires: {},
+  gating: false,
+  defaultConfig: {},
+  async run(ctx) {
+    const { root, config, vault } = ctx;
+    const targets = (config?.hosted?.targets || []).filter((t) => t.kind === "aurora-postgres-data-api");
+    if (!targets.length) return { failed: false, findings: [], report: "" };
+
+    // The user's spine (the policy — their `your-checks/` for the hosted half). Path is repo-relative.
+    let spine = loadSpine({});
+    if (config?.hosted?.spine) {
+      try {
+        spine = loadSpine(JSON.parse(readFileSync(join(root, config.hosted.spine), "utf8")));
+      } catch {
+        /* no spine → everything is unrecorded (PROVE-OR-DIE) */
+      }
+    }
+    const codeBlob = readCodeBlob(root, spine.appCodeRoots);
+
+    const findings = [];
+    const killOrders = [];
+    for (const target of targets) {
+      const tables = await vaultRdsQuery(vault, target, TABLES_SQL);
+      const internalSrc = (await vaultRdsQuery(vault, target, INTERNAL_SRC_SQL)).map((r) => String(r.src ?? "")).join("\n");
+      for (const t of tables) {
+        const name = String(t.name);
+        const rows = Number(t.rows) || 0;
+        const dbRefs = countOccurrences(internalSrc, name);
+        const appRefs = countOccurrences(codeBlob, name);
+        const alive = rows > 0 || dbRefs > 0 || appRefs > 0;
+        const claim = resolveClaim(spine, name);
+        const verdict = judgeObject({ declared: claim.declared, alive, investigate: claim.investigate, claimedRemove: claim.claimedRemove });
+        const sev = verdictSeverity(verdict);
+        if (!sev) continue; // JUSTIFIED
+        findings.push(
+          createFinding({
+            id: "db-object-verdict",
+            title: `${verdict}: ${name}`,
+            severity: sev,
+            resource: `${target.database}.${name}`,
+            account: target.vaultInstance,
+            verdict,
+            message: `${verdict} — rows=${rows}, app-refs=${appRefs}, db-refs=${dbRefs}, declared=${claim.declared}${claim.claimedBy ? ` (by ${claim.claimedBy})` : ""}`,
+            fix: verdict === "PROVE-OR-DIE" ? `Add a spine claim for "${name}" or drop it.` : null,
+          }),
+        );
+        if (verdict === "CONDEMNED") {
+          killOrders.push(`-- ${target.database}.${name}: CONDEMNED (rows=${rows}, app-refs=${appRefs}, db-refs=${dbRefs})\n-- drop table if exists "${name}";  -- REVIEW + previewed read before running`);
+        }
+      }
+    }
+
+    findings.sort((a, b) => (VERDICT_RANK[a.verdict] ?? 9) - (VERDICT_RANK[b.verdict] ?? 9));
+    const warnings = findings.filter((f) => f.severity === "warning").length;
+    const report = findings.length
+      ? `# DB justify-existence\n\n${findings.map((f) => `- ${f.verdict}  ${f.resource} — ${f.message}`).join("\n")}` +
+        (killOrders.length ? `\n\n## Remediation — REVIEW + previewed read before running (never auto-executed)\n\n\`\`\`sql\n${killOrders.join("\n\n")}\n\`\`\`` : "") +
+        `\n\nErrors: 0\nWarnings: ${warnings}\n`
+      : "";
+    return { failed: false, findings, report };
+  },
+};
+
+// Concatenate the repo's code once so each table name can be counted against it (the external-reference
+// axis). Bounded so a huge monorepo doesn't blow memory; honors the spine's appCodeRoots if set.
+function readCodeBlob(root, appCodeRoots) {
+  const roots = appCodeRoots && appCodeRoots.length ? appCodeRoots.map((r) => join(root, r)) : [root];
+  let blob = "";
+  let budget = 4000;
+  for (const r of roots) {
+    for (const file of walkFiles(r)) {
+      if (budget-- <= 0) break;
+      if (!CODE_EXT.has(file.slice(file.lastIndexOf(".")))) continue;
+      try {
+        blob += "\n" + readFileSync(file, "utf8");
+      } catch {
+        /* skip unreadable */
+      }
+    }
+  }
+  return blob;
+}
+
+function countOccurrences(haystack, name) {
+  if (!name) return 0;
+  const re = new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "g");
+  const m = haystack.match(re);
+  return m ? m.length : 0;
+}

package/src/core/discovery.mjs

@@ -0,0 +1,36 @@
+// Auto-discovery — the heart of the core/extension model. A check is ANY .mjs that exports `audit`
+// with an `id` + `run()`. No registry to edit; the file IS the registration. We scan MULTIPLE roots in
+// priority order and merge: later roots OVERRIDE earlier by id, so a user's `your-checks/` check shadows
+// a core check of the same id (patch a core check without touching the core). The folder name = the group.
+import { existsSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+import { walkFiles } from "./fs-walk.mjs";
+
+export async function discoverAudits(roots) {
+  const byId = new Map();
+  const loadErrors = [];
+  const shadowed = [];
+  for (const root of roots) {
+    if (!root || !existsSync(root)) continue;
+    for (const file of walkFiles(root)) {
+      if (!file.endsWith(".mjs") || file.endsWith(".test.mjs")) continue;
+      let mod;
+      try {
+        mod = await import(pathToFileURL(file).href);
+      } catch (e) {
+        // A check that won't even load must be LOUD (crash≠silent-pass), never silently dropped.
+        loadErrors.push({ file, error: String(e?.message || e) });
+        continue;
+      }
+      const audit = mod.audit;
+      if (!audit || typeof audit.id !== "string" || typeof audit.run !== "function") continue;
+      if (byId.has(audit.id)) shadowed.push({ id: audit.id, by: file });
+      audit.__file = file;
+      audit.__group = basename(dirname(file));
+      audit.__root = root;
+      byId.set(audit.id, audit);
+    }
+  }
+  return { audits: [...byId.values()], loadErrors, shadowed };
+}

package/src/core/finding.mjs

@@ -0,0 +1,40 @@
+// The one Finding shape every check emits — for code AND hosted/infra checks. Distilled from arkitect's
+// normalized finding + risk scoring. A check may also return plain objects of this shape; createFinding
+// just fills defaults. Carries infra fields (resource/account/region) so the hosted half reuses it verbatim.
+
+export const SEVERITY = Object.freeze({ error: "error", warning: "warning", info: "info" });
+
+export function createFinding({
+  id,
+  title,
+  severity = "error",
+  file = null,
+  line = null,
+  message = "",
+  resource = null, // hosted: an ARN / table / bucket / role
+  account = null, // hosted: which cloud account
+  region = null,
+  verdict = null, // hosted: JUSTIFIED | WATCH | PROVE-OR-DIE | INVESTIGATE | CONDEMNED
+  fix = null, // a one-line suggested remediation
+} = {}) {
+  return { id, title, severity, file, line, message: message || title, resource, account, region, verdict, fix };
+}
+
+export function countSeverities(findings = []) {
+  let errors = 0,
+    warnings = 0,
+    infos = 0;
+  for (const f of findings) {
+    if (f.severity === "error") errors++;
+    else if (f.severity === "warning") warnings++;
+    else infos++;
+  }
+  return { errors, warnings, infos };
+}
+
+// Cheap risk ordering for the FIX_QUEUE — errors first, then by reachability hints. Kept deliberately
+// simple in Phase 1; the full arkitect risk axes (exposure × data × reachability × safety-net) land in Phase 2.
+export function riskRank(finding) {
+  const sev = finding.severity === "error" ? 0 : finding.severity === "warning" ? 1 : 2;
+  return sev;
+}

package/src/core/fs-walk.mjs

@@ -0,0 +1,22 @@
+// One filesystem walker, reused by discovery + every check (DRY). Skips the usual build/vendor dirs.
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { IGNORE_DIRS } from "./project-detect.mjs";
+
+export function* walkFiles(dir, { ignore = IGNORE_DIRS, includeDotfiles = false } = {}) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (!includeDotfiles && e.name.startsWith(".")) continue;
+    const p = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (!ignore.has(e.name)) yield* walkFiles(p, { ignore, includeDotfiles });
+    } else {
+      yield p;
+    }
+  }
+}

package/src/core/hosted/judge.mjs

@@ -0,0 +1,45 @@
+// The generic "justify existence" judge — distilled from daggar's 3-axis verdict system, generalized so
+// it works on ANY live resource (a DB table, an S3 bucket, an IAM role), not just our schema.
+//
+// daggar judged each DB object on DATA (rows) × APP-CODE refs × DB-internal refs, against a per-workspace
+// "justify existence" spine. The generalization: an object is JUSTIFIED only when it is BOTH
+//   • DECLARED — a human wrote down why it exists (a spine claim), AND
+//   • ALIVE    — something actually uses it (holds data, or is referenced by external code, or by another
+//                internal object).
+// An explicit spine verdict (INVESTIGATE / REMOVE) overrides the inference — so a squatter can't be
+// auto-justified by a loose prefix-claim, and a human kill-order is honored.
+
+// Ranked worst→best, for sorting kill-orders.
+export const VERDICT_RANK = Object.freeze({
+  CONDEMNED: 0,
+  "PROVE-OR-DIE": 1,
+  INVESTIGATE: 2,
+  WATCH: 3,
+  JUSTIFIED: 4,
+});
+
+/**
+ * Judge ONE object.
+ * @param {object} o
+ * @param {boolean} o.declared      - the spine claims this object (a recorded reason to exist)
+ * @param {boolean} o.alive         - anything references/uses it (rows > 0 OR external ref OR internal ref)
+ * @param {boolean} [o.investigate] - the spine explicitly flags it for human review (overrides)
+ * @param {boolean} [o.claimedRemove] - the spine explicitly orders removal (overrides)
+ * @returns {"JUSTIFIED"|"WATCH"|"PROVE-OR-DIE"|"INVESTIGATE"|"CONDEMNED"}
+ */
+export function judgeObject({ declared, alive, investigate = false, claimedRemove = false }) {
+  if (investigate) return "INVESTIGATE"; // explicit human flag wins
+  if (claimedRemove) return "CONDEMNED"; // explicit kill-order wins
+  if (declared && alive) return "JUSTIFIED"; // recorded AND used
+  if (declared && !alive) return "WATCH"; // recorded but inert — keep an eye on it
+  if (!declared && alive) return "PROVE-OR-DIE"; // used but no recorded reason — earn a spine entry or die
+  return "CONDEMNED"; // unrecorded AND inert
+}
+
+// Verdict → finding severity. This is a read-only GOVERNANCE judgment (recommends, never mutates), so the
+// strongest verdicts surface as warnings, the softer ones as info. JUSTIFIED produces no finding.
+export function verdictSeverity(verdict) {
+  if (verdict === "CONDEMNED" || verdict === "PROVE-OR-DIE") return "warning";
+  if (verdict === "WATCH" || verdict === "INVESTIGATE") return "info";
+  return null; // JUSTIFIED
+}

package/src/core/hosted/spine.mjs

@@ -0,0 +1,42 @@
+// The "justify existence" SPINE — the user-extension space for the HOSTED half (the daggar spine,
+// generalized + portable). The user declares WHY each live object exists; the framework judges against it.
+// This is the hosted equivalent of `your-checks/`: the policy is the user's, the engine is the core's.
+//
+// Shape (justify-existence.json):
+// {
+//   "appCodeRoots": ["src", "services"],          // where to grep for external references (default: repo root)
+//   "features": [                                   // each feature CLAIMS the objects it owns
+//     { "name": "billing", "claims": ["invoices", "payment_*"] }
+//   ],
+//   "verdicts": { "legacy_temp": "REMOVE", "weird_table": "INVESTIGATE" }  // explicit overrides
+// }
+// A claim ending in `*` is a prefix claim; otherwise it's an exact name.
+
+export function loadSpine(json) {
+  const s = json && typeof json === "object" ? json : {};
+  return {
+    appCodeRoots: Array.isArray(s.appCodeRoots) && s.appCodeRoots.length ? s.appCodeRoots : null,
+    features: Array.isArray(s.features) ? s.features : [],
+    verdicts: s.verdicts && typeof s.verdicts === "object" ? s.verdicts : {},
+  };
+}
+
+/**
+ * Resolve what the spine says about an object by name.
+ * Explicit `verdicts[name]` overrides any feature claim (so a prefix-claim can't auto-justify a squatter,
+ * and a human REMOVE/INVESTIGATE is honored).
+ * @returns {{ declared: boolean, investigate: boolean, claimedRemove: boolean, claimedBy: string|null }}
+ */
+export function resolveClaim(spine, name) {
+  const override = spine.verdicts?.[name];
+  if (override === "INVESTIGATE") return { declared: true, investigate: true, claimedRemove: false, claimedBy: "verdicts" };
+  if (override === "REMOVE") return { declared: true, investigate: false, claimedRemove: true, claimedBy: "verdicts" };
+
+  for (const f of spine.features || []) {
+    for (const claim of f.claims || []) {
+      const matched = claim.endsWith("*") ? name.startsWith(claim.slice(0, -1)) : claim === name;
+      if (matched) return { declared: true, investigate: false, claimedRemove: false, claimedBy: f.name || claim };
+    }
+  }
+  return { declared: false, investigate: false, claimedRemove: false, claimedBy: null };
+}

package/src/core/hosted/vault-exec.mjs

@@ -0,0 +1,61 @@
+// Run a READ-ONLY query against the user's OWN cloud DB THROUGH the MCP vault — value-blind: the
+// credential never enters the model context; the MCP injects it server-side (the same seam deploy_static
+// uses). The `vault` handle is provided by the MCP-hosted runner. Standalone (`npx architect`, no MCP)
+// there is no vault, so hosted checks are skipped (see runner.mjs) — the code half still runs.
+//
+// target: { kind:"aurora-postgres-data-api", vaultInstance, resourceArn, secretArn, database, region? }
+
+export async function vaultRdsQuery(vault, target, sql) {
+  if (!vault || typeof vault.awsCall !== "function") {
+    throw new Error("hosted checks require the Connections MCP vault (no vault handle present)");
+  }
+  const res = await vault.awsCall({
+    instance: target.vaultInstance,
+    service: "rds-data",
+    region: target.region || "us-east-1",
+    method: "POST",
+    path: "/Execute",
+    body: JSON.stringify({
+      resourceArn: target.resourceArn,
+      secretArn: target.secretArn,
+      database: target.database,
+      sql,
+      includeResultMetadata: true,
+    }),
+  });
+  return parseRdsRecords(res);
+}
+
+// RDS Data API returns { records: [[{stringValue|longValue|…}, …], …], columnMetadata: [{name},…] }.
+// Flatten to plain {col: value} rows. Mirrors daggar's cell() extraction. Pure → unit-testable.
+export function parseRdsRecords(res) {
+  const body = typeof res?.body === "string" ? safeJson(res.body) : (res?.body ?? res);
+  if (!body || !Array.isArray(body.records)) return [];
+  const cols = (body.columnMetadata || []).map((c) => c.name);
+  return body.records.map((rec) => {
+    const row = {};
+    rec.forEach((cell, i) => {
+      row[cols[i] ?? i] = cellValue(cell);
+    });
+    return row;
+  });
+}
+
+function cellValue(cell) {
+  if (!cell || typeof cell !== "object") return cell;
+  if (cell.isNull) return null;
+  if ("stringValue" in cell) return cell.stringValue;
+  if ("longValue" in cell) return cell.longValue;
+  if ("doubleValue" in cell) return cell.doubleValue;
+  if ("booleanValue" in cell) return cell.booleanValue;
+  if ("blobValue" in cell) return cell.blobValue;
+  return null;
+}
+
+function safeJson(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}

package/src/core/index.mjs

@@ -0,0 +1,12 @@
+// Public API for check authors: `import { createFinding } from "connections-architect"`.
+export { createFinding, countSeverities, riskRank, SEVERITY } from "./finding.mjs";
+export { detectProject, checkAppliesToProject, IGNORE_DIRS } from "./project-detect.mjs";
+export { walkFiles } from "./fs-walk.mjs";
+export { discoverAudits } from "./discovery.mjs";
+export { runAudits } from "./runner.mjs";
+export { toSarif } from "./sarif.mjs";
+export { runFamilyConformance } from "./oracle/family-conformance.mjs";
+export { judgeObject, verdictSeverity, VERDICT_RANK } from "./hosted/judge.mjs";
+export { loadSpine, resolveClaim } from "./hosted/spine.mjs";
+export { vaultRdsQuery, parseRdsRecords } from "./hosted/vault-exec.mjs";
+export { selfUpdate, applyCoreManifest, isNewer, sha256Hex } from "../update/self-update.mjs";

package/src/core/oracle/family-conformance.mjs

@@ -0,0 +1,83 @@
+// Generic, project-agnostic conformance oracle — the reference-mode counterpart to sibling-consensus'
+// consensus mode. Distilled from arkitect's `family-conformance-engine`: declare what CORRECT looks like
+// (a reference member OR the majority) and flag any diverger. One oracle replaces dozens of point-checks
+// and catches divergence nobody has named yet.
+//
+// Usage:
+//   const { findings } = await runFamilyConformance({ family, project, mode, referenceId });
+//   // findings: Array<{ member, expected, actual }> — raw divergences; the CALLER creates Finding objects.
+
+/**
+ * Run conformance checking over a family of members.
+ *
+ * @param {object} opts
+ * @param {Array<{path:string, [key:string]:any}>} opts.family   Members to compare; each must have `path`.
+ * @param {function(member): any}                  opts.project  Extracts a comparable fingerprint per member.
+ * @param {"reference"|"consensus"}                opts.mode     How to derive the expected fingerprint.
+ * @param {string}                                 [opts.referenceId]  (reference mode) path or id to use as truth.
+ * @returns {Promise<{findings: Array<{member,expected,actual}>, consensusOrReference: any}>}
+ */
+export async function runFamilyConformance({ family, project, mode, referenceId }) {
+  if (!Array.isArray(family) || family.length === 0) {
+    return { findings: [], consensusOrReference: null };
+  }
+
+  // Compute fingerprints for all members. `project` may be async.
+  const projected = await Promise.all(
+    family.map(async (member) => {
+      let fingerprint;
+      try {
+        fingerprint = await project(member);
+      } catch {
+        fingerprint = null;
+      }
+      return { member, fingerprint, key: JSON.stringify(fingerprint ?? null) };
+    }),
+  );
+
+  let expectedKey;
+  let consensusOrReference;
+
+  if (mode === "reference") {
+    // Find the reference member by `path` (or `.id` as fallback).
+    const ref = projected.find(
+      (p) => p.member.path === referenceId || p.member.id === referenceId,
+    );
+    if (!ref) {
+      // No reference found — cannot judge; return clean.
+      return { findings: [], consensusOrReference: null };
+    }
+    expectedKey = ref.key;
+    consensusOrReference = ref.fingerprint;
+  } else {
+    // Consensus: the most common fingerprint across the family.
+    const counts = new Map();
+    for (const p of projected) counts.set(p.key, (counts.get(p.key) || 0) + 1);
+    const [topKey] = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+    const topCount = counts.get(topKey);
+    // Only meaningful when a clear majority (> half) exists.
+    if (topCount <= projected.length / 2) {
+      return { findings: [], consensusOrReference: null };
+    }
+    expectedKey = topKey;
+    consensusOrReference = JSON.parse(topKey);
+  }
+
+  const findings = [];
+  for (const p of projected) {
+    // In reference mode, skip the reference member itself.
+    if (mode === "reference") {
+      const isRef = p.member.path === referenceId || p.member.id === referenceId;
+      if (isRef) continue;
+    }
+    if (p.key !== expectedKey) {
+      findings.push({
+        member: p.member,
+        expected: JSON.parse(expectedKey),
+        actual: p.fingerprint,
+      });
+    }
+  }
+
+  return { findings, consensusOrReference };
+}

package/src/core/project-detect.mjs

@@ -0,0 +1,106 @@
+// THE portability primitive (distilled from arkitect's project-detect + `requires` gating).
+// Detect what a repo IS (languages / ecosystems / frameworks) from the filesystem, then let each check
+// declare `requires:{…}` and SKIP itself when the repo doesn't match. A generic CORE check declares
+// `requires:{}` (or omits it) → runs on ANY repo. This is what makes a check portable to a stranger's codebase.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, extname } from "node:path";
+
+const MANIFEST_ECOSYSTEM = {
+  "package.json": "npm",
+  "Cargo.toml": "cargo",
+  "go.mod": "go",
+  "requirements.txt": "pip",
+  "pyproject.toml": "pip",
+  "Gemfile": "gem",
+  "composer.json": "composer",
+  "pom.xml": "maven",
+  "build.gradle": "gradle",
+};
+const EXT_LANG = {
+  ".ts": "typescript",
+  ".tsx": "typescript",
+  ".js": "javascript",
+  ".jsx": "javascript",
+  ".mjs": "javascript",
+  ".cjs": "javascript",
+  ".py": "python",
+  ".rs": "rust",
+  ".go": "go",
+  ".rb": "ruby",
+  ".java": "java",
+  ".php": "php",
+  ".vue": "vue",
+  ".svelte": "svelte",
+};
+export const IGNORE_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  "cdk.out",
+  ".next",
+  ".nuxt",
+  "coverage",
+  "tmp",
+  ".turbo",
+  "vendor",
+  "target",
+]);
+
+export function detectProject(root) {
+  const ecosystems = new Set();
+  for (const [f, eco] of Object.entries(MANIFEST_ECOSYSTEM)) if (existsSync(join(root, f))) ecosystems.add(eco);
+
+  const frameworks = new Set();
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    if (deps.vue || deps.nuxt) frameworks.add("vue");
+    if (deps.react || deps.next) frameworks.add("react");
+    if (deps.svelte) frameworks.add("svelte");
+    if (deps.express || deps.fastify) frameworks.add("node-server");
+  } catch {
+    /* no/unreadable package.json — fine */
+  }
+
+  // Sample file extensions with a bounded walk (don't traverse the whole tree).
+  const languages = new Set();
+  let budget = 4000;
+  const walk = (dir) => {
+    if (budget <= 0) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (budget <= 0) return;
+      if (e.name.startsWith(".")) continue;
+      if (e.isDirectory()) {
+        if (!IGNORE_DIRS.has(e.name)) walk(join(dir, e.name));
+        continue;
+      }
+      budget--;
+      const lang = EXT_LANG[extname(e.name)];
+      if (lang) languages.add(lang);
+    }
+  };
+  walk(root);
+
+  return { root, languages: [...languages], ecosystems: [...ecosystems], frameworks: [...frameworks] };
+}
+
+// A check runs only if every dimension it requires is satisfied. Empty/absent `requires` ⇒ always runs.
+export function checkAppliesToProject(requires, project) {
+  if (!requires) return true;
+  const ok = (key) => {
+    const need = requires[key];
+    if (!need || need.length === 0) return true;
+    const have = project[key] || [];
+    return need.some((v) => have.includes(v));
+  };
+  return ok("languages") && ok("ecosystems") && ok("frameworks");
+}