@openpresentation/opf 0.13.0 → 0.15.1

package/dist/finding-CT_f_vbD.d.ts

@@ -0,0 +1,212 @@
+/**
+ * `error` makes a report invalid. `warning` is a problem the author should fix. `info` is advisory.
+ *
+ * This interface was referenced by `FindingReport`'s JSON-Schema
+ * via the `definition` "FindingSeverity".
+ */
+type FindingSeverity = ("error" | "warning" | "info");
+/**
+ * What kind of question the finding answers. Core uses `format` (is it well-formed OPF), `references` (does everything it points at resolve), `policy` (host house rules), `accessibility`, `layout` (will it present as authored) and `content` (is anything left unfinished). Other producers may use their own category names, such as `narrative` or `audience-fit`.
+ *
+ * This interface was referenced by `FindingReport`'s JSON-Schema
+ * via the `definition` "FindingCategory".
+ */
+type FindingCategory = (("format" | "references" | "policy" | "accessibility" | "layout" | "content") | string);
+/**
+ * One RFC 6902 JSON Patch operation. Paths are JSON Pointers into the checked presentation.
+ *
+ * This interface was referenced by `FindingReport`'s JSON-Schema
+ * via the `definition` "JsonPatchOperation".
+ */
+type JsonPatchOperation = ({
+    op: ("add" | "replace" | "test");
+    path: string;
+    value: unknown;
+} | {
+    op: "remove";
+    path: string;
+} | {
+    op: ("move" | "copy");
+    from: string;
+    path: string;
+});
+/**
+ * The report format every OPF tool shares. A finding is one thing a checker found at one place in a presentation: a stable rule id, a severity, a category, a JSON Pointer path, a message, and optionally source positions, the measured numbers behind it and suggested fixes as JSON Patch. `validate` in `@openpresentation/opf`, the Markdown and YAML converters, the editor's Review panel and hosted reviewers such as pptx.dev's AI review all produce this shape, so a host shows and applies findings from any of them the same way. A report lists findings, tells whether any has severity `error` (`valid`) and counts them by severity; `validate` adds `schemaValid`, `checks` and variable fields on top of it. Core's checks are deterministic and run locally; findings from other producers use their own rule-id prefix and say so in `source`.
+ */
+interface FindingReport {
+    /**
+     * True when no finding has severity `error`.
+     */
+    valid: boolean;
+    /**
+     * Every finding, in report order.
+     */
+    findings: Finding[];
+    /**
+     * How many findings each severity has.
+     */
+    counts: {
+        error: number;
+        warning: number;
+        info: number;
+    };
+}
+/**
+ * One thing a checker found at one place in a presentation.
+ *
+ * This interface was referenced by `FindingReport`'s JSON-Schema
+ * via the `definition` "Finding".
+ */
+interface Finding {
+    /**
+     * Stable `<producer>/<rule>` id, such as `opf/text-contrast` for core or `pptx.dev/narrative-gap` for a hosted reviewer. Ids do not change between releases.
+     */
+    ruleId: string;
+    /**
+     * The producer: `opf` (the default) for core, or the name of another tool such as `pptx.dev/review`.
+     */
+    source?: string;
+    severity: FindingSeverity;
+    category: FindingCategory;
+    /**
+     * JSON Pointer to the value the finding is about, such as `/slides/4/title`. Empty for the whole document, or for a value in a supplied context such as a loaded catalog.
+     */
+    path: string;
+    /**
+     * `document` (the default) when `path` points into the checked presentation, `context` when it points into host-supplied context such as loaded catalog records.
+     */
+    scope?: ("document" | "context");
+    /**
+     * What is wrong, in a sentence.
+     */
+    message: string;
+    /**
+     * What to do about it.
+     */
+    help?: string;
+    /**
+     * Zero-based index of the slide the finding belongs to.
+     */
+    slide?: number;
+    /**
+     * The id of that slide, when it has one.
+     */
+    slideId?: string;
+    location?: FindingLocation;
+    /**
+     * A link to the rule's documentation or to the schema constraint or catalog record the finding is about.
+     */
+    definition?: string;
+    /**
+     * Arguments for the `opf schema` or `opf catalog` command that shows the definition, as an argument list rather than a shell string.
+     */
+    lookup?: string[];
+    suggestions?: FindingSuggestion[];
+    /**
+     * The numbers behind the finding, such as `{ "ratio": 2.1, "needed": 4.5 }`.
+     */
+    measured?: {
+        [k: string]: number | string | boolean | null;
+    };
+    fixes?: FindingFix[];
+    validation?: ValidationIssue;
+}
+/**
+ * A range in the checked text: UTF-16 offset and length from the start, and the one-based line and column of the start. Present when the finding was produced from text (JSON, Markdown or YAML).
+ *
+ * This interface was referenced by `FindingReport`'s JSON-Schema
+ * via the `definition` "FindingLocation".
+ */
+interface FindingLocation {
+    offset: number;
+    length: number;
+    line: number;
+    column: number;
+}
+/**
+ * A value the author could use instead, such as a catalog record that exists. Suggestions name records actually present in the checked context and never replace authored values silently.
+ *
+ * This interface was referenced by `FindingReport`'s JSON-Schema
+ * via the `definition` "FindingSuggestion".
+ */
+interface FindingSuggestion {
+    value: (string | number | boolean | null);
+    label: string;
+    /**
+     * Where the suggestion comes from: `schema`, `document` (a record the document embeds), `registered` (a catalog the host registered) or `contract`.
+     */
+    origin: string;
+    /**
+     * Where the suggested record or constraint is defined.
+     */
+    definition?: string;
+}
+/**
+ * A suggested repair. Core never applies it: the host shows it and applies it through its own undoable edit path. A `patch` fix carries JSON Patch operations; a `focus` fix only names the field the author has to fill in.
+ *
+ * This interface was referenced by `FindingReport`'s JSON-Schema
+ * via the `definition` "FindingFix".
+ */
+interface FindingFix {
+    /**
+     * What applying the fix does, in a few words.
+     */
+    title: string;
+    /**
+     * Stable id within one finding, such as `focus-alt` or `use-readable-color`.
+     */
+    id?: string;
+    /**
+     * `patch` fixes carry `patch`; `focus` fixes carry `focus`.
+     */
+    kind?: ("patch" | "focus");
+    /**
+     * True when applying the fix cannot change what the content says or how it looks beyond the repair, such as switching a failing colour to the one the theme chose. False fixes need a deliberate choice.
+     */
+    safe?: boolean;
+    /**
+     * RFC 6902 JSON Patch operations that apply the fix to the checked presentation.
+     */
+    patch?: JsonPatchOperation[];
+    focus?: FindingFocus;
+}
+/**
+ * The field an author has to fill in, for a fix that cannot be written as a patch.
+ *
+ * This interface was referenced by `FindingReport`'s JSON-Schema
+ * via the `definition` "FindingFocus".
+ */
+interface FindingFocus {
+    /**
+     * JSON Pointer of the field to edit.
+     */
+    path: string;
+    /**
+     * What the field is, such as `alt`, `title`, `text`, `link`, `language` or `fontSize`.
+     */
+    field: string;
+    /**
+     * The field's current value, when it has one.
+     */
+    value?: (string | number | boolean | null | unknown[] | {});
+}
+/**
+ * The raw schema or semantic issue behind a finding, kept with every union alternative so a host can inspect the exact constraint.
+ *
+ * This interface was referenced by `FindingReport`'s JSON-Schema
+ * via the `definition` "ValidationIssue".
+ */
+interface ValidationIssue {
+    path: string;
+    message: string;
+    /**
+     * The JSON Schema keyword that failed, or `opf` for a rule the schema cannot express.
+     */
+    keyword: string;
+    schemaPath: string;
+    params: {
+        [k: string]: unknown;
+    };
+}
+
+export type { FindingReport as F, JsonPatchOperation as J, ValidationIssue as V, Finding as a, FindingLocation as b, FindingSeverity as c, FindingCategory as d, FindingFix as e, FindingFocus as f, FindingSuggestion as g };

