@gmb/bitmark-parser 7.2.0 → 7.4.0

package/config/bitmark-json.tsp

@@ -0,0 +1,439 @@
+/**
+ * bitmark.json — the resolved bitmark configuration document.
+ *
+ * `bitmark-confgen` resolves the hand-edited jsonc config tree
+ * (`resources/bitmark-configurator/config`) plus `manifest.jsonc` into this
+ * one document at build time (PLAN-144, PLAN-207). The parser's lookup tables,
+ * the JSON Schema, the TypeScript types and the docs site are all generated
+ * from it, and the npm package ships the exact document its parser was
+ * compiled against as `@gmb/bitmark-parser/bitmark.json`, with this file
+ * beside it as `@gmb/bitmark-parser/bitmark-json.tsp`.
+ *
+ * Prose spec with the derivation algorithms: `.zen/specs/BITMARK-JSON-FORMAT.md`.
+ * Shape source of truth: `crates/app/bitmark_confgen/src/model.rs` — any change
+ * there updates this file in the same PR.
+ *
+ * Conventions:
+ * - Identity is text. Root entities are keyed by name in sorted maps; every
+ *   single-parent construct nests inside its owner. There are no numeric ids.
+ * - Optional members are omitted when absent, never `null`. Two exceptions:
+ *   flag booleans (`bodyRequired`, `alwaysEmit`, …) are present only when
+ *   `true`, and `TagDef.default` is `null` to mean "omit".
+ * - Arrays are in semantic (declaration) order; maps are sorted by key.
+ * - Derived members (`allTags`, `usedBy`, `parentOverrides`, `resources`) are
+ *   computed by confgen, never authored.
+ */
+namespace BitmarkConfig;
+
+/** A mapping-id → key-pattern record. Ids are registered in `mappingTypes`;
+ *  a pattern is the verbatim authored JSON value (string, object or array of
+ *  predicate records — see `crates/lib/jsonkey_parser/doc/`). */
+model MappingKeys is Record<unknown>;
+
+/** The document. */
+model BitmarkJson {
+  /** App semver, from `manifest.jsonc` (kept in lockstep with the packages). */
+  version: string;
+
+  /** Provenance: `fnv1a64:<16 hex>` over every input file keyed by its
+   *  config-relative path, plus the manifest. Independent of where the tree
+   *  lives on disk; no wall clock. */
+  label: string;
+
+  /** Manifest order, verbatim. */
+  locales: Locale[];
+
+  /** Manifest order, verbatim. */
+  mappingTypes: MappingType[];
+
+  /** Bits by technical name (sorted). Abstract base definitions are absent. */
+  bits: Record<Bit>;
+
+  /** Tag groups by name (sorted). */
+  groups: Record<Group>;
+
+  /** Card sets by key (sorted). */
+  cardSets: Record<CardSet>;
+
+  /** Resource catalog by resource type (sorted); derived from the
+   *  `resource-<type>` groups minus the manifest's `resourceUtilityGroups`. */
+  resources: Record<Resource>;
+
+  /** Bit-group registry by key (sorted). Metadata only: membership lives on
+   *  each bit's `bitGroups`. */
+  bitGroups: Record<BitGroup>;
+
+  /** Resource-group registry by key (sorted). Here the member list is
+   *  authoritative. */
+  resourceGroups: Record<ResourceGroup>;
+
+  /** Text tags by JSON type (sorted): the heads of inline property lists
+   *  (`==text==|head:value|child:value|…|`) and the JSON-only marks
+   *  (PLAN-217). Group references are expanded. */
+  textTags: Record<TextTag>;
+
+  /** ProseMirror nodes that are not text tags (sorted): mappings only. */
+  textNodes: Record<TextNode>;
+}
+
+model Locale {
+  /** BCP-47 language code, e.g. "en". */
+  code: string;
+  isBase: boolean;
+  /** English label, e.g. "English". */
+  label: string;
+}
+
+/** A registered mapping id and its representation type. */
+model MappingType {
+  /** Mapping id used as a key in every `mappingKeys` record, e.g. "json". */
+  id: string;
+
+  /** Representation type: "json" | "html" | "xml" (open set); informational. */
+  type: string;
+
+  /** Parent mapping id: key lookups under this id fall back to the base
+   *  (publisher overrides). */
+  `extends`?: string;
+}
+
+model Bit {
+  description: string;
+
+  /** English display name; other languages come from `translations.json`.
+   *  Absent when unauthored. */
+  title?: string;
+
+  /** Bit-group memberships, sorted — the single home of that fact. Omitted
+   *  when the bit is deliberately ungrouped. */
+  bitGroups?: string[];
+
+  /** Author-facing usage notes, one bullet per entry; docs-only. */
+  usageNotes?: string[];
+
+  /** "bitmark" | "text" | "latex" | "json" | "xml". */
+  bodyFormat: string;
+
+  /** Flag booleans: present only when `true`. */
+  bodyRequired?: true;
+  bodyForbidden?: true;
+  footerRequired?: true;
+  footerForbidden?: true;
+
+  /** Version string at which the bit was deprecated; docs-only. */
+  deprecated?: string;
+
+  /** Migration target: engines re-emit input using this (deprecated) bit
+   *  type under the named bit. */
+  migrateTo?: string;
+
+  /** "all" | "none". */
+  resourceAttachmentAllowed: string;
+
+  /** Required resource type (a key of `resources`); omitted when none. */
+  resourceRequired?: string;
+
+  /** Key of `cardSets`; omitted when the bit has no card set. */
+  cardSet?: string;
+
+  /** Bit-level named element keys for markup import; omitted when empty. */
+  mappingKeys?: MappingKeys;
+
+  /** Ordered declaration list: inline tag definitions and group references. */
+  tags: TagRef[];
+
+  /** Computed transitive closure of tags, as scoped keys, in declaration-DFS
+   *  order with name dedup (first position kept, later declaration wins).
+   *  A scoped key is `<kind>:<ownerPath>.<tag>` — `bit:article.#`,
+   *  `group:article.#`, `variant:flashcard.default.question.1.@example` —
+   *  and a chain child appends to its parent's key. */
+  allTags: string[];
+}
+
+/** One entry of a `tags` / `chain` array: an inline definition or a group
+ *  reference, told apart by which of `tag` / `group` is present. */
+union TagRef {
+  TagDef,
+  GroupRef,
+}
+
+model TagDef {
+  /** Config key including its sigil (`@example`, `#`, `&image`, `%`, …) —
+   *  the identity within the owner scope. */
+  tag: string;
+
+  description: string;
+
+  /** "string" | "bitmark+" | "boolean" | "number" | "numberList4" | "enum". */
+  format: string;
+
+  /** Enum vocabulary: present (non-empty, unique) exactly when `format` is
+   *  "enum". */
+  values?: string[];
+
+  min: int64;
+
+  /** -1 = unlimited. */
+  max: int64;
+
+  /** Always present. `null` means OMIT: absence is the canonical state and a
+   *  present value is never stripped nor an absent one materialised.
+   *  Otherwise the format's natural value ("false" / "0" / "") or an
+   *  authored non-natural value, which requires `alwaysEmit`. */
+  default: string | null;
+
+  /** Flag boolean: pin the key even in optimised mode, materialising the
+   *  default when absent. */
+  alwaysEmit?: true;
+
+  /** Version string at which the tag was deprecated; docs-only. */
+  deprecated?: string;
+
+  /** Omitted when none. A `json` member may be the string "@ignore": the
+   *  tag takes no value. */
+  mappingKeys?: MappingKeys;
+
+  /** Ordered chain children; omitted when empty. */
+  chain?: TagRef[];
+
+  /** Computed: overrides this tag receives from each parent context, sorted
+   *  by (parentType, parent). Omitted when empty. */
+  parentOverrides?: ParentOverride[];
+}
+
+/** A reference to a group, with optional link overrides. */
+model GroupRef {
+  /** A key of `groups`. */
+  group: string;
+  mappingKeys?: MappingKeys;
+  min?: int64;
+  max?: int64;
+}
+
+model ParentOverride {
+  /** "bit" | "group" | "tag" | "variant" (never "cardSet"). */
+  parentType: string;
+
+  /** Name (bit / group), variant path, or — for `tag` — the parent tag's
+   *  scoped key (`group:person.@partner`). */
+  parent: string;
+
+  /** At least one of the three is present. */
+  mappingKeys?: MappingKeys;
+  min?: int64;
+  max?: int64;
+}
+
+model Group {
+  description: string;
+  tags: TagRef[];
+  allTags: string[];
+
+  /** Computed reverse references; omitted when nothing references the group. */
+  usedBy?: UsedBy;
+}
+
+/** Reverse references; each member sorted lexicographically and omitted when
+ *  empty. */
+model UsedBy {
+  bits?: string[];
+  cardSets?: string[];
+  /** `<cardSetKey>.<cardName>.<sideName>.<variantIndex>` (1-based). */
+  variants?: string[];
+  groups?: string[];
+  /** Scoped keys (`group:person.@partner`) of the tags whose chains
+   *  reference the group. */
+  tags?: string[];
+}
+
+model CardSet {
+  mappingKeys?: MappingKeys;
+
+  /** Card-set-level references; omitted when empty. */
+  tags?: TagRef[];
+  allTags?: string[];
+
+  /** Bits using this card set, sorted; omitted when none. */
+  usedBy?: UsedBy;
+
+  /** Ordered. */
+  cards: Card[];
+}
+
+model Card {
+  name: string;
+  isDefault: boolean;
+
+  /** 0 = no lower bound. */
+  min: int64;
+
+  /** 0 = unbounded (cards use 0, not -1). */
+  max: int64;
+
+  mappingKeys?: MappingKeys;
+
+  /** Ordered. */
+  sides: Side[];
+}
+
+model Side {
+  name: string;
+
+  /** -1 = repeat forever; omitted when none. */
+  repeatCount?: int64;
+
+  mappingKeys?: MappingKeys;
+
+  /** Ordered; a variant's identity is its 1-based index. */
+  variants: Variant[];
+}
+
+model Variant {
+  bodyFormat: string;
+  bodyRequired?: true;
+  bodyForbidden?: true;
+
+  /** -1 = infinite; omitted when none. */
+  repeatCount?: int64;
+
+  mappingKeys?: MappingKeys;
+  tags: TagRef[];
+  allTags: string[];
+}
+
+model Resource {
+  /** Name of the defining `resource-<type>` group. */
+  group: string;
+
+  /** Component resource types of a composed resource; omitted when empty. */
+  composedOf?: string[];
+}
+
+/** A search/filter category over bit types. Deliberately no member list:
+ *  membership is authored per bit (`Bit.bitGroups`). */
+model BitGroup {
+  /** English display name; other languages come from `translations.json`. */
+  title: string;
+  description: string;
+
+  /** Alternative keys accepted by lookups; omitted when empty. */
+  aliases?: string[];
+
+  /** Informational parent group; never implies membership. */
+  subgroupOf?: string;
+
+  /** Flag boolean: the group is allowed to have no members. */
+  allowEmpty?: true;
+}
+
+/** A value format of a text tag or child. `none`: no value. `duration`: `P`
+ *  followed by anything (the 8.41.1 grammar rule). */
+union TextFormat {
+  "none",
+  "string",
+  "bitmark+",
+  "boolean",
+  "number",
+  "enum",
+  "duration",
+}
+
+/** What an invalid value or a missing required child does: `warn` keeps it
+ *  and reports; `invalid` rejects the segment and ends the chain. */
+union OnInvalid {
+  "warn",
+  "invalid",
+}
+
+/** A text tag (PLAN-217). */
+model TextTag {
+  description: string;
+
+  /** `mark` decorates the text run; `node` replaces it. */
+  kind: "mark" | "node";
+
+  /** Source spelling of the head; omitted → no bitmark form. An identifier
+   *  (letters, digits and `*`, starting with a letter) followed by `:value`,
+   *  or a sigil — one non-letter BMP character outside the chain syntax
+   *  (`|:^@=*`) — that runs straight into its value (`#`, `►`, `?`). */
+  key?: string;
+
+  format: TextFormat;
+
+  /** Enum vocabulary; emitted only for `enum`. */
+  values?: string[];
+
+  /** `null` = omit (absence is its own state); always `null` for `none`. */
+  default: string | null;
+
+  /** Flag boolean (PLAN-152). */
+  alwaysEmit?: true;
+
+  /** Always emitted: `invalid` for `none`, else `warn` unless authored. */
+  onInvalid: OnInvalid;
+
+  /** `first`: valid only as the first segment; omitted = any position. */
+  headPosition?: "first";
+
+  /** Text tags that may start after this head's chain; omitted = any. */
+  followingHeads?: string[];
+
+  /** A named value transform applied on read. */
+  transform?: "lowercase";
+
+  /** JSON input of this (legacy) type is read as the named text tag. */
+  migrateTo?: string;
+
+  /** `json`: `{"type": <name>, …fields}` — a field value is `"$"` (the
+   *  head's value), `"$text"` (the text between `==`) or a constant. A head
+   *  with a value places it exactly once (`"$"`); a `none` head places none;
+   *  no two fields of the head and its chain write the same path. */
+  mappingKeys?: MappingKeys;
+
+  /** Children in canonical order (D16); omitted when empty. */
+  chain?: TextChild[];
+}
+
+/** A child of a text tag. */
+model TextChild {
+  /** Source spelling (`?`, `►`, `provider`, …); same rules as
+   *  `TextTag.key`. */
+  tag: string;
+  description: string;
+
+  /** Never `none`: a child always takes a value. */
+  format: TextFormat;
+  values?: string[];
+  min: int64;
+
+  /** `-1` = unlimited. */
+  max: int64;
+  default: string | null;
+  alwaysEmit?: true;
+
+  /** Emitted only when `min >= 1`. Always `invalid` for now: `warn` needs
+   *  the `text-tag-missing` warning, added with its first use (D13). */
+  onMissing?: OnInvalid;
+  onInvalid: OnInvalid;
+
+  /** Always has `json`: one field — `"$"` or `["$"]` (append) under
+   *  `attrs` or at the top level. */
+  mappingKeys: MappingKeys;
+}
+
+/** A ProseMirror node that is not a text tag. */
+model TextNode {
+  description: string;
+  mappingKeys?: MappingKeys;
+}
+
+/** A search/filter category over resource types. The member list is the
+ *  single home of that fact. */
+model ResourceGroup {
+  title: string;
+  description: string;
+  aliases?: string[];
+
+  /** Member resource types, sorted; each is a key of `resources`. */
+  resourceTypes: string[];
+}