connections-arkitect 0.3.4

package/src/core/sarif.mjs

@@ -0,0 +1,63 @@
+// SARIF 2.1.0 emitter — converts architect run results into the Static Analysis Results Interchange Format
+// understood by GitHub Code Scanning, VS Code, and CI toolchains. Zero external dependencies.
+// Spec: https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+
+/**
+ * Map an architect finding severity to a SARIF level.
+ * SARIF levels: "error" | "warning" | "note" | "none"
+ */
+function toSarifLevel(severity) {
+  if (severity === "error") return "error";
+  if (severity === "warning") return "warning";
+  return "note"; // info → note
+}
+
+/**
+ * Convert a flat array of per-check run results (as returned by runner.runAudits) into a SARIF 2.1.0 object.
+ *
+ * @param {Array<{id:string, audit:{id:string,title:string}, findings?:Array, status:string}>} results
+ * @returns {object}  SARIF 2.1.0 document
+ */
+export function toSarif(results) {
+  // Collect unique rule definitions (one per unique check id that produced findings).
+  const rulesById = new Map();
+  const sarifResults = [];
+
+  for (const r of results) {
+    const findings = r.findings || [];
+    if (!findings.length) continue;
+
+    const ruleId = r.id;
+    if (!rulesById.has(ruleId)) {
+      rulesById.set(ruleId, { id: ruleId, name: r.audit?.title ?? ruleId, shortDescription: { text: r.audit?.title ?? ruleId } });
+    }
+
+    for (const f of findings) {
+      const result = { ruleId, level: toSarifLevel(f.severity), message: { text: f.message || f.title || ruleId } };
+
+      // Physical location — only when we have a file reference.
+      if (f.file) {
+        const loc = {
+          physicalLocation: {
+            artifactLocation: {
+              // SARIF URIs use forward-slash separators and are typically relative.
+              uri: f.file.replace(/\\/g, "/"),
+            },
+          },
+        };
+        if (typeof f.line === "number" && f.line > 0) {
+          loc.physicalLocation.region = { startLine: f.line };
+        }
+        result.locations = [loc];
+      }
+
+      sarifResults.push(result);
+    }
+  }
+
+  return {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [{ tool: { driver: { name: "@connections/architect", rules: [...rulesById.values()] } }, results: sarifResults }],
+  };
+}

package/src/engines/surface/surface-size-coverage-engine.mjs

