@ogygie/core 0.18.0 → 0.20.0

package/src/repo-adapter-github.test.ts

@@ -0,0 +1,179 @@
+/**
+ * @intent Proves the GitHub API implementation of `RepoAdapter` (D51) against
+ * a fake `fetch`: one snapshot per adapter (the ref is resolved once), the
+ * listing comes from one recursive tree, dot-directories and node_modules stay
+ * out of it, the traversal guard refuses before any request, and every
+ * failure mode a plausible answer could hide — a truncated tree, a directory
+ * asked as a file, a large file served by the blob endpoint — is said loudly.
+ */
+import { describe, expect, it } from "vitest";
+import { OgygieFailure } from "./error.schema.js";
+import { createGithubApiRepoAdapter, normalizeRepoPath } from "./repo-adapter-github.js";
+
+const BASE = "https://api.github.com/repos/acme/site";
+
+function fakeFetch(routes: Record<string, { status: number; body?: unknown }>) {
+  const calls: { url: string; headers: Record<string, string> }[] = [];
+  const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = String(input);
+    calls.push({ url, headers: init?.headers as Record<string, string> });
+    const route = routes[url.replace(BASE, "")];
+    if (route === undefined) return new Response("not found", { status: 404 });
+    return new Response(route.body === undefined ? null : JSON.stringify(route.body), { status: route.status });
+  }) as typeof fetch;
+  return { fetchImpl, calls };
+}
+
+const b64 = (text: string): string => Buffer.from(text, "utf8").toString("base64");
+
+const SNAPSHOT = {
+  "/commits/main": { status: 200, body: { sha: "c0ffee" } },
+  "/git/trees/c0ffee?recursive=1": {
+    status: 200,
+    body: {
+      truncated: false,
+      tree: [
+        { path: "AGENTS.md", type: "blob", size: 6 },
+        { path: "specs", type: "tree" },
+        { path: "specs/notes.spec.md", type: "blob", size: 12 },
+        { path: "specs/orders.spec.md", type: "blob", size: 30 },
+        { path: ".github/workflows/ci.yml", type: "blob", size: 9 },
+        { path: "node_modules/left-pad/index.js", type: "blob", size: 20 },
+        { path: "apps/api/src/features/orders/schemas.ts", type: "blob", size: 18 },
+      ],
+    },
+  },
+  "/contents/AGENTS.md?ref=c0ffee": {
+    status: 200,
+    body: { type: "file", encoding: "base64", content: b64("règles"), sha: "blob1" },
+  },
+  "/contents/specs?ref=c0ffee": { status: 200, body: [{ name: "notes.spec.md" }] },
+  "/contents/big.bin?ref=c0ffee": {
+    status: 200,
+    body: { type: "file", encoding: "none", content: "", sha: "blobbig" },
+  },
+  "/git/blobs/blobbig": { status: 200, body: { content: b64("gros fichier"), encoding: "base64" } },
+};
+
+function adapterOn(routes: Record<string, { status: number; body?: unknown }> = SNAPSHOT) {
+  const { fetchImpl, calls } = fakeFetch(routes);
+  const adapter = createGithubApiRepoAdapter({ owner: "acme", repo: "site", ref: "main", fetchImpl, token: "tkn" });
+  return { adapter, calls };
+}
+
+async function codeOf(action: () => Promise<unknown>): Promise<string> {
+  try {
+    await action();
+    return "<no refusal>";
+  } catch (thrown) {
+    return thrown instanceof OgygieFailure ? thrown.error.code : "<not an OgygieFailure>";
+  }
+}
+
+describe("repo-adapter-github — la garde textuelle, avant toute requête", () => {
+  it.each(["/etc/passwd", "C:\\secrets", "../outside", "specs/../../x", "a/./../.."])(
+    "%s → PATH_OUTSIDE_REPO",
+    async (path) => {
+      const { adapter, calls } = adapterOn();
+      expect(await codeOf(() => adapter.readFile(path))).toBe("PATH_OUTSIDE_REPO");
+      expect(await codeOf(() => adapter.listDirectory(path))).toBe("PATH_OUTSIDE_REPO");
+      expect(await codeOf(() => adapter.exists(path))).toBe("PATH_OUTSIDE_REPO");
+      expect(calls).toEqual([]);
+    },
+  );
+
+  it("normalise `./specs/` et `specs` sur le même chemin", () => {
+    expect(normalizeRepoPath("./specs/")).toBe("specs");
+    expect(normalizeRepoPath("specs")).toBe("specs");
+    expect(normalizeRepoPath("")).toBe("");
+  });
+});
+
+describe("repo-adapter-github — un adaptateur, un instantané", () => {
+  it("ÉTANT DONNÉ une branche QUAND on lit le ref ALORS c'est le SHA du commit, résolu UNE fois", async () => {
+    const { adapter, calls } = adapterOn();
+    expect(await adapter.currentRef()).toBe("c0ffee");
+    expect(await adapter.currentRef()).toBe("c0ffee");
+    await adapter.listDirectory("specs");
+    expect(calls.filter((call) => call.url.endsWith("/commits/main"))).toHaveLength(1);
+    expect(calls[0]?.headers["authorization"]).toBe("Bearer tkn");
+    expect(calls[0]?.headers["user-agent"]).toBeDefined();
+  });
+
+  it("lit un fichier à ce SHA, décodé du base64", async () => {
+    const { adapter, calls } = adapterOn();
+    expect(await adapter.readFile("AGENTS.md")).toBe("règles");
+    expect(calls.some((call) => call.url.endsWith("/contents/AGENTS.md?ref=c0ffee"))).toBe(true);
+  });
+
+  it("un fichier trop gros pour l'endpoint contents est lu par son blob", async () => {
+    const { adapter } = adapterOn();
+    expect(await adapter.readFile("big.bin")).toBe("gros fichier");
+  });
+
+  it("un chemin absent, ou un dossier demandé comme fichier → REPO_FILE_NOT_FOUND", async () => {
+    const { adapter } = adapterOn();
+    expect(await codeOf(() => adapter.readFile("nope.md"))).toBe("REPO_FILE_NOT_FOUND");
+    expect(await codeOf(() => adapter.readFile("specs"))).toBe("REPO_FILE_NOT_FOUND");
+  });
+
+  it("liste RÉCURSIVEMENT depuis UN arbre, triée, relative au dossier, sans dot-dirs ni node_modules", async () => {
+    const { adapter, calls } = adapterOn();
+    expect(await adapter.listDirectory("specs")).toEqual([
+      { path: "notes.spec.md", sizeBytes: 12 },
+      { path: "orders.spec.md", sizeBytes: 30 },
+    ]);
+    expect((await adapter.listDirectory("")).map((entry) => entry.path)).toEqual([
+      "AGENTS.md",
+      "apps/api/src/features/orders/schemas.ts",
+      "specs/notes.spec.md",
+      "specs/orders.spec.md",
+    ]);
+    expect(await adapter.listDirectory("missing")).toEqual([]);
+    expect(calls.filter((call) => call.url.includes("/git/trees/"))).toHaveLength(1);
+  });
+
+  it("exists répond vrai pour un fichier ET pour un dossier de l'arbre", async () => {
+    const { adapter } = adapterOn();
+    expect(await adapter.exists("specs/orders.spec.md")).toBe(true);
+    expect(await adapter.exists("specs")).toBe(true);
+    expect(await adapter.exists("apps/api")).toBe(true);
+    expect(await adapter.exists("spec")).toBe(false);
+    expect(await adapter.exists("")).toBe(true);
+  });
+});
+
+describe("repo-adapter-github — ce qu'une réponse plausible pourrait cacher", () => {
+  it("un ref inconnu → GITHUB_UNAVAILABLE qui nomme le ref, jamais null", async () => {
+    const { adapter } = adapterOn({});
+    expect(await codeOf(() => adapter.currentRef())).toBe("GITHUB_UNAVAILABLE");
+  });
+
+  it("un arbre tronqué → REPO_TREE_TRUNCATED, jamais une liste partielle", async () => {
+    const { adapter } = adapterOn({
+      "/commits/main": { status: 200, body: { sha: "c0ffee" } },
+      "/git/trees/c0ffee?recursive=1": { status: 200, body: { truncated: true, tree: [] } },
+    });
+    expect(await codeOf(() => adapter.listDirectory(""))).toBe("REPO_TREE_TRUNCATED");
+  });
+
+  it("401 → GITHUB_UNAVAILABLE pointant le jeton ; panne réseau → GITHUB_UNAVAILABLE aussi", async () => {
+    const { adapter } = adapterOn({ "/commits/main": { status: 401 } });
+    try {
+      await adapter.currentRef();
+      expect.fail("expected a refusal");
+    } catch (thrown) {
+      expect(thrown).toBeInstanceOf(OgygieFailure);
+      expect((thrown as OgygieFailure).error.suggestedFix).toContain("token");
+    }
+    const down = createGithubApiRepoAdapter({
+      owner: "acme",
+      repo: "site",
+      ref: "main",
+      fetchImpl: (async () => {
+        throw new Error("ECONNRESET");
+      }) as typeof fetch,
+    });
+    expect(await codeOf(() => down.exists("AGENTS.md"))).toBe("GITHUB_UNAVAILABLE");
+  });
+});

