app/lib/publications/parse.mjs

Functions

Imports

It imports app/lib/yaml-plain.mjs. Imported by app/kb/registry/host.server.ts, app/lib/carrel/publication-handler.server.ts, app/lib/health/checks.server.ts, app/lib/operator/api.server.ts, app/lib/operator/sync-tools.server.ts, app/lib/phages/save.server.ts, app/lib/publications/compile.mjs, app/lib/publications/save.server.ts, app/lib/publications/serialize.mjs.

Source

1// Reads a publication file (docs/PUBLICATIONS.md) into the front matter as written and the one body
2// section it may carry, the extracted full text. Nothing here judges: validate.mjs does, so the check and
3// the save tool read one parse.
4
5import matter from "gray-matter";
6
7import { yamlPlain } from "../yaml-plain.mjs";
8
9export const PUBLICATIONS_DIR = "content/publications";
10
11/** The repository path of a publication's file. */
12export function publicationPath(/** @type {string} */ slug) {
13  return `${PUBLICATIONS_DIR}/${slug}.md`;
14}
15
16/** The only heading the body may carry. Everything after it is the PDF's extracted text. */
17export const FULL_TEXT_HEADING = "## Full text";
18
19const FULL_TEXT_LINE = /^## Full text[ \t]*$/m;
20
21/**
22 * @typedef {{ data: Record<string, unknown>, fullText: string | null, problems: string[] }} ParsedPublication
23 */
24
25/**
26 * @param {{ file: string, raw: string }} input
27 * @returns {ParsedPublication} `fullText` is null when the file has no Full text section, and a string (possibly empty) when it has.
28 */
29export function parsePublication({ file, raw }) {
30  /** @type {string[]} */
31  const problems = [];
32  /** @type {Record<string, unknown>} */
33  let data = {};
34  let content = "";
35  try {
36    // An options object, even an empty one: gray-matter caches by input when it is omitted, and a
37    // cached parse is one object shared by every caller.
38    const parsed = matter(raw, {});
39    data = /** @type {Record<string, unknown>} */ (yamlPlain(parsed.data));
40    content = parsed.content;
41  } catch (error) {
42    problems.push(`${file}: the front matter does not parse: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`);
43    return { data, fullText: null, problems };
44  }
45  if (!raw.startsWith("---")) {
46    problems.push(`${file}: the file must start with a --- front matter block`);
47  }
48
49  const heading = FULL_TEXT_LINE.exec(content);
50  if (!heading) {
51    if (content.trim() !== "") {
52      problems.push(
53        `${file}: the body carries text outside a "${FULL_TEXT_HEADING}" section. The abstract belongs in front matter, and the body holds only the PDF's extracted text under that heading.`,
54      );
55    }
56    return { data, fullText: null, problems };
57  }
58  const before = content.slice(0, heading.index).trim();
59  if (before !== "") {
60    problems.push(
61      `${file}: the body carries text before the "${FULL_TEXT_HEADING}" heading. The abstract belongs in front matter, and the body holds only the PDF's extracted text.`,
62    );
63  }
64  const fullText = content.slice(heading.index + heading[0].length).trim();
65  return { data, fullText, problems };
66}