app/lib/media/template-refs.mjs

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1// Runs at BUILD time and ships as a committed artifact: the Worker has no repository, and its ASSETS
2// binding can only fetch. The match is LITERAL, so a constructed path like `/diagrams/${id}.svg` is
3// invisible; that is why the library says "no reference found" rather than "unused".
4
5// `content/posts` is absent: post citations belong to the other tracker, and an asset must not claim both.
6export const SOURCE_ROOTS = ["app", "workers"];
7
8export const SOURCE_FILES = ["public/site.webmanifest", "content/features.json"];
9
10// Each paper's file names its PDF by path (`pdfPath`) and each dictionary entry its pronunciation clip (`audio`), so
11// these markdown files are sources: without them every hosted PDF and clip would read as unreferenced. Passed
12// through unstripped, like JSON: the extracted text has apostrophes. Each cohort's file under content/roster names its
13// photograph by path, so without it the nine photographs would read as unreferenced.
14export const SOURCE_DIRECTORIES = ["content/publications", "content/dictionary", "content/roster"];
15
16const SOURCE_EXTENSIONS = [".ts", ".tsx", ".mjs", ".js", ".css", ".json", ".webmanifest"];
17
18// Checked first because `SOURCE_FILES` bypass the root rule. `assets.json` lists every asset path.
19const SELF_REFERENTIAL = ["content/generated/assets.json"];
20
21/**
22 * @param {string} file repo-relative, forward slashes
23 * @returns {boolean}
24 */
25export function isSourceFile(file) {
26  if (SELF_REFERENTIAL.includes(file)) return false;
27  if (SOURCE_FILES.includes(file)) return true;
28  if (SOURCE_DIRECTORIES.some((dir) => file.startsWith(`${dir}/`) && file.endsWith(".md"))) return true;
29  const root = file.split("/")[0] ?? "";
30  if (!SOURCE_ROOTS.includes(root)) return false;
31  return SOURCE_EXTENSIONS.some((ext) => file.endsWith(ext));
32}
33
34/**
35 * Prose about an asset is not a reference. A tokenizer, not a regex: stripping from `//` to end of line
36 * would destroy every `https://` inside a string literal, which is where real references live.
37 *
38 * @param {string} text
39 * @param {boolean} [cssOnly] true for `.css`, which has no line comments
40 * @returns {string} the same length, with comment bytes blanked to spaces
41 */
42export function stripComments(text, cssOnly = false) {
43  let out = "";
44  let i = 0;
45  /** @type {"code"|"line"|"block"|"'"|"\""|"`"} */
46  let mode = "code";
47  while (i < text.length) {
48    const c = text[i];
49    const next = text[i + 1];
50    if (mode === "code") {
51      if (c === "/" && next === "*") { mode = "block"; out += "  "; i += 2; continue; }
52      if (!cssOnly && c === "/" && next === "/") { mode = "line"; out += "  "; i += 2; continue; }
53      if (!cssOnly && (c === "'" || c === '"' || c === "`")) { mode = c; out += c; i += 1; continue; }
54      if (cssOnly && (c === "'" || c === '"')) { mode = c; out += c; i += 1; continue; }
55      out += c; i += 1; continue;
56    }
57    if (mode === "line") {
58      if (c === "\n") { mode = "code"; out += c; i += 1; continue; }
59      // Blanked rather than deleted, so offsets stay comparable and lines cannot join.
60      out += " "; i += 1; continue;
61    }
62    if (mode === "block") {
63      if (c === "*" && next === "/") { mode = "code"; out += "  "; i += 2; continue; }
64      out += c === "\n" ? c : " "; i += 1; continue;
65    }
66    if (c === "\\") { out += text.slice(i, i + 2); i += 2; continue; }
67    if (c === mode) { mode = "code"; out += c; i += 1; continue; }
68    out += c; i += 1;
69  }
70  return out;
71}
72
73/**
74 * Both ends must be boundaries: `/dustin-edwards-logo.svg` is a prefix of `/dustin-edwards-logo-dark.svg`,
75 * and `"public/site.webmanifest"` ends with `/site.webmanifest`.
76 *
77 * @param {string} text the file contents
78 * @param {string[]} assetPaths every known asset path
79 * @returns {string[]} the subset referenced, in the order given
80 */
81export function referencesIn(text, assetPaths) {
82  return assetPaths.filter((asset) => {
83    let from = 0;
84    for (;;) {
85      const at = text.indexOf(asset, from);
86      if (at < 0) return false;
87      const before = at === 0 ? undefined : text[at - 1];
88      const after = text[at + asset.length];
89      /** @param {string | undefined} ch */
90      const bounded = (ch) => ch === undefined || !/[A-Za-z0-9._~/-]/.test(ch);
91      if (bounded(before) && bounded(after)) return true;
92      from = at + 1;
93    }
94  });
95}
96
97/**
98 * Sorted, so the generated artifact does not churn with directory order and a gate can byte-compare it.
99 *
100 * @param {Array<{ file: string, assets: string[] }>} scanned
101 * @returns {{ generated: number, refs: Record<string, string[]> }}
102 */
103export function foldRefs(scanned) {
104  /** @type {Record<string, string[]>} */
105  const refs = {};
106  for (const { file, assets } of scanned) {
107    for (const asset of assets) {
108      if (!refs[asset]) refs[asset] = [];
109      if (!refs[asset].includes(file)) refs[asset].push(file);
110    }
111  }
112  /** @type {Record<string, string[]>} */
113  const sorted = {};
114  for (const asset of Object.keys(refs).sort()) sorted[asset] = (refs[asset] ?? []).slice().sort();
115  return { generated: Object.keys(sorted).length, refs: sorted };
116}