@chartcoach/catalog 0.1.3

package/src/catalog/model.ts

@@ -0,0 +1,105 @@
+import { CatalogError } from "./errors";
+import type { CatalogManifest } from "./manifest";
+import { validateManifestCoverage } from "./manifest";
+
+export type GuidelineSection = {
+  role: string;
+  title: string;
+  content: string;
+};
+
+export type Guideline = {
+  id: string;
+  title: string;
+  bibliography?: string;
+  description: string;
+  labels: readonly string[];
+  body: string;
+  sections: readonly GuidelineSection[];
+  references: readonly string[];
+};
+
+export type CatalogOptions = {
+  manifest?: CatalogManifest;
+};
+
+export class Catalog implements Iterable<Guideline> {
+  readonly guidelines: readonly Guideline[];
+  readonly manifest?: CatalogManifest;
+  private readonly byId: Map<string, Guideline>;
+
+  constructor(guidelines: Iterable<Guideline> = [], options: CatalogOptions = {}) {
+    const records = Array.from(guidelines, copyGuideline);
+    const byId = new Map<string, Guideline>();
+    for (const guideline of records) {
+      if (byId.has(guideline.id)) {
+        throw new CatalogError(`Catalog contains duplicate guideline id: ${guideline.id}.`);
+      }
+      byId.set(guideline.id, guideline);
+    }
+    if (options.manifest) {
+      validateManifestCoverage(records, options.manifest);
+    }
+
+    this.guidelines = records;
+    this.manifest = options.manifest;
+    this.byId = byId;
+  }
+
+  get length(): number {
+    return this.guidelines.length;
+  }
+
+  get size(): number {
+    return this.guidelines.length;
+  }
+
+  get(id: string): Guideline | undefined {
+    return this.byId.get(id);
+  }
+
+  require(id: string): Guideline {
+    const guideline = this.get(id);
+    if (!guideline) {
+      throw new CatalogError(`Unknown guideline id: ${id}.`);
+    }
+    return guideline;
+  }
+
+  labels(): string[] {
+    return sortedUnique(this.guidelines.flatMap((guideline) => [...guideline.labels]));
+  }
+
+  sectionRoles(): string[] {
+    return sortedUnique(
+      this.guidelines.flatMap((guideline) =>
+        guideline.sections.map((section) => section.role),
+      ),
+    );
+  }
+
+  [Symbol.iterator](): Iterator<Guideline> {
+    return this.guidelines[Symbol.iterator]();
+  }
+}
+
+function copyGuideline(guideline: Guideline): Guideline {
+  return {
+    id: guideline.id,
+    title: guideline.title,
+    bibliography: guideline.bibliography,
+    description: guideline.description,
+    labels: [...guideline.labels],
+    body: guideline.body,
+    sections: guideline.sections.map((section) => ({
+      role: section.role,
+      title: section.title,
+      content: section.content,
+    })),
+    references: [...guideline.references],
+  };
+}
+
+function sortedUnique(values: Iterable<string>): string[] {
+  return Array.from(new Set(values)).sort();
+}

package/src/catalog/wire.ts

@@ -0,0 +1,93 @@
+import { CatalogError } from "./errors";
+import { normalizeLabel } from "./labels";
+import type { Guideline, GuidelineSection } from "./model";
+
+export type CatalogRowWire = {
+  id: string;
+  guideline: {
+    id: string;
+    title: string;
+    bibliography?: string | null;
+    description: string;
+    labels: string[];
+    body: string;
+    sections: GuidelineSection[];
+  };
+  references: string[];
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isGuidelineSection(value: unknown): value is GuidelineSection {
+  return (
+    isRecord(value) &&
+    typeof value.role === "string" &&
+    value.role.trim().length > 0 &&
+    typeof value.title === "string" &&
+    typeof value.content === "string"
+  );
+}
+
+function isSectionArray(value: unknown): value is GuidelineSection[] {
+  return Array.isArray(value) && value.every(isGuidelineSection);
+}
+
+function sectionsFromWire(value: GuidelineSection[]): GuidelineSection[] {
+  return value.map((section) => ({
+    role: section.role.trim(),
+    title: section.title,
+    content: section.content,
+  }));
+}
+
+export function isCatalogRowWire(value: unknown): value is CatalogRowWire {
+  if (!isRecord(value)) return false;
+  if (typeof value.id !== "string" || value.id.length === 0) return false;
+  if (!isRecord(value.guideline)) return false;
+  if (value.guideline.id !== value.id) return false;
+  if (typeof value.guideline.title !== "string") return false;
+  if (typeof value.guideline.description !== "string") return false;
+  if (typeof value.guideline.body !== "string") return false;
+  if (!isStringArray(value.guideline.labels)) return false;
+  if (!isSectionArray(value.guideline.sections)) return false;
+  if (!isStringArray(value.references)) return false;
+  return true;
+}
+
+export function guidelineFromWire(value: unknown): Guideline | null {
+  if (!isCatalogRowWire(value)) return null;
+
+  const { guideline, references } = value;
+  const sections = sectionsFromWire(guideline.sections);
+  let labels: string[];
+  try {
+    labels = guideline.labels.map((label) => normalizeLabel(label, "guideline label"));
+  } catch {
+    return null;
+  }
+
+  return {
+    id: guideline.id,
+    title: guideline.title,
+    bibliography: typeof guideline.bibliography === "string" ? guideline.bibliography : undefined,
+    description: guideline.description,
+    labels,
+    body: guideline.body,
+    sections,
+    references: [...references],
+  };
+}
+
+export function requireGuidelineFromWire(value: unknown, context?: string): Guideline {
+  const guideline = guidelineFromWire(value);
+  if (guideline) return guideline;
+
+  const suffix = context ? ` (${context})` : "";
+  throw new CatalogError(`Invalid catalog row format${suffix}.`);
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export { Catalog, type CatalogOptions, type Guideline, type GuidelineSection } from "./catalog/model";
+export { CatalogError } from "./catalog/errors";
+export {
+  DEFAULT_CATALOG,
+  catalogArtifact,
+  catalogArtifactUrl,
+  parseCatalogReleaseMetadata,
+  type ArtifactDescriptor,
+  type ArtifactKind,
+  type CatalogReleaseMetadata,
+} from "./catalog/artifacts";
+export {
+  loadCatalog,
+  type AsyncBuffer,
+  type CatalogBytes,
+  type LoadCatalogInput,
+  type ParquetBytes,
+} from "./catalog/load-parquet-core";
+export {
+  type CatalogManifest,
+  type ManifestDefinition,
+  parseCatalogManifest,
+} from "./catalog/manifest";
+export { parseLabel, type CatalogLabel } from "./catalog/labels";
+export { toMarkdown } from "./catalog/markdown";