@wildwinter/toolkit 0.1.0 → 0.2.1

package/dist/extensions.d.ts

@@ -0,0 +1,324 @@
+/** The manifest schema tag this build reads and writes. */
+declare const MANIFEST_SCHEMA = "wildwinter/extension@0";
+/** What a manifest file is called: `<id>.extension.json`. */
+declare const MANIFEST_FILE_SUFFIX = ".extension.json";
+/** The hosts an extension can target. */
+type HostName = "patter" | "storylets";
+interface HostSpec {
+    /** The node kinds a target may name. */
+    readonly kinds: readonly string[];
+    /** The node kinds a `reference` may point at. */
+    readonly references: readonly string[];
+    /** The node kinds with host fields of their own, which a claim may present. */
+    readonly claimable: readonly string[];
+}
+/** Each host's node kinds, references and claimable kinds. */
+declare const HOSTS: Readonly<Record<HostName, HostSpec>>;
+/** The family's seven scalar types, spelled as the family spells them. */
+declare const SCALAR_TYPES: readonly ["text", "multiline", "number", "boolean", "enum", "flags", "quality"];
+type ScalarType = typeof SCALAR_TYPES[number];
+/** Every type a value can take. */
+declare const VALUE_TYPES: readonly ["text", "multiline", "number", "boolean", "enum", "flags", "quality", "reference", "record", "map", "list"];
+type ValueType = typeof VALUE_TYPES[number];
+/** A JSON value, as extension data holds it. */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * A value's type, with the constraints that belong to it. A target's fields
+ * and a record's fields add a name and the editor's words (`FieldDecl`); the
+ * `of` of a map or a list is a bare type.
+ */
+interface TypeDecl {
+    readonly type: string;
+    /** An enum's values, or the flags a flags value may hold. */
+    readonly values?: readonly string[];
+    /** A quality's ladder. */
+    readonly stages?: readonly string[];
+    /** A quality's renames: every name a stage has had, to the stage it is now. */
+    readonly renamedStages?: Readonly<Record<string, string>>;
+    /** A reference's node kind. */
+    readonly to?: string;
+    /** A record's fields. */
+    readonly fields?: readonly FieldDecl[];
+    /** A map's key. */
+    readonly key?: {
+        readonly type: string;
+        readonly to?: string;
+    };
+    /** A map's or a list's value type. */
+    readonly of?: TypeDecl;
+    /** A list's id field: the text field of its records that keys each item. */
+    readonly id?: string;
+    /** A number's bounds. */
+    readonly min?: number;
+    readonly max?: number;
+    /** One sentence per enum or flags value, or quality stage. Editor only. */
+    readonly valueHelp?: Readonly<Record<string, string>>;
+    /** Optional in source: the type's own default when absent (`defaultOf`). */
+    readonly default?: unknown;
+}
+/** A named field: a target's, or a record's. */
+interface FieldDecl extends TypeDecl {
+    readonly name: string;
+    readonly label?: string;
+    readonly help?: string;
+    /** A node of this kind must set it. */
+    readonly required?: boolean;
+    /** A heading within the extension's group in the editor. */
+    readonly group?: string;
+    /** Stripped at compile: editor data, never in a bundle. A target's own fields only. */
+    readonly editorOnly?: boolean;
+}
+/** A claim on a host field, named through one of the manifest's settings. */
+interface ClaimDecl extends TypeDecl {
+    readonly setting: string;
+    readonly label?: string;
+    readonly help?: string;
+    readonly required?: boolean;
+}
+/** What an extension declares for one node kind of one host. */
+interface TargetDecl {
+    readonly fields?: readonly FieldDecl[];
+    readonly claims?: readonly ClaimDecl[];
+}
+/** A project setting, naming a host field a claim presents. */
+interface SettingDecl {
+    readonly name: string;
+    readonly label?: string;
+    readonly help?: string;
+    /** The field name used when the project names none. */
+    readonly default: string;
+}
+interface Manifest {
+    readonly schema: string;
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly docs?: string;
+    readonly settings?: readonly SettingDecl[];
+    readonly targets: Readonly<Partial<Record<HostName, Readonly<Record<string, TargetDecl>>>>>;
+}
+/** One thing wrong, with where it is. A host words it in its own report shape. */
+interface Problem {
+    readonly severity: "error" | "warning";
+    /** A stable name for the kind of problem, for tests and quick fixes. */
+    readonly code: string;
+    /** Where, relative to what was checked: `targets.storylets.card.fields[2].stages`. */
+    readonly path: string;
+    readonly message: string;
+    /** The values a quick fix may offer (an enum's values, the stages either side). */
+    readonly options?: readonly string[];
+}
+/** The format-neutral part of an extension data shard. */
+interface ExtensionData {
+    readonly extension: string;
+    /** By node kind, then node id, then field name. */
+    readonly entries: Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, unknown>>>>>>;
+    readonly unresolved?: readonly UnresolvedEntry[];
+}
+/** How a three-way merge failed to agree on one value. */
+type ConflictKind = "both-changed" | "delete-vs-edit" | "added-both" | "structural";
+/** One clash, as the reserved `unresolved` key of a merged shard holds it. */
+interface UnresolvedEntry {
+    readonly path: string;
+    readonly kind: ConflictKind;
+    readonly base?: unknown;
+    readonly ours?: unknown;
+    readonly theirs?: unknown;
+}
+
+/** Read a manifest file's text (JSON, or JSON5). Throws on text that will not parse. */
+declare function parseManifest(text: string): Manifest;
+/** Every problem with a manifest, by path. An empty list means it is sound. */
+declare function manifestProblems(manifest: unknown): Problem[];
+/** The host field each of a manifest's settings names, the project's choice
+ *  first, else the setting's default. */
+declare function settingValues(manifest: Manifest, chosen?: Readonly<Record<string, unknown>>): Record<string, string>;
+/** A claim as a project resolves it: the host field it presents, by name. */
+interface ResolvedClaim {
+    readonly extension: string;
+    readonly host: HostName;
+    readonly kind: string;
+    /** The host field's name, through the setting. */
+    readonly field: string;
+    readonly claim: ClaimDecl;
+}
+/** Every claim of a manifest for one host, resolved through the project's settings. */
+declare function resolvedClaims(manifest: Manifest, host: HostName, chosen?: Readonly<Record<string, unknown>>): ResolvedClaim[];
+/** Two extensions claiming one host field: an error naming both, once per pair. */
+declare function claimClashes(claims: readonly ResolvedClaim[]): Problem[];
+/** One manifest's declarations for one host and node kind, or undefined. */
+declare function targetOf(manifest: Manifest | undefined, host: HostName, kind: string): TargetDecl | undefined;
+/**
+ * A claim as a host draws and checks its field: the claim's label, help, value help and constraints, over the
+ * host's own declaration for what the claim leaves out (an enum's or flags' values, a quality's stages, the
+ * default). The host's vocabulary stands when the claim names none, as the host's ladder always does.
+ */
+declare function effectiveClaim<C extends ClaimDecl>(claim: C, hostDecl: {
+    readonly type?: string;
+    readonly values?: readonly string[];
+    readonly stages?: readonly string[];
+    readonly default?: unknown;
+}): C;
+
+/** What the host knows about its nodes, for references. */
+interface ValueContext {
+    /** Does a node of `kind` with `id` exist? Absent, references are not checked
+     *  (a host checking a manifest's default, say, has no nodes to hand). */
+    readonly exists?: (kind: string, id: string) => boolean;
+}
+/** Every problem with `value` as a value of `decl`, paths relative to the value. */
+declare function valueProblems(decl: TypeDecl, value: unknown, ctx?: ValueContext, path?: string): Problem[];
+/** Every problem with one node's entry, against its target. */
+declare function entryProblems(target: TargetDecl, entry: unknown, ctx?: ValueContext, path?: string): Problem[];
+/**
+ * A declaration's default: the one it gives, else its type's. A scalar's is
+ * the kernel's (`defaultFor`: false, 0, "", the first enum value, no flags,
+ * the first stage), a reference's is none (""), a record's is each of its
+ * fields' defaults, a map's and a list's are empty.
+ */
+declare function defaultOf(decl: TypeDecl): unknown;
+/** A target's fields with every default resolved and the editor's words gone, as a bundle carries them;
+ *  editor-only fields are left out. */
+declare function compiledTarget(target: TargetDecl): FieldDecl[];
+/**
+ * A node's values as a bundle carries them: raw and sparse, with editor-only
+ * and undeclared fields left out and renamed stages renamed. Undefined when
+ * nothing is left, so a host writes no `extensions` entry for the node.
+ */
+declare function compileEntry(target: TargetDecl, entry: Readonly<Record<string, unknown>>): Record<string, unknown> | undefined;
+interface StageRename {
+    readonly path: string;
+    readonly from: string;
+    readonly to: string;
+}
+/** Rename every stage the manifest says was renamed, at any depth. Returns the
+ *  entry (a new object when anything changed) and the renames made. */
+declare function renameStages(target: TargetDecl, entry: Readonly<Record<string, unknown>>): {
+    entry: Record<string, unknown>;
+    renames: StageRename[];
+};
+
+/**
+ * A merge strategy, as data:
+ *   atomic          one value, classic three-way (objects compare by content)
+ *   map(of)         an open string-keyed map, each value merged by `of`
+ *   set             a list of strings as a set: additions union, deletions respected
+ *   keyed(key, of)  a list of objects keyed by the string field `key`; output
+ *                   sorted by key, or in the authored order with `order: "preserve"`
+ *   object(fields)  named keys by their own strategy, every other key by `other`
+ *                   (atomic when absent)
+ */
+type Strategy = {
+    readonly kind: "atomic";
+} | {
+    readonly kind: "map";
+    readonly of: Strategy;
+} | {
+    readonly kind: "set";
+} | {
+    readonly kind: "keyed";
+    readonly key: string;
+    readonly of: Strategy;
+    readonly order?: "sorted" | "preserve";
+    readonly renameWarning?: string;
+} | {
+    readonly kind: "object";
+    readonly fields: Readonly<Record<string, Strategy>>;
+    readonly other?: Strategy;
+};
+declare const ATOMIC: Strategy;
+declare const SET: Strategy;
+declare const mapOf: (of: Strategy) => Strategy;
+declare const keyedBy: (key: string, of: Strategy, opts?: {
+    order?: "sorted" | "preserve";
+    renameWarning?: string;
+}) => Strategy;
+declare const objectOf: (fields: Readonly<Record<string, Strategy>>, other?: Strategy) => Strategy;
+/** One clash; the merged value holds OURS for it. */
+interface Conflict {
+    /** The entity key involved (a keyed item's key, a map's key), or "" at the top. */
+    readonly id: string;
+    /** Where, from the root: `entries.card.c_1.perf.v_ann.look`, `cards[c_1].priority`. */
+    readonly path: string;
+    readonly base: unknown;
+    readonly ours: unknown;
+    readonly theirs: unknown;
+    readonly kind: ConflictKind;
+}
+/** A note on a merge that went through but that a person should check. */
+interface MergeWarning {
+    readonly id: string;
+    readonly path: string;
+    readonly message: string;
+}
+interface TreeMergeResult {
+    readonly merged: unknown;
+    readonly conflicts: Conflict[];
+    readonly warnings: MergeWarning[];
+}
+interface TreeMergeOptions {
+    /** Whether two values say the same thing. Content equality with keys in any
+     *  order by default; a format whose canonical form is looser passes its own. */
+    readonly equal?: (a: unknown, b: unknown) => boolean;
+}
+/** JSON with every object's keys sorted: two values with this text say the same thing. */
+declare function stableStringify(value: unknown): string;
+/** Three-way merge `base`, `ours` and `theirs` by `strategy`. A clash keeps ours. */
+declare function mergeTree(strategy: Strategy, base: unknown, ours: unknown, theirs: unknown, opts?: TreeMergeOptions): TreeMergeResult;
+/** How a value of this type merges (the README's table). */
+declare function strategyForType(decl: TypeDecl): Strategy;
+/** How one node's entry merges: field by field, each by its type. */
+declare function strategyForTarget(target: TargetDecl): Strategy;
+/**
+ * How an extension data shard merges for one host. With the manifest, each
+ * kind's entries merge node by node and each entry field by field; a kind the
+ * manifest does not target, and every kind without the manifest, merges node
+ * by node with each entry as one value.
+ */
+declare function extensionDataStrategy(manifest: Manifest | undefined, host: HostName): Strategy;
+/** The reserved key a merged shard carries its clashes under. */
+declare const UNRESOLVED_KEY = "unresolved";
+/** A shard's mark, when it carries one. */
+declare function unresolvedOf(shard: unknown): readonly UnresolvedEntry[] | undefined;
+/** A shard without its mark, for merging and for comparing content. */
+declare function withoutMark<T>(shard: T): T;
+/**
+ * Write a merge's clashes into the merged shard under `unresolved`, carrying
+ * any mark either side already had (a mark is a set by path: one side
+ * resolving it, by removing it, resolves it). A clash found now replaces a
+ * carried one at the same path. With nothing to mark, the key is absent.
+ */
+declare function markUnresolved<T extends Record<string, unknown>>(merged: T, conflicts: readonly Conflict[], sides?: {
+    base?: unknown;
+    ours?: unknown;
+    theirs?: unknown;
+}): T;
+/** Validation's refusal of a marked shard: one error per clash, or one for an empty mark. */
+declare function unresolvedProblems(shard: unknown): Problem[];
+interface DataMergeResult {
+    /** The merged shard: ours where it clashed, with the mark written in. */
+    readonly merged: Record<string, unknown>;
+    readonly conflicts: Conflict[];
+    readonly warnings: MergeWarning[];
+}
+/**
+ * Three-way merge of one extension data shard. `manifest` is the project's copy,
+ * read from the working tree, or undefined when it is missing, unreadable or
+ * itself in conflict, which merges each node's entry as one value: always safe.
+ * The shard's other keys (a format's schema tag, the extension id) merge as values.
+ */
+declare function mergeExtensionData(base: Record<string, unknown>, ours: Record<string, unknown>, theirs: Record<string, unknown>, opts: {
+    manifest?: Manifest;
+    host: HostName;
+} & TreeMergeOptions): DataMergeResult;
+/** Entries naming a node the host no longer has: kept, and reported as warnings. */
+declare function orphanedEntries(data: unknown, exists: (kind: string, id: string) => boolean): Problem[];
+
+/** `base` and then the key `key`. */
+declare const atKey: (base: string, key: string) => string;
+/** `base` and then list position `i`. */
+declare const atIndex: (base: string, i: number) => string;
+
+export { ATOMIC, type ClaimDecl, type Conflict, type ConflictKind, type DataMergeResult, type ExtensionData, type FieldDecl, HOSTS, type HostName, type HostSpec, type JsonValue, MANIFEST_FILE_SUFFIX, MANIFEST_SCHEMA, type Manifest, type MergeWarning, type Problem, type ResolvedClaim, SCALAR_TYPES, SET, type ScalarType, type SettingDecl, type StageRename, type Strategy, type TargetDecl, type TreeMergeOptions, type TreeMergeResult, type TypeDecl, UNRESOLVED_KEY, type UnresolvedEntry, VALUE_TYPES, type ValueContext, type ValueType, atIndex, atKey, claimClashes, compileEntry, compiledTarget, defaultOf, effectiveClaim, entryProblems, extensionDataStrategy, keyedBy, manifestProblems, mapOf, markUnresolved, mergeExtensionData, mergeTree, objectOf, orphanedEntries, parseManifest, renameStages, resolvedClaims, settingValues, stableStringify, strategyForTarget, strategyForType, targetOf, unresolvedOf, unresolvedProblems, valueProblems, withoutMark };