@chartcoach/catalog 0.1.7 → 0.2.0

package/src/catalog/identity.ts

@@ -0,0 +1,69 @@
+import { CatalogError } from "./errors";
+import { isJsonObject, type JsonObject, type JsonValue } from "./json";
+import type { Guideline } from "./model";
+
+export async function catalogEntriesDigest(guidelines: readonly Guideline[]): Promise<string> {
+  const rows = [...guidelines]
+    .sort((left, right) => compareUnicode(left.id, right.id))
+    .map((guideline): JsonObject => ({
+      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,
+    }));
+
+  return sha256Text(rows.map(canonicalJson).join(""));
+}
+
+export async function manifestDigest(markdown: string): Promise<string> {
+  return sha256Text(markdown);
+}
+
+export function canonicalJson(value: JsonValue): string {
+  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(",")}}`;
+}
+
+export async function sha256Bytes(value: Uint8Array): Promise<string> {
+  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("");
+}
+
+export function compareUnicode(left: string, right: string): number {
+  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: string): Promise<string> {
+  return sha256Bytes(new TextEncoder().encode(value));
+}

package/src/catalog/json.ts

@@ -0,0 +1,32 @@
+type JsonScalar = boolean | null | number | string;
+
+export interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+export type JsonValue = JsonScalar | JsonObject | readonly JsonValue[];
+
+export function parseJson(text: string): JsonValue {
+  return JSON.parse(text);
+}
+
+export function isJsonObject(value: JsonValue | undefined): value is JsonObject {
+  return (
+    value !== null &&
+    value !== undefined &&
+    !Array.isArray(value) &&
+    Object.prototype.toString.call(value) === "[object Object]"
+  );
+}
+
+export function isJsonNumber(value: JsonValue | undefined): value is number {
+  return (
+    Object.prototype.toString.call(value) === "[object Number]" &&
+    value === value?.valueOf() &&
+    Number.isFinite(value)
+  );
+}
+
+export function isJsonString(value: JsonValue | undefined): value is string {
+  return Object.prototype.toString.call(value) === "[object String]" && value === value?.valueOf();
+}

package/src/catalog/labels.ts

@@ -7,20 +7,22 @@ export type CatalogLabel = {
   modifier?: string;
 };
 
-export function parseLabel(value: unknown, context = "label"): CatalogLabel {
-  if (typeof value !== "string") {
-    throw new CatalogError(`${context} must be a string.`);
-  }
+export function parseLabel(value: string, context = "label"): CatalogLabel {
   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];
+
+  const family = parts[0]!;
+  const category = parts[1]!;
+  const modifier = parts[2];
+
   return {
     value: modifier === undefined ? `${family}:${category}` : `${family}:${category}:${modifier}`,
     family,
@@ -29,6 +31,6 @@ export function parseLabel(value: unknown, context = "label"): CatalogLabel {
   };
 }
 
-export function normalizeLabel(value: unknown, context = "label"): string {
+export function normalizeLabel(value: string, context = "label"): string {
   return parseLabel(value, context).value;
 }

package/src/catalog/manifest.ts

@@ -2,52 +2,68 @@ import { CatalogError } from "./errors";
 import { parseLabel } from "./labels";
 import type { Guideline } from "./model";
 
-export const REQUIRED_MANIFEST_HEADINGS = ["Section Roles", "Label Families"] as const;
+const REQUIRED_MANIFEST_HEADINGS = ["Section Roles", "Label Families"] as const;
 
 export type ManifestDefinition = {
-  name: string;
-  description: string;
-  examples: string[];
+  readonly name: string;
+  readonly description: string;
+  readonly examples: readonly string[];
 };
 
 export type CatalogManifest = {
-  markdown: string;
-  sectionRoles: Record<string, ManifestDefinition>;
-  labelFamilies: Record<string, ManifestDefinition>;
+  readonly markdown: string;
+  readonly sectionRoles: Readonly<Record<string, ManifestDefinition>>;
+  readonly labelFamilies: Readonly<Record<string, ManifestDefinition>>;
+};
+
+type ManifestDefinitions = {
+  "Section Roles": Record<string, ManifestDefinition>;
+  "Label Families": Record<string, ManifestDefinition>;
 };
 
 const headingPattern = /^(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/;
+
 const codeSpanPattern = /`([^`\n]+)`/g;
 
+function manifestDefinitions(): Record<string, ManifestDefinition> {
+  const definitions: Record<string, ManifestDefinition> = Object.create(null);
+
+  return definitions;
+}
+
 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": {},
+
+  const definitions: ManifestDefinitions = {
+    "Section Roles": manifestDefinitions(),
+    "Label Families": manifestDefinitions(),
   };
-  let currentHeading: keyof typeof definitions | string | undefined;
+
+  let currentHeading: 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,
@@ -59,6 +75,7 @@ export function parseCatalogManifest(markdown: string): CatalogManifest {
 
   for (const line of markdown.split("\n")) {
     const match = headingPattern.exec(line);
+
     if (!match) {
       if (currentName !== undefined) currentLines.push(line);
       continue;
@@ -72,9 +89,11 @@ export function parseCatalogManifest(markdown: string): CatalogManifest {
       currentHeading = title;
       currentName = undefined;
       currentLines = [];
+
       if (title === "Section Roles" || title === "Label Families") {
         requiredSeen.add(title);
       }
+
       continue;
     }
 
@@ -83,9 +102,11 @@ export function parseCatalogManifest(markdown: string): CatalogManifest {
       (currentHeading === "Section Roles" || currentHeading === "Label Families")
     ) {
       flushDefinition();
+
       if (!title) {
         throw new CatalogError(`Manifest heading ${currentHeading} contains an empty subheading.`);
       }
+
       currentName = title;
       currentLines = [];
       continue;
@@ -97,21 +118,32 @@ export function parseCatalogManifest(markdown: string): CatalogManifest {
   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.`);
+      throw new CatalogError(`Manifest heading ${heading} must contain definitions.`);
     }
   }
+
   validateLabelFamilyExamples(Object.values(definitions["Label Families"]));
 
-  return {
+  return copyCatalogManifest({
     markdown: markdown.endsWith("\n") ? markdown : `${markdown}\n`,
     sectionRoles: definitions["Section Roles"],
     labelFamilies: definitions["Label Families"],
-  };
+  });
+}
+
+export function copyCatalogManifest(manifest: CatalogManifest): CatalogManifest {
+  return Object.freeze({
+    markdown: manifest.markdown,
+    sectionRoles: copyDefinitions(manifest.sectionRoles),
+    labelFamilies: copyDefinitions(manifest.labelFamilies),
+  });
 }
 
 export function validateManifestCoverage(
@@ -124,57 +156,70 @@ export function validateManifestCoverage(
   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.");
       }
+
+      if (role === "__dangling__") continue;
       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)
+    .filter((role) => !Object.hasOwn(manifest.sectionRoles, role))
     .sort();
+
   const missingFamilies = Array.from(usedFamilies)
-    .filter((family) => manifest.labelFamilies[family] === undefined)
+    .filter((family) => !Object.hasOwn(manifest.labelFamilies, family))
     .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[]) {
+function validateLabelFamilyExamples(definitions: readonly 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.`,
@@ -182,3 +227,19 @@ function validateLabelFamilyExamples(definitions: ManifestDefinition[]) {
     }
   }
 }
+
+function copyDefinitions(
+  definitions: Readonly<Record<string, ManifestDefinition>>,
+): Readonly<Record<string, ManifestDefinition>> {
+  const owned = manifestDefinitions();
+
+  for (const [name, definition] of Object.entries(definitions)) {
+    owned[name] = Object.freeze({
+      name: definition.name,
+      description: definition.description,
+      examples: Object.freeze([...definition.examples]),
+    });
+  }
+
+  return Object.freeze(owned);
+}

package/src/catalog/markdown.ts

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