src/public-code.ts

Functions

Imports

It imports src/env.ts, src/github/client.ts, src/public-code-schema.ts, src/system-model.ts. Imported by src/public-data.ts.

Source

1import type { Env } from "./env";
2import { ghFetch } from "./github/client";
3import { CodeMapSchema, type PublicCode } from "./public-code-schema";
4import { publicRepos, type RepoPrivacy, type SystemModel } from "./system-model";
5
6// The public code maps (design capsid/research/design-system-explorer.md, section 5;
7// docs/public-data.md). devkit's code-map workflow writes code-map.json to an orphan
8// `code-map` branch in each repo that calls it. The daily public build reads that file
9// for every repo of a public system, parses it into new objects here, and stores the
10// lot as one document for the explorer's build. A repo of a private system is never
11// read, so its map cannot be published.
12
13const BRANCH = "code-map";
14const FILE = "code-map.json";
15// Capsid's own map is the largest, a few thousand functions; a file far past that is
16// not one devkit wrote.
17const MAX_FILE_BYTES = 8_000_000;
18
19/** The repo's code-map.json from its code-map branch, or null when the repo has none
20 *  (no branch, no file). Any other failure throws. */
21export async function readCodeMap(env: Env, repoFull: string): Promise<unknown> {
22  const [owner, repo] = repoFull.split("/");
23  const resp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/contents/${FILE}?ref=${BRANCH}`, {
24    headers: { Accept: "application/vnd.github.raw+json" },
25  });
26  if (resp.status === 404) return null;
27  if (!resp.ok) throw new Error(`code map read failed for ${repoFull} (${resp.status})`);
28  const text = await resp.text();
29  if (text.length > MAX_FILE_BYTES) throw new Error(`code map for ${repoFull} is ${text.length} bytes, over ${MAX_FILE_BYTES}`);
30  return JSON.parse(text);
31}
32
33/**
34 * Reads and parses the code map of every repo of a public system. A repo with no map is
35 * left out; a map that fails the schema, or names another repo, throws, so the build keeps
36 * the last good document rather than publish one it did not check.
37 */
38export async function buildPublicCode(
39  env: Env,
40  model: SystemModel,
41  privacy: RepoPrivacy,
42  asOf: string,
43  read: (env: Env, repo: string) => Promise<unknown> = readCodeMap
44): Promise<PublicCode> {
45  const maps: PublicCode["maps"] = [];
46  for (const { system, repo } of publicRepos(model, privacy)) {
47    const raw = await read(env, repo);
48    if (raw === null) continue;
49    const parsed = CodeMapSchema.safeParse(raw);
50    if (!parsed.success) throw new Error(`code map for ${repo} is invalid: ${parsed.error.issues.slice(0, 3).map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
51    if (parsed.data.repo.toLowerCase() !== repo.toLowerCase()) throw new Error(`code map on ${repo} names ${parsed.data.repo}`);
52    maps.push({ ...parsed.data, repo, system });
53  }
54  return { version: 1, as_of: asOf, maps };
55}