@chartcoach/catalog 0.1.3

package/README.md

@@ -0,0 +1,71 @@
+# @chartcoach/catalog
+
+JavaScript models and parsers for chartcoach catalog artifacts.
+
+Read the package docs at [docs.chartcoach.dev/javascript](https://docs.chartcoach.dev/javascript).
+Read the catalog contract at [docs.chartcoach.dev/catalog](https://docs.chartcoach.dev/catalog).
+
+Install the package from an application root:
+
+```bash
+npm install @chartcoach/catalog
+```
+
+```ts
+import { DEFAULT_CATALOG, loadCatalog } from "@chartcoach/catalog"
+
+const entries = await fetch(DEFAULT_CATALOG.entriesUrl).then((response) =>
+  response.arrayBuffer(),
+)
+const manifestText = await fetch(DEFAULT_CATALOG.manifestUrl).then((response) =>
+  response.text(),
+)
+
+const catalog = await loadCatalog({ entries, manifestText })
+const guideline = catalog.require("compare-percentages-with-bars-not-pies")
+```
+
+`@chartcoach/catalog` accepts bytes that the caller already acquired. Use
+`fetch`, `fs.readFile`, `Bun.file`, `Deno.readFile`, or a test fixture to read
+the artifacts, then pass `entries` and optional manifest data to `loadCatalog`.
+
+```ts
+import { readFile } from "node:fs/promises"
+import { loadCatalog } from "@chartcoach/catalog"
+
+const catalog = await loadCatalog({
+  entries: await readFile("entries.parquet"),
+  manifestText: await readFile("MANIFEST.md", "utf8"),
+})
+```
+
+Parse release metadata when code needs artifact URLs:
+
+```ts
+import {
+  catalogArtifact,
+  catalogArtifactUrl,
+  parseCatalogReleaseMetadata,
+} from "@chartcoach/catalog"
+
+const metadata = parseCatalogReleaseMetadata(await response.json())
+const entriesUrl = catalogArtifactUrl(
+  metadataUrl,
+  catalogArtifact(metadata, "entries"),
+)
+
+const entries = await fetch(entriesUrl).then((response) => response.arrayBuffer())
+```
+
+Run package checks from the repository root:
+
+```bash
+pnpm --dir packages/catalog-javascript lint
+pnpm --dir packages/catalog-javascript typecheck
+pnpm --dir packages/catalog-javascript test
+pnpm --dir packages/catalog-javascript build
+```
+
+## License
+
+MIT. See [LICENSE](../../LICENSE).

package/dist/catalog/artifacts.d.ts

@@ -0,0 +1,27 @@
+export declare const DEFAULT_CATALOG: {
+    readonly version: "0.1.3";
+    readonly digest: "7cfd43ee820be252b8ae9058c4c36109a9c8415c6b3a5ff8a9127117b4a10c19";
+    readonly releaseRootUrl: string;
+    readonly metadataUrl: string;
+    readonly entriesUrl: string;
+    readonly manifestUrl: string;
+};
+export type ArtifactKind = "manifest" | "entries" | "lancedb-index";
+export type ArtifactDescriptor = {
+    kind: ArtifactKind;
+    path: string;
+    digest: string;
+    bytes: number;
+    format?: string;
+    rows?: number;
+    [key: string]: unknown;
+};
+export type CatalogReleaseMetadata = {
+    version: string;
+    digest: string;
+    artifacts: ArtifactDescriptor[];
+};
+export declare function parseCatalogReleaseMetadata(value: unknown): CatalogReleaseMetadata;
+export declare function catalogArtifactUrl(baseUrl: string | URL, descriptor: ArtifactDescriptor): string;
+export declare function catalogArtifact(metadata: CatalogReleaseMetadata, kind: ArtifactKind): ArtifactDescriptor;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/catalog/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/catalog/artifacts.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,eAAe;;;;;;;CAOlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,eAAe,CAAC;AAEpE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,kBAAkB,EAAE,CAAC;CACjC,CAAC;AAEF,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,CAgBlF;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GAAG,GAAG,EACrB,UAAU,EAAE,kBAAkB,GAC7B,MAAM,CAER;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,sBAAsB,EAChC,IAAI,EAAE,YAAY,GACjB,kBAAkB,CAMpB"}

package/dist/catalog/artifacts.js

@@ -0,0 +1,90 @@
+import { CatalogError } from "./errors.js";
+const defaultCatalogArtifactBaseUrl = "https://artifacts.chartcoach.dev";
+const defaultCatalogDigest = "7cfd43ee820be252b8ae9058c4c36109a9c8415c6b3a5ff8a9127117b4a10c19";
+const defaultCatalogVersion = "0.1.3";
+const defaultCatalogReleaseRootUrl = new URL(`catalog/releases/${defaultCatalogVersion}/${defaultCatalogDigest}/`, `${defaultCatalogArtifactBaseUrl}/`).toString();
+export const DEFAULT_CATALOG = {
+    version: defaultCatalogVersion,
+    digest: defaultCatalogDigest,
+    releaseRootUrl: defaultCatalogReleaseRootUrl,
+    metadataUrl: new URL("metadata.json", defaultCatalogReleaseRootUrl).toString(),
+    entriesUrl: new URL("entries.parquet", defaultCatalogReleaseRootUrl).toString(),
+    manifestUrl: new URL("MANIFEST.md", defaultCatalogReleaseRootUrl).toString(),
+};
+export function parseCatalogReleaseMetadata(value) {
+    if (!isRecord(value)) {
+        throw new CatalogError("Catalog release metadata must be an object.");
+    }
+    const artifacts = value.artifacts;
+    if (!Array.isArray(artifacts)) {
+        throw new CatalogError("Catalog release metadata artifacts must be a list.");
+    }
+    const metadata = {
+        version: requiredString(value, "version"),
+        digest: requiredString(value, "digest"),
+        artifacts: artifacts.map(parseArtifactDescriptor),
+    };
+    catalogArtifact(metadata, "manifest");
+    catalogArtifact(metadata, "entries");
+    return metadata;
+}
+export function catalogArtifactUrl(baseUrl, descriptor) {
+    return new URL(descriptor.path, baseUrl).toString();
+}
+export function catalogArtifact(metadata, kind) {
+    const descriptor = metadata.artifacts.find((item) => item.kind === kind);
+    if (!descriptor) {
+        throw new CatalogError(`Catalog release metadata is missing a ${kind} artifact.`);
+    }
+    return descriptor;
+}
+function parseArtifactDescriptor(value) {
+    if (!isRecord(value)) {
+        throw new CatalogError("Catalog artifact descriptor must be an object.");
+    }
+    const kind = value.kind;
+    if (kind !== "manifest" && kind !== "entries" && kind !== "lancedb-index") {
+        throw new CatalogError(`Unsupported catalog artifact kind: ${String(kind)}`);
+    }
+    const path = requiredString(value, "path");
+    validateRelativePath(path);
+    const descriptor = {
+        kind,
+        path,
+        digest: requiredString(value, "digest"),
+        bytes: requiredInteger(value, "bytes"),
+    };
+    if (typeof value.format === "string")
+        descriptor.format = value.format;
+    if (typeof value.rows === "number" && Number.isInteger(value.rows)) {
+        descriptor.rows = value.rows;
+    }
+    for (const [key, rawValue] of Object.entries(value)) {
+        if (!["kind", "path", "digest", "bytes", "format", "rows"].includes(key)) {
+            descriptor[key] = rawValue;
+        }
+    }
+    return descriptor;
+}
+function validateRelativePath(path) {
+    if (path.startsWith("/") || path.split("/").includes("..")) {
+        throw new CatalogError(`Catalog artifact path must be relative: ${path}`);
+    }
+}
+function requiredString(value, key) {
+    const raw = value[key];
+    if (typeof raw !== "string" || raw.length === 0) {
+        throw new CatalogError(`Catalog release metadata ${key} must be a string.`);
+    }
+    return raw;
+}
+function requiredInteger(value, key) {
+    const raw = value[key];
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
+        throw new CatalogError(`Catalog release metadata ${key} must be a non-negative integer.`);
+    }
+    return raw;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/dist/catalog/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class CatalogError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/catalog/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/catalog/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B"}

package/dist/catalog/errors.js

@@ -0,0 +1,6 @@
+export class CatalogError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CatalogError";
+    }
+}

