@chartcoach/catalog 0.1.6 → 0.2.0

package/src/catalog/references.ts

@@ -0,0 +1,336 @@
+import { BibDocument, Document, init, Library, ParseError, Style } from "refkit-js";
+import { CatalogError } from "./errors";
+import { canonicalJson, compareUnicode } from "./identity";
+import { isJsonString, type JsonObject } from "./json";
+import type { Catalog } from "./model";
+
+await init();
+
+const citationStyle = Style.load("apa");
+
+const DEFAULT_GUIDELINE_URL_TEMPLATE = "https://chartcoach.dev/guidelines/{id}";
+
+export type MinimalSourceRecord = Readonly<{
+  reference_id: string;
+  authors_text: string | null;
+  year: string | null;
+  source_title: string | null;
+  doi: string | null;
+  url: string | null;
+}>;
+
+export type FullSourceRecord = Readonly<{
+  guideline_id: string;
+  reference_id: string;
+  source_type: string | null;
+  authors: readonly string[];
+  authors_text: string | null;
+  year: string | null;
+  source_title: string | null;
+  journal: string | null;
+  booktitle: string | null;
+  publisher: string | null;
+  url: string | null;
+  doi: string | null;
+}>;
+
+export type CitationSource = Readonly<{
+  reference_id: string;
+  source_type: string | null;
+  authors_text: string | null;
+  year: string | null;
+  source_title: string | null;
+  journal: string | null;
+  booktitle: string | null;
+  publisher: string | null;
+  doi: string | null;
+  url: string | null;
+  citation: string;
+}>;
+
+export type CiteOptions = Readonly<{
+  ids: readonly string[];
+  urlTemplate?: string;
+}>;
+
+export type CitationRecord = Readonly<{
+  id: string;
+  title: string;
+  url: string;
+  guideline_citation: string;
+  sources: readonly CitationSource[];
+}>;
+
+type ParsedReference = Readonly<{
+  id: string;
+  bibtex: string;
+  sourceType: string;
+  authors: readonly string[];
+  authorsText: string | null;
+  year: string | null;
+  title: string | null;
+  journal: string | null;
+  booktitle: string | null;
+  publisher: string | null;
+  url: string | null;
+  doi: string | null;
+  fingerprint: string;
+  citation: string;
+}>;
+
+type ReferenceIndex = Readonly<{
+  byId: ReadonlyMap<string, ParsedReference>;
+  idsByGuideline: ReadonlyMap<string, readonly string[]>;
+}>;
+
+const indexes = new WeakMap<Catalog, ReferenceIndex>();
+
+export function sourceRecords(
+  catalog: Catalog,
+  guidelineId: string,
+  detail: "minimal" | "full",
+): readonly (MinimalSourceRecord | FullSourceRecord)[] {
+  const index = referenceIndex(catalog);
+  const ids = index.idsByGuideline.get(guidelineId) ?? [];
+
+  return Object.freeze(
+    ids.map((id) => {
+      const reference = index.byId.get(id)!;
+
+      return detail === "minimal" ? minimalSource(reference) : fullSource(guidelineId, reference);
+    }),
+  );
+}
+
+export function citationRecords(catalog: Catalog, options: CiteOptions): readonly CitationRecord[] {
+  if (Object.prototype.toString.call(options) !== "[object Object]") {
+    throw new CatalogError("Citation options must be an object.");
+  }
+
+  if (!Array.isArray(options.ids) || !options.ids.every(isJsonString)) {
+    throw new CatalogError("ids must be an array of strings.");
+  }
+
+  const urlTemplate = options.urlTemplate ?? DEFAULT_GUIDELINE_URL_TEMPLATE;
+
+  if (!isJsonString(urlTemplate) || !urlTemplate.includes("{id}")) {
+    throw new CatalogError("Guideline URL template must include `{id}`.", {
+      hints: [`Use a template such as \`${DEFAULT_GUIDELINE_URL_TEMPLATE}\`.`],
+    });
+  }
+
+  if (options.ids.length === 0) return Object.freeze([]);
+
+  const index = referenceIndex(catalog);
+
+  return Object.freeze(
+    options.ids.map((id) => {
+      const guideline = catalog.require(id);
+      const url = urlTemplate.replace("{id}", id);
+
+      const sources = Object.freeze(
+        (index.idsByGuideline.get(id) ?? []).map((referenceId) =>
+          citationSource(index.byId.get(referenceId)!),
+        ),
+      );
+
+      return Object.freeze({
+        id,
+        title: guideline.title,
+        url,
+        guideline_citation: `[${guideline.title}](${url}) (\`${id}\`)`,
+        sources,
+      });
+    }),
+  );
+}
+
+export function referenceIndex(catalog: Catalog): ReferenceIndex {
+  const cached = indexes.get(catalog);
+
+  if (cached) return cached;
+
+  const byId = new Map<string, ParsedReference>();
+  const parsed = new Map<string, ParsedReference>();
+  const idsByGuideline = new Map<string, readonly string[]>();
+
+  for (const guideline of catalog.guidelines) {
+    const ids = new Set<string>();
+
+    for (const bibtex of guideline.references) {
+      let reference = parsed.get(bibtex);
+
+      if (!reference) {
+        reference = parseReference(bibtex);
+        parsed.set(bibtex, reference);
+      }
+
+      const previous = byId.get(reference.id);
+
+      if (previous && previous.fingerprint !== reference.fingerprint) {
+        throw new CatalogError(
+          `Conflicting BibTeX definitions for reference id: ${reference.id}.`,
+          {
+            details: { reference_id: reference.id },
+          },
+        );
+      }
+
+      byId.set(
+        reference.id,
+        previous && compareUnicode(previous.bibtex, reference.bibtex) <= 0 ? previous : reference,
+      );
+      ids.add(reference.id);
+    }
+
+    idsByGuideline.set(guideline.id, Object.freeze([...ids].sort(compareUnicode)));
+  }
+
+  const created = Object.freeze({ byId, idsByGuideline });
+  indexes.set(catalog, created);
+
+  return created;
+}
+
+function parseReference(bibtex: string): ParsedReference {
+  try {
+    return parsedReference(bibtex);
+  } catch (error) {
+    if (error instanceof CatalogError) throw error;
+
+    const details: JsonObject = {
+      exception_type: error instanceof Error ? error.name : "Error",
+    };
+
+    if (error instanceof ParseError) {
+      details.diagnostics = error.diagnostics.map((diagnostic) => ({ ...diagnostic }));
+    }
+
+    throw new CatalogError("BibTeX reference could not be parsed.", {
+      details,
+    });
+  }
+}
+
+function parsedReference(bibtex: string): ParsedReference {
+  const document = BibDocument.parse(bibtex);
+  const entries = document.resolve();
+
+  if (entries.length !== 1) {
+    throw new CatalogError(`Expected one BibTeX entry, found ${entries.length}.`);
+  }
+
+  const entry = entries[0]!;
+  const properties = entry.fields;
+  const authorsText = textOrNull(properties.author);
+
+  const authors = Object.freeze(
+    authorsText === null
+      ? []
+      : authorsText
+          .split(" and ")
+          .map((author) => author.trim())
+          .filter(Boolean),
+  );
+
+  return Object.freeze({
+    id: entry.key,
+    bibtex,
+    sourceType: entry.entryType,
+    authors,
+    authorsText,
+    year: textOrNull(properties.year),
+    title: textOrNull(properties.title),
+    journal: textOrNull(properties.journal),
+    booktitle: textOrNull(properties.booktitle),
+    publisher: textOrNull(properties.publisher),
+    url: referenceUrl(properties),
+    doi: textOrNull(properties.doi),
+    citation: new Document(
+      Library.parseBibtex(document.tidy().bibtex, { recovery: "report" }),
+      citationStyle,
+      {
+        locale: "en-US",
+      },
+    ).fullBibliography().text,
+    fingerprint: canonicalJson({
+      type: entry.entryType,
+      label: entry.key,
+      properties: { ...properties },
+    }),
+  });
+}
+
+function minimalSource(reference: ParsedReference): MinimalSourceRecord {
+  return Object.freeze({
+    reference_id: reference.id,
+    authors_text: reference.authorsText,
+    year: reference.year,
+    source_title: reference.title,
+    doi: reference.doi,
+    url: reference.url,
+  });
+}
+
+function fullSource(guidelineId: string, reference: ParsedReference): FullSourceRecord {
+  return Object.freeze({
+    guideline_id: guidelineId,
+    reference_id: reference.id,
+    source_type: reference.sourceType,
+    authors: reference.authors,
+    authors_text: reference.authorsText,
+    year: reference.year,
+    source_title: reference.title,
+    journal: reference.journal,
+    booktitle: reference.booktitle,
+    publisher: reference.publisher,
+    url: reference.url,
+    doi: reference.doi,
+  });
+}
+
+function citationSource(reference: ParsedReference): CitationSource {
+  const source = {
+    reference_id: reference.id,
+    source_type: reference.sourceType,
+    authors_text: reference.authorsText,
+    year: reference.year,
+    source_title: reference.title,
+    journal: reference.journal,
+    booktitle: reference.booktitle,
+    publisher: reference.publisher,
+    doi: reference.doi,
+    url: reference.url,
+  };
+
+  const locators = [source.doi ? doiUrl(source.doi) : null, source.url].filter(
+    (value): value is string => value !== null && !reference.citation.includes(value),
+  );
+
+  return Object.freeze({
+    ...source,
+    citation: [reference.citation, ...new Set(locators)].join(" "),
+  });
+}
+
+function textOrNull(value: string | undefined): string | null {
+  if (value === undefined) return null;
+  const text = value.trim();
+
+  return text || null;
+}
+
+function referenceUrl(properties: Readonly<Record<string, string>>): string | null {
+  const explicit = textOrNull(properties.url);
+  const value = explicit ?? textOrNull(properties.howpublished);
+
+  if (value === null) return null;
+  const wrapped = /^\\url\{([^{}]*)\}$/.exec(value);
+  const candidate = wrapped?.[1] ?? value;
+
+  return /^https?:\/\/[^\s{}\\/?#]+[^\s{}\\]*$/i.test(candidate) ? candidate : explicit;
+}
+
+function doiUrl(value: string): string {
+  return `https://doi.org/${value.replace(/^https?:\/\/doi\.org\//, "")}`;
+}

package/src/catalog/registration.ts

@@ -0,0 +1,74 @@
+import type { Catalog } from "./model";
+import { CatalogError } from "./errors";
+import { isJsonString } from "./json";
+import { tableNames, tableSchemas, type CatalogTables, type TableColumnInfo } from "./tables";
+
+export type RegisterCatalogOptions = Readonly<{ ids?: readonly string[] }>;
+
+export function registrationPlan(
+  catalog: Catalog,
+  options: RegisterCatalogOptions,
+  source: "parameter" | "file",
+): readonly Readonly<{ sql: string; rows: string }>[] {
+  if (Object.prototype.toString.call(options) !== "[object Object]")
+    throw new CatalogError("Registration options must be an object.");
+
+  if (
+    options.ids !== undefined &&
+    (!Array.isArray(options.ids) || !options.ids.every(isJsonString))
+  )
+    throw new CatalogError("ids must be an array of strings.");
+  const ids = options.ids === undefined ? undefined : new Set(options.ids);
+
+  for (const id of ids ?? []) catalog.require(id);
+  const tables = selectedTables(catalog, ids);
+  const json = source === "file" ? "(SELECT content FROM read_text(?))" : "?";
+
+  return tableNames.map((name) => {
+    const columns = tableSchemas[name]
+      .map(({ name, type }) => `"${name}" ${sqlType(type)}`)
+      .join(", ");
+
+    return {
+      sql: `CREATE OR REPLACE TABLE "${name}" AS SELECT record.*
+       FROM UNNEST(CAST(CAST(${json} AS JSON) AS STRUCT(${columns})[])) AS records(record)`,
+      rows: JSON.stringify(tables[name]),
+    };
+  });
+}
+
+function selectedTables(catalog: Catalog, ids: ReadonlySet<string> | undefined): CatalogTables {
+  const links = catalog.table("guideline_references");
+  const selectedLinks = ids ? links.filter(({ guideline_id }) => ids.has(guideline_id)) : links;
+  const references = new Set(selectedLinks.map(({ reference_id }) => reference_id));
+
+  return {
+    guidelines: ids
+      ? catalog.table("guidelines").filter(({ id }) => ids.has(id))
+      : catalog.table("guidelines"),
+    sections: ids
+      ? catalog.table("sections").filter(({ guideline_id }) => ids.has(guideline_id))
+      : catalog.table("sections"),
+    guideline_labels: ids
+      ? catalog.table("guideline_labels").filter(({ guideline_id }) => ids.has(guideline_id))
+      : catalog.table("guideline_labels"),
+    references: ids
+      ? catalog.table("references").filter(({ id }) => references.has(id))
+      : catalog.table("references"),
+    guideline_references: selectedLinks,
+    guideline_sources: ids
+      ? catalog.table("guideline_sources").filter(({ guideline_id }) => ids.has(guideline_id))
+      : catalog.table("guideline_sources"),
+  };
+}
+
+function sqlType(type: TableColumnInfo["type"]): string {
+  switch (type) {
+    case "String":
+      return "VARCHAR";
+    case "List(String)":
+      return "VARCHAR[]";
+    case "List(Struct({'role': String, 'title': String, 'content': String}))":
+      return "STRUCT(role VARCHAR, title VARCHAR, content VARCHAR)[]";
+  }
+}

package/src/catalog/tables.ts

@@ -0,0 +1,250 @@
+import { CatalogError } from "./errors";
+import { compareUnicode } from "./identity";
+import { parseLabel } from "./labels";
+import type { Catalog, Guideline, GuidelineSection } from "./model";
+import { referenceIndex } from "./references";
+
+type ReferenceRow = Readonly<{
+  id: string;
+  source_type: string | null;
+  authors: readonly string[];
+  authors_text: string | null;
+  year: string | null;
+  title: string | null;
+  journal: string | null;
+  booktitle: string | null;
+  publisher: string | null;
+  url: string | null;
+  doi: string | null;
+  bibtex: string;
+}>;
+
+type GuidelineReferenceRow = Readonly<{
+  guideline_id: string;
+  reference_id: string;
+}>;
+
+export type CatalogTables = Readonly<{
+  guidelines: readonly Omit<Guideline, "references">[];
+  sections: readonly Readonly<GuidelineSection & { guideline_id: string }>[];
+  guideline_labels: readonly Readonly<{
+    guideline_id: string;
+    label: string;
+    family: string;
+    category: string;
+    modifier: string | null;
+  }>[];
+  references: readonly ReferenceRow[];
+  guideline_references: readonly GuidelineReferenceRow[];
+  guideline_sources: readonly Readonly<
+    Omit<ReferenceRow, "id" | "title"> & GuidelineReferenceRow & { source_title: string | null }
+  >[];
+}>;
+
+export type TableName = keyof CatalogTables;
+
+export type TableColumnInfo = Readonly<{
+  name: string;
+  type:
+    | "String"
+    | "List(String)"
+    | "List(Struct({'role': String, 'title': String, 'content': String}))";
+}>;
+
+export type TableInfo = Readonly<{
+  name: TableName;
+  rows: number;
+  columns: readonly TableColumnInfo[];
+}>;
+
+function columns(
+  schema: Readonly<Record<string, TableColumnInfo["type"]>>,
+): readonly TableColumnInfo[] {
+  return Object.freeze(Object.entries(schema).map(([name, type]) => Object.freeze({ name, type })));
+}
+
+export const tableSchemas: Readonly<Record<TableName, readonly TableColumnInfo[]>> = Object.freeze({
+  guidelines: columns({
+    id: "String",
+    title: "String",
+    description: "String",
+    labels: "List(String)",
+    body: "String",
+    sections: "List(Struct({'role': String, 'title': String, 'content': String}))",
+  }),
+  sections: columns({ guideline_id: "String", role: "String", title: "String", content: "String" }),
+  guideline_labels: columns({
+    guideline_id: "String",
+    label: "String",
+    family: "String",
+    category: "String",
+    modifier: "String",
+  }),
+  references: columns({
+    id: "String",
+    source_type: "String",
+    authors: "List(String)",
+    authors_text: "String",
+    year: "String",
+    title: "String",
+    journal: "String",
+    booktitle: "String",
+    publisher: "String",
+    url: "String",
+    doi: "String",
+    bibtex: "String",
+  }),
+  guideline_references: columns({ guideline_id: "String", reference_id: "String" }),
+  guideline_sources: columns({
+    guideline_id: "String",
+    reference_id: "String",
+    source_type: "String",
+    authors: "List(String)",
+    authors_text: "String",
+    year: "String",
+    source_title: "String",
+    journal: "String",
+    booktitle: "String",
+    publisher: "String",
+    url: "String",
+    doi: "String",
+    bibtex: "String",
+  }),
+});
+
+export const tableNames: readonly TableName[] = Object.freeze<TableName[]>([
+  "guidelines",
+  "sections",
+  "guideline_labels",
+  "references",
+  "guideline_references",
+  "guideline_sources",
+]);
+
+const tablesByCatalog = new WeakMap<Catalog, Map<TableName, CatalogTables[TableName]>>();
+
+export function catalogTable<Name extends TableName>(
+  catalog: Catalog,
+  name: Name,
+): CatalogTables[Name] {
+  if (!Object.hasOwn(tableSchemas, name)) {
+    throw new CatalogError(`Unknown table: ${name}`, {
+      code: "lookup",
+      details: { table: name, available: tableNames },
+      hints: ["Call catalog.describe() to inspect catalog tables."],
+    });
+  }
+
+  let tables = tablesByCatalog.get(catalog);
+
+  if (!tables) {
+    tables = new Map();
+    tablesByCatalog.set(catalog, tables);
+  }
+
+  let rows = tables.get(name);
+
+  if (!rows) {
+    rows = tableBuilders[name](catalog);
+    Object.freeze(rows);
+    tables.set(name, rows);
+  }
+
+  // SAFETY: Each cached value comes from the builder indexed by the same validated table name.
+  return rows as CatalogTables[Name];
+}
+
+export function catalogTableInfo(catalog: Catalog): readonly TableInfo[] {
+  return Object.freeze(
+    tableNames.map((name) =>
+      Object.freeze({
+        name,
+        rows: catalog.table(name).length,
+        columns: tableSchemas[name],
+      }),
+    ),
+  );
+}
+
+const tableBuilders: { [Name in TableName]: (catalog: Catalog) => CatalogTables[Name] } = {
+  guidelines: (catalog) =>
+    catalog.guidelines.map(({ id, title, description, labels, body, sections }) =>
+      Object.freeze({ id, title, description, labels, body, sections }),
+    ),
+  sections: (catalog) =>
+    catalog.guidelines.flatMap((guideline) =>
+      guideline.sections.map((section) =>
+        Object.freeze({ guideline_id: guideline.id, ...section }),
+      ),
+    ),
+  guideline_labels: (catalog) =>
+    catalog.guidelines
+      .flatMap((guideline) =>
+        [...new Set(guideline.labels)].map((label) => {
+          const parsed = parseLabel(label);
+
+          return Object.freeze({
+            guideline_id: guideline.id,
+            label,
+            family: parsed.family,
+            category: parsed.category,
+            modifier: parsed.modifier ?? null,
+          });
+        }),
+      )
+      .sort(
+        (left, right) =>
+          compareUnicode(left.guideline_id, right.guideline_id) ||
+          compareUnicode(left.label, right.label),
+      ),
+  references: (catalog) =>
+    [...referenceIndex(catalog).byId.values()]
+      .sort((left, right) => compareUnicode(left.id, right.id))
+      .map((reference) =>
+        Object.freeze({
+          id: reference.id,
+          source_type: reference.sourceType,
+          authors: reference.authors,
+          authors_text: reference.authorsText,
+          year: reference.year,
+          title: reference.title,
+          journal: reference.journal,
+          booktitle: reference.booktitle,
+          publisher: reference.publisher,
+          url: reference.url,
+          doi: reference.doi,
+          bibtex: reference.bibtex,
+        }),
+      ),
+  guideline_references: (catalog) =>
+    [...referenceIndex(catalog).idsByGuideline]
+      .sort(([left], [right]) => compareUnicode(left, right))
+      .flatMap(([guideline_id, ids]) =>
+        ids.map((reference_id) => Object.freeze({ guideline_id, reference_id })),
+      ),
+  guideline_sources: (catalog) => {
+    const references = new Map(
+      catalog.table("references").map((reference) => [reference.id, reference]),
+    );
+
+    return catalog.table("guideline_references").map(({ guideline_id, reference_id }) => {
+      const reference = references.get(reference_id)!;
+
+      return Object.freeze({
+        guideline_id,
+        reference_id,
+        source_type: reference.source_type,
+        authors: reference.authors,
+        authors_text: reference.authors_text,
+        year: reference.year,
+        source_title: reference.title,
+        journal: reference.journal,
+        booktitle: reference.booktitle,
+        publisher: reference.publisher,
+        url: reference.url,
+        doi: reference.doi,
+        bibtex: reference.bibtex,
+      });
+    });
+  },
+};