@pptx-studio/validate 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,707 @@
+import { XAttribute, XDocument, XElement, XNode } from "@pptx-studio/xml";
+import { PartName, PartStore, ReadZipOptions, ZipArchive } from "@pptx-studio/opc";
+//#region src/errors.d.ts
+/**
+ * The single error type this package throws.
+ *
+ * Same invariant as `@pptx-studio/opc` and `@pptx-studio/xml`: **every failure
+ * path throws a `ValidateError` and nothing else.**
+ *
+ * There is a second thing worth saying here, because this package is the one
+ * where the distinction matters most. A *finding* is not an error. A finding is
+ * the normal output of this package - it says a rule was broken, names the part
+ * and the element, and is data a caller can render, sort or ignore. An error is
+ * thrown only when validation itself could not be carried out, or when a caller
+ * asked for bytes and the report says they must not have them.
+ *
+ * Getting that split wrong is how a validator becomes something people disable.
+ * If every broken rule were an exception, the only way to see the second
+ * problem would be to fix the first, and a caller with a deck that breaks nine
+ * rules would learn about them one export at a time.
+ */
+/**
+ * Machine-readable failure reasons.
+ *
+ * Deliberately few. Almost everything this package has to say is a finding.
+ */
+declare const VALIDATE_ERROR_CODES: readonly ["ERR_VALIDATION_FAILED", "ERR_UNVALIDATABLE", "ERR_UNKNOWN_RULE"];
+type ValidateErrorCode = (typeof VALIDATE_ERROR_CODES)[number];
+interface ValidateErrorDetail {
+  /** The part the failure is about, if it is about one. */
+  readonly part?: string;
+  /** The rule id a caller got wrong, for `ERR_UNKNOWN_RULE`. */
+  readonly rule?: string;
+  /**
+   * The full report, for `ERR_VALIDATION_FAILED`.
+   *
+   * Typed `unknown` rather than `Report` on purpose: `report.ts` imports this
+   * module for the error, so typing this field would make the two circular.
+   * Callers narrow it with `isReport`.
+   */
+  readonly report?: unknown;
+}
+declare class ValidateError extends Error {
+  readonly code: ValidateErrorCode;
+  readonly detail: ValidateErrorDetail;
+  constructor(code: ValidateErrorCode, message: string, detail?: ValidateErrorDetail);
+}
+declare function isValidateError(value: unknown): value is ValidateError;
+//#endregion
+//#region src/rules/rules.d.ts
+/**
+ * The twenty-nine rules, and the evidence for each.
+ *
+ * ## Why a table and not twenty-nine functions
+ *
+ * The functions are in the files beside this one. What lives here is the part a
+ * person reads: what each rule claims, how sure we are, and *how we know*. A
+ * validator whose rules exist only as code is a validator nobody can audit, and
+ * this one has to be audited, because roughly half of it enforces things no
+ * schema says.
+ *
+ * That is the fact that shapes the whole package. ECMA-376 is a description of
+ * a file format; PowerPoint is an implementation that refuses files the
+ * description permits. Sub-phase 0.7 and the corpus bisections in
+ * `tools/corpus/ROSTER.md` found nineteen such refusals by building a package
+ * with one change in it and watching PowerPoint decline to open it - no
+ * diagnostic, no log, no part named, just "PowerPoint could not open the file"
+ * or `0x80070570`. Every rule below whose `evidence` says `measured` came from
+ * that loop and from nowhere else.
+ *
+ * So each rule carries three things beyond its check:
+ *
+ * - `evidence` - `schema` (ECMA-376 says so), `measured` (we watched PowerPoint
+ *   refuse it), or `both`.
+ * - `why` - the sentence that justifies the rule to somebody who is about to
+ *   delete it because it fired on their file.
+ * - `severity` - `fatal` refuses an export; `warning` is reported and does not.
+ *
+ * ## On being wrong in the safe direction
+ *
+ * A false positive here blocks an export a user wanted. A false negative hands
+ * them a file PowerPoint will not open, with no way to find out why. Those are
+ * not symmetric, but the first is not free either - a validator that fires on
+ * good files gets turned off, and then it catches nothing.
+ *
+ * The resolution is `origin`, which lives on the finding rather than here: a
+ * fatal a caller *introduced* refuses the export, and the identical fatal that
+ * was already in the file when it was opened is reported and does not. That is
+ * the same split `PartStore.write` already makes for dangling relationships,
+ * and for the same reason - refusing to re-export a file we did not break makes
+ * the file unopenable in this editor and does not fix anything.
+ */
+type RuleCategory = 'package' | 'relationships' | 'order' | 'required' | 'ids' | 'refused' | 'preservation';
+type Severity = 'fatal' | 'warning';
+/** Where the rule comes from. See the header. */
+type Evidence = 'schema' | 'measured' | 'both';
+interface Rule {
+  readonly id: RuleId;
+  readonly category: RuleCategory;
+  readonly severity: Severity;
+  readonly evidence: Evidence;
+  /** One line, imperative, in the voice of the thing that must be true. */
+  readonly title: string;
+  /** Why the rule exists, for whoever is about to argue with it. */
+  readonly why: string;
+  /**
+   * True when the rule needs the package as it was opened as well as the
+   * package about to be written.
+   *
+   * Six rules do. They are skipped rather than passed when no baseline is
+   * given, and the report says so - a preservation rule that silently reports
+   * nothing because it had nothing to compare against is worse than one that
+   * did not run, because it looks like a pass.
+   */
+  readonly needsBaseline?: true;
+}
+declare const RULES: readonly [{
+  readonly id: "V001";
+  readonly category: "package";
+  readonly severity: "fatal";
+  readonly evidence: "both";
+  readonly title: "every part resolves to a content type";
+  readonly why: string;
+}, {
+  readonly id: "V002";
+  readonly category: "package";
+  readonly severity: "fatal";
+  readonly evidence: "both";
+  readonly title: "the content-type map is internally consistent";
+  readonly why: string;
+}, {
+  readonly id: "V003";
+  readonly category: "package";
+  readonly severity: "fatal";
+  readonly evidence: "schema";
+  readonly title: "the archive carries no directory entries and no ZIP64 record";
+  readonly why: string;
+}, {
+  readonly id: "V004";
+  readonly category: "package";
+  readonly severity: "fatal";
+  readonly evidence: "both";
+  readonly title: "part names are ASCII, well formed, and free of pointless percent-escapes";
+  readonly why: string;
+}, {
+  readonly id: "V005";
+  readonly category: "package";
+  readonly severity: "fatal";
+  readonly evidence: "both";
+  readonly title: "there is exactly one main presentation part, of a matching content type";
+  readonly why: string;
+}, {
+  readonly id: "V006";
+  readonly category: "relationships";
+  readonly severity: "fatal";
+  readonly evidence: "both";
+  readonly title: "every relationship reference resolves in its own part’s `.rels`";
+  readonly why: string;
+}, {
+  readonly id: "V007";
+  readonly category: "relationships";
+  readonly severity: "fatal";
+  readonly evidence: "schema";
+  readonly title: "relationship ids are unique within a `.rels` and match the `xsd:ID` grammar";
+  readonly why: string;
+}, {
+  readonly id: "V008";
+  readonly category: "relationships";
+  readonly severity: "fatal";
+  readonly evidence: "both";
+  readonly title: "internal targets resolve inside the package, relative to the source part’s folder";
+  readonly why: string;
+}, {
+  readonly id: "V009";
+  readonly category: "relationships";
+  readonly severity: "fatal";
+  readonly evidence: "measured";
+  readonly title: "the relationship edges a part must have, and the ones it must not";
+  readonly why: string;
+}, {
+  readonly id: "V010";
+  readonly category: "order";
+  readonly severity: "fatal";
+  readonly evidence: "both";
+  readonly title: "children appear in schema-sequence order";
+  readonly why: string;
+}, {
+  readonly id: "V011";
+  readonly category: "order";
+  readonly severity: "fatal";
+  readonly evidence: "schema";
+  readonly title: "`extLst` is last among its siblings, and every `a:ext` carries a `@uri`";
+  readonly why: string;
+}, {
+  readonly id: "V012";
+  readonly category: "order";
+  readonly severity: "fatal";
+  readonly evidence: "both";
+  readonly title: "no child appears in a parent whose content model has no place for it";
+  readonly why: string;
+}, {
+  readonly id: "V013";
+  readonly category: "required";
+  readonly severity: "fatal";
+  readonly evidence: "schema";
+  readonly title: "`p:presentation` carries `p:notesSz`";
+  readonly why: string;
+}, {
+  readonly id: "V014";
+  readonly category: "required";
+  readonly severity: "fatal";
+  readonly evidence: "schema";
+  readonly title: "`p:clrMap` carries all twelve attributes";
+  readonly why: string;
+}, {
+  readonly id: "V015";
+  readonly category: "required";
+  readonly severity: "fatal";
+  readonly evidence: "schema";
+  readonly title: "`p:spTree` begins with `p:nvGrpSpPr` then `p:grpSpPr`";
+  readonly why: string;
+}, {
+  readonly id: "V016";
+  readonly category: "required";
+  readonly severity: "fatal";
+  readonly evidence: "schema";
+  readonly title: "every text body has `a:bodyPr` and at least one `a:p`";
+  readonly why: string;
+}, {
+  readonly id: "V017";
+  readonly category: "required";
+  readonly severity: "fatal";
+  readonly evidence: "schema";
+  readonly title: "`p:graphicFrame` carries `p:xfrm` and `a:graphic`";
+  readonly why: string;
+}, {
+  readonly id: "V018";
+  readonly category: "ids";
+  readonly severity: "fatal";
+  readonly evidence: "schema";
+  readonly title: "`p:sldId/@id` is 256…2147483647 and unique";
+  readonly why: string;
+}, {
+  readonly id: "V019";
+  readonly category: "ids";
+  readonly severity: "fatal";
+  readonly evidence: "both";
+  readonly title: "master and layout ids are ≥ 2147483648 and unique **across both lists**";
+  readonly why: string;
+}, {
+  readonly id: "V020";
+  readonly category: "ids";
+  readonly severity: "fatal";
+  readonly evidence: "both";
+  readonly title: "`p:cNvPr/@id` is unique within its part and ≤ 2147483647";
+  readonly why: string;
+}, {
+  readonly id: "V021";
+  readonly category: "ids";
+  readonly severity: "warning";
+  readonly evidence: "schema";
+  readonly title: "a slide placeholder’s `(type, idx)` has a counterpart in its layout";
+  readonly why: string;
+}, {
+  readonly id: "V022";
+  readonly category: "refused";
+  readonly severity: "fatal";
+  readonly evidence: "measured";
+  readonly title: "`p:ph/@type` is not `hdr` or `sldImg` outside a notes or handout part";
+  readonly why: string;
+}, {
+  readonly id: "V023";
+  readonly category: "refused";
+  readonly severity: "fatal";
+  readonly evidence: "measured";
+  readonly title: "every geometry guide named is a guide that is defined";
+  readonly why: string;
+}, {
+  readonly id: "V024";
+  readonly category: "refused";
+  readonly severity: "fatal";
+  readonly evidence: "both";
+  readonly title: "`c:tx` holds `c:strRef` or `c:v`, never `c:strLit`";
+  readonly why: string;
+}, {
+  readonly id: "V025";
+  readonly category: "refused";
+  readonly severity: "fatal";
+  readonly evidence: "measured";
+  readonly title: "no `p:control`";
+  readonly why: string;
+}, {
+  readonly id: "V026";
+  readonly category: "refused";
+  readonly severity: "fatal";
+  readonly evidence: "measured";
+  readonly title: "a `cs:chartStyle` carries all thirty-one of its entries";
+  readonly why: string;
+}, {
+  readonly id: "V027";
+  readonly category: "preservation";
+  readonly severity: "fatal";
+  readonly evidence: "schema";
+  readonly needsBaseline: true;
+  readonly title: "a part nobody edited comes back out byte-for-byte";
+  readonly why: string;
+}, {
+  readonly id: "V028";
+  readonly category: "preservation";
+  readonly severity: "fatal";
+  readonly evidence: "schema";
+  readonly needsBaseline: true;
+  readonly title: "no `mc:AlternateContent` branch and no `extLst` was rebuilt";
+  readonly why: string;
+}, {
+  readonly id: "V029";
+  readonly category: "preservation";
+  readonly severity: "fatal";
+  readonly evidence: "both";
+  readonly needsBaseline: true;
+  readonly title: "text and field identity survive: `xml:space`, `a:fld/@id`, cached field text";
+  readonly why: string;
+}];
+type RuleId = (typeof RULES)[number]['id'];
+declare function ruleById(id: string): Rule | undefined;
+declare const RULE_IDS: readonly RuleId[];
+/** Rules that need the package as it was opened. See `Rule.needsBaseline`. */
+declare const BASELINE_RULES: readonly RuleId[];
+//#endregion
+//#region src/report/location.d.ts
+/**
+ * Where a finding is, in a form a person can act on.
+ *
+ * ## Why an XPath and not a byte offset
+ *
+ * Both, actually - the offset is on the finding too, because it is what
+ * `cli bisect` needs in sub-phase 1.5 and what a diff viewer can highlight. But
+ * the offset is useless to a human: it names a position in a file that is
+ * usually one line long and often two megabytes wide, and it stops being true
+ * the moment anything above it changes.
+ *
+ * An XPath survives editing, survives reformatting, and can be pasted into
+ * every XML tool there is. More to the point, it is the only form in which
+ * a report about eleven parts is *readable* - `ppt/slides/slide3.xml` at
+ * `/p:sld/p:cSld/p:spTree/p:sp[2]/p:nvSpPr/p:cNvPr/@id` says what is wrong in
+ * one line, and byte 41 207 does not.
+ *
+ * ## Prefixes are the document's own, always
+ *
+ * The path is built from `qname` as written in the file - not from a canonical
+ * prefix table, and not from the namespace URI. If a part spells the
+ * PresentationML namespace `pp:` instead of `p:`, the path says `pp:`, because
+ * the point of the path is that a reader can find the element in the file in
+ * front of them. A canonicalised path would be *more correct* as an XPath
+ * expression and less useful as a location, and this is a diagnostic rather
+ * than a query.
+ *
+ * The same choice is made everywhere in this project for the same reason, and
+ * it is not stylistic: `mc:Ignorable` and `mc:Choice/@Requires` hold prefixes
+ * rather than URIs, so a prefix is load-bearing data in OOXML and inventing one
+ * is never a neutral act.
+ *
+ * ## The positional predicate
+ *
+ * `[n]` is emitted only where it disambiguates - that is, when the element has
+ * a sibling of the same `qname`. `/p:sld/p:cSld/p:spTree/p:sp[2]` is exact;
+ * `/p:sld[1]/p:cSld[1]/p:spTree[1]` is noise. Positions are 1-based, counting
+ * only elements of that name, which is what XPath means by `position()` inside
+ * a name test and is what every XML tool will agree with.
+ */
+/** A location inside a part, or the part itself. */
+interface Location {
+  /**
+   * The part name, with its leading slash: `/ppt/slides/slide1.xml`.
+   *
+   * `/` means the finding is about the package rather than about any one part -
+   * the archive shape, the content-type map, the relationship graph as a whole.
+   */
+  readonly part: string;
+  /** The path to the element or attribute, or `null` for a whole-part finding. */
+  readonly xpath: string | null;
+  /** Byte offset of the node in the part's source, or `null`. For `cli bisect`. */
+  readonly offset: number | null;
+}
+/** A location that names a part and nothing inside it. */
+declare function partLocation(part: string): Location;
+/** The location of the package itself: the archive, the content types, the graph. */
+declare const PACKAGE_LOCATION: Location;
+/**
+ * The XPath of an element, from the document root.
+ *
+ * Never throws and never returns an empty string: a detached element - one
+ * whose `parent` chain does not reach a root - still gets its own name, so a
+ * finding built from a node the caller synthesised is degraded rather than
+ * lost.
+ */
+declare function xpathOf(element: XElement): string;
+/** The XPath of an attribute: its owner's path, then `/@qname`. */
+declare function xpathOfAttribute(owner: XElement, attr: XAttribute | string): string;
+/** A location for an element inside a named part. */
+declare function elementLocation(part: string, element: XElement): Location;
+/**
+ * A location for one attribute of an element.
+ *
+ * The offset is the attribute's own start when the element carries it, and the
+ * element's start when it does not - which is the case that matters, because a
+ * *missing* required attribute is a finding and it has to point somewhere.
+ */
+declare function attributeLocation(part: string, element: XElement, qname: string): Location;
+/**
+ * `line:column` for an offset, 1-based, or `null`.
+ *
+ * Not part of `Location`, because computing it means scanning the source from
+ * the beginning and a report with three hundred findings would scan it three
+ * hundred times. Callers that render a report for a human ask for it once, at
+ * the point of rendering, for the findings they are about to show.
+ */
+declare function lineColumn(source: string, offset: number): {
+  line: number;
+  column: number;
+};
+/** Document order, for sorting findings within a part. */
+declare function inDocumentOrder(a: XNode, b: XNode): number;
+/** The root element's qname, for the handful of rules that dispatch on it. */
+declare function rootName(document: XDocument): string;
+//#endregion
+//#region src/report/report.d.ts
+/**
+ * What validation produces.
+ *
+ * ## Origin, and why it is computed rather than guessed
+ *
+ * The hardest question this package has to answer is not "is this file valid".
+ * It is **"did we break it"**, and those are different questions with different
+ * consequences. A fatal finding in a deck the user imported ten seconds ago is
+ * information; the same finding in a deck they just edited is a bug in us, and
+ * handing over the bytes would give them a repair prompt with no explanation.
+ *
+ * Refusing both would be the strict-looking choice and it is the wrong one. It
+ * would mean that a deck with one pre-existing defect - a dangling image
+ * relationship, say, which PowerPoint tolerates and which is common in files
+ * that have been through three other tools - could be opened in this editor and
+ * never saved again. The editor would be refusing to give the user back their
+ * own file over a problem it did not cause and cannot fix. `PartStore.write`
+ * already made exactly this call for dangling relationships, and this is the
+ * same call generalised to all twenty-nine rules.
+ *
+ * So `origin` is not a per-rule judgement call. It is computed by running the
+ * rules a second time against the package **as it was opened** and differencing
+ * the two reports: a finding that is in both is `inherited`, one that is only in
+ * the new report is `introduced`. That is exact, it needs no rule to reason
+ * about history, and it cannot drift from what the rules actually do.
+ *
+ * The second pass only happens when the first found something fatal, so a clean
+ * export - the overwhelmingly common case - pays nothing for it.
+ */
+type Origin =
+/** The finding is in the package we are about to write and was not in the original. */
+'introduced' |
+/** The finding was already there when the package was opened. */
+'inherited' |
+/** No baseline was supplied, so the question was not asked. */
+'unknown';
+interface Finding {
+  readonly rule: RuleId;
+  readonly severity: Severity;
+  readonly category: RuleCategory;
+  readonly where: Location;
+  /**
+   * What is wrong, in one sentence, naming the values involved.
+   *
+   * Written to be read on its own: a message that says "invalid id" and leaves
+   * the reader to go and look is a message that costs more than it saves.
+   */
+  readonly message: string;
+  readonly origin: Origin;
+}
+/** A rule that did not run, and why. Never silent - see `Report.skipped`. */
+interface SkippedRule {
+  readonly rule: RuleId;
+  readonly why: string;
+}
+/** Something that could not be read. Not a rule violation; a gap in coverage. */
+interface ReadProblem {
+  readonly part: string;
+  readonly message: string;
+}
+interface Report {
+  /** Sorted: fatal before warning, then by part, then by offset. */
+  readonly findings: readonly Finding[];
+  /** Rules that ran. */
+  readonly checked: readonly RuleId[];
+  /**
+   * Rules that did not run, and why.
+   *
+   * Present so that a report can never quietly mean less than it looks like it
+   * means. Six rules need the package as it was opened; asked to validate a
+   * package with no baseline they report nothing, and "reported nothing" and
+   * "found nothing" are the same shape on a screen and opposite in meaning.
+   */
+  readonly skipped: readonly SkippedRule[];
+  /** Parts that could not be read, and the rules that therefore did not see them. */
+  readonly problems: readonly ReadProblem[];
+  /** Fatal findings this session introduced. The number that refuses an export. */
+  readonly blocking: number;
+  /** True when nothing blocking was found. Not the same as "no findings". */
+  readonly ok: boolean;
+}
+/**
+ * The key two reports are differenced on.
+ *
+ * Includes the message, because the message carries the instance - the id that
+ * collided, the guide that was not defined. Two findings of the same rule at
+ * the same place with different values are different findings, and treating
+ * them as one would let an introduced defect hide behind an inherited one.
+ */
+declare function findingKey(finding: Finding): string;
+declare function buildReport(input: {
+  readonly findings: readonly Finding[];
+  readonly checked: readonly RuleId[];
+  readonly skipped: readonly SkippedRule[];
+  readonly problems: readonly ReadProblem[];
+}): Report;
+declare function isReport(value: unknown): value is Report;
+interface FormatOptions {
+  /** Include `inherited` findings. Default true. */
+  readonly inherited?: boolean;
+  /** Include warnings. Default true. */
+  readonly warnings?: boolean;
+  /** Append each rule's `why`, once per rule. Default false. */
+  readonly explain?: boolean;
+}
+/**
+ * A report as text.
+ *
+ * Grouped by part rather than by rule, because the question a reader has is
+ * "what is wrong with this file", and a file is a set of parts. Grouping by
+ * rule is the right shape for the corpus gate and the wrong one here.
+ */
+declare function formatReport(report: Report, options?: FormatOptions): string;
+//#endregion
+//#region src/context.d.ts
+/**
+ * The state a rule reads, and the one method it writes.
+ *
+ * Every rule is `(ctx: Context) => void`. That is a deliberately small
+ * interface, and it is the same shape `checkLayering({manifests, catalog})` and
+ * `checkCorpus({manifests, files, ...})` already have in this repository, for
+ * the same reason: a rule that takes a context and returns nothing is a rule
+ * that can be run against a package assembled in a test, with no temporary
+ * directory, no archive on disk and no other twenty-eight rules running beside
+ * it obscuring which one fired.
+ *
+ * ## Everything is lazy, and everything is cached
+ *
+ * Twelve of the rules want the parsed tree of every XML part. Parsing each part
+ * once per rule would be twelve passes over a deck that can be two hundred
+ * megabytes. Parsing all of them up front would be one pass too many for the
+ * package-level rules, which need no trees at all.
+ *
+ * So `document()` parses on first ask and remembers. A part that is not XML
+ * returns `null` and is not asked again. A part that will not *parse* also
+ * returns `null` - and records a `ReadProblem`, because a rule that silently
+ * saw nothing is indistinguishable from a rule that found nothing, and those
+ * are opposite answers.
+ */
+interface Context {
+  /** The package about to be handed over, or the one being inspected. */
+  readonly store: PartStore;
+  /** The archive bytes, when the caller had them. `null` when only a store was given. */
+  readonly bytes: Uint8Array | null;
+  /**
+   * The archive those bytes describe, central directory only - nothing is
+   * inflated to build it.
+   *
+   * `PartStore` deliberately does not expose this. It drops directory entries
+   * on the way in, because a directory entry is not a part and carrying a thing
+   * with no part name through the whole system would mean every consumer has to
+   * remember it is there. That is right for the store and it leaves three rules
+   * with nothing to look at: whether the archive has directory entries, whether
+   * it carries a ZIP64 record, and what `[Content_Types].xml` actually *says* as
+   * opposed to what parsing it produced.
+   *
+   * `null` when the caller passed a store and no bytes; the rules that need it
+   * are then skipped with a reason rather than passing vacuously.
+   */
+  readonly archive: ZipArchive | null;
+  /** The package as it was opened. `null` for an inspection with no history. */
+  readonly baseline: PartStore | null;
+  /** Part names in package order, `[Content_Types].xml` excluded - it is not a part. */
+  parts(): readonly PartName[];
+  /** A part's bytes, or `null` if it is not there. Never throws. */
+  read(part: string): Uint8Array | null;
+  /** Content type, or `undefined` when nothing in the map covers the part. */
+  contentType(part: string): string | undefined;
+  /** The parsed tree, cached. `null` for binary parts and for parts that will not parse. */
+  document(part: string): XDocument | null;
+  /**
+   * `[Content_Types].xml` as the archive holds it, parsed.
+   *
+   * Not reachable through `parts()`: the content-type stream is not a part. It
+   * has no content type of its own and nothing ever relates to it, which is why
+   * `PartStore` keeps it outside the part map entirely.
+   *
+   * Read from the markup rather than from `store.contentTypes` for the reason
+   * `rels.ts` gives at length: `ContentTypes.parse` collapses a duplicate
+   * `Default` that agrees with itself and refuses one that does not, so a rule
+   * that asks the parsed map whether there are duplicates is asking the one
+   * object in the system that cannot answer.
+   */
+  contentTypesDocument(): XDocument | null;
+  /** The same three, against the baseline. `null` throughout when there is none. */
+  baselineRead(part: string): Uint8Array | null;
+  baselineDocument(part: string): XDocument | null;
+  /**
+   * True when this session replaced or added the part.
+   *
+   * Derived from `PartInfo.fromArchive`, which is the store's own record of
+   * whether a part's bytes still come from the archive it was opened from. It
+   * is the only honest source for "did we touch this" - a byte comparison
+   * cannot tell an edit that happened to produce identical bytes from no edit
+   * at all, and the preservation rules care about the difference.
+   */
+  edited(part: string): boolean;
+  add(rule: RuleId, where: Location, message: string): void;
+  problem(part: string, message: string): void;
+}
+interface ContextInput {
+  readonly store: PartStore;
+  readonly bytes?: Uint8Array | null;
+  readonly archive?: ZipArchive | null;
+  readonly baseline?: PartStore | null;
+}
+declare class RuntimeContext implements Context {
+  #private;
+  readonly store: PartStore;
+  readonly bytes: Uint8Array | null;
+  readonly archive: ZipArchive | null;
+  readonly baseline: PartStore | null;
+  readonly findings: Finding[];
+  readonly problems: ReadProblem[];
+  constructor(input: ContextInput);
+  parts(): readonly PartName[];
+  read(part: string): Uint8Array | null;
+  contentType(part: string): string | undefined;
+  document(part: string): XDocument | null;
+  baselineDocument(part: string): XDocument | null;
+  contentTypesDocument(): XDocument | null;
+  baselineRead(part: string): Uint8Array | null;
+  edited(part: string): boolean;
+  add(rule: RuleId, where: Location, message: string): void;
+  problem(part: string, message: string): void;
+}
+declare function createContext(input: ContextInput): RuntimeContext;
+//#endregion
+//#region src/validate.d.ts
+interface ValidateOptions {
+  /**
+   * The package about to be handed over.
+   *
+   * On an export this is the store the writer emitted from, **not** a store
+   * re-opened from the written bytes. The difference is `V027`: a re-opened
+   * store thinks every part came from the archive, so the one rule that asks
+   * "did anything change that nobody edited" would have no history to ask
+   * about and would answer yes about every deliberate edit.
+   */
+  readonly store?: PartStore;
+  /**
+   * The archive, when the caller has it.
+   *
+   * Required for `V003` and for the duplicate half of `V002` - a duplicate
+   * `<Default>` is visible only in the markup, because the parsed content-type
+   * map collapses one that agrees with itself. Given a `store` and no `bytes`,
+   * those are skipped and the report says so.
+   */
+  readonly bytes?: Uint8Array;
+  /** The package as it was opened. The six preservation rules need it. */
+  readonly baseline?: PartStore;
+  /** The baseline's archive, so an inherited `V003` can be recognised as inherited. */
+  readonly baselineBytes?: Uint8Array;
+  /** A subset to run. Defaults to all twenty-nine. */
+  readonly rules?: readonly RuleId[];
+  /** Passed to `readZip` when `bytes` are given. */
+  readonly zip?: ReadZipOptions;
+}
+/**
+ * Check a package against the rules.
+ *
+ * Never throws for anything it finds - a broken package produces a report with
+ * findings in it, which is the shape a caller can render. It throws only when
+ * it was handed something it cannot open at all.
+ */
+declare function validatePackage(options: ValidateOptions): Report;
+/**
+ * Validate, and refuse to go on if we broke something.
+ *
+ * The one call an export path makes. It throws rather than returning a boolean
+ * because the failure has to be impossible to ignore: PowerPoint emits no
+ * diagnostic log, its refusal message names no part and no line, and a user who
+ * gets a repair prompt has no way at all to find out why. This is the only
+ * feedback loop that exists, and a caller who forgot to check a return value
+ * would have removed it.
+ */
+declare function assertValid(options: ValidateOptions): Report;
+//#endregion
+export { BASELINE_RULES, type Context, type ContextInput, type Evidence, type Finding, type FormatOptions, type Location, type Origin, PACKAGE_LOCATION, RULES, RULE_IDS, type ReadProblem, type Report, type Rule, type RuleCategory, type RuleId, type Severity, type SkippedRule, VALIDATE_ERROR_CODES, ValidateError, type ValidateErrorCode, type ValidateErrorDetail, type ValidateOptions, assertValid, attributeLocation, buildReport, createContext, elementLocation, findingKey, formatReport, inDocumentOrder, isReport, isValidateError, lineColumn, partLocation, rootName, ruleById, validatePackage, xpathOf, xpathOfAttribute };
+//# sourceMappingURL=index.d.ts.map