package/dist/catalog/labels.d.ts

@@ -0,0 +1,9 @@
+export type CatalogLabel = {
+    value: string;
+    family: string;
+    category: string;
+    modifier?: string;
+};
+export declare function parseLabel(value: unknown, context?: string): CatalogLabel;
+export declare function normalizeLabel(value: unknown, context?: string): string;
+//# sourceMappingURL=labels.d.ts.map

package/dist/catalog/labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../../src/catalog/labels.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,SAAU,GAAG,YAAY,CAkB1E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,SAAU,GAAG,MAAM,CAExE"}

package/dist/catalog/labels.js

@@ -0,0 +1,23 @@
+import { CatalogError } from "./errors.js";
+export function parseLabel(value, context = "label") {
+    if (typeof value !== "string") {
+        throw new CatalogError(`${context} must be a string.`);
+    }
+    const parts = value
+        .trim()
+        .split(":")
+        .map((part) => part.trim());
+    if ((parts.length !== 2 && parts.length !== 3) || parts.some((part) => part.length === 0)) {
+        throw new CatalogError(`${context} must use <family>:<category> or <family>:<category>:<modifier>.`);
+    }
+    const [family, category, modifier] = parts;
+    return {
+        value: modifier === undefined ? `${family}:${category}` : `${family}:${category}:${modifier}`,
+        family,
+        category,
+        modifier,
+    };
+}
+export function normalizeLabel(value, context = "label") {
+    return parseLabel(value, context).value;
+}

