writer

const WRITER_ERROR_CODES: readonly ["ERR_PREPARE_FAILED", "ERR_COLLECTION_UNSAFE", "ERR_PRESERVATION_BROKEN"];

type WriterErrorCode = (typeof WRITER_ERROR_CODES)[number];

interface WriterErrorDetail {
  /** The prepare hook that threw, for `ERR_PREPARE_FAILED`. */
  readonly hook?: string;
  /** The part the failure is about, when it is about one. */
  readonly part?: string;
  /** Relationship parts that would not parse, for `ERR_COLLECTION_UNSAFE`. */
  readonly blockedBy?: readonly string[];
}

class WriterError extends Error {
  readonly name = "WriterError";
  readonly code: WriterErrorCode;
  readonly detail: WriterErrorDetail;
  constructor(code: WriterErrorCode, message: string, detail?: WriterErrorDetail, options?: {
    cause?: unknown;
  });
}

function isWriterError(value: unknown): value is WriterError;

interface Reachability {
  /** Normalised names of every part something can still get to, including `.rels` parts. */
  readonly reachable: ReadonlySet<string>;
  /**
   * False when at least one relationship part could not be read.
   *
   * A caller that deletes on the strength of an incomplete walk is deleting on
   * the strength of a parse error.
   */
  readonly complete: boolean;
  /** The relationship parts that would not parse, and the root if it was unusable. */
  readonly blockedBy: readonly string[];
}

function reachableParts(store: PartStore): Reachability;

function orphanedParts(store: PartStore, walk: Reachability): string[];

type CollectionPolicy =
/** Only parts this session left unreferenced. The default. */
'orphaned-here' |
/** Every unreferenced part in the sweep set, however it got that way. */
'every-orphan' |
/** Collect nothing. */
'none';

function isMediaPart(partName: string): boolean;

interface CollectOptions {
  /** The package about to be written. */
  readonly store: PartStore;
  /** The package as it was opened. Required by `orphaned-here`, ignored otherwise. */
  readonly baseline?: PartStore | null;
  /** Defaults to `orphaned-here`. */
  readonly policy?: CollectionPolicy;
  /**
   * Which parts the sweep may touch at all. Defaults to `isMediaPart`.
   *
   * Sub-phase 8.7 will pass one of its own, to collect a `ppt/fonts/*.fntdata`
   * whose typeface no run uses any more - PowerPoint requires every listed
   * embedded font to be in use. Anything wider than that wants the header above
   * read first.
   */
  readonly sweepable?: (partName: string) => boolean;
}

interface KeptPart {
  readonly part: string;
  readonly why: string;
}

interface CollectionPlan {
  /** Parts removed, in the order they were found. */
  readonly collect: readonly string[];
  /** Orphans left in place, each with a reason. Empty is the normal case. */
  readonly kept: readonly KeptPart[];
  /**
   * False when the relationship graph could not be walked completely.
   *
   * A caller that deletes on the strength of an incomplete walk is deleting on
   * the strength of a parse error.
   */
  readonly safe: boolean;
  /** Relationship parts that would not parse. Empty when `safe`. */
  readonly blockedBy: readonly string[];
}

function planCollection(options: CollectOptions): CollectionPlan;

function collectGarbage(options: CollectOptions): CollectionPlan;

interface PrepareContext {
  /** The package being exported. Hooks mutate this. */
  readonly store: PartStore;
  /** The package as it was opened, when there is one. Read only; never mutate it. */
  readonly baseline: PartStore | null;
  /**
   * Record something worth reporting.
   *
   * Surfaced on `ExportResult.prepared`. A hook that did nothing should say
   * nothing - the common case for every hook on most exports is silence, and a
   * note per hook per save would bury the one that mattered.
   */
  note(message: string): void;
}

interface PrepareHook {
  /** Short and stable. It appears in `ExportResult` and in the error if this hook throws. */
  readonly name: string;
  run(context: PrepareContext): void;
}

interface PrepareRecord {
  readonly hook: string;
  readonly notes: readonly string[];
}

function runPrepare(hooks: readonly PrepareHook[], store: PartStore, baseline: PartStore | null): PrepareRecord[];

interface PreservationCheck {
  /** Entries compared and found identical. */
  readonly checked: number;
  /** Entries deliberately not compared, because this session wrote them. */
  readonly rewritten: number;
  /** Why the check did not run, or `null` when it did. */
  readonly skipped: string | null;
}

function assertPreserved(output: Uint8Array, original: Uint8Array | undefined, rewritten: ReadonlySet<string>, zip?: ReadZipOptions): PreservationCheck;