package/src/repo-adapter-github.ts

@@ -0,0 +1,225 @@
+/**
+ * @intent READ-ONLY access to an Ogygie repo through the GitHub REST API, at
+ * one ref, without a clone (DECISIONS.md D51) — the third implementation of
+ * `RepoAdapter` (D10), next to the filesystem and the in-memory ones.
+ *
+ * Why it exists: the hosted studio (spec ogygie-hosted-mode) reads the default
+ * branch AND every `spec/<id>` branch of a client repo, and must do so without
+ * a clone on its host — the host runs no git, no disk of the repo, nothing a
+ * client's code could reach. The MCP server deferred this adapter for the same
+ * reason (spec ogygie-mcp, `GITHUB_API_ADAPTER`).
+ *
+ * One adapter = one SNAPSHOT: the ref is resolved to a commit SHA on first
+ * use and every later call reads at that SHA, so a listing and the file read
+ * after it never come from two different commits. A consumer that wants the
+ * new head builds a new adapter — the same contract as the filesystem one,
+ * which reads "the repo as it sits on this disk, at this instant".
+ *
+ * No dependency, on purpose: `fetch` is INJECTED (AGENTS.md principle 5), so
+ * the tests hand in a fake and a purity gate finds neither `node:fs` nor
+ * `node:child_process` here. The textual traversal guard is the same rule as
+ * the filesystem adapter's: an absolute path or a `..` segment never reaches
+ * the network.
+ */
+import { throwOgygieError } from "./error.schema.js";
+import type { RepoAdapter, RepoFileEntry } from "./repo-adapter.js";
+
+export interface GithubApiRepoAdapterOptions {
+  owner: string;
+  repo: string;
+  /** Branch name, tag or commit SHA — resolved once to a commit SHA. */
+  ref: string;
+  fetchImpl: typeof fetch;
+  /** Absent on a public repo read anonymously (rate-limited by GitHub). */
+  token?: string;
+  apiBase?: string;
+  /** Sent as `user-agent`, which the GitHub API requires on every call. */
+  userAgent?: string;
+}
+
+/** What the trees endpoint answers, reduced to what a listing needs. */
+interface TreeEntry {
+  path: string;
+  type: "blob" | "tree" | "commit";
+  size?: number;
+}
+
+/** Directories a listing never shows — the filesystem adapter's rule, kept. */
+const NEVER_LISTED = new Set(["node_modules"]);
+
+function isSkippedSegment(segment: string): boolean {
+  return segment.startsWith(".") || NEVER_LISTED.has(segment);
+}
+
+function refusePathOutsideRepo(relativePath: string, cause: string): never {
+  return throwOgygieError(
+    {
+      code: "PATH_OUTSIDE_REPO",
+      message: "The requested path resolves outside the repo root.",
+      file: relativePath,
+      cause,
+      suggestedFix:
+        "Address a path INSIDE the repo, written relative to its root and without `..`.",
+    },
+    400,
+  );
+}
+
+/**
+ * Textual guard, the only one possible without a disk: no absolute path, no
+ * `..` segment. `.` segments and empty segments are dropped so `./specs/` and
+ * `specs` name the same directory, as they do on a filesystem.
+ */
+export function normalizeRepoPath(relativePath: string): string {
+  if (relativePath.startsWith("/") || /^[A-Za-z]:[\\/]/.test(relativePath)) {
+    refusePathOutsideRepo(relativePath, `"${relativePath}" is an absolute path`);
+  }
+  const segments = relativePath.split(/[\\/]+/).filter((segment) => segment !== "" && segment !== ".");
+  if (segments.includes("..")) {
+    refusePathOutsideRepo(relativePath, `"${relativePath}" climbs out of the repo with ".."`);
+  }
+  return segments.join("/");
+}
+
+export function createGithubApiRepoAdapter(options: GithubApiRepoAdapterOptions): RepoAdapter {
+  const apiBase = options.apiBase ?? "https://api.github.com";
+  const repoUrl = `${apiBase}/repos/${options.owner}/${options.repo}`;
+  const where = `${options.owner}/${options.repo}@${options.ref}`;
+
+  async function request<T>(url: string, allowNotFound: boolean): Promise<T | null> {
+    let response: Response;
+    try {
+      response = await options.fetchImpl(url, {
+        method: "GET",
+        headers: {
+          accept: "application/vnd.github+json",
+          "x-github-api-version": "2022-11-28",
+          "user-agent": options.userAgent ?? "ogygie-core",
+          ...(options.token === undefined ? {} : { authorization: `Bearer ${options.token}` }),
+        },
+      });
+    } catch (thrown) {
+      return throwOgygieError({
+        code: "GITHUB_UNAVAILABLE",
+        message: `GitHub could not be reached to read ${where}.`,
+        file: null,
+        cause: thrown instanceof Error ? thrown.message : String(thrown),
+        suggestedFix: "Retry once the network is back — a read has no side effect to undo.",
+      });
+    }
+    if (response.status === 404 && allowNotFound) return null;
+    if (!response.ok) {
+      return throwOgygieError({
+        code: "GITHUB_UNAVAILABLE",
+        message: `GitHub answered ${response.status} for GET ${url.replace(apiBase, "")}.`,
+        file: null,
+        cause: `status=${response.status}`,
+        suggestedFix:
+          response.status === 401 || response.status === 403
+            ? "Check the GitHub token: it must grant contents (read) on this repo."
+            : "Retry later — a read has no side effect to undo.",
+      });
+    }
+    return (await response.json()) as T;
+  }
+
+  // The snapshot: resolved once, shared by every call of this adapter.
+  let commitShaPromise: Promise<string> | null = null;
+  let treePromise: Promise<TreeEntry[]> | null = null;
+
+  function commitSha(): Promise<string> {
+    commitShaPromise ??= (async () => {
+      const commit = await request<{ sha: string }>(
+        `${repoUrl}/commits/${encodeURIComponent(options.ref)}`,
+        true,
+      );
+      if (commit === null) {
+        return throwOgygieError({
+          code: "GITHUB_UNAVAILABLE",
+          message: `Ref "${options.ref}" does not exist on ${options.owner}/${options.repo}.`,
+          file: null,
+          cause: "the commits endpoint answered 404 for that ref",
+          suggestedFix: "Name an existing branch, tag or commit SHA of that repo.",
+        });
+      }
+      return commit.sha;
+    })();
+    return commitShaPromise;
+  }
+
+  function tree(): Promise<TreeEntry[]> {
+    treePromise ??= (async () => {
+      const sha = await commitSha();
+      const answer = await request<{ tree: TreeEntry[]; truncated: boolean }>(
+        `${repoUrl}/git/trees/${sha}?recursive=1`,
+        false,
+      );
+      if (answer === null) return [];
+      if (answer.truncated) {
+        // A partial listing would say "absent" about files that exist — the
+        // silent lie this framework refuses. Said loudly instead.
+        return throwOgygieError({
+          code: "REPO_TREE_TRUNCATED",
+          message: `The tree of ${where} is too large for one GitHub answer.`,
+          file: null,
+          cause: "the trees endpoint set truncated=true",
+          suggestedFix: "Read that repo from a clone (createFilesystemRepoAdapter) rather than through the API.",
+        });
+      }
+      return answer.tree.filter(
+        (entry) =>
+          entry.type === "blob" && !entry.path.split("/").slice(0, -1).some(isSkippedSegment),
+      );
+    })();
+    return treePromise;
+  }
+
+  return {
+    async readFile(relativePath: string): Promise<string> {
+      const path = normalizeRepoPath(relativePath);
+      const sha = await commitSha();
+      const file = await request<
+        { content?: string; encoding?: string; sha: string; type?: string } | unknown[]
+      >(`${repoUrl}/contents/${path}?ref=${sha}`, true);
+      if (file === null || Array.isArray(file) || file.type !== "file") {
+        return throwOgygieError({
+          code: "REPO_FILE_NOT_FOUND",
+          message: "The requested file cannot be read from the repo.",
+          file: relativePath,
+          cause:
+            file === null
+              ? `no file at "${path}" in ${where}`
+              : `"${path}" is not a file in ${where}`,
+          suggestedFix:
+            "Check the path against what the map declares — the manifest is the only chart of a repo.",
+        });
+      }
+      if (file.encoding === "base64" && file.content !== undefined) {
+        return Buffer.from(file.content, "base64").toString("utf8");
+      }
+      // Above 1 MB the contents endpoint ships no content: the blob does.
+      const blob = await request<{ content: string }>(`${repoUrl}/git/blobs/${file.sha}`, false);
+      return Buffer.from(blob?.content ?? "", "base64").toString("utf8");
+    },
+
+    async listDirectory(relativePath: string): Promise<RepoFileEntry[]> {
+      const path = normalizeRepoPath(relativePath);
+      const prefix = path === "" ? "" : `${path}/`;
+      return (await tree())
+        .filter((entry) => entry.path.startsWith(prefix))
+        .map((entry) => ({ path: entry.path.slice(prefix.length), sizeBytes: entry.size ?? 0 }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    },
+
+    async exists(relativePath: string): Promise<boolean> {
+      const path = normalizeRepoPath(relativePath);
+      if (path === "") return true;
+      const prefix = `${path}/`;
+      return (await tree()).some((entry) => entry.path === path || entry.path.startsWith(prefix));
+    },
+
+    async currentRef(): Promise<string | null> {
+      return commitSha();
+    },
+  };
+}

package/src/repo-adapter.ts

@@ -305,3 +305,14 @@ export function createInMemoryRepoAdapter(
     },
   };
 }