package/dist/catalog/load-parquet-core.d.ts

@@ -0,0 +1,15 @@
+import { Catalog } from "./model.js";
+import type { CatalogManifest } from "./manifest.js";
+export type AsyncBuffer = {
+    byteLength: number;
+    slice(start: number, end?: number): ArrayBuffer | Promise<ArrayBuffer>;
+};
+export type ParquetBytes = ArrayBuffer | ArrayBufferView;
+export type CatalogBytes = ParquetBytes | AsyncBuffer;
+export type LoadCatalogInput = CatalogBytes | {
+    entries: CatalogBytes;
+    manifest?: CatalogManifest;
+    manifestText?: string;
+};
+export declare function loadCatalog(input: LoadCatalogInput): Promise<Catalog>;
+//# sourceMappingURL=load-parquet-core.d.ts.map

package/dist/catalog/load-parquet-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-parquet-core.d.ts","sourceRoot":"","sources":["../../src/catalog/load-parquet-core.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAkB,MAAM,SAAS,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,MAAM,MAAM,WAAW,GAAG;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACxE,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,eAAe,CAAC;AACzD,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,WAAW,CAAC;AACtD,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAC5C,OAAO,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAWF,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,OAAO,CAAC,CAiBlB"}

package/dist/catalog/load-parquet-core.js