interface ExportOptions {
  /** The package to write, with whatever edits have been made to it. */
  readonly store: PartStore;
  /**
   * The package as it was opened.
   *
   * Optional, and the three things it costs to leave out are worth knowing
   * before deciding to. Without it the three preservation rules are skipped
   * rather than passed; the media sweep collects nothing, because there is no
   * way to tell what this session orphaned; and `origin` is unavailable, so
   * every fatal finding counts as one we introduced. `openPackage` produces a
   * correct one in a line.
   */
  readonly baseline?: PartStore;
  /** The archive the baseline was opened from. Needed by `V003` and the preservation check. */
  readonly baselineBytes?: Uint8Array;
  /** Run in the order given, before everything else. See `prepare.ts`. */
  readonly prepare?: readonly PrepareHook[];
  /** Media garbage collection. Defaults to `orphaned-here`. See `collect.ts`. */
  readonly collect?: CollectionPolicy;
  /** Which parts the sweep may touch. Defaults to `/ppt/media/`. */
  readonly sweepable?: (partName: string) => boolean;
  /**
   * Set false to write without the firewall.
   *
   * There is no legitimate production use. It exists so that a test can build a
   * deliberately broken package and look at it, and so that `cli bisect` in 1.5
   * can emit the intermediate packages whose whole purpose is to be rejected.
   */
  readonly validate?: boolean;
  /** A subset of rules to run. Defaults to every rule. */
  readonly rules?: readonly RuleId[];
  /** Set false to skip comparing the output against the source archive. */
  readonly verifyPreservation?: boolean;
  /** Passed through to `PartStore.write`. */
  readonly normalizeEntryOrder?: boolean;
  /** Passed through to `PartStore.write`. */
  readonly deflateLevel?: number;
  /** Passed to `readZip` wherever this package re-opens an archive. */
  readonly zip?: ReadZipOptions;
}

interface ExportResult {
  /** The package. Only ever returned when every check above passed. */
  readonly bytes: Uint8Array;
  /** `null` when validation was turned off. */
  readonly report: Report | null;
  /** Hooks that had something to say. Silent hooks are not listed. */
  readonly prepared: readonly PrepareRecord[];
  readonly collection: CollectionPlan;
  /** Parts serialised afresh. Empty on a no-op export - that is the point. */
  readonly rewritten: readonly string[];
  /** Parts streamed out of the source archive without being decompressed. */
  readonly streamed: number;
  readonly preservation: PreservationCheck;
}

interface OpenPackage {
  readonly store: PartStore;
  readonly baseline: PartStore;
  readonly baselineBytes: Uint8Array;
}

function openPackage(bytes: Uint8Array, options?: ReadZipOptions): OpenPackage;

function exportPackage(options: ExportOptions): ExportResult;

interface Span {
  readonly start: number;
  readonly end: number;
}

type ChangeKind =
/** The entry exists only in the broken package. */
'entry-added' |
/** The entry exists only in the original. */
'entry-removed' |
/** A whole entry. Binary, or markup whose two sides do not line up. */
'entry' |
/** One element and everything under it. */
'element' |
/** One text, CDATA, comment, PI or declaration node. */
'node' |
/**
 * A run of children replaced by another run of a different length.
 *
 * What an insertion or a deletion looks like. `was` empty means children were
 * added; `text` empty means they were taken away.
 */
'children' |
/** One element's start tag: its name, its attributes and their spacing. */
'tag' |
/** One attribute, including the whitespace in front of it. */
'attribute';

interface Change {
  readonly id: number;
  /** ZIP entry name, without a leading slash: `ppt/slides/slide1.xml`. */
  readonly entry: string;
  readonly kind: ChangeKind;
  /**
   * Where in the entry, for a person to read.
   *
   * An XPath-ish path for markup - `/p:sld/p:cSld/p:spTree/p:sp[3]/@name` -
   * built from qualified names exactly as the file writes them, because a path
   * that renamed prefixes could not be pasted back into a search.
   */
  readonly where: string;
  /** Distance from the entry, so a report can indent. */
  readonly depth: number;
  /** Where this sits in the **original** entry's text. Null for a whole entry. */
  readonly span: Span | null;
  /** What the broken package has there. Null when the entry is only original. */
  readonly text: string | null;
  /** What the original has there. Null when the entry is only in the broken one. */
  readonly was: string | null;
  /**
   * Finer changes that together reproduce this one exactly.
   *
   * The exactness is what makes descending free: the regions between the
   * children are the regions that compared equal, so applying every child is
   * the same package as applying the parent. HDD relies on it to move down a
   * level without spending a run to re-establish that the configuration fails.
   */
  readonly children: readonly Change[];
}

function flattenChanges(changes: readonly Change[]): Change[];

function leafChanges(changes: readonly Change[]): Change[];

type Verdict = 'fails' | 'passes' | 'unresolved';

type Oracle = (bytes: Uint8Array, label: string) => Verdict;

interface RunEvent {
  readonly run: number;
  readonly applied: number;
  readonly total: number;
  readonly label: string;
}

