@chartcoach/catalog 0.1.6 → 0.2.0

package/dist/catalog/manifest.js

@@ -1,143 +0,0 @@
-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

@@ -1,3 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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,CAAC,SAAS,EAAE,IAAI,GAAG,OAAO,GAAG,cAAc,GAAG,aAAa,GAAG,QAAQ,GAAG,MAAM,CAAC,GAC9F,MAAM,CAYR"}

package/dist/catalog/markdown.js

@@ -1,13 +0,0 @@
-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

@@ -1,33 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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;IAMxB,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,SAAS,CAAC;CAGzC"}

package/dist/catalog/model.js

@@ -1,67 +0,0 @@
-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

@@ -1,18 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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"}

package/dist/catalog/wire.js

@@ -1,78 +0,0 @@
-import { CatalogError } from "./errors.js";
-import { normalizeLabel } from "./labels.js";
-function isRecord(value) {
-    return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-function isStringArray(value) {
-    return Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-function isGuidelineSection(value) {
-    return (isRecord(value) &&
-        typeof value.role === "string" &&
-        value.role.trim().length > 0 &&
-        typeof value.title === "string" &&
-        typeof value.content === "string");
-}
-function isSectionArray(value) {
-    return Array.isArray(value) && value.every(isGuidelineSection);
-}
-function sectionsFromWire(value) {
-    return value.map((section) => ({
-        role: section.role.trim(),
-        title: section.title,
-        content: section.content,
-    }));
-}
-export function isCatalogRowWire(value) {
-    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) {
-    if (!isCatalogRowWire(value))
-        return null;
-    const { guideline, references } = value;
-    const sections = sectionsFromWire(guideline.sections);
-    let labels;
-    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, context) {
-    const guideline = guidelineFromWire(value);
-    if (guideline)
-        return guideline;
-    const suffix = context ? ` (${context})` : "";
-    throw new CatalogError(`Invalid catalog row format${suffix}.`);
-}

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,2BAA2B,EAC3B,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,WAAW,EACX,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}

package/src/catalog/chartcoach-defaults.ts

@@ -1,17 +0,0 @@
-export type ChartCoachDefaults = {
-  catalogArtifactBaseUrl: string;
-  catalogDigest: string;
-  catalogVersion: string;
-  guidelineUrlTemplate: string;
-  indexTopK: number;
-  lanceDocumentTable: string;
-};
-
-export const CHARTCOACH_DEFAULTS = {
-  catalogArtifactBaseUrl: "https://artifacts.chartcoach.dev",
-  catalogDigest: "7cfd43ee820be252b8ae9058c4c36109a9c8415c6b3a5ff8a9127117b4a10c19",
-  catalogVersion: "0.1.6",
-  guidelineUrlTemplate: "https://chartcoach.dev/guidelines/{id}",
-  indexTopK: 10,
-  lanceDocumentTable: "catalog_documents",
-} as const satisfies ChartCoachDefaults;

package/src/catalog/load-parquet-core.ts

@@ -1,78 +0,0 @@
-import { parquetReadObjects } from "hyparquet";
-import { compressors } from "hyparquet-compressors";
-import { Catalog, type Guideline } from "./model";
-import { CatalogError } from "./errors";
-import type { CatalogManifest } from "./manifest";
-import { parseCatalogManifest } from "./manifest";
-import { requireGuidelineFromWire } from "./wire";
-
-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;
-    };
-
-function normalizeParquetBytes(bytes: ParquetBytes): ArrayBuffer {
-  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: LoadCatalogInput): Promise<Catalog> {
-  const { entries, manifest } = resolveLoadCatalogInput(input);
-  const normalizedFile =
-    entries instanceof ArrayBuffer || ArrayBuffer.isView(entries)
-      ? normalizeParquetBytes(entries as ParquetBytes)
-      : entries;
-
-  const rows = (await parquetReadObjects({
-    file: normalizedFile,
-    compressors,
-  })) as Array<Record<string, unknown>>;
-
-  const guidelines: Guideline[] = rows.map((row, index) =>
-    requireGuidelineFromWire(row, `parquet row ${index}`),
-  );
-
-  return new Catalog(guidelines, { manifest });
-}
-
-function resolveLoadCatalogInput(input: LoadCatalogInput): {
-  entries: CatalogBytes;
-  manifest?: CatalogManifest;
-} {
-  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: LoadCatalogInput): value is CatalogBytes {
-  return (
-    value instanceof ArrayBuffer ||
-    ArrayBuffer.isView(value) ||
-    (typeof value === "object" &&
-      value !== null &&
-      typeof (value as AsyncBuffer).byteLength === "number" &&
-      typeof (value as AsyncBuffer).slice === "function")
-  );
-}