@@ -0,0 +1,47 @@
+import { parquetReadObjects } from "hyparquet";
+import { compressors } from "hyparquet-compressors";
+import { Catalog } from "./model.js";
+import { CatalogError } from "./errors.js";
+import { parseCatalogManifest } from "./manifest.js";
+import { requireGuidelineFromWire } from "./wire.js";
+function normalizeParquetBytes(bytes) {
+    if (bytes instanceof ArrayBuffer)
+        return bytes;
+    // TypedArray/DataView may be a view into a larger ArrayBuffer (or SharedArrayBuffer).
+    // Copy to a standalone ArrayBuffer covering exactly the view range.
+    const u8 = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return u8.slice().buffer;
+}
+export async function loadCatalog(input) {
+    const { entries, manifest } = resolveLoadCatalogInput(input);
+    const normalizedFile = entries instanceof ArrayBuffer || ArrayBuffer.isView(entries)
+        ? normalizeParquetBytes(entries)
+        : entries;
+    const rows = (await parquetReadObjects({
+        file: normalizedFile,
+        compressors,
+    }));
+    const guidelines = rows.map((row, index) => requireGuidelineFromWire(row, `parquet row ${index}`));
+    return new Catalog(guidelines, { manifest });
+}
+function resolveLoadCatalogInput(input) {
+    if (isCatalogBytes(input))
+        return { entries: input };
+    if (input.manifest && input.manifestText !== undefined) {
+        throw new CatalogError("Pass manifest or manifestText, not both.");
+    }
+    return {
+        entries: input.entries,
+        manifest: input.manifestText === undefined
+            ? input.manifest
+            : parseCatalogManifest(input.manifestText),
+    };
+}
+function isCatalogBytes(value) {
+    return (value instanceof ArrayBuffer ||
+        ArrayBuffer.isView(value) ||
+        (typeof value === "object" &&
+            value !== null &&
+            typeof value.byteLength === "number" &&
+            typeof value.slice === "function"));
+}

package/dist/catalog/manifest.d.ts

@@ -0,0 +1,15 @@
+import type { Guideline } from "./model.js";
+export declare const REQUIRED_MANIFEST_HEADINGS: readonly ["Section Roles", "Label Families"];
+export type ManifestDefinition = {
+    name: string;
+    description: string;
+    examples: string[];
+};
+export type CatalogManifest = {
+    markdown: string;
+    sectionRoles: Record<string, ManifestDefinition>;
+    labelFamilies: Record<string, ManifestDefinition>;
+};
+export declare function parseCatalogManifest(markdown: string): CatalogManifest;
+export declare function validateManifestCoverage(guidelines: readonly Guideline[], manifest: CatalogManifest): void;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/catalog/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/catalog/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,eAAO,MAAM,0BAA0B,8CAA+C,CAAC;AAEvF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACjD,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CACnD,CAAC;AAKF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAkGtE;AAED,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,EAAE,QAAQ,EAAE,eAAe,QAkCnG"}

package/dist/catalog/manifest.js

