@miroshnik/elves 0.0.0 → 2026.1018.1

package/dist/spec/scripts/architecture.js

@@ -0,0 +1,628 @@
+import {
+  locale_default
+} from "./harness-qzb932c8.js";
+import {
+  invariant2,
+  codeOnly2,
+  envNamesInCode2
+} from "./harness-v9s1v9w3.js";
+
+// skills/spec/scripts/architecture.ts
+import { readdirSync, readFileSync } from "node:fs";
+import { builtinModules } from "node:module";
+import path from "node:path";
+function deployUnits(root) {
+  const out = new Set;
+  for (const f of ["docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"]) {
+    let text;
+    try {
+      text = readFileSync(path.join(root, f), "utf8");
+    } catch {
+      continue;
+    }
+    let inServices = false;
+    for (const line of text.split(/\r?\n/)) {
+      if (/^services:\s*$/.test(line))
+        inServices = true;
+      else if (/^\S/.test(line))
+        inServices = false;
+      else if (inServices) {
+        const m = /^ {2}([A-Za-z0-9_.-]+):\s*$/.exec(line);
+        if (m)
+          out.add(`compose:${m[1]}`);
+      }
+    }
+  }
+  try {
+    for (const e of readdirSync(path.join(root, "supabase", "functions"), { withFileTypes: true })) {
+      if (e.isDirectory() && !e.name.startsWith("_"))
+        out.add(`supabase-function:${e.name}`);
+    }
+  } catch {}
+  try {
+    const v = JSON.parse(readFileSync(path.join(root, "vercel.json"), "utf8"));
+    for (const c of v.crons ?? [])
+      out.add(`vercel-cron:${c.path}`);
+  } catch {}
+  walkDirs(root, (rel, entries) => {
+    for (const e of entries) {
+      if (!e.isFile() || !e.name.endsWith(".tf"))
+        continue;
+      for (const m of readFileSync(path.join(root, rel, e.name), "utf8").matchAll(TF_RESOURCE)) {
+        if (TERRAFORM_UNITS.has(m[1]))
+          out.add(`terraform:${m[1]}.${m[2]}`);
+      }
+    }
+  });
+  return sorted([...out]);
+}
+var TERRAFORM_UNITS = new Set([
+  "aws_ecs_service",
+  "aws_lambda_function",
+  "aws_apprunner_service",
+  "google_cloud_run_service",
+  "google_cloud_run_v2_service",
+  "google_cloud_run_v2_job",
+  "google_cloudfunctions_function",
+  "google_cloudfunctions2_function",
+  "azurerm_container_app",
+  "azurerm_linux_function_app",
+  "kubernetes_deployment",
+  "kubernetes_deployment_v1",
+  "kubernetes_cron_job_v1"
+]);
+var TF_RESOURCE = /^[ \t]*resource\s+"([\w-]+)"\s+"([\w-]+)"/gm;
+function workspacePackages(root) {
+  const patterns = [];
+  try {
+    const ws = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")).workspaces;
+    patterns.push(...Array.isArray(ws) ? ws : ws?.packages ?? []);
+  } catch {}
+  try {
+    let inPackages = false;
+    for (const line of readFileSync(path.join(root, "pnpm-workspace.yaml"), "utf8").split(/\r?\n/)) {
+      if (/^packages:\s*$/.test(line))
+        inPackages = true;
+      else if (/^\S/.test(line))
+        inPackages = false;
+      else if (inPackages) {
+        const m = /^\s+-\s+(["']?)(.+?)\1\s*(?:#.*)?$/.exec(line);
+        if (m)
+          patterns.push(m[2]);
+      }
+    }
+  } catch {}
+  if (!patterns.length)
+    return [];
+  const include = patterns.filter((p) => !p.startsWith("!")).map(glob);
+  const exclude = patterns.filter((p) => p.startsWith("!")).map((p) => glob(p.slice(1)));
+  const out = [];
+  walkDirs(root, (rel, entries) => {
+    if (!rel || !entries.some((e) => e.isFile() && e.name === "package.json"))
+      return;
+    if (include.some((r) => r.test(rel)) && !exclude.some((r) => r.test(rel)))
+      out.push(rel);
+  });
+  return sorted(out);
+}
+function glob(pattern) {
+  const segs = pattern.replace(/^\.\//, "").replace(/\/+$/, "").split("/");
+  const body = segs.map((s) => s === "**" ? "\x00" : s.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")).join("/").replace(/\0\//g, "(?:.*/)?").replace(/\/\0/g, "(?:/.*)?").replace(/\0/g, ".*");
+  return new RegExp(`^${body}$`);
+}
+function walkDirs(root, visit, rel = "") {
+  let entries;
+  try {
+    entries = readdirSync(path.join(root, rel), { withFileTypes: true });
+  } catch {
+    return;
+  }
+  visit(rel, entries);
+  for (const e of entries) {
+    if (e.isDirectory() && !SKIP.has(e.name) && !e.name.startsWith("."))
+      walkDirs(root, visit, rel ? `${rel}/${e.name}` : e.name);
+  }
+}
+function hasCode(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  return entries.some((e) => e.isDirectory() ? !SKIP.has(e.name) && hasCode(path.join(dir, e.name)) : CODE.test(e.name) && !/\.d\.[cm]?ts$/.test(e.name));
+}
+var CODE = /\.[cm]?[jt]sx?$/;
+var SKIP = new Set(["node_modules", ".git", "dist", "build", "coverage", ".next"]);
+var BUILTIN = new Set(builtinModules);
+var paths = (m) => (Array.isArray(m.path) ? m.path : [m.path]).map((p) => p.replace(/\/+$/, ""));
+var names = (model) => Object.keys(model.modules).sort();
+var sorted = (xs) => [...xs].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+function boundariesConfig(model, boundaries, opts = {}) {
+  const all = names(model);
+  const roots = model.roots ?? ["src"];
+  const policies = all.flatMap((name) => {
+    const allowed = new Set([name, ...model.modules[name].dependsOn ?? []]);
+    const denied = all.filter((n) => !allowed.has(n));
+    if (!denied.length)
+      return [];
+    return [
+      {
+        from: { element: { type: name } },
+        disallow: { to: { element: { types: { anyOf: denied } } } },
+        message: `module ${name} doesn't depend on {{to.element.type}} — module dependencies are in tests/architecture/model.ts`
+      }
+    ];
+  });
+  return [
+    {
+      files: opts.files ?? roots.map((r) => `${r}/**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}`),
+      plugins: { boundaries },
+      settings: {
+        "boundaries/elements": all.flatMap((name) => paths(model.modules[name]).map((p) => ({ type: name, pattern: p }))).sort((a, b) => b.pattern.length - a.pattern.length),
+        "import/resolver": { node: { extensions: [".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".mts", ".cts"] } },
+        ...opts.settings
+      },
+      rules: { "boundaries/dependencies": [2, { default: "allow", policies }] }
+    }
+  ];
+}
+var IMPORT = /^\s*(import|export)\s+(type\s+)?[^;'"]*?\s*from\s*["']([^"']+)["']|^\s*import\s*["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)|\brequire\s*\(\s*["']([^"']+)["']\s*\)/gm;
+function importsIn(text, aliases = {}) {
+  const out = [];
+  for (const m of text.matchAll(IMPORT)) {
+    if (m[2])
+      continue;
+    const spec = m[3] ?? m[4] ?? m[5] ?? m[6];
+    if (!spec || spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("node:"))
+      continue;
+    if (Object.keys(aliases).some((a) => spec.startsWith(a)))
+      continue;
+    const parts = spec.split("/");
+    const pkg = spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+    if (BUILTIN.has(pkg) || out.includes(pkg))
+      continue;
+    out.push(pkg);
+  }
+  return out;
+}
+var URL_HOST = /["'`]https?:\/\/([a-z0-9-]+(?:\.[a-z0-9-]+)+)(?::\d+)?(?=[\/"'`?#])/gi;
+var isLocal = (h) => h === "localhost" || h.endsWith(".localhost") || /^127(\.\d+){3}$/.test(h) || h === "0.0.0.0" || h === "[::1]";
+var isReserved = (h) => /(^|\.)(example|invalid|test)$|(^|\.)example\.(com|net|org)$/.test(h);
+var XMLNS = /xmlns(?::[\w-]+)?\s*=\s*$/;
+var NAMESPACE_HOSTS = new Set(["www.w3.org"]);
+var HREF = /(?<![.\w$])["']?href["']?\s*(?:=\s*\{?|:)\s*$/;
+var OPEN_TAG = /<([A-Za-z][\w.:-]*)[^<>]*$/;
+var isLink = (text, at) => HREF.test(text.slice(Math.max(0, at - 40), at)) && OPEN_TAG.exec(text.slice(Math.max(0, at - 2000), at))?.[1] !== "link";
+function hostsIn(source, file) {
+  return hostsInCode(codeOnly2(source, file));
+}
+function hostsInCode(text) {
+  const out = new Set;
+  for (const m of text.matchAll(URL_HOST)) {
+    const h = m[1].toLowerCase();
+    if (isLocal(h) || isReserved(h) || NAMESPACE_HOSTS.has(h) || XMLNS.test(text.slice(Math.max(0, m.index - 40), m.index)))
+      continue;
+    if (isLink(text, m.index))
+      continue;
+    out.add(h);
+  }
+  return [...out];
+}
+var HEADER_LITERAL = /(["'`])([A-Za-z][A-Za-z0-9-]*)\1/g;
+function headersInCode(text, declared) {
+  const out = new Set;
+  for (const m of text.matchAll(HEADER_LITERAL)) {
+    const h = m[2].toLowerCase();
+    if (declared.has(h))
+      out.add(h);
+  }
+  return [...out];
+}
+function sources(root, model, readers) {
+  const out = [];
+  const declared = new Set(Object.values(model.externals ?? {}).flatMap((e) => (e.headers ?? []).map((h) => h.toLowerCase())));
+  const walk = (rel) => {
+    let entries;
+    try {
+      entries = readdirSync(path.join(root, rel), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const child = `${rel}/${e.name}`;
+      if (e.isDirectory()) {
+        if (!SKIP.has(e.name))
+          walk(child);
+      } else if (CODE.test(e.name) && !/\.d\.[cm]?ts$/.test(e.name)) {
+        const text = readFileSync(path.join(root, child), "utf8");
+        const code = codeOnly2(text, child);
+        out.push({
+          file: child,
+          dir: rel,
+          packages: importsIn(text, model.aliases),
+          hosts: hostsInCode(code),
+          env: envNamesInCode2(code, { file: child, readers }),
+          headers: declared.size ? headersInCode(code, declared) : []
+        });
+      }
+    }
+  };
+  for (const r of model.roots ?? ["src"])
+    walk(r.replace(/\/+$/, ""));
+  return out.sort((a, b) => a.file < b.file ? -1 : 1);
+}
+function owners(model, dir) {
+  let best = -1;
+  let out = [];
+  for (const n of names(model)) {
+    for (const p of paths(model.modules[n])) {
+      if (dir !== p && !dir.startsWith(p + "/"))
+        continue;
+      if (p.length > best)
+        [best, out] = [p.length, [n]];
+      else if (p.length === best && !out.includes(n))
+        out.push(n);
+    }
+  }
+  return out;
+}
+function architecture(it, opts) {
+  const { model } = opts;
+  const N = locale_default.names(locale_default.projectLanguage());
+  const specs = [];
+  const add = (spec) => void specs.push(spec);
+  const src = sources(opts.root, model, opts.readers);
+  const dirs = sorted([...new Set(src.map((s) => s.dir))]);
+  const moduleOf = (dir) => owners(model, dir);
+  add({
+    registry: N.spec.architecture.dirsRegistry,
+    items: dirs,
+    name: (d) => locale_default.fill(N.spec.architecture.dirName, { dir: d, module: moduleOf(d).length === 1 ? moduleOf(d)[0] : "?" }),
+    key: (d) => d,
+    check: (d) => {
+      const own = moduleOf(d);
+      if (!own.length)
+        throw new Error(`${d}: code outside the model's modules — add a module to tests/architecture/model.ts or move the code`);
+      if (own.length > 1)
+        throw new Error(`${d}: the directory is in several modules — ${own.join(", ")}`);
+    },
+    violator: { name: N.spec.architecture.dirViolator, item: "__outside_model__" }
+  });
+  const roots = (model.roots ?? ["src"]).map((r) => r.replace(/^\.\//, "").replace(/\/+$/, ""));
+  const inRoots = (p) => roots.some((r) => r === p || r.startsWith(p + "/") || p.startsWith(r + "/"));
+  const packages = roots.some((r) => r === "" || r === ".") ? [] : workspacePackages(opts.root).filter((p) => hasCode(path.join(opts.root, p)));
+  if (packages.length) {
+    add({
+      registry: N.spec.architecture.workspaceRegistry,
+      items: packages,
+      name: (p) => locale_default.fill(N.spec.architecture.workspaceName, { path: p }),
+      key: (p) => p,
+      fileOf: (p) => path.resolve(opts.root, p, "package.json"),
+      check: (p) => {
+        if (!inRoots(p))
+          throw new Error(`${p}: a workspace package with code outside the model's roots — add it to roots in tests/architecture/model.ts`);
+      },
+      violator: { name: N.spec.architecture.workspaceViolator, item: "__outside_roots__" }
+    });
+  }
+  const used = new Map;
+  for (const s of src) {
+    const own = moduleOf(s.dir);
+    if (own.length !== 1)
+      continue;
+    const byPkg = used.get(own[0]) ?? new Map;
+    for (const p of s.packages)
+      byPkg.set(p, [...byPkg.get(p) ?? [], s.file]);
+    used.set(own[0], byPkg);
+  }
+  const imports = [...used].flatMap(([mod, byPkg]) => [...byPkg].map(([pkg, files]) => ({ mod, pkg, files })));
+  const allowed = (mod) => model.modules[mod]?.packages ?? [];
+  add({
+    registry: N.spec.architecture.importsRegistry,
+    items: imports,
+    name: (i) => locale_default.fill(N.spec.architecture.importsName, { module: i.mod, package: i.pkg }),
+    key: (i) => `${i.mod}:${i.pkg}`,
+    check: (i) => {
+      if (!allowed(i.mod).includes(i.pkg))
+        throw new Error(`package ${i.pkg} is not allowed for module ${i.mod}: ${i.files.join(", ")}`);
+    },
+    violator: { name: N.spec.architecture.importsViolator, item: { mod: names(model)[0] ?? "", pkg: "__not_allowed__", files: ["__violator__"] } }
+  });
+  const declared = names(model).flatMap((mod) => allowed(mod).map((pkg) => ({ mod, pkg })));
+  add({
+    registry: N.spec.architecture.allowedRegistry,
+    items: declared,
+    name: (d) => locale_default.fill(N.spec.architecture.allowedName, { module: d.mod, package: d.pkg }),
+    key: (d) => `${d.mod}:${d.pkg}`,
+    check: (d) => {
+      if (!used.get(d.mod)?.has(d.pkg))
+        throw new Error(`module ${d.mod} doesn't import ${d.pkg} — remove the package from the model or fix the code`);
+    },
+    violator: { name: N.spec.architecture.allowedViolator, item: { mod: "__no_module__", pkg: "__unused__" } }
+  });
+  if (model.externals)
+    c1(add, N, model, src);
+  if (model.containers)
+    c2(add, N, opts.root, model, src);
+  const exceptions = route(opts.exceptions ?? [], specs);
+  const outside = route(opts.outside ?? [], specs);
+  for (const [i, spec] of specs.entries())
+    invariant2(it, { ...spec, exceptions: exceptions[i], outside: outside[i] });
+}
+var REGISTRIES = [
+  (n) => n.spec.architecture.dirsRegistry,
+  (n) => n.spec.architecture.workspaceRegistry,
+  (n) => n.spec.architecture.importsRegistry,
+  (n) => n.spec.architecture.allowedRegistry,
+  (n) => n.spec.architecture.containersRegistry,
+  (n) => n.spec.architecture.edgesRegistry,
+  (n) => n.spec.architecture.unitsRegistry,
+  (n) => n.spec.architecture.clientsRegistry,
+  (n) => n.spec.architecture.hostsRegistry,
+  (n) => n.spec.architecture.packagesRegistry,
+  (n) => n.spec.architecture.envRegistry,
+  (n) => n.spec.architecture.headersRegistry
+];
+var registryOf = (rule, n) => REGISTRIES.find((pick) => locale_default.every(pick).includes(rule))?.(n) ?? rule;
+function route(xs, specs) {
+  const keys = specs.map((sp) => new Set(sp.items.map((x) => String((sp.key ?? sp.name)(x)))));
+  const out = specs.map(() => []);
+  const n = locale_default.names(locale_default.projectLanguage());
+  for (const { rule, ...x } of xs) {
+    const byRule = rule ? specs.findIndex((sp) => sp.registry === registryOf(rule, n)) : -1;
+    let to = byRule >= 0 ? [byRule] : keys.flatMap((k, i) => !rule && k.has(x.item) ? [i] : []);
+    if (!to.length)
+      to = [0];
+    for (const i of to)
+      out[i].push(x);
+  }
+  return out;
+}
+function moduleContainers(model) {
+  const cont = model.containers ?? {};
+  const out = new Map(Object.keys(model.modules).map((m) => [m, new Set(Object.keys(cont).filter((c) => (cont[c].modules ?? []).includes(m)))]));
+  for (let changed = true;changed; ) {
+    changed = false;
+    for (const [m, x] of Object.entries(model.modules)) {
+      for (const d of x.dependsOn ?? []) {
+        if (!model.modules[d]?.library)
+          continue;
+        const to = out.get(d);
+        for (const c of out.get(m)) {
+          if (to.has(c))
+            continue;
+          to.add(c);
+          changed = true;
+        }
+      }
+    }
+  }
+  return new Map([...out].map(([m, cs]) => [m, sorted([...cs])]));
+}
+function c2(add, N, root, model, src) {
+  const cont = model.containers;
+  const of = moduleContainers(model);
+  const containerOf = (m) => of.get(m) ?? [];
+  const isLibrary = (m) => !!model.modules[m]?.library;
+  add({
+    registry: N.spec.architecture.containersRegistry,
+    items: names(model),
+    name: (m) => isLibrary(m) ? locale_default.fill(N.spec.architecture.libraryName, { module: m, containers: containerOf(m).join(", ") || "?" }) : locale_default.fill(N.spec.architecture.moduleName, { module: m, container: containerOf(m).length === 1 ? containerOf(m)[0] : "?" }),
+    key: (m) => m,
+    check: (m) => {
+      const c = containerOf(m);
+      if (isLibrary(m)) {
+        if (!c.length)
+          throw new Error(`library ${m} is in no container: no module of the containers depends on it`);
+        return;
+      }
+      if (!c.length)
+        throw new Error(`module ${m} is in no container of the model`);
+      if (c.length > 1)
+        throw new Error(`module ${m} is in several containers: ${c.join(", ")} — mark a shared package with library: true`);
+    },
+    violator: { name: N.spec.architecture.containersViolator, item: "__outside_containers__" }
+  });
+  const edges = names(model).flatMap((m) => (model.modules[m].dependsOn ?? []).map((d) => ({ m, d })));
+  if (edges.length) {
+    add({
+      registry: N.spec.architecture.edgesRegistry,
+      items: edges,
+      name: (e) => locale_default.fill(N.spec.architecture.edgeName, { from: e.m, to: e.d }),
+      key: (e) => `${e.m}→${e.d}`,
+      check: (e) => {
+        const a = containerOf(e.m);
+        const b = containerOf(e.d);
+        if (!a.length || a.some((c) => !b.includes(c))) {
+          throw new Error(`${e.m} (${a.join(", ") || "?"}) depends on ${e.d} (${b.join(", ") || "?"}) — across containers only a uses link`);
+        }
+      },
+      violator: { name: N.spec.architecture.edgeViolator, item: { m: "__a__", d: "__b__" } }
+    });
+  }
+  const found = deployUnits(root);
+  const declared = new Map;
+  for (const [c, x] of Object.entries(cont))
+    for (const d of x.deploy ?? [])
+      declared.set(d, c);
+  add({
+    registry: N.spec.architecture.unitsRegistry,
+    items: sorted([...new Set([...found, ...declared.keys()])]),
+    name: (u) => locale_default.fill(N.spec.architecture.unitName, { unit: u, container: declared.get(u) ?? "?" }),
+    key: (u) => u,
+    check: (u) => {
+      if (!declared.has(u))
+        throw new Error(`${u} is in the deploy configs but not in the model — add a container to tests/architecture/model.ts`);
+      if (!found.includes(u))
+        throw new Error(`${u} of container ${declared.get(u)} is not in the deploy configs — the model diverged from the deploy`);
+    },
+    violator: { name: N.spec.architecture.unitViolator, item: "__outside_model__" }
+  });
+  const storages = Object.entries(cont).flatMap(([s, x]) => (x.clients ?? []).map((pkg) => ({ s, pkg })));
+  if (storages.length) {
+    const uses = new Map;
+    for (const src1 of src) {
+      const mod = owners(model, src1.dir);
+      if (mod.length !== 1)
+        continue;
+      for (const c of containerOf(mod[0])) {
+        for (const st of storages) {
+          if (!src1.packages.includes(st.pkg))
+            continue;
+          const k = `${st.pkg}:${st.s}:${c}`;
+          const u = uses.get(k) ?? { ...st, c, files: [] };
+          u.files.push(src1.file);
+          uses.set(k, u);
+        }
+      }
+    }
+    add({
+      registry: N.spec.architecture.clientsRegistry,
+      items: [...uses.values()],
+      name: (u) => locale_default.fill(N.spec.architecture.clientName, { package: u.pkg, storage: u.s, container: u.c }),
+      key: (u) => `${u.pkg}:${u.c}`,
+      check: (u) => {
+        if (u.c !== u.s && !(cont[u.c]?.uses ?? []).includes(u.s)) {
+          throw new Error(`container ${u.c} imports client ${u.pkg} of storage ${u.s} without a uses link: ${u.files.join(", ")}`);
+        }
+      },
+      violator: { name: N.spec.architecture.clientViolator, item: { s: "__storage__", pkg: "__client__", c: "__container__", files: [] } }
+    });
+  }
+}
+var adaptersOf = (e) => e.adapter === undefined ? [] : Array.isArray(e.adapter) ? e.adapter : [e.adapter];
+var adapterWord = (a, one, many) => `${a.length === 1 ? one : many} ${a.join(", ")}`;
+function c1(add, N, model, src) {
+  const ext = model.externals;
+  const inAdapters = (s, a) => owners(model, s.dir).some((m) => a.includes(m));
+  const files = (xs) => xs.map((s) => s.file).join(", ");
+  const hostOwner = new Map;
+  for (const [name, e] of Object.entries(ext))
+    for (const h of e.hosts ?? [])
+      hostOwner.set(h.toLowerCase(), name);
+  const hostFiles = new Map;
+  for (const s of src)
+    for (const h of s.hosts)
+      hostFiles.set(h, [...hostFiles.get(h) ?? [], s]);
+  const hosts = sorted([...new Set([...hostOwner.keys(), ...hostFiles.keys()])]);
+  if (hosts.length) {
+    add({
+      registry: N.spec.architecture.hostsRegistry,
+      items: hosts,
+      name: (h) => {
+        const x = hostOwner.get(h);
+        if (!x)
+          return locale_default.fill(N.spec.architecture.hostName, { host: h, adapters: locale_default.fill(N.spec.architecture.inAdapter, { list: "?" }) });
+        const a = adaptersOf(ext[x]);
+        const adapters = locale_default.fill(a.length === 1 ? N.spec.architecture.inAdapter : N.spec.architecture.inAdapters, { list: a.join(", ") });
+        return a.length ? locale_default.fill(N.spec.architecture.hostName, { host: h, adapters }) : locale_default.fill(N.spec.architecture.hostPerimeter, { host: h, system: x });
+      },
+      key: (h) => h,
+      check: (h) => {
+        const found = hostFiles.get(h) ?? [];
+        const x = hostOwner.get(h);
+        if (!x)
+          throw new Error(`host ${h} is declared by no external system of the model: ${files(found)}`);
+        const a = adaptersOf(ext[x]);
+        const outside = found.filter((s) => !inAdapters(s, a));
+        if (!outside.length)
+          return;
+        if (!a.length)
+          throw new Error(`external system ${x} has no adapter, yet host ${h} is in the code: ${files(outside)}`);
+        throw new Error(`host ${h} of external system ${x} is outside its ${adapterWord(a, "adapter", "adapters")}: ${files(outside)}`);
+      },
+      violator: { name: N.spec.architecture.hostViolator, item: "__outside_model__.example" }
+    });
+  }
+  const pkgs = Object.entries(ext).flatMap(([x, e]) => (e.packages ?? []).map((p) => ({ x, p, a: adaptersOf(e) })));
+  if (pkgs.length) {
+    add({
+      registry: N.spec.architecture.packagesRegistry,
+      items: pkgs,
+      name: (i) => i.a.length ? locale_default.fill(N.spec.architecture.packageName, { package: i.p, system: i.x, adapters: locale_default.fill(i.a.length === 1 ? N.spec.architecture.withAdapter : N.spec.architecture.withAdapters, { list: i.a.join(", ") }) }) : locale_default.fill(N.spec.architecture.packagePerimeter, { package: i.p, system: i.x }),
+      key: (i) => `${i.x}:${i.p}`,
+      check: (i) => {
+        const allowedTo = names(model).filter((n) => (model.modules[n].packages ?? []).includes(i.p));
+        if (!i.a.length) {
+          if (allowedTo.length)
+            throw new Error(`external system ${i.x} has no adapter, yet package ${i.p} is allowed for modules: ${allowedTo.join(", ")}`);
+          return;
+        }
+        if (!i.a.some((a) => allowedTo.includes(a))) {
+          throw new Error(`package ${i.p} of external system ${i.x} is not allowed in the model for ${i.a.length === 1 ? `adapter ${i.a[0]}` : `any of adapters ${i.a.join(", ")}`}`);
+        }
+        const others = allowedTo.filter((n) => !i.a.includes(n));
+        if (others.length)
+          throw new Error(`package ${i.p} of external system ${i.x} is allowed not only for ${i.a.length === 1 ? "the adapter" : "the adapters"}: ${others.join(", ")}`);
+      },
+      violator: { name: N.spec.architecture.packageViolator, item: { x: "__violator__", p: "__none__", a: ["__no_module__"] } }
+    });
+  }
+  const readOnlyByAdapters = (registry, noun, word, list, reads, fake) => {
+    const items = Object.entries(ext).flatMap(([x, e]) => (list(e) ?? []).map((k) => ({ x, k, a: adaptersOf(e) })));
+    if (!items.length)
+      return;
+    add({
+      registry,
+      items,
+      name: (i) => i.a.length ? locale_default.fill(i.a.length === 1 ? N.spec.architecture.readName : N.spec.architecture.readNameMany, { noun, key: i.k, system: i.x, list: i.a.join(", ") }) : locale_default.fill(N.spec.architecture.readPerimeter, { noun, key: i.k, system: i.x }),
+      key: (i) => `${i.x}:${i.k}`,
+      check: (i) => {
+        const outside = (i.src ?? src).filter((s) => reads(s, i.k) && !inAdapters(s, i.a));
+        if (!outside.length)
+          return;
+        if (!i.a.length)
+          throw new Error(`external system ${i.x} has no adapter, yet ${word} ${i.k} is read in the code: ${files(outside)}`);
+        throw new Error(`${word} ${i.k} of external system ${i.x} is read outside its ${adapterWord(i.a, "adapter", "adapters")}: ${files(outside)}`);
+      },
+      violator: {
+        name: locale_default.fill(N.spec.architecture.readViolator, { noun }),
+        item: { x: "__violator__", k: "__KEY__", a: ["__no_module__"], src: [{ file: "__violator__.ts", dir: "__outside_model__", packages: [], hosts: [], env: [], headers: [], ...fake }] }
+      }
+    });
+  };
+  readOnlyByAdapters(N.spec.architecture.envRegistry, N.spec.architecture.envNoun, "key", (e) => e.env, (s, k) => s.env.includes(k), { env: ["__KEY__"] });
+  readOnlyByAdapters(N.spec.architecture.headersRegistry, N.spec.architecture.headerNoun, "header", (e) => e.headers, (s, k) => s.headers.includes(k.toLowerCase()), { headers: ["__key__"] });
+}
+function networkGuard(model, fetchImpl = globalThis.fetch, opts = {}) {
+  const owner = new Map;
+  for (const [name, e] of Object.entries(model.externals ?? {}))
+    for (const h of e.hosts ?? [])
+      owner.set(h.toLowerCase(), name);
+  const allow = new Set((opts.allow ?? []).map((h) => h.toLowerCase()));
+  const rejected = [];
+  const guard = async (input, init) => {
+    const href = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const host = new URL(href).hostname.toLowerCase();
+    if (isLocal(host) || allow.has(host))
+      return fetchImpl(input, init);
+    rejected.push(host);
+    const system = owner.get(host);
+    throw new Error(system ? `request to host ${host} of external system ${system} without a mock — mock the request: tests go to the network only to local addresses and allow` : `request to host ${host} outside the model — declare the external system in tests/architecture/model.ts and mock the request`);
+  };
+  const check = () => {
+    if (!rejected.length)
+      return;
+    const hosts = [...new Set(rejected)].join(", ");
+    rejected.length = 0;
+    throw new Error(`network requests rejected by the guard: ${hosts} — mock them (the code under test may have caught the fetch exception)`);
+  };
+  return Object.assign(guard, { rejected, check });
+}
+function cspConnectSrc(model, self = ["'self'"]) {
+  const hosts = sorted([...new Set(Object.values(model.externals ?? {}).flatMap((e) => (e.hosts ?? []).map((h) => h.toLowerCase())))]);
+  return ["connect-src", ...self, ...hosts.map((h) => `https://${h}`)].join(" ");
+}
+export {
+  adaptersOf,
+  architecture,
+  boundariesConfig,
+  cspConnectSrc,
+  deployUnits,
+  hostsIn,
+  importsIn,
+  moduleContainers,
+  networkGuard,
+  workspacePackages
+};

package/dist/spec/scripts/eslint-config.js

@@ -0,0 +1,54 @@
+// skills/spec/scripts/eslint-config.ts
+import { readdirSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+var FRAGMENT = new Set(["eslint.ts", "eslint.mts", "eslint.mjs", "eslint.js"]);
+var SKIP = new Set(["node_modules", ".git"]);
+var SKIP_REL = new Set(["tests/lib"]);
+function eslintFragments(root, dirs = ["tests"]) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!SKIP.has(e.name) && !SKIP_REL.has(path.relative(root, full).split(path.sep).join("/")))
+          walk(full);
+      } else if (FRAGMENT.has(e.name))
+        out.push(full);
+    }
+  };
+  for (const d of dirs)
+    walk(path.join(root, d));
+  return out.sort();
+}
+async function collectEslint(root, dirs = ["tests"]) {
+  const configs = [{ linterOptions: { reportUnusedDisableDirectives: "error" } }];
+  for (const file of eslintFragments(root, dirs)) {
+    const mod = await import(pathToFileURL(file).href);
+    if (!mod.default)
+      throw new Error(`${path.relative(root, file)}: no export default — not a flat config fragment`);
+    configs.push(...Array.isArray(mod.default) ? mod.default : [mod.default]);
+  }
+  return configs;
+}
+var SPEC_PLUGIN = { meta: { name: "spec" }, rules: {} };
+function restrict(o) {
+  SPEC_PLUGIN.rules[o.id] = {
+    meta: { type: "problem", schema: [], docs: { description: o.message } },
+    create(context) {
+      return Object.fromEntries(o.selectors.map((sel) => [sel, (node) => context.report({ node, message: o.message })]));
+    }
+  };
+  return [{ files: o.files, ...o.ignores ? { ignores: o.ignores } : {}, plugins: { spec: SPEC_PLUGIN }, rules: { [`spec/${o.id}`]: "error" } }];
+}
+export {
+  collectEslint,
+  eslintFragments,
+  restrict
+};