src/model-drift.ts

Functions

Imports

It imports src/env.ts, src/github/client.ts, src/log.ts, src/ops-sites.ts, src/ops-types/views.ts, src/system-model.ts. Imported by src/maintenance.ts.

Source

1import type { Env } from "./env";
2import type { OpsMaintenanceItem } from "./ops-types/views";
3import { listInstalledRepos, parseReposList, type InstalledRepo } from "./github/client";
4import { logEvent } from "./log";
5import { readSiteConfig, sitesFrom } from "./ops-sites";
6import type { SystemModel } from "./system-model";
7
8// The model's drift check, the daily half (design capsid/research/design-system-explorer.md,
9// section 1; docs/public-data.md). system/model.json is written by hand, so it falls
10// behind what Capsid knows: a repo mapped to a namespace or installed for the App that
11// the model never names, a repo the model names that GitHub no longer lists, a watched
12// site whose host is no model system's domain. Each is one line in the daily maintenance
13// list. The check lists and never edits: the model changes by pull request. Every repo,
14// private ones included, belongs in the model unless its `left_off` list names it
15// (Dustin, 2026-10-23).
16
17const MAX_ITEMS = 50;
18
19export interface DriftFacts {
20  /** Every repo a namespace maps, with its namespace. */
21  mapped: Array<{ namespace: string; repo: string }>;
22  /** Every repo the App can see, or null when the listing could not be read. */
23  installed: InstalledRepo[] | null;
24  /** Each watched site's host, by namespace. */
25  sites: Array<{ namespace: string; host: string }>;
26}
27
28function hostCovered(host: string, domains: readonly string[]): boolean {
29  return domains.some((d) => host === d || host.endsWith(`.${d}`));
30}
31
32/** The drift lines, both ways, and how many facts were compared. Pure. */
33export function modelDrift(model: SystemModel, facts: DriftFacts): { items: OpsMaintenanceItem[]; read: number } {
34  const items: OpsMaintenanceItem[] = [];
35  const modelRepos = new Map<string, string>();
36  for (const s of model.systems) for (const r of s.repos) modelRepos.set(r.toLowerCase(), s.id);
37  const leftOff = new Set((model.left_off ?? []).map((l) => l.repo.toLowerCase()));
38  const known = (repo: string) => modelRepos.has(repo.toLowerCase()) || leftOff.has(repo.toLowerCase());
39  const add = (namespace: string, line: string) => {
40    if (items.length < MAX_ITEMS) items.push({ rule: "model-drift", namespace, job: null, line });
41  };
42
43  const flagged = new Set<string>();
44  for (const { namespace, repo } of facts.mapped) {
45    if (known(repo) || flagged.has(repo.toLowerCase())) continue;
46    flagged.add(repo.toLowerCase());
47    add(namespace, `${repo} is mapped to ${namespace} but is not in system/model.json: add it.`);
48  }
49
50  if (facts.installed === null) {
51    items.push({ rule: "model-not-checked", namespace: "capsid", job: null, line: "The App's repo list could not be read, so the model was not compared with GitHub today." });
52  } else {
53    const live = new Map(facts.installed.map((r) => [r.full_name.toLowerCase(), r]));
54    for (const r of facts.installed) {
55      if (r.archived || known(r.full_name) || flagged.has(r.full_name.toLowerCase())) continue;
56      flagged.add(r.full_name.toLowerCase());
57      add("capsid", `${r.full_name} is installed for the App but is not in system/model.json: add it.`);
58    }
59    for (const [repo, system] of modelRepos) {
60      if (!live.has(repo)) add("capsid", `system/model.json names ${repo} (system ${system}), which the App does not list: fix the model, or install the App there.`);
61    }
62    for (const repo of leftOff) {
63      if (!live.has(repo)) add("capsid", `system/model.json leaves ${repo} off the map, but the App no longer lists it: drop it from left_off.`);
64    }
65  }
66
67  const domains = model.systems.flatMap((s) => (s.domain ? [s.domain] : []));
68  for (const { namespace, host } of facts.sites) {
69    if (!hostCovered(host, domains)) add(namespace, `The watched site ${host} is no model system's domain: add the domain to its system in system/model.json.`);
70  }
71
72  return { items, read: facts.mapped.length + (facts.installed?.length ?? 0) + facts.sites.length };
73}
74
75/** Reads the facts and runs the check, for the daily maintenance pass. */
76export async function gatherModelDriftItems(
77  env: Env,
78  model: SystemModel,
79  listRepos: (env: Env) => Promise<{ repos: InstalledRepo[] }> = listInstalledRepos
80): Promise<{ items: OpsMaintenanceItem[]; read: number }> {
81  const rows = await env.DB.prepare("SELECT namespace, repos FROM namespaces").all<{ namespace: string; repos: string }>();
82  const mapped: DriftFacts["mapped"] = [];
83  const unreadable: OpsMaintenanceItem[] = [];
84  for (const row of rows.results ?? []) {
85    const parsed = parseReposList(row.repos);
86    if ("list" in parsed) for (const r of parsed.list) mapped.push({ namespace: row.namespace, repo: r.repo });
87    else unreadable.push({ rule: "model-not-checked", namespace: row.namespace, job: null, line: `${row.namespace}'s repo mapping could not be read (${parsed.error}), so its repos were not compared with the model.` });
88  }
89
90  // A failed listing becomes a model-not-checked line in the list (modelDrift), and the
91  // rest of the check still runs.
92  let installed: InstalledRepo[] | null = null;
93  try {
94    installed = (await listRepos(env)).repos;
95  } catch (e) {
96    logEvent("error", "MODEL_DRIFT_LIST_FAILED", { message: `MODEL_DRIFT_LIST_FAILED ${e instanceof Error ? e.message : String(e)}` });
97  }
98
99  const sites = sitesFrom(await readSiteConfig(env.DB)).map((s) => ({ namespace: s.namespace, host: new URL(s.origin).hostname }));
100  const drift = modelDrift(model, { mapped, installed, sites });
101  return { items: [...unreadable, ...drift.items], read: drift.read };
102}