@@ -0,0 +1,144 @@
+import { CatalogError } from "./errors.js";
+import { parseLabel } from "./labels.js";
+export const REQUIRED_MANIFEST_HEADINGS = ["Section Roles", "Label Families"];
+const headingPattern = /^(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/;
+const codeSpanPattern = /`([^`\n]+)`/g;
+export function parseCatalogManifest(markdown) {
+    const requiredSeen = new Set();
+    const definitions = {
+        "Section Roles": {},
+        "Label Families": {},
+    };
+    let currentHeading;
+    let currentName;
+    let currentLines = [];
+    function flushDefinition() {
+        if (currentHeading !== "Section Roles" &&
+            currentHeading !== "Label Families") {
+            currentLines = [];
+            return;
+        }
+        if (currentName === undefined) {
+            currentLines = [];
+            return;
+        }
+        const description = currentLines.join("\n").trim();
+        if (!description) {
+            throw new CatalogError(`Manifest definition ${currentHeading}/${currentName} must include prose.`);
+        }
+        definitions[currentHeading][currentName] = {
+            name: currentName,
+            description,
+            examples: Array.from(description.matchAll(codeSpanPattern), (match) => match[1] ?? ""),
+        };
+        currentName = undefined;
+        currentLines = [];
+    }
+    for (const line of markdown.split("\n")) {
+        const match = headingPattern.exec(line);
+        if (!match) {
+            if (currentName !== undefined)
+                currentLines.push(line);
+            continue;
+        }
+        const level = match[1].length;
+        const title = match[2].trim();
+        if (level === 2) {
+            flushDefinition();
+            currentHeading = title;
+            currentName = undefined;
+            currentLines = [];
+            if (title === "Section Roles" || title === "Label Families") {
+                requiredSeen.add(title);
+            }
+            continue;
+        }
+        if (level === 3 &&
+            (currentHeading === "Section Roles" || currentHeading === "Label Families")) {
+            flushDefinition();
+            if (!title) {
+                throw new CatalogError(`Manifest heading ${currentHeading} contains an empty subheading.`);
+            }
+            currentName = title;
+            currentLines = [];
+            continue;
+        }
+        if (currentName !== undefined)
+            currentLines.push(line);
+    }
+    flushDefinition();
+    const missing = REQUIRED_MANIFEST_HEADINGS.filter((heading) => !requiredSeen.has(heading));
+    if (missing.length > 0) {
+        throw new CatalogError(`MANIFEST.md is missing required heading(s): ${missing.join(", ")}.`);
+    }
+    for (const heading of REQUIRED_MANIFEST_HEADINGS) {
+        if (Object.keys(definitions[heading]).length === 0) {
+            throw new CatalogError(`Manifest heading ${heading} must define entries.`);
+        }
+    }
+    validateLabelFamilyExamples(Object.values(definitions["Label Families"]));
+    return {
+        markdown: markdown.endsWith("\n") ? markdown : `${markdown}\n`,
+        sectionRoles: definitions["Section Roles"],
+        labelFamilies: definitions["Label Families"],
+    };
+}
+export function validateManifestCoverage(guidelines, manifest) {
+    const usedRoles = new Set();
+    const usedFamilies = new Set();
+    for (const guideline of guidelines) {
+        for (const section of guideline.sections) {
+            const role = section.role.trim();
+            if (!role) {
+                throw new CatalogError("Section role values must not be empty.");
+            }
+            usedRoles.add(role);
+        }
+        for (const label of guideline.labels) {
+            usedFamilies.add(parseLabel(label, `label ${JSON.stringify(label)}`).family);
+        }
+    }
+    const missingRoles = Array.from(usedRoles)
+        .filter((role) => manifest.sectionRoles[role] === undefined)
+        .sort();
+    const missingFamilies = Array.from(usedFamilies)
+        .filter((family) => manifest.labelFamilies[family] === undefined)
+        .sort();
+    const errors = [];
+    if (missingRoles.length > 0) {
+        errors.push(`undefined section role(s): ${missingRoles.join(", ")}`);
+    }
+    if (missingFamilies.length > 0) {
+        errors.push(`undefined label family/families: ${missingFamilies.join(", ")}`);
+    }
+    if (errors.length > 0) {
+        throw new CatalogError(`Catalog manifest validation failed: ${errors.join("; ")}.`);
+    }
+}
+function validateLabelFamilyExamples(definitions) {
+    for (const definition of definitions) {
+        const familyExamples = [];
+        const invalidExamples = [];
+        for (const example of definition.examples) {
+            let parsed;
+            try {
+                parsed = parseLabel(example, `manifest label example ${JSON.stringify(example)}`);
+            }
+            catch {
+                continue;
+            }
+            if (parsed.family === definition.name) {
+                familyExamples.push(parsed.value);
+            }
+            else if (example.includes(":")) {
+                invalidExamples.push(example);
+            }
+        }
+        if (invalidExamples.length > 0) {
+            throw new CatalogError(`Label family ${definition.name} has example(s) from another family: ${invalidExamples.join(", ")}.`);
+        }
+        if (familyExamples.length === 0) {
+            throw new CatalogError(`Label family ${definition.name} must include at least one label example.`);
+        }
+    }
+}

package/dist/catalog/markdown.d.ts

@@ -0,0 +1,3 @@
+import type { Guideline } from "./model.js";
+export declare function toMarkdown(guideline: Pick<Guideline, "id" | "title" | "bibliography" | "description" | "labels" | "body">): string;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/catalog/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/catalog/markdown.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,wBAAgB,UAAU,CACxB,SAAS,EAAE,IAAI,CACb,SAAS,EACT,IAAI,GAAG,OAAO,GAAG,cAAc,GAAG,aAAa,GAAG,QAAQ,GAAG,MAAM,CACpE,GACA,MAAM,CAYR"}

package/dist/catalog/markdown.js

@@ -0,0 +1,13 @@
+import { stringify as stringifyYaml } from "yaml";
+export function toMarkdown(guideline) {
+    const frontmatter = {
+        id: guideline.id,
+        title: guideline.title,
+        ...(guideline.bibliography ? { bibliography: guideline.bibliography } : {}),
+        description: guideline.description,
+        labels: [...guideline.labels],
+    };
+    const frontmatterYaml = stringifyYaml(frontmatter, { sortMapEntries: false }).trim();
+    const body = guideline.body.trim();
+    return ["---", frontmatterYaml, "---", "", body, ""].join("\n");
+}

package/dist/catalog/model.d.ts

@@ -0,0 +1,33 @@
+import type { CatalogManifest } from "./manifest.js";
+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 declare class Catalog implements Iterable<Guideline> {
+    readonly guidelines: readonly Guideline[];
+    readonly manifest?: CatalogManifest;
+    private readonly byId;
+    constructor(guidelines?: Iterable<Guideline>, options?: CatalogOptions);
+    get length(): number;
+    get size(): number;
+    get(id: string): Guideline | undefined;
+    require(id: string): Guideline;
+    labels(): string[];
+    sectionRoles(): string[];
+    [Symbol.iterator](): Iterator<Guideline>;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/catalog/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/catalog/model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B,CAAC;AAEF,qBAAa,OAAQ,YAAW,QAAQ,CAAC,SAAS,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;gBAElC,UAAU,GAAE,QAAQ,CAAC,SAAS,CAAM,EAAE,OAAO,GAAE,cAAmB;IAkB9E,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAItC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS;IAQ9B,MAAM,IAAI,MAAM,EAAE;IAIlB,YAAY,IAAI,MAAM,EAAE;IAQxB,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,SAAS,CAAC;CAGzC"}

package/dist/catalog/model.js

@@ -0,0 +1,67 @@
+import { CatalogError } from "./errors.js";
+import { validateManifestCoverage } from "./manifest.js";
+export class Catalog {
+    guidelines;
+    manifest;
+    byId;
+    constructor(guidelines = [], options = {}) {
+        const records = Array.from(guidelines, copyGuideline);
+        const byId = new Map();
+        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() {
+        return this.guidelines.length;
+    }
+    get size() {
+        return this.guidelines.length;
+    }
+    get(id) {
+        return this.byId.get(id);
+    }
+    require(id) {
+        const guideline = this.get(id);
+        if (!guideline) {
+            throw new CatalogError(`Unknown guideline id: ${id}.`);
+        }
+        return guideline;
+    }
+    labels() {
+        return sortedUnique(this.guidelines.flatMap((guideline) => [...guideline.labels]));
+    }
+    sectionRoles() {
+        return sortedUnique(this.guidelines.flatMap((guideline) => guideline.sections.map((section) => section.role)));
+    }
+    [Symbol.iterator]() {
+        return this.guidelines[Symbol.iterator]();
+    }
+}
+function copyGuideline(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) {
+    return Array.from(new Set(values)).sort();
+}

package/dist/catalog/wire.d.ts

@@ -0,0 +1,18 @@
+import type { Guideline, GuidelineSection } from "./model.js";
+export type CatalogRowWire = {
+    id: string;
+    guideline: {
+        id: string;
+        title: string;
+        bibliography?: string | null;
+        description: string;
+        labels: string[];
+        body: string;
+        sections: GuidelineSection[];
+    };
+    references: string[];
+};
+export declare function isCatalogRowWire(value: unknown): value is CatalogRowWire;
+export declare function guidelineFromWire(value: unknown): Guideline | null;
+export declare function requireGuidelineFromWire(value: unknown, context?: string): Guideline;
+//# sourceMappingURL=wire.d.ts.map

package/dist/catalog/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/catalog/wire.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3D,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE;QACT,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,gBAAgB,EAAE,CAAC;KAC9B,CAAC;IACF,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAgCF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAYxE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAsBlE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAMpF"}