@chartcoach/catalog 0.1.3

package/dist/catalog/wire.js

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

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

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACtG,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EACL,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,2BAA2B,EAC3B,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,sBAAsB,GAC5B,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/dist/index.js

@@ -0,0 +1,7 @@
+export { Catalog } from "./catalog/model.js";
+export { CatalogError } from "./catalog/errors.js";
+export { DEFAULT_CATALOG, catalogArtifact, catalogArtifactUrl, parseCatalogReleaseMetadata, } from "./catalog/artifacts.js";
+export { loadCatalog, } from "./catalog/load-parquet-core.js";
+export { parseCatalogManifest, } from "./catalog/manifest.js";
+export { parseLabel } from "./catalog/labels.js";
+export { toMarkdown } from "./catalog/markdown.js";

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@chartcoach/catalog",
+  "version": "0.1.3",
+  "description": "JavaScript models and artifact parsers for the chartcoach visualization guideline catalog.",
+  "license": "MIT",
+  "author": "Péter Ferenc Gyarmati <dev.petergy@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chartcoach/chartcoach.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chartcoach/chartcoach/issues"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -b tsconfig.build.json --force && tsc-alias -p tsconfig.build.json --resolve-full-paths --resolve-full-extension .js",
+    "lint": "oxlint . && pnpm run lint:imports",
+    "lint:imports": "node scripts/check-extensionless-imports.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "hyparquet": "^1.26.1",
+    "hyparquet-compressors": "^1.1.1",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.21",
+    "tsc-alias": "^1.8.17",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6"
+  }
+}

package/src/catalog/artifacts.ts

@@ -0,0 +1,127 @@
+import { CatalogError } from "./errors";
+
+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(),
+} as const;
+
+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 function parseCatalogReleaseMetadata(value: unknown): CatalogReleaseMetadata {
+  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: string | URL,
+  descriptor: ArtifactDescriptor,
+): string {
+  return new URL(descriptor.path, baseUrl).toString();
+}
+
+export function catalogArtifact(
+  metadata: CatalogReleaseMetadata,
+  kind: ArtifactKind,
+): ArtifactDescriptor {
+  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: unknown): ArtifactDescriptor {
+  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: ArtifactDescriptor = {
+    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: string): void {
+  if (path.startsWith("/") || path.split("/").includes("..")) {
+    throw new CatalogError(`Catalog artifact path must be relative: ${path}`);
+  }
+}
+
+function requiredString(value: Record<string, unknown>, key: string): string {
+  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: Record<string, unknown>, key: string): number {
+  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: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/src/catalog/errors.ts

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

package/src/catalog/labels.ts

@@ -0,0 +1,32 @@
+import { CatalogError } from "./errors";
+
+export type CatalogLabel = {
+  value: string;
+  family: string;
+  category: string;
+  modifier?: string;
+};
+
+export function parseLabel(value: unknown, context = "label"): CatalogLabel {
+  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 as [string, string, string | undefined];
+  return {
+    value: modifier === undefined ? `${family}:${category}` : `${family}:${category}:${modifier}`,
+    family,
+    category,
+    modifier,
+  };
+}
+
+export function normalizeLabel(value: unknown, context = "label"): string {
+  return parseLabel(value, context).value;
+}

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

@@ -0,0 +1,81 @@
+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"
+    )
+  );
+}

package/src/catalog/manifest.ts

@@ -0,0 +1,186 @@
+import { CatalogError } from "./errors";
+import { parseLabel } from "./labels";
+import type { Guideline } from "./model";
+
+export const REQUIRED_MANIFEST_HEADINGS = ["Section Roles", "Label Families"] as const;
+
+export type ManifestDefinition = {
+  name: string;
+  description: string;
+  examples: string[];
+};
+
+export type CatalogManifest = {
+  markdown: string;
+  sectionRoles: Record<string, ManifestDefinition>;
+  labelFamilies: Record<string, ManifestDefinition>;
+};
+
+const headingPattern = /^(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/;
+const codeSpanPattern = /`([^`\n]+)`/g;
+
+export function parseCatalogManifest(markdown: string): CatalogManifest {
+  const requiredSeen = new Set<string>();
+  const definitions: {
+    "Section Roles": Record<string, ManifestDefinition>;
+    "Label Families": Record<string, ManifestDefinition>;
+  } = {
+    "Section Roles": {},
+    "Label Families": {},
+  };
+  let currentHeading: keyof typeof definitions | string | undefined;
+  let currentName: string | undefined;
+  let currentLines: string[] = [];
+
+  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: readonly Guideline[], manifest: CatalogManifest) {
+  const usedRoles = new Set<string>();
+  const usedFamilies = new Set<string>();
+
+  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: string[] = [];
+  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: ManifestDefinition[]) {
+  for (const definition of definitions) {
+    const familyExamples: string[] = [];
+    const invalidExamples: string[] = [];
+    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/src/catalog/markdown.ts

@@ -0,0 +1,22 @@
+import { stringify as stringifyYaml } from "yaml";
+
+import type { Guideline } from "./model";
+
+export function toMarkdown(
+  guideline: Pick<
+    Guideline,
+    "id" | "title" | "bibliography" | "description" | "labels" | "body"
+  >,
+): string {
+  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");
+}