@openpresentation/opf 0.13.0 → 0.14.0

package/dist/yaml.js

@@ -0,0 +1,321 @@
+import { Ctx } from './chunk-4LDGKLUC.js';
+import { sortPresentationKeys } from './chunk-5ZU6JAPP.js';
+import { same } from './chunk-CSQHPVGL.js';
+import { validate } from './chunk-JDJBDYSR.js';
+import './chunk-6OXY2CP3.js';
+import './chunk-S5W34SIJ.js';
+import './chunk-XOZ4KMSR.js';
+import { presentation } from './chunk-LS2FMPI5.js';
+import { Parser, parseDocument, isMap, Document, visit, isScalar, isAlias, isSeq } from 'yaml';
+
+var MAX_ALIAS_COUNT = 100;
+var CORE_TAGS = new Set(["map", "seq", "str", "int", "float", "bool", "null"].map((name) => `tag:yaml.org,2002:${name}`));
+var ALIAS_HELP = "Write each value out instead of using anchors (&name), aliases (*name) and merge keys (<<). Pass aliases: true (CLI: --aliases) to expand them.";
+var TAG_HELP = "Custom tags are not accepted. Remove the tag; quote a value to keep it as text.";
+var CYCLE_HELP = "An alias must not appear inside its own anchor. Write the nested value out.";
+var decode = (part) => part.replaceAll("~1", "/").replaceAll("~0", "~");
+var encode = (part) => part.replaceAll("~", "~0").replaceAll("/", "~1");
+var pointerOf = (parts) => parts.length ? `/${parts.map(encode).join("/")}` : "";
+function rangeOfPointer(doc, pointer) {
+  const root = doc?.contents;
+  if (!root?.range) return void 0;
+  const parts = pointer === "" ? [] : pointer.slice(1).split("/").map(decode);
+  let node = root;
+  let key;
+  for (const part of parts) {
+    if (isAlias(node)) break;
+    let child;
+    let childKey;
+    if (isMap(node)) {
+      const pairs = node.items;
+      const pair = pairs.find((item) => isScalar(item.key) && String(item.key.value) === part) ?? pairs.find((item) => isMergeKey(item.key) && item.value);
+      if (pair) {
+        childKey = pair.key;
+        child = pair.value ?? childKey;
+      }
+    } else if (isSeq(node)) child = node.items[/^(?:0|[1-9]\d*)$/.test(part) ? Number(part) : -1];
+    if (!child?.range) break;
+    node = child;
+    key = childKey;
+  }
+  const [start, end] = node.range;
+  if (key?.range && (isMap(node) || isSeq(node) || isAlias(node))) return { start: key.range[0], end };
+  return { start, end: Math.max(start, end) };
+}
+function isMergeKey(key) {
+  return isScalar(key) && (typeof key.value === "symbol" || key.value === "<<" && key.type === "PLAIN");
+}
+function describeError(error) {
+  const text = error.message.split("\n")[0] ?? error.message;
+  switch (error.code) {
+    case "DUPLICATE_KEY":
+      return { rule: "duplicate-key", message: `YAML: ${text}`, help: "Remove or rename one of the repeated keys. JSON-compatible YAML needs every key once in each mapping." };
+    case "MULTIPLE_DOCS":
+      return { rule: "multiple-documents", message: "The input holds more than one YAML document.", help: "An OPF file is exactly one document: remove the extra --- separators, or put each deck in its own file." };
+    case "TAG_RESOLVE_FAILED":
+      return { rule: "tag", message: `YAML: ${text}`, help: TAG_HELP };
+    case "BAD_ALIAS":
+      return { rule: "alias", message: `YAML: ${text}`, help: ALIAS_HELP };
+    default:
+      return { rule: "syntax", message: `YAML: ${text}`, help: "Fix the YAML syntax at this position. An OPF file holds JSON-compatible YAML 1.2: mappings, sequences and scalars." };
+  }
+}
+function keyRangeAt(doc, start) {
+  let found;
+  visit(doc, {
+    Pair(_key, pair) {
+      const key = pair.key;
+      if (!found && key?.range && key.range[0] === start) found = { start, end: key.range[1] };
+    }
+  });
+  return found;
+}
+function readYamlDocument(source, aliases, rootKind = "mapping") {
+  const bom = source.startsWith("\uFEFF") ? 1 : 0;
+  const text = source.slice(bom);
+  const ctx = new Ctx(text);
+  const findings = [];
+  const locate = (range) => {
+    const location = ctx.location(range);
+    return { ...location, offset: location.offset + bom };
+  };
+  const add = (rule, message, help, range, path = "") => {
+    findings.push({ ruleId: `yaml/${rule}`, severity: "error", category: "format", scope: "document", path, message, help, location: locate(range) });
+  };
+  const doc = parseDocument(text, { schema: "core", uniqueKeys: true, merge: aliases, prettyErrors: false });
+  const finish = (value2) => ({
+    value: value2,
+    locatePointer: (pointer) => {
+      const range = rangeOfPointer(doc, pointer);
+      return range ? locate(range) : void 0;
+    },
+    findings,
+    errors: findings.length
+  });
+  for (const error of [...doc.errors, ...doc.warnings.filter((warning) => warning.code === "TAG_RESOLVE_FAILED")]) {
+    const described = describeError(error);
+    const [start, end] = error.pos;
+    add(described.rule, described.message, described.help, (error.code === "DUPLICATE_KEY" ? keyRangeAt(doc, start) : void 0) ?? { start, end: Math.max(start, end) });
+  }
+  if (findings.length) return finish({});
+  const root = doc.contents;
+  if (root === null || !root.range) {
+    add("empty", "The input holds no YAML document.", "An OPF file is one YAML mapping: write the deck properties (name, slides, ...) as key: value lines.", { start: 0, end: Math.min(1, text.length) });
+    return finish({});
+  }
+  const rootRange = { start: root.range[0], end: root.range[1] };
+  if (rootKind === "mapping" && !isMap(root)) {
+    add("not-mapping", "The document is not a mapping.", "An OPF deck is a YAML mapping of keys and values (name:, slides:, ...), not a list or a single value.", rootRange);
+    return finish({});
+  }
+  checkTree({ doc, text, aliases, add }, root, [], []);
+  if (findings.length) return finish({});
+  let value;
+  try {
+    value = doc.toJS({ maxAliasCount: aliases ? MAX_ALIAS_COUNT : 0 });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/excessive alias/i.test(message)) add("alias-limit", `The anchors and aliases expand beyond the limit of ${MAX_ALIAS_COUNT} aliases.`, "Aliases that contain aliases grow exponentially. Write the repeated values out, or reduce the aliasing.", rootRange);
+    else add("alias", `YAML: ${message}`, ALIAS_HELP, rootRange);
+    return finish({});
+  }
+  if (isCircular(value)) {
+    add("alias-cycle", "An alias refers to the value that contains it, so the document is infinitely deep.", CYCLE_HELP, rootRange);
+    return finish({});
+  }
+  const bad = nonJson(value);
+  if (bad) {
+    add("number", `The YAML holds ${bad}, which JSON cannot carry.`, "Quote it to keep it as text, or write a finite number.", rootRange);
+    return finish({});
+  }
+  return finish(value);
+}
+function propertyRange(text, nodeStart, token, fallback) {
+  const found = text.lastIndexOf(token, nodeStart);
+  return found >= 0 && found < nodeStart ? { start: found, end: found + token.length } : fallback;
+}
+function checkTree(env, node, trail, ancestors) {
+  const { doc, text, aliases, add } = env;
+  const path = pointerOf(trail);
+  const range = (target) => ({ start: target.range?.[0] ?? 0, end: Math.max(target.range?.[0] ?? 0, target.range?.[1] ?? 0) });
+  if (isAlias(node)) {
+    const name = node.source;
+    if (!aliases) add("alias", `The alias *${name} is not allowed.`, ALIAS_HELP, range(node), path);
+    else {
+      const target = node.resolve(doc);
+      if (target && ancestors.includes(target)) add("alias-cycle", `The alias *${name} refers to a value that contains it.`, CYCLE_HELP, range(node), path);
+    }
+    return;
+  }
+  const anchor = node.anchor;
+  if (anchor !== void 0 && !aliases) add("alias", `The anchor &${anchor} is not allowed.`, ALIAS_HELP, propertyRange(text, node.range?.[0] ?? 0, `&${anchor}`, range(node)), path);
+  const tag = node.tag;
+  if (tag !== void 0 && !CORE_TAGS.has(tag)) {
+    let start = text.lastIndexOf("!", node.range?.[0] ?? 0);
+    while (start > 0 && text[start - 1] === "!") start--;
+    const written = start >= 0 ? /^!\S*/.exec(text.slice(start))?.[0] : void 0;
+    add("tag", `The tag ${written ?? tag} is not allowed.`, TAG_HELP, written && start < (node.range?.[0] ?? 0) ? { start, end: start + written.length } : range(node), path);
+  }
+  if (isScalar(node)) {
+    const value = node.value;
+    if (typeof value === "number" && !Number.isFinite(value)) add("number", `${String(node.source ?? value)} is not a finite number, and JSON cannot carry it.`, 'Quote it (".inf", ".nan") to keep it as text, or write a finite number.', range(node), path);
+    return;
+  }
+  const inside = [...ancestors, node];
+  if (isMap(node)) {
+    for (const pair of node.items) {
+      const key = pair.key;
+      if (key && isMergeKey(key)) {
+        if (!aliases) add("alias", "The merge key << is not allowed.", ALIAS_HELP, range(key), path);
+        else {
+          const source = pair.value;
+          if (source && isSeq(source)) for (const item of source.items) checkTree(env, item, [...trail, "<<"], inside);
+          else if (source) checkTree(env, source, [...trail, "<<"], inside);
+        }
+        continue;
+      }
+      const resolved = key && isAlias(key) ? key.resolve(doc) : key;
+      const name = resolved && isScalar(resolved) && typeof resolved.value === "string" ? resolved.value : void 0;
+      if (key) checkTree(env, key, trail, inside);
+      if (name === void 0) {
+        add("key", "A mapping key is not a string.", 'JSON keys are always strings. Quote the key, for example "1": value.', key ? range(key) : range(node), path);
+        continue;
+      }
+      if (pair.value) checkTree(env, pair.value, [...trail, name], inside);
+    }
+    return;
+  }
+  if (isSeq(node)) {
+    const items = node.items;
+    for (let index = 0; index < items.length; index++) checkTree(env, items[index], [...trail, String(index)], inside);
+  }
+}
+function nonJson(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? void 0 : "a number that is not finite";
+  if (value === null || typeof value === "string" || typeof value === "boolean") return void 0;
+  if (Array.isArray(value)) return value.map(nonJson).find(Boolean);
+  if (typeof value === "object") {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) return `a ${value.constructor?.name ?? "non-JSON"} value`;
+    return Object.values(value).map(nonJson).find(Boolean);
+  }
+  return `a ${typeof value}`;
+}
+function isCircular(value, stack = /* @__PURE__ */ new Set()) {
+  if (typeof value !== "object" || value === null) return false;
+  if (stack.has(value)) return true;
+  stack.add(value);
+  const found = Object.values(value).some((child) => isCircular(child, stack));
+  stack.delete(value);
+  return found;
+}
+function scanYamlComments(source) {
+  const text = source.startsWith("\uFEFF") ? source.slice(1) : source;
+  let count = 0;
+  let modeline;
+  const visit3 = (value) => {
+    if (Array.isArray(value)) value.forEach(visit3);
+    else if (value && typeof value === "object") {
+      const token = value;
+      if (token.type === "comment" && typeof token.source === "string") {
+        if (modeline === void 0 && token.offset === 0 && /^#\s*yaml-language-server:/.test(token.source)) modeline = token.source;
+        else count++;
+      } else for (const child of Object.values(value)) visit3(child);
+    }
+  };
+  for (const token of new Parser().parse(text)) visit3(token);
+  return { count, ...modeline === void 0 ? {} : { modeline } };
+}
+var AMBIGUOUS = [
+  /^(?:y|n|yes|no|on|off|true|false|null|~|=|<<)$/i,
+  /^[-+]?(?:0[0-7_]+|0b[01_]+|0x[0-9a-f_]+|[0-9][0-9_]*(?:\.[0-9_]*)?(?:e[-+]?[0-9]+)?|\.[0-9_]+(?:e[-+]?[0-9]+)?|\.inf)$/i,
+  /^\.nan$/i,
+  /^\d{4}-\d{1,2}-\d{1,2}(?:[Tt ].*)?$/,
+  /^[-+]?[0-9][0-9_]*(?::[0-5]?[0-9])+(?:\.[0-9_]*)?$/
+];
+var isAmbiguous = (text) => AMBIGUOUS.some((pattern) => pattern.test(text));
+function writeCanonicalYaml(value, reads) {
+  const expected = JSON.stringify(value);
+  for (const blockQuote of [true, false]) {
+    const doc = new Document(value, { schema: "core" });
+    visit(doc, {
+      Scalar(_key, node) {
+        if (isScalar(node) && typeof node.value === "string" && isAmbiguous(node.value)) node.type = "QUOTE_DOUBLE";
+      }
+    });
+    const text = doc.toString({ indent: 2, lineWidth: 0, minContentWidth: 0, blockQuote, defaultStringType: "PLAIN", defaultKeyType: "PLAIN" });
+    const out = text.endsWith("\n") ? text : `${text}
+`;
+    let back;
+    try {
+      back = reads(out);
+    } catch {
+      continue;
+    }
+    if (JSON.stringify(back) === expected) return out;
+  }
+  return void 0;
+}
+
+// src/yaml.ts
+var YAML_SCHEMA_URL = presentation.$id;
+var NOT_CHECKED = { syntax: "checked", schema: "not-run", references: "not-run", policy: "not-run", accessibility: "not-run", content: "not-run", layout: "not-run", backgroundPixels: "not-read", imageBytes: "embedded-only", nativeExport: "not-checked" };
+function fromYaml(yaml, options = {}) {
+  if (typeof yaml !== "string") throw new TypeError("fromYaml expects a string.");
+  const parsed = readYamlDocument(yaml, options.aliases === true);
+  const findings = [...parsed.findings];
+  let report = { schemaValid: null, checks: NOT_CHECKED };
+  if (!parsed.errors && options.validate !== false) {
+    const checked = validate(parsed.value, options.validate === true || options.validate === void 0 ? { only: ["format", "references"] } : options.validate);
+    report = {
+      schemaValid: checked.schemaValid,
+      checks: { ...checked.checks, syntax: "checked" },
+      ...checked.template === void 0 ? {} : { template: checked.template },
+      ...checked.unfilledVariables === void 0 ? {} : { unfilledVariables: checked.unfilledVariables }
+    };
+    for (const found of checked.findings) {
+      const location = parsed.locatePointer(found.path) ?? parsed.locatePointer("") ?? { offset: 0, length: 0, line: 1, column: 1 };
+      findings.push({ ...found, location });
+    }
+  }
+  findings.sort((a, b) => a.location.offset - b.location.offset);
+  const counts = { error: 0, warning: 0, info: 0 };
+  for (const found of findings) counts[found.severity]++;
+  return { presentation: parsed.value, valid: counts.error === 0, findings, counts, ...report };
+}
+var OPFYamlError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "OPFYamlError";
+    this.code = code;
+    this.details = details;
+  }
+};
+function toYaml(document, options = {}) {
+  const checked = validate(document, { only: ["format"] });
+  if (!checked.valid) {
+    const errors = checked.findings.filter((found) => found.severity === "error");
+    const first = errors[0];
+    throw new OPFYamlError("invalid-document", `The document is not valid OPF: ${first?.message ?? "unknown error"}${first?.path ? ` (${first.path})` : ""}.`, { findings: errors });
+  }
+  const sorted = sortPresentationKeys(document);
+  const text = writeCanonicalYaml(sorted, (out) => {
+    const back = readYamlDocument(out, false);
+    if (back.errors) throw new Error("The YAML does not read back.");
+    return back.value;
+  });
+  if (text === void 0) throw new OPFYamlError("not-representable", "The document holds a value that YAML cannot carry exactly.");
+  if (!same(JSON.parse(JSON.stringify(sorted)), readYamlDocument(text, false).value)) throw new OPFYamlError("not-representable", "The document does not read back from its YAML.");
+  const schema = typeof sorted.$schema === "string" && !/[\r\n]/.test(sorted.$schema) ? sorted.$schema : YAML_SCHEMA_URL;
+  return { yaml: options.schemaComment ? `# yaml-language-server: $schema=${schema}
+${text}` : text };
+}
+function parseYamlData(yaml, options = {}) {
+  if (typeof yaml !== "string") throw new TypeError("parseYamlData expects a string.");
+  const parsed = readYamlDocument(yaml, options.aliases === true, "any");
+  return { value: parsed.errors ? null : parsed.value, valid: parsed.errors === 0, findings: parsed.findings };
+}
+
+export { OPFYamlError, YAML_SCHEMA_URL, fromYaml, parseYamlData, scanYamlComments, toYaml };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpresentation/opf",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Canonical Open Presentation Format schemas, catalogs, TypeScript types, and local validation.",
   "license": "MIT",
   "author": "Open Presentation",
