@awak-app/simy-cli 0.3.3 → 0.4.0

package/src/sqm/bundle-store.js

@@ -0,0 +1,249 @@
+import { createHash, createPublicKey } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { verifyBundleIntegrity } from "./canonical.js";
+import { validateKnowledgeBundle } from "./validation.js";
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+export const SQM_BUNDLE_FETCH_TIMEOUT_MS = 15_000;
+
+export async function loadKnowledgeBundle({
+  repository,
+  cliVersion,
+  endpoint = process.env.SIMY_SQM_BUNDLE_URL,
+  token = process.env.SIMY_SQM_TOKEN || process.env.SIMY_ACCESS_TOKEN,
+  accountId = process.env.SIMY_SQM_ACCOUNT_ID || (token ? `token:${createHash("sha256").update(token).digest("hex")}` : "anonymous"),
+  organizationId = process.env.SIMY_SQM_ORGANIZATION_ID,
+  cacheRoot = process.env.SIMY_SQM_CACHE_DIR || path.join(process.env.SIMY_HOME?.trim() || path.join(homedir(), ".simy"), "sqm"),
+  ttlMs = numberEnv("SIMY_SQM_CACHE_TTL_MS", DEFAULT_TTL_MS),
+  offline = false,
+  refresh = false,
+  fetchImpl = globalThis.fetch,
+  now = Date.now(),
+  publicKeys = publicKeysFromEnvironment(),
+}) {
+  if (!organizationId) {
+    return result(null, ["SQM organization identity is unavailable; shadow checks were skipped."], "unavailable");
+  }
+  const cacheIdentity = normalizedCacheIdentity({ endpoint, accountId, organizationId, repository });
+  const location = cacheLocation(cacheRoot, cacheIdentity);
+  const validation = { cliVersion, publicKeys, organizationId };
+  const cached = await readVerifiedCache(location, validation, cacheIdentity);
+  const fresh =
+    cached &&
+    now - cached.fetchedAt < ttlMs &&
+    Date.parse(cached.bundle.expires_at) > now;
+  if (!offline && endpoint && (!fresh || refresh)) {
+    try {
+      const fetched = await fetchBundle({ endpoint, repository, cliVersion, token, organizationId, etag: cached?.etag, fetchImpl });
+      if (fetched.notModified) {
+        if (!cached) throw new Error("SQM Cloud returned 304 without a verified local bundle.");
+        if (Date.parse(cached.bundle.expires_at) <= now) throw nonFallbackError("SQM Cloud returned 304 for an expired knowledge bundle.");
+        await writeMetadata(location, { ...cached.metadata, fetched_at: new Date(now).toISOString(), etag: fetched.etag || cached.etag });
+        return result(cached.bundle, [], "cache_revalidated");
+      }
+      const discoveredTrust = signingTrustForFetch({
+        bundle: fetched.bundle,
+        endpoint,
+        publicKeys,
+        signingKeyId: fetched.signingKeyId,
+        signingPublicKey: fetched.signingPublicKey,
+      });
+      const bundle = verifyAndValidate(fetched.bundle, {
+        ...validation,
+        publicKeys: discoveredTrust.publicKeys,
+      });
+      if (Date.parse(bundle.expires_at) <= now) {
+        throw nonFallbackError("SQM Cloud returned an expired knowledge bundle.");
+      }
+      if (fetched.etag && unquote(fetched.etag) !== bundle.integrity.digest) throw nonFallbackError("SQM response ETag does not match the bundle digest.");
+      await writeCache(location, bundle, {
+        ...cacheIdentity,
+        fetched_at: new Date(now).toISOString(),
+        etag: fetched.etag || `\"${bundle.integrity.digest}\"`,
+        signing_key_id: discoveredTrust.signingKeyId,
+        signing_public_key: discoveredTrust.signingPublicKey,
+      });
+      return result(bundle, [], "cloud");
+    } catch (error) {
+      if (error?.fallbackAllowed !== false && cached && Date.parse(cached.bundle.expires_at) > now) return result(cached.bundle, [`SQM Cloud unavailable; using last verified bundle: ${message(error)}`], "stale_cache");
+      return result(null, [`SQM knowledge could not be used; shadow checks were skipped: ${message(error)}`], "unavailable");
+    }
+  }
+  if (cached) {
+    if (Date.parse(cached.bundle.expires_at) <= now) return result(null, ["The cached SQM knowledge bundle is expired; shadow checks were skipped."], "unavailable");
+    const warnings = [];
+    if (offline) warnings.push("SQM is offline; using the last verified knowledge bundle.");
+    else if (!endpoint) warnings.push("SQM Cloud endpoint is not configured; using the last verified knowledge bundle.");
+    return result(cached.bundle, warnings, fresh ? "cache" : "stale_cache");
+  }
+  const reason = offline ? "offline mode" : "SQM Cloud endpoint is not configured";
+  return result(null, [`SQM has no verified cache (${reason}); shadow checks were skipped.`], "unavailable");
+}
+
+export function verifyAndValidate(bundle, { cliVersion, publicKeys, organizationId } = {}) {
+  try { validateKnowledgeBundle(bundle, { cliVersion }); } catch (error) { throw nonFallbackError(message(error), error); }
+  if (organizationId && bundle.organization_id !== organizationId) throw nonFallbackError(`SQM bundle organization mismatch: expected ${organizationId}.`);
+  for (const module of bundle.modules) {
+    if (module.scope.visibility === "organization" && module.scope.organization_id !== bundle.organization_id) throw nonFallbackError(`SQM module ${module.id} is scoped to a different organization.`);
+  }
+  const keyId = bundle.integrity.key_id;
+  const key = publicKeys.get(keyId);
+  if (!key) throw nonFallbackError(`No trusted SQM public key is configured for ${keyId}.`);
+  try { verifyBundleIntegrity(bundle, key); } catch (error) { throw nonFallbackError(message(error), error); }
+  return bundle;
+}
+
+export function publicKeysFromEnvironment(env = process.env) {
+  const keys = new Map();
+  if (env.SIMY_SQM_PUBLIC_KEYS_JSON) {
+    let parsed;
+    try { parsed = JSON.parse(env.SIMY_SQM_PUBLIC_KEYS_JSON); } catch { throw new Error("SIMY_SQM_PUBLIC_KEYS_JSON is not valid JSON."); }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("SIMY_SQM_PUBLIC_KEYS_JSON must be an object keyed by key ID.");
+    for (const [id, value] of Object.entries(parsed)) keys.set(id, parsePublicKey(value));
+  }
+  if (env.SIMY_SQM_PUBLIC_KEY && env.SIMY_SQM_KEY_ID) keys.set(env.SIMY_SQM_KEY_ID, parsePublicKey(env.SIMY_SQM_PUBLIC_KEY));
+  return keys;
+}
+
+function parsePublicKey(value) {
+  const text = String(value || "").replace(/\\n/g, "\n").trim();
+  if (text.startsWith("-----BEGIN")) return createPublicKey(text);
+  const raw = Buffer.from(text, "base64");
+  if (raw.length === 32) {
+    const prefix = Buffer.from("302a300506032b6570032100", "hex");
+    return createPublicKey({ key: Buffer.concat([prefix, raw]), format: "der", type: "spki" });
+  }
+  return createPublicKey({ key: raw, format: "der", type: "spki" });
+}
+
+function signingTrustForFetch({ bundle, endpoint, publicKeys, signingKeyId, signingPublicKey }) {
+  const keyId = bundle?.integrity?.key_id;
+  if (publicKeys.has(keyId)) {
+    return { publicKeys, signingKeyId: null, signingPublicKey: null };
+  }
+  if (!trustedDiscoveryEndpoint(endpoint)) {
+    throw nonFallbackError("SQM signing-key discovery requires authenticated HTTPS or loopback.");
+  }
+  if (!signingKeyId || signingKeyId !== keyId || !signingPublicKey) {
+    throw nonFallbackError(`SQM Cloud did not provide the trusted public key for ${keyId}.`);
+  }
+  const discovered = new Map(publicKeys);
+  try {
+    discovered.set(keyId, parsePublicKey(signingPublicKey));
+  } catch (error) {
+    throw nonFallbackError(`SQM Cloud returned an invalid public key for ${keyId}.`, error);
+  }
+  return {
+    publicKeys: discovered,
+    signingKeyId,
+    signingPublicKey: String(signingPublicKey).trim(),
+  };
+}
+
+function trustedDiscoveryEndpoint(endpoint) {
+  const url = new URL(endpoint);
+  return url.protocol === "https:" ||
+    (url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname));
+}
+
+async function fetchBundle({ endpoint, repository, cliVersion, token, organizationId, etag, fetchImpl }) {
+  const url = new URL(endpoint);
+  url.searchParams.set("repository", repository);
+  url.searchParams.set("cli_version", cliVersion);
+  const headers = { Accept: "application/json" };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  if (organizationId) headers["x-simy-org-id"] = organizationId;
+  if (etag) headers["If-None-Match"] = etag;
+  const response = await fetchImpl(url, {
+    headers,
+    signal: AbortSignal.timeout(SQM_BUNDLE_FETCH_TIMEOUT_MS),
+  });
+  const responseEtag = response.headers?.get?.("etag") || null;
+  const signingKeyId = response.headers?.get?.("x-simy-sqm-key-id") || null;
+  const signingPublicKey = response.headers?.get?.("x-simy-sqm-public-key") || null;
+  if (response.status === 304) {
+    return { notModified: true, etag: responseEtag, signingKeyId, signingPublicKey };
+  }
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    const error = new Error(`SQM Cloud returned HTTP ${response.status}${body ? `: ${body.slice(0, 300)}` : ""}.`);
+    error.fallbackAllowed = response.status >= 500 && response.status <= 599;
+    throw error;
+  }
+  try {
+    return {
+      notModified: false,
+      etag: responseEtag,
+      signingKeyId,
+      signingPublicKey,
+      bundle: await response.json(),
+    };
+  } catch (error) {
+    throw nonFallbackError("SQM Cloud returned an invalid JSON knowledge bundle.", error);
+  }
+}
+
+async function readVerifiedCache(location, options, identity) {
+  try {
+    const [bundleRaw, metadataRaw] = await Promise.all([readFile(location.bundle, "utf8"), readFile(location.metadata, "utf8")]);
+    const metadata = JSON.parse(metadataRaw);
+    for (const key of ["endpoint", "account_id", "organization_id", "repository"]) if (metadata[key] !== identity[key]) throw new Error("SQM cache identity does not match the current tenant context.");
+    const publicKeys = new Map(options.publicKeys);
+    if (metadata.signing_key_id && metadata.signing_public_key && !publicKeys.has(metadata.signing_key_id)) {
+      publicKeys.set(metadata.signing_key_id, parsePublicKey(metadata.signing_public_key));
+    }
+    const bundle = verifyAndValidate(JSON.parse(bundleRaw), { ...options, publicKeys });
+    if (metadata.digest !== bundle.integrity.digest || metadata.bundle_id !== bundle.bundle_id || metadata.version !== bundle.version) throw new Error("SQM cache metadata does not match its bundle.");
+    if (metadata.signing_key_id && metadata.signing_key_id !== bundle.integrity.key_id) throw new Error("SQM cache signing key does not match its bundle.");
+    return { bundle, metadata, etag: metadata.etag || null, fetchedAt: Date.parse(metadata.fetched_at) || 0 };
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(location, bundle, metadata) {
+  await mkdir(location.directory, { recursive: true, mode: 0o700 });
+  await atomicWrite(location.bundle, `${JSON.stringify(bundle)}\n`);
+  await writeMetadata(location, { ...metadata, bundle_id: bundle.bundle_id, version: bundle.version, digest: bundle.integrity.digest, verified_at: new Date().toISOString() });
+}
+
+async function writeMetadata(location, metadata) {
+  await mkdir(location.directory, { recursive: true, mode: 0o700 });
+  await atomicWrite(location.metadata, `${JSON.stringify(metadata)}\n`);
+}
+
+async function atomicWrite(target, content) {
+  const temporary = `${target}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+  await writeFile(temporary, content, { encoding: "utf8", mode: 0o600 });
+  await rename(temporary, target);
+}
+
+function cacheLocation(root, identity) {
+  const id = createHash("sha256").update(JSON.stringify(identity)).digest("hex");
+  const directory = path.join(root, id);
+  return { directory, bundle: path.join(directory, "bundle.json"), metadata: path.join(directory, "metadata.json") };
+}
+
+function normalizedCacheIdentity({ endpoint, accountId, organizationId, repository }) {
+  let normalizedEndpoint = "unconfigured";
+  if (endpoint) {
+    const url = new URL(endpoint);
+    url.hash = "";
+    normalizedEndpoint = url.href;
+  }
+  return { endpoint: normalizedEndpoint, account_id: String(accountId || "anonymous"), organization_id: organizationId ? String(organizationId) : null, repository: String(repository).toLowerCase() };
+}
+
+function nonFallbackError(message, cause) {
+  const error = new Error(message, { cause });
+  error.fallbackAllowed = false;
+  return error;
+}
+
+function result(bundle, warnings, source) { return { bundle, warnings, source }; }
+function message(error) { return error instanceof Error ? error.message : String(error); }
+function numberEnv(name, fallback) { const parsed = Number(process.env[name]); return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback; }
+function unquote(value) { return String(value).replace(/^W\//, "").replace(/^\"|\"$/g, ""); }

package/src/sqm/canonical.js

@@ -0,0 +1,45 @@
+import { createHash, verify } from "node:crypto";
+
+export function canonicalize(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("JCS does not allow non-finite numbers.");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`)
+      .join(",")}}`;
+  }
+  throw new TypeError(`JCS does not allow ${typeof value} values.`);
+}
+
+export function bundlePayloadBytes(bundle) {
+  const { integrity: _integrity, ...payload } = bundle;
+  return Buffer.from(canonicalize(payload), "utf8");
+}
+
+export function bundleDigest(bundle) {
+  return createHash("sha256").update(bundlePayloadBytes(bundle)).digest();
+}
+
+export function verifyBundleIntegrity(bundle, publicKey) {
+  const digest = bundleDigest(bundle);
+  const expected = `sha256:${digest.toString("hex")}`;
+  if (bundle?.integrity?.digest !== expected) {
+    throw new Error(`SQM bundle digest mismatch: expected ${expected}.`);
+  }
+  const encoded = String(bundle?.integrity?.signature || "");
+  if (!/^[A-Za-z0-9+/]+$/.test(encoded)) {
+    throw new Error("SQM bundle signature is not valid base64.");
+  }
+  const signature = Buffer.from(encoded, "base64");
+  if (signature.length !== 64 || !verify(null, digest, publicKey, signature)) {
+    throw new Error("SQM bundle Ed25519 signature verification failed.");
+  }
+  return expected;
+}

package/src/sqm/checkers.js

@@ -0,0 +1,299 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_FILES_PER_PATTERN = 5_000;
+
+export async function executeKnowledgeBundle(bundle, repository) {
+  return (await evaluateKnowledgeBundle(bundle, repository)).findings;
+}
+
+export async function evaluateKnowledgeBundle(bundle, repository) {
+  const findings = [];
+  const modules = [];
+  for (const module of bundle.modules) {
+    if (["candidate", "retired"].includes(module.lifecycle.status)) continue;
+    if (!moduleApplies(module, repository.repository)) continue;
+    if (!(await matchModule(module, repository))) continue;
+    const exceptions = activeExceptionPatterns(module);
+    const ruleResults = [];
+    for (const rule of module.detection.checks) {
+      const violations = await executeRule(rule, repository);
+      const accepted = violations.filter((violation) => !exceptions.some((glob) => globMatches(glob, violation.file)));
+      ruleResults.push({ rule_id: rule.id, status: accepted.length ? "failed" : "passed", finding_count: accepted.length });
+      for (const violation of accepted) {
+        const evidenceHash = sha256(violation.evidence);
+        const findingId = sha256([bundle.integrity.digest, module.id, rule.id, violation.file || "repository", violation.line ?? "", violation.side || "", evidenceHash].join("\0"));
+        const assurance = assuranceContext(module, rule.id);
+        findings.push({
+          finding_id: `sqm:${findingId}`,
+          module_id: module.id,
+          module_version: module.version,
+          rule_id: rule.id,
+          lifecycle: module.lifecycle.status,
+          severity: module.lifecycle.severity,
+          message: rule.message,
+          invariant: module.invariant.statement,
+          remediation: module.invariant.remediation ?? null,
+          incident_refs: [...module.incident_refs],
+          file: violation.file,
+          line: violation.line ?? null,
+          side: violation.side ?? null,
+          evidence_hash: `sha256:${evidenceHash}`,
+          bundle_id: bundle.bundle_id,
+          bundle_version: bundle.version,
+          bundle_digest: bundle.integrity.digest,
+          state_model_ids: assurance.state_model_ids,
+          transition_ids: assurance.transition_ids,
+          stressor_ids: assurance.stressor_ids,
+          strength_ids: assurance.strength_ids,
+          scenario_ids: assurance.scenario_ids,
+        });
+      }
+    }
+    modules.push(evaluateAssurance(module, ruleResults));
+  }
+  return { findings, modules };
+}
+
+function evaluateAssurance(module, ruleResults) {
+  const failed = new Set(ruleResults.filter((result) => result.status === "failed").map((result) => result.rule_id));
+  const assurance = module.assurance;
+  if (!assurance) {
+    return {
+      module_id: module.id,
+      module_version: module.version,
+      lifecycle: module.lifecycle.status,
+      severity: module.lifecycle.severity,
+      rule_results: ruleResults,
+      state_models: [],
+      stressors: [],
+      strengths: [],
+      scenarios: [],
+    };
+  }
+  const stressors = assurance.stressors.map((stressor) => ({
+    id: stressor.id,
+    status: stressor.activation_check_refs.some((ref) => failed.has(ref)) ? "activated" : "not_activated",
+    check_refs: [...stressor.activation_check_refs],
+  }));
+  const strengths = assurance.strengths.map((strength) => ({
+    id: strength.id,
+    status: strength.check_refs.some((ref) => failed.has(ref)) ? "failed" : "passed",
+    check_refs: [...strength.check_refs],
+  }));
+  const strengthStatus = new Map(strengths.map((strength) => [strength.id, strength.status]));
+  const scenarios = assurance.scenarios.map((scenario) => {
+    let status = scenario.execution_requirement;
+    if (scenario.execution_requirement === "local") {
+      const checkFailed = scenario.check_refs.some((ref) => failed.has(ref));
+      const strengthFailed = scenario.expected_strength_refs.some((ref) => strengthStatus.get(ref) === "failed");
+      status = checkFailed || strengthFailed ? "failed" : "passed";
+    }
+    return {
+      id: scenario.id,
+      state_model_id: scenario.state_model_id,
+      transition_id: scenario.transition_id,
+      status,
+      stressor_refs: [...scenario.stressor_refs],
+      expected_strength_refs: [...scenario.expected_strength_refs],
+      check_refs: [...scenario.check_refs],
+    };
+  });
+  const scenarioStatus = new Map(scenarios.map((scenario) => [scenario.id, scenario.status]));
+  const stateModels = assurance.state_models.map((model) => ({
+    id: model.id,
+    version: model.version,
+    transitions: model.transitions.map((transition) => ({
+      id: transition.id,
+      from: transition.from,
+      event: transition.event,
+      to: transition.to,
+      status: transition.scenario_refs.some((ref) => scenarioStatus.get(ref) === "failed") ? "failed" :
+        transition.scenario_refs.some((ref) => ["requires_human", "requires_post_deploy"].includes(scenarioStatus.get(ref))) ? "skipped" : "passed",
+      scenario_refs: [...transition.scenario_refs],
+    })),
+  }));
+  return {
+    module_id: module.id,
+    module_version: module.version,
+    lifecycle: module.lifecycle.status,
+    severity: module.lifecycle.severity,
+    rule_results: ruleResults,
+    state_models: stateModels,
+    stressors,
+    strengths,
+    scenarios,
+  };
+}
+
+function assuranceContext(module, ruleId) {
+  const assurance = module.assurance;
+  if (!assurance) return { state_model_ids: [], transition_ids: [], stressor_ids: [], strength_ids: [], scenario_ids: [] };
+  const stressorIds = assurance.stressors.filter((item) => item.activation_check_refs.includes(ruleId)).map((item) => item.id);
+  const strengthIds = assurance.strengths.filter((item) => item.check_refs.includes(ruleId)).map((item) => item.id);
+  const scenarios = assurance.scenarios.filter((item) => item.check_refs.includes(ruleId) || item.stressor_refs.some((id) => stressorIds.includes(id)) || item.expected_strength_refs.some((id) => strengthIds.includes(id)));
+  const scenarioIds = scenarios.map((item) => item.id);
+  const stateModelIds = [...new Set(scenarios.map((item) => item.state_model_id))];
+  const transitionIds = [...new Set(scenarios.map((item) => item.transition_id))];
+  return { state_model_ids: stateModelIds, transition_ids: transitionIds, stressor_ids: stressorIds, strength_ids: strengthIds, scenario_ids: scenarioIds };
+}
+
+function moduleApplies(module, repository) {
+  const scoped = module.scope.repositories;
+  return !scoped?.length || scoped.some((item) => item.toLowerCase() === repository.toLowerCase());
+}
+
+async function matchModule(module, repository) {
+  for (const matcher of module.detection.matchers) {
+    if (!(await match(matcher, repository))) return false;
+  }
+  return true;
+}
+
+async function match(matcher, repository) {
+  const changed = repository.diff.filter((file) => matchesAny(matcher.paths, file.path));
+  if (matcher.type === "changed_path") return changed.length > 0;
+  const regex = safeRegex(matcher.pattern);
+  if (matcher.type === "diff_regex" || matcher.type === "reference") {
+    return changed.some((file) => file.lines.some((line) => sideMatches(matcher.side, line.side) && test(regex, line.text)));
+  }
+  if (matcher.type === "content_regex") {
+    const files = selectPaths(repository.paths, matcher.paths);
+    for (const file of files) if (test(regex, await readText(repository.root, file))) return true;
+  }
+  return false;
+}
+
+async function executeRule(rule, repository) {
+  switch (rule.type) {
+    case "diff_regex":
+      return diffRegex(rule, repository);
+    case "path_presence":
+      return pathPresence(rule, repository);
+    case "content_regex":
+      return contentRegex(rule, repository);
+    case "reference_definition":
+      return referenceDefinition(rule, repository);
+    default:
+      throw new Error(`Unsupported SQM checker type: ${rule.type}`);
+  }
+}
+
+function diffRegex(rule, repository) {
+  const regex = safeRegex(rule.pattern);
+  const matches = [];
+  for (const file of repository.diff.filter((item) => matchesAny(rule.paths || ["**"], item.path))) {
+    for (const line of file.lines) if (sideMatches(rule.side, line.side) && test(regex, line.text)) matches.push({ file: file.path, line: line.line, side: line.side, evidence: `${line.side}: ${line.text}` });
+  }
+  if (rule.expect === "present") return matches.length ? [] : [{ file: null, evidence: "Required diff pattern was not present." }];
+  return matches;
+}
+
+function pathPresence(rule, repository) {
+  const matches = selectPaths(repository.paths, rule.paths || []);
+  if (rule.expect === "present") return matches.length ? [] : [{ file: null, evidence: `Required repository path was not present: ${(rule.paths || []).join(", ")}` }];
+  return matches.map((file) => ({ file, evidence: `Forbidden repository path is present: ${file}` }));
+}
+
+async function contentRegex(rule, repository) {
+  const regex = safeRegex(rule.pattern);
+  const matches = [];
+  for (const file of selectPaths(repository.paths, rule.paths || ["**"])) {
+    const content = await readText(repository.root, file);
+    for (const result of matchLines(regex, content)) matches.push({ file, line: result.line, evidence: truncate(result.text) });
+  }
+  if (rule.expect === "present") return matches.length ? [] : [{ file: null, evidence: "Required content pattern was not present." }];
+  return matches;
+}
+
+async function referenceDefinition(rule, repository) {
+  const regex = safeRegex(rule.pattern);
+  const references = [];
+  for (const file of repository.diff.filter((item) => matchesAny(rule.paths || ["**"], item.path))) {
+    for (const line of file.lines.filter((item) => item.side === "added")) {
+      for (const match of allMatches(regex, line.text)) references.push({ value: match[1] || match[0], file: file.path, line: line.line });
+    }
+  }
+  const definitions = await Promise.all(selectPaths(repository.paths, rule.definition_paths || []).map((file) => readText(repository.root, file)));
+  return references
+    .filter((reference) => !definitions.some((content) => content.includes(reference.value)))
+    .map((reference) => ({ file: reference.file, line: reference.line, evidence: `Reference ${reference.value} has no definition in ${(rule.definition_paths || []).join(", ")}.` }));
+}
+
+function activeExceptionPatterns(module) {
+  const now = Date.now();
+  return (module.detection.exceptions || [])
+    .filter((item) => !item.expires_at || Date.parse(item.expires_at) > now)
+    .flatMap((item) => item.paths);
+}
+
+function selectPaths(paths, globs) {
+  return paths.filter((file) => matchesAny(globs, file)).slice(0, MAX_FILES_PER_PATTERN);
+}
+
+function matchesAny(globs, file) {
+  return globs.some((glob) => globMatches(glob, file));
+}
+
+export function globMatches(glob, file) {
+  const value = String(glob);
+  let source = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (character === "*" && value[index + 1] === "*" && value[index + 2] === "/") {
+      source += "(?:.*/)?";
+      index += 2;
+    } else if (character === "*" && value[index + 1] === "*") {
+      source += ".*";
+      index += 1;
+    } else if (character === "*") source += "[^/]*";
+    else if (character === "?") source += "[^/]";
+    else source += /[.+^${}()|[\]\\]/.test(character) ? `\\${character}` : character;
+  }
+  return new RegExp(`^${source}$`).test(file);
+}
+
+function safeRegex(pattern) {
+  let source = String(pattern || "");
+  let flags = "g";
+  const leadingFlags = source.match(/^\(\?([ims]+)\)/);
+  if (leadingFlags) {
+    flags += [...new Set(leadingFlags[1])].join("");
+    source = source.slice(leadingFlags[0].length);
+  }
+  if (source.length > 2_000 || /\\[1-9]|\(\?[=!<]|\([^)]*[+*][^)]*\)[+*{]/.test(source)) {
+    throw new Error("SQM regex uses an unsupported potentially unsafe construct.");
+  }
+  if (/\(\?[ims-]/.test(source)) {
+    throw new Error("SQM regex flags must appear once at the start of the pattern.");
+  }
+  return new RegExp(source, flags);
+}
+
+function test(regex, text) { regex.lastIndex = 0; return regex.test(text); }
+function allMatches(regex, text) { regex.lastIndex = 0; return [...text.matchAll(regex)]; }
+function sideMatches(expected, actual) { return !expected || expected === "either" || expected === actual; }
+function truncate(value) { const text = String(value); return text.length > 300 ? `${text.slice(0, 297)}...` : text; }
+function sha256(value) { return createHash("sha256").update(String(value)).digest("hex"); }
+
+function matchLines(regex, content) {
+  const results = [];
+  for (const [index, line] of content.split(/\r?\n/).entries()) if (test(regex, line)) results.push({ line: index + 1, text: line });
+  return results;
+}
+
+async function readText(root, relative) {
+  const resolved = path.resolve(root, relative);
+  if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) throw new Error("SQM path escaped the repository root.");
+  try {
+    const fileStat = await lstat(resolved);
+    if (!fileStat.isFile() || fileStat.isSymbolicLink()) return "";
+    const buffer = await readFile(resolved);
+    if (buffer.length > MAX_FILE_BYTES || buffer.includes(0)) return "";
+    return buffer.toString("utf8");
+  } catch {
+    return "";
+  }
+}