@chartcoach/catalog 0.1.7 → 0.2.0

package/dist/registration-CgQGMUIH.d.ts

@@ -0,0 +1,6 @@
+//#region src/catalog/registration.d.ts
+type RegisterCatalogOptions = Readonly<{
+  ids?: readonly string[];
+}>;
+//#endregion
+export { RegisterCatalogOptions as t };

package/dist/registration-DXhS7vgr.js

@@ -0,0 +1,41 @@
+import { a as CatalogError, r as isJsonString } from "./json-CBWjz9b4.js";
+import { i as tableSchemas, r as tableNames } from "./tables-DcgKnXwF.js";
+//#region src/catalog/registration.ts
+function registrationPlan(catalog, options, source) {
+	if (Object.prototype.toString.call(options) !== "[object Object]") throw new CatalogError("Registration options must be an object.");
+	if (options.ids !== void 0 && (!Array.isArray(options.ids) || !options.ids.every(isJsonString))) throw new CatalogError("ids must be an array of strings.");
+	const ids = options.ids === void 0 ? void 0 : 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, ids) {
+	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) {
+	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)[]";
+	}
+}
+//#endregion
+export { registrationPlan as t };

package/dist/tables-DcgKnXwF.js

@@ -0,0 +1,389 @@
+import { a as CatalogError, n as isJsonObject, r as isJsonString } from "./json-CBWjz9b4.js";
+import { BibDocument, Document, Library, ParseError, Style, init } from "refkit-js";
+//#region src/catalog/labels.ts
+function parseLabel(value, context = "label") {
+	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 = parts[0];
+	const category = parts[1];
+	const modifier = parts[2];
+	return {
+		value: modifier === void 0 ? `${family}:${category}` : `${family}:${category}:${modifier}`,
+		family,
+		category,
+		modifier
+	};
+}
+function normalizeLabel(value, context = "label") {
+	return parseLabel(value, context).value;
+}
+//#endregion
+//#region src/catalog/identity.ts
+async function catalogEntriesDigest(guidelines) {
+	return sha256Text([...guidelines].sort((left, right) => compareUnicode(left.id, right.id)).map((guideline) => ({
+		id: guideline.id,
+		title: guideline.title,
+		description: guideline.description,
+		labels: guideline.labels,
+		sections: guideline.sections.map((section) => ({
+			role: section.role,
+			title: section.title,
+			content: section.content
+		})),
+		references: guideline.references
+	})).map(canonicalJson).join(""));
+}
+async function manifestDigest(markdown) {
+	return sha256Text(markdown);
+}
+function canonicalJson(value) {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (!isJsonObject(value)) return JSON.stringify(value) ?? "null";
+	return `{${Object.keys(value).sort(compareUnicode).map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+}
+async function sha256Bytes(value) {
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) throw new CatalogError("SHA-256 digest support is unavailable in this runtime.", { code: "unavailable_capability" });
+	const digest = await subtle.digest("SHA-256", value.slice().buffer);
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function compareUnicode(left, right) {
+	const leftPoints = Array.from(left, (character) => character.codePointAt(0));
+	const rightPoints = Array.from(right, (character) => character.codePointAt(0));
+	const length = Math.min(leftPoints.length, rightPoints.length);
+	for (let index = 0; index < length; index += 1) {
+		const difference = leftPoints[index] - rightPoints[index];
+		if (difference !== 0) return difference;
+	}
+	return leftPoints.length - rightPoints.length;
+}
+async function sha256Text(value) {
+	return sha256Bytes(new TextEncoder().encode(value));
+}
+//#endregion
+//#region src/catalog/references.ts
+await init();
+const citationStyle = Style.load("apa");
+const DEFAULT_GUIDELINE_URL_TEMPLATE = "https://chartcoach.dev/guidelines/{id}";
+const indexes = /* @__PURE__ */ new WeakMap();
+function sourceRecords(catalog, guidelineId, detail) {
+	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);
+	}));
+}
+function citationRecords(catalog, options) {
+	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
+		});
+	}));
+}
+function referenceIndex(catalog) {
+	const cached = indexes.get(catalog);
+	if (cached) return cached;
+	const byId = /* @__PURE__ */ new Map();
+	const parsed = /* @__PURE__ */ new Map();
+	const idsByGuideline = /* @__PURE__ */ new Map();
+	for (const guideline of catalog.guidelines) {
+		const ids = /* @__PURE__ */ new Set();
+		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) {
+	try {
+		return parsedReference(bibtex);
+	} catch (error) {
+		if (error instanceof CatalogError) throw error;
+		const details = { 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) {
+	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) {
+	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, reference) {
+	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) {
+	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 !== null && !reference.citation.includes(value));
+	return Object.freeze({
+		...source,
+		citation: [reference.citation, ...new Set(locators)].join(" ")
+	});
+}
+function textOrNull(value) {
+	if (value === void 0) return null;
+	return value.trim() || null;
+}
+function referenceUrl(properties) {
+	const explicit = textOrNull(properties.url);
+	const value = explicit ?? textOrNull(properties.howpublished);
+	if (value === null) return null;
+	const candidate = /^\\url\{([^{}]*)\}$/.exec(value)?.[1] ?? value;
+	return /^https?:\/\/[^\s{}\\/?#]+[^\s{}\\]*$/i.test(candidate) ? candidate : explicit;
+}
+function doiUrl(value) {
+	return `https://doi.org/${value.replace(/^https?:\/\/doi\.org\//, "")}`;
+}
+//#endregion
+//#region src/catalog/tables.ts
+function columns(schema) {
+	return Object.freeze(Object.entries(schema).map(([name, type]) => Object.freeze({
+		name,
+		type
+	})));
+}
+const tableSchemas = 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"
+	})
+});
+const tableNames = Object.freeze([
+	"guidelines",
+	"sections",
+	"guideline_labels",
+	"references",
+	"guideline_references",
+	"guideline_sources"
+]);
+const tablesByCatalog = /* @__PURE__ */ new WeakMap();
+function catalogTable(catalog, 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 = /* @__PURE__ */ new Map();
+		tablesByCatalog.set(catalog, tables);
+	}
+	let rows = tables.get(name);
+	if (!rows) {
+		rows = tableBuilders[name](catalog);
+		Object.freeze(rows);
+		tables.set(name, rows);
+	}
+	return rows;
+}
+function catalogTableInfo(catalog) {
+	return Object.freeze(tableNames.map((name) => Object.freeze({
+		name,
+		rows: catalog.table(name).length,
+		columns: tableSchemas[name]
+	})));
+}
+const tableBuilders = {
+	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
+			});
+		});
+	}
+};
+//#endregion
+export { citationRecords as a, catalogEntriesDigest as c, sha256Bytes as d, normalizeLabel as f, tableSchemas as i, compareUnicode as l, catalogTableInfo as n, sourceRecords as o, parseLabel as p, tableNames as r, canonicalJson as s, catalogTable as t, manifestDigest as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chartcoach/catalog",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "JavaScript models and artifact parsers for the chartcoach visualization guideline catalog.",
   "bugs": {
     "url": "https://github.com/chartcoach/chartcoach/issues"
@@ -23,30 +23,59 @@
       "types": "./dist/index.d.ts",
       "source": "./src/index.ts",
       "default": "./dist/index.js"
+    },
+    "./duckdb": {
+      "types": "./dist/duckdb.d.ts",
+      "source": "./src/duckdb.ts",
+      "default": "./dist/duckdb.js"
+    },
+    "./duckdb-wasm": {
+      "types": "./dist/duckdb-wasm.d.ts",
+      "source": "./src/duckdb-wasm.ts",
+      "default": "./dist/duckdb-wasm.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "source": "./src/node.ts",
+      "default": "./dist/node.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "vp pack",
+    "check": "vp check",
+    "prepack": "vp run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
   "dependencies": {
-    "hyparquet": "^1.26.1",
-    "hyparquet-compressors": "^1.1.1",
-    "yaml": "^2.9.0"
+    "hyparquet": ">=1.29.2",
+    "hyparquet-compressors": ">=1.1.1",
+    "refkit-js": ">=0.3.0",
+    "tar": ">=7.5.22",
+    "yaml": ">=2.9.0"
   },
   "devDependencies": {
-    "@types/node": "^22.20.0",
-    "tsc-alias": "^1.8.17",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.6"
+    "@duckdb/duckdb-wasm": "catalog:",
+    "@duckdb/node-api": "catalog:",
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vite-plus": "catalog:"
   },
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "format": "oxfmt src test scripts package.json tsconfig.json tsconfig.build.json vitest.config.ts",
-    "format:check": "oxfmt src test scripts package.json tsconfig.json tsconfig.build.json vitest.config.ts --check",
-    "lint": "oxlint .",
-    "sync:defaults": "node scripts/sync-chartcoach-defaults.mjs",
-    "sync:defaults:check": "node scripts/sync-chartcoach-defaults.mjs --check",
-    "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+  "peerDependencies": {
+    "@duckdb/duckdb-wasm": ">=1.33.1-dev57.0",
+    "@duckdb/node-api": ">=1.5.5-r.4"
+  },
+  "peerDependenciesMeta": {
+    "@duckdb/duckdb-wasm": {
+      "optional": true
+    },
+    "@duckdb/node-api": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.19.0"
   }
-}
+}