+
+/**
+ * The third implementation, over the GitHub REST API without a clone (D51):
+ * declared in its own module so a consumer that must prove it never touches a
+ * disk (the hosted studio) can import it without dragging `node:fs` along.
+ */
+export {
+  createGithubApiRepoAdapter,
+  normalizeRepoPath,
+  type GithubApiRepoAdapterOptions,
+} from "./repo-adapter-github.js";

package/src/spec.schema.test.ts

@@ -7,7 +7,7 @@
  * rejection of a non-kebab-case blockedBy target.
  */
 import { describe, expect, it } from "vitest";
-import { SpecFrontmatterSchema, parseSpecFrontmatter } from "./spec.schema.js";
+import { SpecFrontmatterSchema, compositionOfSpec, parseSpecDocument, parseSpecFrontmatter } from "./spec.schema.js";
 
 const NOMINAL_FRONTMATTER = `
 id: order-flow
@@ -141,3 +141,41 @@ status: validated
     ).toBe(true);
   });
 });
+
+describe("parseSpecDocument — la spec entière, frontmatter jugé et corps toujours rendu (D51)", () => {
+  const VALID = "---\nid: orders\nstatus: draft\ndepends_on: []\npriority: P1\n---\n\n# @intent\nCommander.\n";
+
+  it("ÉTANT DONNÉ un frontmatter valide ALORS il est parsé ET validé, le corps commence après le bloc", () => {
+    const parsed = parseSpecDocument(VALID);
+    expect(parsed.problems).toEqual([]);
+    expect(parsed.frontmatter?.id).toBe("orders");
+    expect(parsed.frontmatter?.refs).toEqual([]); // the schema's default applies
+    expect(parsed.body).toBe("\n\n# @intent\nCommander.\n");
+  });
+
+  it("ÉTANT DONNÉ un fichier sans bloc --- ALORS frontmatter null, un problème nommé, et le fichier ENTIER en corps", () => {
+    const parsed = parseSpecDocument("# @intent\nSans frontmatter.\n");
+    expect(parsed.frontmatter).toBeNull();
+    expect(parsed.problems).toHaveLength(1);
+    expect(parsed.body).toBe("# @intent\nSans frontmatter.\n");
+  });
+
+  it("MUTATION — un frontmatter au format illisible, ou au schéma violé, rend ses problèmes et jamais un frontmatter partiel", () => {
+    const badFormat = parseSpecDocument(VALID.replace("depends_on: []", "depends_on: ["));
+    expect(badFormat.frontmatter).toBeNull();
+    expect(badFormat.problems.length).toBeGreaterThan(0);
+    const badSchema = parseSpecDocument(VALID.replace("priority: P1", "priority: P9"));
+    expect(badSchema.frontmatter).toBeNull();
+    expect(badSchema.problems.some((problem) => problem.startsWith("priority"))).toBe(true);
+  });
+});
+
+describe("compositionOfSpec — la composition déclarée sous # Design (D53)", () => {
+  it("lit `Composition : <nom>` dans la section Design seulement, en kebab-case, sinon null", () => {
+    const spec = "# @intent\nx\n\n# Design\n\n- Tokens du starter.\n- Composition : `liste-d-abord` — la liste puis le formulaire.\n\n# Non-objectifs\nComposition : ailleurs\n";
+    expect(compositionOfSpec(spec)).toBe("liste-d-abord");
+    expect(compositionOfSpec("# @intent\nComposition : hors-section\n")).toBeNull();
+    expect(compositionOfSpec("# Design\ncomposition: Formulaire\n")).toBeNull();
+    expect(compositionOfSpec("# Design\nRien.\n")).toBeNull();
+  });
+});

package/src/spec.schema.ts

@@ -182,3 +182,66 @@ export function parseSpecFrontmatter(text: string): ParsedSpecFrontmatter {
   }
   return { value, problems };
 }
+
+// ---------------------------------------------------------- whole document
+/**
+ * A spec file read as a whole: the frontmatter PARSED and VALIDATED, or the
+ * problems that prevent it, and the body in every case. A broken spec comes
+ * back WITH its body: a client asked to repair one needs to see it, and a bare
+ * refusal would leave it blind (spec ogygie-mcp B3). Shared by the MCP server
+ * and the proposal module (D51), so "what a readable spec is" is said once.
+ */
+export interface ParsedSpecDocument {
+  frontmatter: SpecFrontmatter | null;
+  /** Format or schema problems; non-empty ⇔ `frontmatter` is null. */
+  problems: string[];
+  /** Everything after the frontmatter block — the whole file when there is none. */
+  body: string;
+}
+
+const FRONTMATTER_BLOCK = /^---\n([\s\S]*?)\n---/;
+
+export function parseSpecDocument(content: string): ParsedSpecDocument {
+  const match = FRONTMATTER_BLOCK.exec(content);
+  if (match === null || match[1] === undefined) {
+    return {
+      frontmatter: null,
+      problems: ["file does not start with a --- ... --- frontmatter block"],
+      body: content,
+    };
+  }
+  const body = content.slice(match[0].length);
+  const parsed = parseSpecFrontmatter(match[1]);
+  if (parsed.problems.length > 0) {
+    return { frontmatter: null, problems: parsed.problems, body };
+  }
+  const checked = SpecFrontmatterSchema.safeParse(parsed.value);
+  if (!checked.success) {
+    return {
+      frontmatter: null,
+      problems: checked.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`),
+      body,
+    };
+  }
+  return { frontmatter: checked.data, problems: [], body };
+}
+
+// ------------------------------------------------------------- # Design (D53)
+export const DESIGN_SECTION_TITLE = "Design";
+const COMPOSITION_LINE = /^\s*(?:[-*]\s*)?[Cc]omposition\s*:\s*`?([a-z][a-z0-9]*(?:-[a-z0-9]+)*)`?(?![A-Za-z0-9])/mu;
+
+/**
+ * The composition a spec declares in its `# Design` section (spec
+ * ogygie-hosted-mode B10, D53): a line `Composition : <kebab-name>`, the name
+ * the generator renders the screen's previews under and the studio lets the
+ * client choose between. Null when the spec declares none — then the screen
+ * has a single composition and its previews sit at the root of its folder.
+ */
+export function compositionOfSpec(content: string): string | null {
+  const heading = new RegExp(`^# ${DESIGN_SECTION_TITLE}\\s*$`, "mu").exec(content);
+  if (heading === null) return null;
+  const rest = content.slice(heading.index + heading[0].length);
+  const next = /^# /mu.exec(rest);
+  const section = next === null ? rest : rest.slice(0, next.index);
+  return COMPOSITION_LINE.exec(section)?.[1] ?? null;
+}