package/dist/format.d.ts

@@ -1,4 +1,4 @@
-declare class FormatError extends Error {
+declare class OPFFormatError extends Error {
     constructor(message: string);
 }
 interface FormatOptions {
@@ -11,10 +11,10 @@ interface FormatOptions {
 declare function sortPresentationKeys<T>(document: T): T;
 /**
  * Canonical text for an OPF document. `input` is either JSON source text or
- * a parsed document. Throws `FormatError` for text that is not JSON.
+ * a parsed document. Throws `OPFFormatError` for text that is not JSON.
  */
-declare function formatPresentation(input: unknown, options?: FormatOptions): string;
+declare function format(input: unknown, options?: FormatOptions): string;
 /** True when `source` is already exactly the canonical text. */
 declare function isFormatted(source: string, options?: FormatOptions): boolean;
 
-export { FormatError, type FormatOptions, formatPresentation, isFormatted, sortPresentationKeys };
+export { type FormatOptions, OPFFormatError, format, isFormatted, sortPresentationKeys };

package/dist/format.js

@@ -1,83 +1,2 @@
-import { presentation } from './chunk-7QBCWNWL.js';
-
-// src/format.ts
-var FormatError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "FormatError";
-  }
-};
-var root = presentation;
-var flattenCache = /* @__PURE__ */ new WeakMap();
-function collect(schema, seen) {
-  if (!schema || typeof schema !== "object" || seen.has(schema)) return [];
-  seen.add(schema);
-  const node = schema;
-  const out = [node];
-  if (typeof node.$ref === "string" && node.$ref.startsWith("#/$defs/")) out.push(...collect(root.$defs?.[node.$ref.slice("#/$defs/".length)], seen));
-  for (const list of [node.oneOf, node.anyOf, node.allOf]) for (const branch of list ?? []) out.push(...collect(branch, seen));
-  out.push(...collect(node.then, seen), ...collect(node.else, seen));
-  return out;
-}
-function flatten(schema) {
-  if (!schema || typeof schema !== "object") return [];
-  const cached = flattenCache.get(schema);
-  if (cached) return cached;
-  const nodes = collect(schema, /* @__PURE__ */ new Set());
-  flattenCache.set(schema, nodes);
-  return nodes;
-}
-var own = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
-function arrange(value, schemas) {
-  if (Array.isArray(value)) {
-    const itemSchemas = schemas.flatMap((node) => node.items && typeof node.items === "object" ? flatten(node.items) : []);
-    return value.map((item) => arrange(item, itemSchemas));
-  }
-  if (!value || typeof value !== "object") return value;
-  const record = value;
-  const declared = [];
-  const seen = /* @__PURE__ */ new Set();
-  for (const node of schemas) for (const key of Object.keys(node.properties ?? {})) if (!seen.has(key)) {
-    seen.add(key);
-    declared.push(key);
-  }
-  const present = Object.keys(record);
-  const ordered = [...declared.filter((key) => own(record, key)), ...present.filter((key) => !seen.has(key))];
-  const out = {};
-  for (const key of ordered) {
-    let children = schemas.flatMap((node) => node.properties && own(node.properties, key) ? flatten(node.properties[key]) : []);
-    if (!children.length && !seen.has(key)) children = schemas.flatMap((node) => node.additionalProperties && typeof node.additionalProperties === "object" ? flatten(node.additionalProperties) : []);
-    Object.defineProperty(out, key, { value: arrange(record[key], children), enumerable: true, configurable: true, writable: true });
-  }
-  return out;
-}
-function sortPresentationKeys(document) {
-  return arrange(document, flatten(root));
-}
-function formatPresentation(input, options = {}) {
-  let document = input;
-  if (typeof input === "string") {
-    try {
-      document = JSON.parse(input.replace(/^/u, ""));
-    } catch (error) {
-      throw new FormatError(`Invalid JSON: ${error.message}`);
-    }
-  }
-  const indent = options.indent ?? 2;
-  if (!Number.isInteger(indent) || indent < 0 || indent > 8) throw new FormatError("indent must be an integer from 0 to 8.");
-  if (options.eol !== void 0 && options.eol !== "lf" && options.eol !== "crlf") throw new FormatError("eol must be lf or crlf.");
-  const text = JSON.stringify(sortPresentationKeys(document), null, indent);
-  if (text === void 0) throw new FormatError("Nothing to format.");
-  return options.eol === "crlf" ? `${text.replaceAll("\n", "\r\n")}\r
-` : `${text}
-`;
-}
-function isFormatted(source, options = {}) {
-  try {
-    return formatPresentation(source, options) === source;
-  } catch {
-    return false;
-  }
-}
-
-export { FormatError, formatPresentation, isFormatted, sortPresentationKeys };
+export { OPFFormatError, format, isFormatted, sortPresentationKeys } from './chunk-ZPU46TFA.js';
+import './chunk-2CJPC4HI.js';