interface BisectOptions {
  readonly oracle: Oracle;
  /**
   * Ceiling on oracle runs.
   *
   * `ddmin` is quadratic in the worst case and the interesting oracle takes
   * about a second and a half, so a run against a large delta can take a long
   * time. When the ceiling is hit the result carries `exhausted: true` and the
   * smallest failing configuration found so far - never a truncated answer
   * presented as a minimal one.
   */
  readonly maxRuns?: number;
  /** Called before each oracle run, for a progress line. */
  readonly onRun?: (run: RunEvent) => void;
  readonly zip?: ReadZipOptions;
  /**
   * Ceiling on the size of the delta tree.
   *
   * Two packages that share nothing produce a tree the size of the document.
   * Past this, subtrees stop being decomposed and stay atomic, which costs
   * precision and not correctness; `truncated` says when it happened.
   */
  readonly maxChanges?: number;
}

type BisectOutcome =
/** A minimal failing set was found. */
'localized' |
/** The two packages hold the same entries, byte for byte. */
'identical' |
/** The broken package passes the oracle. There is nothing to look for. */
'broken-passes' |
/** The original fails too, so the cause is not in the difference. */
'original-fails';

interface BisectResult {
  readonly outcome: BisectOutcome;
  /** The whole delta, as a forest. One root per differing entry. */
  readonly changes: readonly Change[];
  /** The 1-minimal failing subset: drop any one of these and it passes. */
  readonly minimal: readonly Change[];
  /** The smallest package still showing the problem. Ready to open, or to keep. */
  readonly bytes: Uint8Array;
  /** Oracle runs actually performed. */
  readonly runs: number;
  /** Configurations answered from the cache instead of the oracle. */
  readonly cached: number;
  /** Runs that answered neither question. */
  readonly unresolved: number;
  /** True when `maxRuns` stopped the reduction early. */
  readonly exhausted: boolean;
  /** True when `maxChanges` stopped the delta being decomposed further. */
  readonly truncated: boolean;
}

function collectDelta(original: ZipArchive, broken: ZipArchive, maxChanges?: number): {
  changes: Change[];
  text: Map<string, string>;
  truncated: boolean;
};

function bisectPackages(originalBytes: Uint8Array, brokenBytes: Uint8Array, options: BisectOptions): BisectResult;

function describeChange(change: Change): string;

function summarizeBisect(result: BisectResult): string;

type DifferenceKind =
/** A part is in the original and not in what was written. */
'part-removed' |
/** A part is in what was written and not in the original. */
'part-added' |
/** Both have the part; the content types disagree. */
'content-type' |
/** Both have the part; the canonical XML disagrees. */
'xml' |
/** Both have the part; the bytes disagree. */
'binary' |
/** The relationship graphs of one source part disagree. */
'relationship' |
/** A part could not be read on one side or the other, so nothing can be said. */
'unreadable';

interface Difference {
  readonly kind: DifferenceKind;
  /** The part it is about. For a relationship difference, the *source* part. */
  readonly part: string;
  readonly detail: string;
}

type CompareHow = 'xml' | 'binary' | 'relationships';

interface PartComparison {
  readonly part: string;
  readonly how: CompareHow;
  readonly same: boolean;
  /**
   * The digest of the compared form on the original side: the canonical XML for
   * an XML part, the bytes for anything else, and the relationship graph with
   * the ids left out for a `.rels`.
   *
   * Two parts with the same digest are the same part in the sense this module
   * means. That is the value worth writing into a report.
   */
  readonly digest: string;
  /** The same digest on the written side. Equal to `digest` whenever `same`. */
  readonly writtenDigest: string;
}

interface Relabelling {
  /** The part whose `.rels` this is - `/` for the package root. */
  readonly source: string;
  readonly from: string;
  readonly to: string;
  /** What both ids point at, which is why they are the same label. */
  readonly target: string;
}

interface RoundTripReport {
  readonly ok: boolean;
  readonly parts: readonly PartComparison[];
  readonly differences: readonly Difference[];
  /**
   * Ids that moved. Empty for anything this package wrote, and the interesting
   * field when the comparison is against a file PowerPoint saved.
   */
  readonly relabelled: readonly Relabelling[];
  readonly counts: {
    readonly xml: number;
    readonly binary: number;
    readonly relationships: number;
    readonly same: number;
  };
}

interface CompareOptions {
  /** Passed to `parseXml` for both sides. */
  readonly limits?: XmlParseLimits;
}

function comparePackages(original: PartStore, written: PartStore, options?: CompareOptions): RoundTripReport;

function summarizeRoundTrip(report: RoundTripReport): string;

function roundTripPackage(bytes: Uint8Array, options?: RoundTripOptions): RoundTripResult;

interface RoundTripOptions extends Omit<ExportOptions, 'store' | 'baseline' | 'baselineBytes'>, CompareOptions {}

interface RoundTripResult {
  readonly exported: ExportResult;
  /** The package as re-opened from the bytes that were written. */
  readonly written: PartStore;
  readonly comparison: RoundTripReport;
  readonly ok: boolean;
}