@@ -0,0 +1,199 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { countFileLines, walkFiles } from "@lunawerx/arkitect-core/core/files";
+
+export const SURFACE_SIZE_COVERAGE_DEFAULTS = {
+  title: "Surface Size And Coverage Audit",
+  roots: ["services/main/web/src"],
+  extensions: [".css", ".ts", ".tsx", ".vue"],
+  warnLines: 700,
+  reviewLines: 1200,
+  highRiskLines: 2000,
+  includeSizeQueue: true,
+  failOnSizeRegressions: true,
+  growthLines: 100,
+  top: 35,
+  outputPath: "tmp/audits/SURFACE_SIZE_COVERAGE_AUDIT.md",
+  coverageTerms: [],
+  coverageColumnLabel: "Covered by tests",
+  testFilePattern: "\\.spec\\.ts$",
+  largestFilesHeading: "Largest Surface Files",
+  oversizedLabel: "Surface files",
+  attentionQueueLabel: "Files in attention queue",
+  policyNote:
+    "Line count is a maintainability heuristic, not a universal safety rule. Use the queue to find files that may mix responsibilities; strict failures come from size regressions or missing coverage terms.",
+};
+
+export async function runSurfaceSizeCoverageAudit(context) {
+  const checkConfig = applyLegacyArgs(context.checkConfig, context.checkArgs);
+  const files = (
+    await Promise.all(
+      (
+        await walkFiles({
+          root: context.root,
+          roots: checkConfig.roots,
+          extensions: checkConfig.extensions,
+          skipSegments: checkConfig.skipSegments,
+        })
+      ).map(async (filePath) => ({ path: filePath, lines: await countFileLines(context.root, filePath) })),
+    )
+  ).sort((left, right) => right.lines - left.lines);
+
+  const oversized = checkConfig.includeSizeQueue ? files.filter((file) => file.lines >= checkConfig.warnLines) : [];
+  const testFilePattern = new RegExp(checkConfig.testFilePattern);
+  const testFiles = files.filter((file) => testFilePattern.test(file.path));
+  const testText = (await Promise.all(testFiles.map((file) => fs.readFile(path.resolve(context.root, file.path), "utf8")))).join("\n");
+
+  const coverage = checkConfig.coverageTerms.map((term) => ({
+    label: term.label,
+    covered: new RegExp(term.pattern, term.flags ?? "i").test(testText),
+  }));
+  const uncovered = coverage.filter((item) => !item.covered);
+  const regressions =
+    context.baseline?.files && checkConfig.includeSizeQueue && checkConfig.failOnSizeRegressions
+      ? oversized.filter((file) => {
+          const baselineLines = context.baseline.files?.[file.path]?.lines;
+          if (baselineLines === undefined) {
+            return true;
+          }
+          return file.lines - baselineLines >= checkConfig.growthLines;
+        })
+      : [];
+  const sizeBands = buildSizeBands(oversized, checkConfig);
+
+  const baselineDocument = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    includeSizeQueue: checkConfig.includeSizeQueue,
+    failOnSizeRegressions: checkConfig.failOnSizeRegressions,
+    warnLines: checkConfig.warnLines,
+    reviewLines: checkConfig.reviewLines,
+    highRiskLines: checkConfig.highRiskLines,
+    growthLines: checkConfig.growthLines,
+    files: Object.fromEntries(oversized.map((file) => [file.path, { lines: file.lines }])),
+    coverage: Object.fromEntries(coverage.map((item) => [item.label, item.covered])),
+  };
+
+  const report = renderMarkdown({
+    baseline: context.baseline,
+    checkConfig,
+    coverage,
+    files,
+    oversized,
+    regressions,
+    sizeBands,
+    testFiles,
+    uncovered,
+  });
+
+  return {
+    baselineDocument,
+    failed: regressions.length > 0 || uncovered.length > 0,
+    jsonPayload: { files, oversized, testFiles, coverage, uncovered, regressions },
+    outputPath: checkConfig.outputPath,
+    report,
+  };
+}
+
+function readArg(args, name, fallback) {
+  const prefix = `${name}=`;
+  const value = args.find((arg) => arg.startsWith(prefix));
+  return value ? value.slice(prefix.length) : fallback;
+}
+
+function readBooleanArg(args, name, fallback) {
+  const rawValue = readArg(args, name, fallback);
+  if (typeof rawValue === "boolean") {
+    return rawValue;
+  }
+
+  return String(rawValue).toLowerCase() !== "false";
+}
+
+function applyLegacyArgs(config, args) {
+  return {
+    ...config,
+    includeSizeQueue: readBooleanArg(args, "--include-size-queue", config.includeSizeQueue),
+    failOnSizeRegressions: readBooleanArg(args, "--fail-on-size-regressions", config.failOnSizeRegressions),
+    warnLines: Number(readArg(args, "--warn-lines", config.warnLines)),
+    reviewLines: Number(readArg(args, "--review-lines", config.reviewLines)),
+    highRiskLines: Number(readArg(args, "--high-risk-lines", config.highRiskLines)),
+    growthLines: Number(readArg(args, "--growth-lines", config.growthLines)),
+    top: Number(readArg(args, "--top", config.top)),
+    outputPath: readArg(args, "--output", config.outputPath),
+  };
+}
+
+function buildSizeBands(oversized, checkConfig) {
+  const highRisk = oversized.filter((file) => file.lines >= checkConfig.highRiskLines);
+  const review = oversized.filter((file) => file.lines >= checkConfig.reviewLines && file.lines < checkConfig.highRiskLines);
+  const attention = oversized.filter((file) => file.lines >= checkConfig.warnLines && file.lines < checkConfig.reviewLines);
+
+  return { attention, review, highRisk };
+}
+
+function sizeBandFor(lines, checkConfig) {
+  if (lines >= checkConfig.highRiskLines) {
+    return "high-risk";
+  }
+
+  if (lines >= checkConfig.reviewLines) {
+    return "review";
+  }
+
+  if (lines >= checkConfig.warnLines) {
+    return "attention";
+  }
+
+  return "below threshold";
+}
+
+function renderMarkdown({ baseline, checkConfig, coverage, files, oversized, regressions, sizeBands, testFiles, uncovered }) {
+  const lines = [
+    `# ${checkConfig.title}`,
+    "",
+    `- Files scanned: ${files.length}`,
+    `- Test files scanned: ${testFiles.length}`,
+    `- Coverage terms checked: ${coverage.length}`,
+    `- Missing coverage terms: ${uncovered.length}`,
+  ];
+
+  if (checkConfig.includeSizeQueue) {
+    lines.push(
+      `- ${checkConfig.attentionQueueLabel} (>= ${checkConfig.warnLines} lines): ${oversized.length}`,
+      `- Attention band (${checkConfig.warnLines}-${checkConfig.reviewLines - 1} lines): ${sizeBands.attention.length}`,
+      `- Review band (${checkConfig.reviewLines}-${checkConfig.highRiskLines - 1} lines): ${sizeBands.review.length}`,
+      `- High-risk band (>= ${checkConfig.highRiskLines} lines): ${sizeBands.highRisk.length}`,
+      `- Size regressions: ${regressions.length}`,
+    );
+  }
+
+  lines.push("");
+
+  if (checkConfig.policyNote) {
+    lines.push("## Policy", "", checkConfig.policyNote, "");
+  }
+
+  if (checkConfig.includeSizeQueue && regressions.length > 0) {
+    lines.push("## Size Regressions", "");
+    for (const file of regressions) {
+      const baselineLines = baseline.files?.[file.path]?.lines ?? "new";
+      lines.push(`- ${file.path}: ${file.lines} lines (baseline: ${baselineLines})`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Coverage Terms", "", `| Term | ${checkConfig.coverageColumnLabel} |`, "| --- | --- |");
+  for (const item of coverage) {
+    lines.push(`| ${item.label} | ${item.covered ? "yes" : "no"} |`);
+  }
+
+  if (checkConfig.includeSizeQueue) {
+    lines.push("", `## ${checkConfig.largestFilesHeading}`, "", "| Lines | Band | File |", "| ---: | --- | --- |");
+    for (const file of files.slice(0, checkConfig.top)) {
+      lines.push(`| ${file.lines} | ${sizeBandFor(file.lines, checkConfig)} | \`${file.path}\` |`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}

package/src/update/self-update.mjs

@@ -0,0 +1,90 @@
+// Self-update — the Architect's pull-and-refresh channel, a direct mirror of the MCP loader.mjs
+// resilience ladder applied to the CORE. On launch (gated by config.update), fetch the published core
+// manifest from Connections, SHA-verify it, and swap the shipped core (src/core + src/checks) in place,
+// keeping a `.prev` for rollback. It NEVER writes outside core/+checks/, so your-checks/ and your config
+// stay yours and the core stays updatable underneath them — exactly the loader's "push to AWS, every
+// machine updates next run" property.
+import { createHash } from "node:crypto";
+import { writeFileSync, mkdirSync, rmSync, cpSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+export const DEFAULT_CORE_URL = "https://connections-architect-core-637560253023.s3.us-east-1.amazonaws.com";
+
+export function sha256Hex(s) {
+  return createHash("sha256").update(s).digest("hex");
+}
+
+// Strictly-newer semver-ish compare ("1.4.0" > "1.3.9").
+export function isNewer(a, b) {
+  const pa = String(a).split(".").map(Number);
+  const pb = String(b).split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x !== y) return x > y;
+  }
+  return false;
+}
+
+// A core manifest is { version, sha, files: { "core/finding.mjs": "<source>", "checks/code/x.mjs": "…" } }.
+// `sha` is sha256 of JSON.stringify(files). Apply it to <srcDir> (the package's src/), with a .prev backup
+// and rollback on any write error. Only ever writes under core/ + checks/.
+export function applyCoreManifest(manifest, srcDir) {
+  if (!manifest || typeof manifest.version !== "string" || !manifest.files || typeof manifest.files !== "object") {
+    throw new Error("invalid core manifest");
+  }
+  const got = sha256Hex(JSON.stringify(manifest.files));
+  if (manifest.sha && manifest.sha !== got) {
+    throw new Error(`core manifest SHA mismatch (want ${String(manifest.sha).slice(0, 12)}…, got ${got.slice(0, 12)}…)`);
+  }
+  const prev = srcDir + ".prev";
+  try {
+    rmSync(prev, { recursive: true, force: true });
+    cpSync(srcDir, prev, { recursive: true });
+  } catch {
+    /* best-effort backup */
+  }
+  try {
+    let applied = 0;
+    for (const [rel, content] of Object.entries(manifest.files)) {
+      if (!/^(core|checks)\//.test(rel) || rel.includes("..")) continue; // never escape core/+checks/
+      const path = join(srcDir, rel);
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, content, "utf8");
+      applied++;
+    }
+    return { applied, version: manifest.version };
+  } catch (e) {
+    // Roll back to the last-good core — never leave a half-written core (loader.mjs's .prev restore).
+    try {
+      rmSync(srcDir, { recursive: true, force: true });
+      cpSync(prev, srcDir, { recursive: true });
+    } catch {
+      /* best-effort restore */
+    }
+    throw e;
+  }
+}
+
+// Orchestration: version-gate → fetch manifest → SHA-verify → apply. Network-gated and fail-soft: any
+// error (offline, 404, bad SHA) keeps the current cached core so a user's run is NEVER broken by an
+// update attempt. Inert until the core bucket exists (pre-release it simply skips).
+export async function selfUpdate({ installedVersion, srcDir, config = {}, coreUrl = DEFAULT_CORE_URL, fetchImpl = fetch }) {
+  const u = config.update || {};
+  if (u.autoUpdate === false) return { skipped: "disabled" };
+  if (u.pinnedVersion) return { skipped: "pinned", pinned: u.pinnedVersion };
+  if (process.env.ARCHITECT_NO_SELF_UPDATE) return { skipped: "env-disabled" };
+  try {
+    const vRes = await fetchImpl(`${coreUrl}/version.json`, { signal: AbortSignal.timeout(5000) });
+    if (!vRes.ok) return { skipped: "no-version" };
+    const v = await vRes.json();
+    if (!v?.version || !isNewer(v.version, installedVersion)) return { skipped: "up-to-date", remote: v?.version };
+    const mRes = await fetchImpl(`${coreUrl}/architect-core.json`, { signal: AbortSignal.timeout(8000) });
+    if (!mRes.ok) return { skipped: "no-manifest" };
+    const manifest = await mRes.json();
+    if (!isNewer(manifest.version, installedVersion)) return { skipped: "stale-manifest" };
+    return applyCoreManifest(manifest, srcDir);
+  } catch (e) {
+    return { skipped: "error", error: String(e?.message || e) };
+  }
+}

package/your-checks/README.md

@@ -0,0 +1,33 @@
+# your-checks/
+
+Your own Architect checks live here. **The core never touches this folder** — self-update only ever
+refreshes the shipped core, so your rules stay yours while the core keeps improving underneath them.
+
+A check is any `.mjs` exporting `audit`:
+
+```js
+export const audit = {
+  id: "my-rule", // unique; SAME id as a core check ⇒ yours SHADOWS the core's
+  title: "My rule",
+  category: "custom",
+  domain: "code", // "code" (your repo) | "hosted" (your cloud, via the MCP vault)
+  requires: {}, // {} = any repo; e.g. { ecosystems: ["npm"] }
+  gating: false, // true ⇒ blocks `architect --fail-on-drift`
+  async run(ctx) {
+    // ctx = { root, config, checkConfig, project, vault? }
+    return {
+      failed: false,
+      findings: [
+        /* createFinding(...) */
+      ],
+      report: "",
+    };
+  },
+};
+```
+
+Drop it under `your-checks/code/` (or `your-checks/hosted/`) and it auto-registers — no wiring. Copy
+`code/example-check.mjs` to start. Import helpers with `import { createFinding, walkFiles } from "connections-arkitect"`.
+
+**Forking / pinning:** set `update.autoUpdate: false` (or pin `update.pinnedVersion`) in `arkitect.config.json`
+to stop pulling the core entirely and own it outright — GitHub-fork style.

package/your-checks/code/example-check.mjs

@@ -0,0 +1,24 @@
+// ── Your own check. Copy this file, rename it, make it yours. ──
+// The Architect core NEVER overwrites anything under your-checks/ — your rules stay yours while the core
+// keeps improving underneath them. A check is just a module exporting `audit` with an `id` + `run(ctx)`.
+//
+//   import { createFinding, walkFiles } from "connections-arkitect";
+//
+// (Plain { id, title, severity, file, line, message } objects work too — createFinding just fills defaults.)
+
+export const audit = {
+  id: "example-your-check",
+  title: "Example — your own check goes here",
+  category: "custom",
+  domain: "code", // "code" runs in your repo; "hosted" runs through the MCP vault against your cloud
+  requires: {}, // {} = any repo; e.g. { ecosystems: ["npm"] } to scope it
+  gating: false, // true ⇒ blocks `architect --fail-on-drift`
+  async run(_ctx) {
+    // rename _ctx → ctx when you use it: { root, config, checkConfig, project, vault? }
+    // Example skeleton:
+    //   const findings = [];
+    //   for (const file of walkFiles(ctx.root)) { /* inspect; push createFinding(...) */ }
+    //   return { failed: findings.some(f => f.severity === "error"), findings, report: "" };
+    return { failed: false, findings: [], report: "" };
+  },
+};