@json-to-office/shared 1.2.0 → 1.4.0

package/dist/capabilities-DtPF3aBj.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Format-independent renderer contracts.
+ *
+ * This module deliberately knows nothing about DOCX or PPTX semantics. Each
+ * format owns its own intermediate representation (`DocxIR`, `PptxIR`) and its
+ * own feature union; the only thing shared between them is the shape of the
+ * contract a backend adapter must satisfy.
+ *
+ * Do not add format-specific feature names, IR nodes or units here.
+ */
+/** The Office formats this repository can produce. */
+type OfficeFormat = 'docx' | 'pptx';
+/**
+ * Options every renderer accepts.
+ *
+ * `deterministic` asks the adapter (and the packaging step after it) to make
+ * output byte-stable across runs: fixed zip entry timestamps, fixed core
+ * metadata timestamps, no random identifiers.
+ *
+ * `generatedAt` pins the timestamp written into package metadata. Callers that
+ * want reproducible bytes pass both.
+ */
+interface RenderOptions {
+    deterministic?: boolean;
+    generatedAt?: Date;
+}
+/**
+ * A backend that turns a format-specific IR into package bytes.
+ *
+ * @typeParam TIR - the format's intermediate representation (plain data)
+ * @typeParam TFeature - the format's feature union (see `capabilities.ts`)
+ * @typeParam TId - the string-literal union of renderer ids for the format
+ */
+interface OfficeRenderer<TIR, TFeature extends string, TId extends string> {
+    readonly id: TId;
+    readonly format: OfficeFormat;
+    readonly capabilities: ReadonlySet<TFeature>;
+    render(document: TIR, options?: RenderOptions): Promise<Uint8Array>;
+}
+/**
+ * Exhaustiveness guard for discriminated-union switches.
+ *
+ * Reaching this at runtime means an IR node kind was added without a matching
+ * `case`, so it throws rather than silently dropping content.
+ */
+declare function assertNever(value: never, context?: string): never;
+
+/**
+ * Diagnostics raised when an IR asks a renderer for something it cannot do.
+ *
+ * These are distinct from `GenerationWarning` (see `../types/warnings`), which
+ * describes authoring problems found while building the document. A renderer
+ * diagnostic describes a *backend* limitation: the document is fine, this
+ * particular adapter just cannot express part of it.
+ */
+type RendererDiagnosticSeverity = 'error' | 'warning';
+/**
+ * One unsupported (or degraded) feature at one place in the IR.
+ *
+ * `path` is an IR path such as `slides[2].elements[0].fill` — not an author-JSON
+ * path — because the check runs against compiled IR. Compilers record the
+ * authoring path alongside where it is useful for the message text.
+ */
+interface RendererDiagnostic<TFeature extends string = string> {
+    feature: TFeature;
+    path: string;
+    severity: RendererDiagnosticSeverity;
+    message: string;
+}
+interface UnsupportedRendererFeatureErrorInit<TFeature extends string = string> {
+    format: OfficeFormat;
+    rendererId: string;
+    diagnostics: readonly RendererDiagnostic<TFeature>[];
+}
+/**
+ * Aggregated failure thrown *before* rendering starts.
+ *
+ * One error carries every unsupported feature found in the IR so a caller sees
+ * the whole gap at once instead of fixing them one render at a time.
+ */
+declare class UnsupportedRendererFeatureError<TFeature extends string = string> extends Error {
+    readonly code = "UNSUPPORTED_RENDERER_FEATURE";
+    readonly format: OfficeFormat;
+    readonly rendererId: string;
+    /** Distinct unsupported features, in first-seen order. */
+    readonly features: readonly TFeature[];
+    /** Distinct IR paths that required them, in first-seen order. */
+    readonly paths: readonly string[];
+    /** Every error-severity diagnostic that produced this failure. */
+    readonly diagnostics: readonly RendererDiagnostic<TFeature>[];
+    constructor(init: UnsupportedRendererFeatureErrorInit<TFeature>);
+}
+/**
+ * A renderer id that is not registered for the format asked for.
+ *
+ * Caller input, not an infrastructure failure — which is the whole reason it is
+ * a class with a `code` rather than a bare `Error`. A server matching on the
+ * message text could only answer `500`, so an unknown id looked like the
+ * service falling over, and a retry looked worth attempting (#263).
+ */
+declare class UnknownRendererError extends Error {
+    readonly code = "UNKNOWN_RENDERER";
+    readonly format: OfficeFormat;
+    /** What the caller asked for. */
+    readonly rendererId: string;
+    /** Every id registered for this format, in registration order. */
+    readonly availableIds: readonly string[];
+    constructor(format: OfficeFormat, rendererId: string, availableIds: readonly string[]);
+}
+/** Build a `RendererDiagnostic` with `severity: 'error'`. */
+declare function rendererError<TFeature extends string>(feature: TFeature, path: string, message: string): RendererDiagnostic<TFeature>;
+/** Build a `RendererDiagnostic` with `severity: 'warning'`. */
+declare function rendererWarning<TFeature extends string>(feature: TFeature, path: string, message: string): RendererDiagnostic<TFeature>;
+/** Split diagnostics into blocking errors and non-blocking warnings. */
+declare function partitionDiagnostics<TFeature extends string>(diagnostics: readonly RendererDiagnostic<TFeature>[]): {
+    errors: RendererDiagnostic<TFeature>[];
+    warnings: RendererDiagnostic<TFeature>[];
+};
+
+/**
+ * Capability checking: what an IR *requires* versus what an adapter *provides*.
+ *
+ * A compiler records one `FeatureRequirement` each time it emits an IR node that
+ * needs a backend capability. Before rendering, `assertRendererSupports` diffs
+ * those requirements against the adapter's `capabilities` set and throws a
+ * single aggregated `UnsupportedRendererFeatureError` if anything is missing.
+ *
+ * The point is that nothing is dropped silently: a feature either appears in the
+ * adapter's capability set and is rendered, or it fails loudly before bytes are
+ * produced.
+ */
+/** One capability an IR node needs, and where in the IR it was needed. */
+interface FeatureRequirement<TFeature extends string = string> {
+    feature: TFeature;
+    /** IR path, e.g. `sections[0].children[3].image`. */
+    path: string;
+    /** Optional detail folded into the failure message. */
+    detail?: string;
+}
+/**
+ * Accumulates feature requirements during compilation.
+ *
+ * Deliberately per-compilation (never module-global) so concurrent generations
+ * never share state.
+ */
+declare class FeatureRequirementCollector<TFeature extends string> {
+    private readonly requirements;
+    private readonly seen;
+    /**
+     * Record that `feature` is needed at `path`.
+     *
+     * Duplicate (feature, path) pairs collapse, so a compiler can call this
+     * unconditionally inside a loop without inflating the diagnostics.
+     */
+    require(feature: TFeature, path: string, detail?: string): void;
+    /** Every recorded requirement, in first-seen order. */
+    list(): readonly FeatureRequirement<TFeature>[];
+    /** Distinct required features, in first-seen order. */
+    features(): readonly TFeature[];
+    /** True when nothing has been required yet. */
+    isEmpty(): boolean;
+}
+/**
+ * Diff required features against a capability set.
+ *
+ * Returns one error-severity diagnostic per unsupported requirement. An empty
+ * array means the renderer can render the IR.
+ */
+declare function diagnoseUnsupportedFeatures<TFeature extends string>(required: readonly FeatureRequirement<TFeature>[], capabilities: ReadonlySet<TFeature>, rendererId: string): RendererDiagnostic<TFeature>[];
+/**
+ * Throw one aggregated error if the renderer is missing any required feature.
+ *
+ * Call this after compiling to IR and before handing the IR to an adapter.
+ */
+declare function assertRendererSupports<TFeature extends string>(required: readonly FeatureRequirement<TFeature>[], renderer: Pick<OfficeRenderer<unknown, TFeature, string>, 'id' | 'format' | 'capabilities'>): void;
+/**
+ * Whether a registered renderer can actually run on this host.
+ *
+ * Registration says a renderer exists; it says nothing about whether its
+ * backend is installed, because the factory is only invoked on selection. A
+ * discovery surface that reports the ids alone therefore advertises renderers
+ * that fail at the first render — which is what `jto_info` and `jto_discover`
+ * used to do for `office-open` on a host that never installed it.
+ */
+interface RendererStatus<TId extends string = string> {
+    id: TId;
+    /** The one used when a caller passes no id. */
+    default: boolean;
+    available: boolean;
+    /** Why not, when not — the message the load failure carried. */
+    reason?: string;
+    /** The command that would make it available. */
+    installHint?: string;
+}
+/**
+ * A registry of renderers for a single format.
+ *
+ * Instances are created per format module, not per generation, and hold only
+ * immutable adapter descriptors — never per-document state.
+ */
+declare class RendererRegistry<TIR, TFeature extends string, TId extends string> {
+    private readonly format;
+    private readonly defaultId;
+    private readonly renderers;
+    constructor(format: OfficeFormat, defaultId: TId);
+    /**
+     * Register a lazily-constructed renderer.
+     *
+     * The factory is async and only invoked on selection, so choosing one
+     * renderer never imports another one's backend.
+     */
+    register(id: TId, factory: () => Promise<OfficeRenderer<TIR, TFeature, TId>>): void;
+    /** Renderer ids registered for this format, in registration order. */
+    ids(): readonly TId[];
+    /** The id used when a caller does not pass one. */
+    getDefaultId(): TId;
+    has(id: string): id is TId;
+    /**
+     * Resolve a renderer, defaulting when `id` is omitted.
+     *
+     * An unknown id is `UnknownRendererError`, which carries the id asked for and
+     * the ones that exist, so a caller boundary can answer "bad request" rather
+     * than "the server broke". A backend that will not load is re-thrown with an
+     * actionable install hint.
+     */
+    resolve(id?: TId): Promise<OfficeRenderer<TIR, TFeature, TId>>;
+    /**
+     * Every registered renderer, with whether it can actually be loaded here.
+     *
+     * Answers the question by loading each one, which is the only answer that
+     * cannot be wrong — a resolver check would still miss a backend that
+     * resolves and then throws on import.
+     *
+     * Memoized, and the promise rather than its value, so concurrent callers
+     * share one probe instead of racing several. Nothing installs a package into
+     * a running process, so the answer cannot go stale within one; without this
+     * `jto_validate` would pay a package import on every call, which is the tool
+     * an agent uses after every edit.
+     */
+    statuses(): Promise<RendererStatus<TId>[]>;
+    private statusCache?;
+    private probeStatuses;
+}
+/**
+ * `Error.name` marking a renderer whose optional backend is not installed.
+ *
+ * A name rather than a subclass: the error crosses a package boundary and an
+ * `instanceof` there would depend on both sides loading the same copy of this
+ * module, which under a workspace layout is not something to rely on.
+ */
+declare const RENDERER_DEPENDENCY_MISSING = "RendererDependencyMissingError";
+
+export { type FeatureRequirement as F, type OfficeFormat as O, RENDERER_DEPENDENCY_MISSING as R, UnknownRendererError as U, FeatureRequirementCollector as a, type OfficeRenderer as b, type RenderOptions as c, type RendererDiagnostic as d, type RendererDiagnosticSeverity as e, RendererRegistry as f, type RendererStatus as g, UnsupportedRendererFeatureError as h, type UnsupportedRendererFeatureErrorInit as i, assertNever as j, assertRendererSupports as k, diagnoseUnsupportedFeatures as l, rendererWarning as m, partitionDiagnostics as p, rendererError as r };