@@ -92,14 +92,14 @@
       "types": "./dist/symbol-font-encodings.d.ts",
       "import": "./dist/symbol-font-encodings.js"
     },
-    "./lint": {
-      "types": "./dist/lint.d.ts",
-      "import": "./dist/lint.js"
-    },
     "./markdown": {
       "types": "./dist/markdown.d.ts",
       "import": "./dist/markdown.js"
     },
+    "./yaml": {
+      "types": "./dist/yaml.d.ts",
+      "import": "./dist/yaml.js"
+    },
     "./patch": {
       "types": "./dist/patch.d.ts",
       "import": "./dist/patch.js"
@@ -115,10 +115,6 @@
     "./convert": {
       "types": "./dist/convert.d.ts",
       "import": "./dist/convert.js"
-    },
-    "./audit": {
-      "types": "./dist/audit.d.ts",
-      "import": "./dist/audit.js"
     }
   },
   "files": [

package/dist/audit.d.ts

@@ -1,35 +0,0 @@
-import { A as AuditThresholds, a as AuditOptions, b as AuditReport, c as AuditRuleInfo } from './lint-B7azdiuE.js';
-export { d as AuditCategory, e as AuditDiagnostic, f as AuditFix, g as AuditPatchOperation, h as AuditSeverity } from './lint-B7azdiuE.js';
-import './catalogs-ywCamd8C.js';
-import './schemas-BbPonsTz.js';
-import './validator-CIylxoIm.js';
-import './presentation-mG-IYErQ.js';
-import './composition-D7we69Tr.js';
-import './chart-data-Cdr6rRVV.js';
-
-/**
- * The series palette opf-render and opf-pptx draw charts with (`CHART_COLORS`), in series order. A host with
- * its own palette passes `AuditOptions.chartPalette`.
- */
-declare const DEFAULT_CHART_PALETTE: readonly string[];
-
-/**
- * Design and accessibility audit of a presentation: contrast, overflow, minimum type size, alt text,
- * reading order, titles, fonts, links, charts, placeholders and more. Read-only and deterministic; no
- * network, clock or model. Each rule has a stable `audit/<name>` id (see docs/audit.md).
- */
-declare const DEFAULT_AUDIT_THRESHOLDS: Readonly<AuditThresholds>;
-/** Every rule the audit can report, with its default severity, rationale and approximations, in report order. */
-declare const auditRules: readonly AuditRuleInfo[];
-/** The rule a full id (`audit/text-contrast`) or bare name (`text-contrast`) names, or undefined. */
-declare function findAuditRule(name: string): AuditRuleInfo | undefined;
-/**
- * Audit a parsed presentation. A document that fails schema validation is not audited; its validation
- * errors come back as `audit/invalid-document` findings. Findings have lint's report shape (rule id,
- * severity, JSON Pointer path, message, help) plus `slide`, `measured` and suggested `fixes`.
- */
-declare function auditPresentation(document: unknown, options?: AuditOptions): AuditReport;
-/** Audit JSON source text. Findings carry original-source UTF-16 ranges and one-based line/column, like `lintSource`. */
-declare function auditSource(source: string, options?: AuditOptions): AuditReport;
-
-export { AuditOptions, AuditReport, AuditRuleInfo, AuditThresholds, DEFAULT_AUDIT_THRESHOLDS, DEFAULT_CHART_PALETTE, auditPresentation, auditRules, auditSource, findAuditRule };

package/dist/audit.js

@@ -1,7 +0,0 @@
-export { DEFAULT_AUDIT_THRESHOLDS, DEFAULT_CHART_PALETTE, auditPresentation, auditRules, auditSource, findAuditRule } from './chunk-7N4VMAT4.js';
-import './chunk-INU7ZNSB.js';
-import './chunk-IYCJUKWD.js';
-import './chunk-MPM7NRG7.js';
-import './chunk-S5W34SIJ.js';
-import './chunk-E34DJ5LL.js';
-import './chunk-7QBCWNWL.js';