fact-kit-facts 0.4.0 → 0.5.0

package/dist/index.json

@@ -4,7 +4,7 @@
   "entry": ".",
   "component": "fact-kit-facts.npm",
   "describes": {
-    "fact-kit-js": "0.9.0"
+    "fact-kit-js": "0.10.0"
   },
   "publish": {
     "target": "npm",
@@ -3681,6 +3681,251 @@
               ]
             }
           }
+        },
+        {
+          "since": "0.10.0-alpha.1",
+          "content": {
+            "value": {
+              "module": "fact-kit",
+              "exports": [
+                {
+                  "name": "defineFacts",
+                  "signature": "defineFacts(module: FactsModule) => FactsModule",
+                  "summary": "Identity helper that types the default export of `facts/<entry>/index.ts`."
+                },
+                {
+                  "name": "history",
+                  "signature": "history(...rows: HistoryRow[]) => HistoryVariants",
+                  "summary": "Expands the rows of a fact into `variants`: `variants: history(...)`. Row fields are in `fact-kit.history-row`. Targets are JSON Pointers (RFC 6901) into the content, and `''` is the root. A row that does not fit throws an error that names the key, and `check` reports it as `history`. The result is still an array of variants, and `mf.value(name, history(...))` takes it. After each row, the check of the builder that made the content runs again, and a row that breaks it throws `BuilderError`, which `check` reports as `builder`. `remove` and `add` also work on an object by property name, such as the `properties` of an `entity`."
+                },
+                {
+                  "name": "keyed",
+                  "signature": "keyed<T>(items: T[], keys?: string[]) => T[]",
+                  "summary": "Declares the fields that identify an item of an array, so `history` can `add`, `remove` and `replace` items by key. Several fields make a key written as an array in that order. Without `keys` the items are scalars and identify themselves. An array that is not keyed can only be replaced whole."
+                },
+                {
+                  "name": "factLink",
+                  "signature": "factLink(fact: Fact) => string",
+                  "summary": "The location of another fact of this package, to write inside a sentence of `content`: `<id>` in the same entry, `<spec>:<id>` in another. The build adds the fact to `derivedFrom`. `relates: [fact]` adds it without text. A fact object that is not one of this package fails `check` with `relates-foreign`."
+                },
+                {
+                  "name": "derive",
+                  "signature": "derive(upstreamSpec: string, id: string, map?: (upstream: Fact) => Partial<Fact>) => DerivedFact",
+                  "summary": "A fact computed from a fact of another package, listed in `facts`. The build reads the installed index of `upstreamSpec`, copies the fact `id`, lets `map` change the copy, and sets `source` to `{ kind: 'derived', from: upstreamSpec, version }` with the upstream version installed, and `derivedFrom` to `<upstreamSpec>:<id>`. The build records each upstream spec and version in `derived.lock.json`, which goes into version control. Building with another upstream version installed fails with `derive-version` until `--accept-upstream` rewrites the lock."
+                },
+                {
+                  "name": "defineExamples",
+                  "signature": "defineExamples(examples: ExampleGroupSource | ExampleGroupSource[]) => typeof examples",
+                  "summary": "Identity helper that types an example file. Each group follows `fact-kit.example-group`. In `outcome` an item may also be `ref(fact)`, `ref(fact, field)` or `statementFrom(fact, render)`, which the build turns into `{ fact, field?, text? }`."
+                },
+                {
+                  "name": "exampleFactRefs",
+                  "signature": "exampleFactRefs(group: ExampleGroup) => { id: string; location: string; in: 'facts' | 'outcome'; field?: string }[]",
+                  "summary": "Every fact id an example group references, with the JSON pointer where it is referenced. `in` is `facts` for `facts` of the group or of a scenario and `outcome` for a `{ fact }` item of an outcome, and `field` is the field that item names."
+                },
+                {
+                  "name": "flattenSchema",
+                  "signature": "flattenSchema(schema: JsonSchema) => SchemaRow[]",
+                  "summary": "One row per field of a JSON Schema, for rendering field tables in docs and prompts. Fields of `anyOf` / `oneOf` branches are merged by name: values are the union, required when every branch requires it."
+                },
+                {
+                  "name": "schemaRowsToMarkdown",
+                  "signature": "schemaRowsToMarkdown(rows: SchemaRow[]) => string",
+                  "summary": "A Markdown table of the rows, with Field, Type, Required, Description and Extensions columns."
+                },
+                {
+                  "name": "valueListToMarkdown",
+                  "signature": "valueListToMarkdown(fact: Fact, options?: { columns?: string[] }) => string",
+                  "summary": "Renders a fact whose `content.value` is an array: one `- item` line per string, or a table for objects (columns default to the keys). Throws an error naming the fact id when the value is not an array."
+                },
+                {
+                  "name": "replaceFactBlocks",
+                  "signature": "replaceFactBlocks(text: string, blocks: Record<string, string>) => { text: string; changed: boolean }",
+                  "summary": "Replaces the text between `<!-- facts:begin NAME -->` and `<!-- facts:end NAME -->` with `blocks[NAME]`. `changed` is false when the document is already current, which is what a `--check` exits on. Throws an error naming the block on a missing end, a repeated name, or a name the document lacks."
+                },
+                {
+                  "name": "readFacts",
+                  "signature": "readFacts(spec, options?) => FactReader",
+                  "summary": "Reads an installed fact package. Parameters and members are in `fact-kit.read-facts`."
+                },
+                {
+                  "name": "selectFacts",
+                  "signature": "selectFacts(index, { version?, include?, platform?, os? }) => SelectedFact[]",
+                  "summary": "The facts one reader sees in a parsed index of format 1.0 or 1.1. A pure function; `readFacts` is built on it."
+                },
+                {
+                  "name": "factsOf",
+                  "signature": "factsOf({ tool, source, prefix?, topics? }) => FactsFactory",
+                  "summary": "Writes facts with the repeated fields filled in: `const mf = factsOf({ tool, source })`, then `mf.value(name, value)`, `mf.schema(name, schema)` and `mf.statement(name, text)` return a fact whose id is `<tool>.<prefix>.<name>` (`<tool>.<name>` without a prefix) and whose title is `name`. Each takes a value, a function that returns it, or the rows of `history(...)` as the second argument, and `{ title?, topics?, description?, when?, relates?, verify?, source?, note? }` as the third. The topics are those of `factsOf` and then those of the call. A fact written with one content exposes the fields of an object value as read-only getters that give a tagged copy, so the build adds the fact read to `derivedFrom`. A scalar, or a value built from scalars, carries no tag, so write it as a function (`mf.value(name, () => ...)`): every read of another fact while the function runs goes into `relates`. A fact written with `history(...)` has no getters, so read it with `contentOf`. Throws `BuilderError` for a name that is empty or starts or ends with a dot, and for rows whose first row is not the kind of the method."
+                },
+                {
+                  "name": "observedDoc",
+                  "signature": "observedDoc({ url: string, fetched: string }) => FactSource",
+                  "summary": "The source `{ kind: 'observed', basis: 'doc', url, fetched }` of a fact read from a page of the documentation."
+                },
+                {
+                  "name": "observedSpike",
+                  "signature": "observedSpike({ fetched: string, url?: string }) => FactSource",
+                  "summary": "The source `{ kind: 'observed', basis: 'spike', fetched }` of a fact seen in a trial run, with `url` when a page led to it."
+                },
+                {
+                  "name": "contentOf",
+                  "signature": "contentOf(fact: Fact, since?: string) => unknown",
+                  "summary": "A copy of the value or the schema of one row of a fact, tagged so the build adds the fact to `derivedFrom` where the copy is embedded. A fact with several rows needs `since`, the `since` of the row to read (any one version of a row written as an array). Throws `BuilderError` when there is no such row or no content."
+                },
+                {
+                  "name": "statementFrom",
+                  "signature": "statementFrom(fact: Fact, render: (value) => Text, options?: { since?: string }) => BuiltStatement",
+                  "summary": "A statement written from the content of another fact: `render` gets the copy that `contentOf` makes and returns the text. Give the result to `mf.statement` or to the `statement` of a `history` row. The fact goes into `relates`, so `derivedFrom` follows it."
+                },
+                {
+                  "name": "subsetOf",
+                  "signature": "subsetOf(parent: Fact, items: T[]) => T[]",
+                  "summary": "A list that must stay inside the list of `parent`, a fact object. When the parent is a typed list (`mf.value('x', ['A', 'B'])`) the type checker rejects an item it does not have. A parent that comes from a conversion has no type, so `check` and `build` test the list again at every version boundary of the two facts and report `subset-of` with the version. The parent goes into `derivedFrom`. Throws `BuilderError` when `parent` is not a fact object."
+                },
+                {
+                  "name": "stateMachine",
+                  "signature": "stateMachine({ initial, states, transitions }) => StateMachine",
+                  "summary": "A state machine as a value: `{ initial, states, transitions }`, each transition `{ from, to, event?, guard? }`. `event` is a string, or a list of strings for several events between the same two states, and `guard` is a string that holds for all of them. `states` is keyed by name and `transitions` by `from` and `to`, so a `history` row can `add`, `remove` and `replace` them by key, for example `remove: { '/states': ['blocked'] }` and `remove: { '/transitions': [['active', 'done']] }`. Give it to `mf.value`. Throws `BuilderError` when `initial`, or the `from` or `to` of a transition, is not in `states`, and `history` checks it again after every row, so a row that drops a state a transition still uses fails. `check` reports it as `builder`."
+                },
+                {
+                  "name": "relations",
+                  "signature": "relations({ nodes, edges }) => Relations",
+                  "summary": "Nodes and named relations as a value: `{ nodes, edges }`, each edge `{ from, to, name, cardinality? }` with `cardinality` `'one'` or `'many'`. `nodes` is keyed by name and `edges` by `from`, `to` and `name`, for example `remove: { '/edges': [['a', 'b', 'has']] }`. Give it to `mf.value`. Throws `BuilderError` when the `from` or `to` of an edge is not in `nodes`, and `history` checks it again after every row."
+                },
+                {
+                  "name": "sequence",
+                  "signature": "sequence({ participants, steps }) => Sequence",
+                  "summary": "Messages between participants as a value: `{ participants, steps }`, each step `{ from, to, action }`. `participants` is keyed by name and `steps` by `action`, which no two steps share. A `history` row can `add` steps only at the end. To insert in the middle or to rename an `action`, replace the whole list: `replace: { '/steps': keyed([...], ['action']) }`. Throws `BuilderError` when the `from` or `to` of a step is not in `participants`, and `history` checks it again after every row."
+                },
+                {
+                  "name": "stateMachineToMermaid",
+                  "signature": "stateMachineToMermaid(source: StateMachine | Fact) => string",
+                  "summary": "A `stateDiagram-v2` of a state machine, without a code fence. `source` is the value or a fact whose content is that value. Each state is declared as `state \"<name>\" as s<i>` in the order of `states`, the initial state is `[*] --> s<i>`, and a transition is `s<i> --> s<j>` followed by `: <events joined by \", \"> [<guard>]` when it has either. The ids are generated, so a name with spaces or punctuation is safe, and `#`, `\"`, `;` and `|` in a name become mermaid entities."
+                },
+                {
+                  "name": "relationsToMermaid",
+                  "signature": "relationsToMermaid(source: Relations | Fact) => string",
+                  "summary": "A `flowchart LR` of nodes and relations, without a code fence. Each node is declared as `n<i>[\"<name>\"]` and each edge is `n<i> -->|<name>| n<j>`. `cardinality` is not drawn. The ids are generated."
+                },
+                {
+                  "name": "sequenceToMermaid",
+                  "signature": "sequenceToMermaid(source: Sequence | UseCase | Fact) => string",
+                  "summary": "A `sequenceDiagram` of a sequence, without a code fence. Each participant is declared as `participant p<i> as <name>` and each step is `p<i>->>p<j>: <action>`. The ids are generated. A use case from `useCase` is drawn too: the participants are `caller` and then each `layer` in the order of first use, and each step is a message from the layer of the step before it (`caller` for the first) to its own layer."
+                },
+                {
+                  "name": "ref",
+                  "signature": "ref(fact: Fact, field?: string) => FactRef",
+                  "summary": "A reference to a fact of this package, or to a field of it written with dots such as `'limits.max'`, for the content of another fact. It returns a placeholder that the build replaces. When it is the whole value of a subschema, the build writes `{ $ref: '#/$defs/<id>' }`, or `{ $ref: '#/$defs/<id>/properties/a/properties/b' }` with a field, and puts the schema of the target into `$defs` of the root schema, flat and once per id. Anywhere else (a value, a statement, a longer string, a `const`) it writes the location of the fact, followed by `#a.b` with a field. A `$ref` inside the embedded schema that points to its own root (`#`, `#/properties/x`) is rewritten to `#/$defs/<id>` and `#/$defs/<id>/properties/x`; one into its own `$defs` or to an anchor stays. When the target has several rows, the build aligns them: the fact that writes the `ref` gets one row for each combination of its own row and the rows of the target that some reader gets together (the boundaries of `subset-of`), each with the `$defs` of that combination, so a reader reads a standard JSON Schema and changes nothing. A fact with one row becomes a fact with `variants`. The target goes into `derivedFrom`. A field the type checker knows is not in the target fails to compile. `check` reports `ref` when the field is missing from a row the two facts share, and `relates-foreign` when the target is no fact of any entry of the package. It also fits `guard` of a transition."
+                },
+                {
+                  "name": "entity",
+                  "signature": "entity({ identity, fields, required? }) => EntitySchema",
+                  "summary": "An entity as a JSON Schema for `mf.schema`: `{ type: 'object', 'x-identity', properties, required? }`, with the topic `ddd:entity`. `identity` is a field name, or a list of at least two different names (a list of one is written as the name), and `fields` maps a name to a schema or to `ref(fact)`. `required` is a keyed list of names. A `history` row drops a field with `remove: { '/properties': ['status'] }`, adds one with `add: { '/properties': { note: {...} } }` and swaps one with `replace: { '/properties/status': {...} }`, and must drop the name from `required` in the same row. Throws `BuilderError` when an identity name or a `required` name is not a field, and `history` checks it again after every row, so a row that leaves one behind fails and `check` reports `builder`."
+                },
+                {
+                  "name": "valueObject",
+                  "signature": "valueObject(fields, options?: { required? }) => ObjectSchema",
+                  "summary": "A value object as a JSON Schema for `mf.schema`: `{ type: 'object', properties, required? }`, with the topic `ddd:value-object`. A `history` row changes the fields by name in the same way as `entity`, and `required` follows them. Throws `BuilderError` when a `required` name is not a field."
+                },
+                {
+                  "name": "domainEvent",
+                  "signature": "domainEvent(fields, options?: { required? }) => ObjectSchema",
+                  "summary": "A domain event as a JSON Schema for `mf.schema`, in the shape and with the rules of `valueObject`, with the topic `ddd:domain-event`."
+                },
+                {
+                  "name": "aggregate",
+                  "signature": "aggregate({ root, members }) => Aggregate",
+                  "summary": "An aggregate as a value for `mf.value`: `{ root, members }`, each member `{ entity, cardinality }` where `cardinality` is `'one'` (the default) or `'many'`. The facts are written as `factLink` placeholders that the build replaces with their location and adds to `derivedFrom`. The topic is `ddd:aggregate`. `members` is keyed by `entity`, so a `history` row names a member by `factLink(entity)`: `remove: { '/members': [factLink(line)] }`. Throws `BuilderError` when `root` is not a fact object or a cardinality is not `'one'` or `'many'`, and `HistoryError` for two members of one entity."
+                },
+                {
+                  "name": "invariant",
+                  "signature": "invariant(subject: Fact, text: Text) => BuiltStatement",
+                  "summary": "A business rule about an entity or value, for `mf.statement` or the `statement` of a `history` row. It carries the text, and `subject` goes into `relates` so `derivedFrom` follows it. The topic is `ddd:invariant`. A later `history` row rewrites the sentence whole with `statement: invariant(...)`, which also carries the new subject. `set: { '': text }` replaces the sentence but not `relates`. Throws `BuilderError` when `subject` is not a fact object or `text` is empty."
+                },
+                {
+                  "name": "useCase",
+                  "signature": "useCase({ input?, output?, steps, errors? }) => UseCase",
+                  "summary": "An application use case as a value for `mf.value`: `{ input?, output?, steps, errors }`. `input` and `output` are `ref(fact)` or a schema. A step is `{ layer, action, rule?, emits?, calls? }` where `layer` is `'application'`, `'domain'` or `'infrastructure'` and the facts in `rule`, `emits` and `calls` become `factLink` placeholders. The topic is `ddd:use-case`. `steps` is keyed by `action`, which no two steps share, and a `history` row can `add` steps only at the end, so to insert in the middle replace the whole list. `errors` is a keyed list of codes. `sequenceToMermaid` draws it. Throws `BuilderError` for a layer that is not one of the three or an empty action, and `HistoryError` for a repeated action or code."
+                },
+                {
+                  "name": "writeFormatted",
+                  "signature": "writeFormatted(file: string, text: string) => Promise<void>",
+                  "summary": "Writes `text` to `file` formatted with the prettier settings that `resolveConfig(file)` finds (none when there is no config), so a rerun gives the same bytes. Creates the parent directories. `prettier` is an optional peer dependency that is loaded when the function runs, and a missing package throws an error that names what to install: `pnpm add -D prettier@3`."
+                },
+                {
+                  "name": "stableJson",
+                  "signature": "stableJson(value: unknown) => string",
+                  "summary": "JSON with two-space indent and the keys of every object in code-unit order, for generated files. Arrays keep their order. There is no trailing newline."
+                },
+                {
+                  "name": "DRAFT_2020_12",
+                  "signature": "const DRAFT_2020_12: 'https://json-schema.org/draft/2020-12/schema'",
+                  "summary": "The `$schema` URL of JSON Schema 2020-12. It is the value `interfaceToJsonSchema` and `normalizeSchema` put in `$schema`."
+                },
+                {
+                  "name": "NormalizeOptions",
+                  "signature": "interface NormalizeOptions { describe?, drop?, notes? }",
+                  "summary": "The options of `normalizeSchema`. `describe(text) => string` is called for each `description` and returns the text to keep. `drop` lists keywords to remove at any depth. `notes` is a `Map<string, number>` that counts what was dropped or rewritten, for the converter report. A type, exported with `export type`."
+                },
+                {
+                  "name": "normalizeSchema",
+                  "signature": "normalizeSchema(input: JsonSchema, options?: NormalizeOptions) => JsonSchema",
+                  "summary": "Rewrites a JSON Schema from another dialect (draft-07, OpenAPI 3.0) to 2020-12, only where a schema is expected, so a property named `items` or `deprecated` is left alone. `definitions` becomes `$defs` and `#/definitions/` references follow. A tuple `items: [...]` becomes `prefixItems` and `additionalItems` becomes `items`. A string `deprecated` becomes `true` and its message is appended to `description` as `Deprecated: <message>`. `nullable: true` adds `null` to `type`. `dependencies` splits into `dependentRequired` and `dependentSchemas`. `x-` keywords that fact-kit does not register (`X_KEYWORDS`), `$id`, `id` and the keywords in `drop` are removed. The result starts with `$schema` set to `DRAFT_2020_12`."
+                },
+                {
+                  "name": "PinnedSource",
+                  "signature": "interface PinnedSource { repo, commit, path, sha256, license }",
+                  "summary": "An upstream file pinned to a commit: `repo` is `owner/name`, `commit` is the full SHA, `path` is the file in the repository, `sha256` is the hex digest of its bytes and `license` is an SPDX id. A type, exported with `export type`."
+                },
+                {
+                  "name": "sourceUrl",
+                  "signature": "sourceUrl(source: PinnedSource) => string",
+                  "summary": "The GitHub page of the pinned file at its commit (`blob/<commit>/<path>` of the repository), where a reader opens it."
+                },
+                {
+                  "name": "readPinned",
+                  "signature": "readPinned(source: PinnedSource, options: { cacheDir: string }) => Promise<string>",
+                  "summary": "The text of the pinned file. Reads `<cacheDir>/<sha256>.txt` when it exists, otherwise downloads the file at that commit from the raw-content address of GitHub, checks the sha256 and writes the cache. `cacheDir` is required, so the cache place does not depend on the working directory. Throws `<repo>/<path>: sha256 is <actual>, expected <sha256>` when the bytes do not match, also for a cached file, and `<url>: HTTP <status>` when the download fails."
+                }
+              ],
+              "schemaRow": [
+                {
+                  "name": "path",
+                  "type": "string",
+                  "summary": "`a.b` for a property, `a[]` for array items, `a.*` for additional properties."
+                },
+                {
+                  "name": "type",
+                  "type": "string",
+                  "summary": "Empty when the schema says nothing."
+                },
+                {
+                  "name": "required",
+                  "type": "boolean"
+                },
+                {
+                  "name": "description",
+                  "type": "string"
+                },
+                {
+                  "name": "values",
+                  "type": "unknown[]",
+                  "summary": "Present only when the field lists `enum` or `const` values, merged over `anyOf` / `oneOf` branches."
+                },
+                {
+                  "name": "extensions",
+                  "type": "Record<string, unknown>",
+                  "summary": "The `x-` keywords of the field."
+                },
+                {
+                  "name": "requiredWhen",
+                  "type": "{ path: string; values: unknown[] }",
+                  "summary": "Present when only some branches require the field and the branches are told apart by a `const` property: required when that property takes one of `values`."
+                }
+              ]
+            }
+          }
         }
       ],
       "tool": "fact-kit",
@@ -3850,6 +4095,46 @@
               "name": "useCase",
               "signature": "useCase({ input?, output?, steps, errors? }) => UseCase",
               "summary": "An application use case as a value for `mf.value`: `{ input?, output?, steps, errors }`. `input` and `output` are `ref(fact)` or a schema. A step is `{ layer, action, rule?, emits?, calls? }` where `layer` is `'application'`, `'domain'` or `'infrastructure'` and the facts in `rule`, `emits` and `calls` become `factLink` placeholders. The topic is `ddd:use-case`. `steps` is keyed by `action`, which no two steps share, and a `history` row can `add` steps only at the end, so to insert in the middle replace the whole list. `errors` is a keyed list of codes. `sequenceToMermaid` draws it. Throws `BuilderError` for a layer that is not one of the three or an empty action, and `HistoryError` for a repeated action or code."
+            },
+            {
+              "name": "writeFormatted",
+              "signature": "writeFormatted(file: string, text: string) => Promise<void>",
+              "summary": "Writes `text` to `file` formatted with the prettier settings that `resolveConfig(file)` finds (none when there is no config), so a rerun gives the same bytes. Creates the parent directories. `prettier` is an optional peer dependency that is loaded when the function runs, and a missing package throws an error that names what to install: `pnpm add -D prettier@3`."
+            },
+            {
+              "name": "stableJson",
+              "signature": "stableJson(value: unknown) => string",
+              "summary": "JSON with two-space indent and the keys of every object in code-unit order, for generated files. Arrays keep their order. There is no trailing newline."
+            },
+            {
+              "name": "DRAFT_2020_12",
+              "signature": "const DRAFT_2020_12: 'https://json-schema.org/draft/2020-12/schema'",
+              "summary": "The `$schema` URL of JSON Schema 2020-12. It is the value `interfaceToJsonSchema` and `normalizeSchema` put in `$schema`."
+            },
+            {
+              "name": "NormalizeOptions",
+              "signature": "interface NormalizeOptions { describe?, drop?, notes? }",
+              "summary": "The options of `normalizeSchema`. `describe(text) => string` is called for each `description` and returns the text to keep. `drop` lists keywords to remove at any depth. `notes` is a `Map<string, number>` that counts what was dropped or rewritten, for the converter report. A type, exported with `export type`."
+            },
+            {
+              "name": "normalizeSchema",
+              "signature": "normalizeSchema(input: JsonSchema, options?: NormalizeOptions) => JsonSchema",
+              "summary": "Rewrites a JSON Schema from another dialect (draft-07, OpenAPI 3.0) to 2020-12, only where a schema is expected, so a property named `items` or `deprecated` is left alone. `definitions` becomes `$defs` and `#/definitions/` references follow. A tuple `items: [...]` becomes `prefixItems` and `additionalItems` becomes `items`. A string `deprecated` becomes `true` and its message is appended to `description` as `Deprecated: <message>`. `nullable: true` adds `null` to `type`. `dependencies` splits into `dependentRequired` and `dependentSchemas`. `x-` keywords that fact-kit does not register (`X_KEYWORDS`), `$id`, `id` and the keywords in `drop` are removed. The result starts with `$schema` set to `DRAFT_2020_12`."
+            },
+            {
+              "name": "PinnedSource",
+              "signature": "interface PinnedSource { repo, commit, path, sha256, license }",
+              "summary": "An upstream file pinned to a commit: `repo` is `owner/name`, `commit` is the full SHA, `path` is the file in the repository, `sha256` is the hex digest of its bytes and `license` is an SPDX id. A type, exported with `export type`."
+            },
+            {
+              "name": "sourceUrl",
+              "signature": "sourceUrl(source: PinnedSource) => string",
+              "summary": "The GitHub page of the pinned file at its commit (`blob/<commit>/<path>` of the repository), where a reader opens it."
+            },
+            {
+              "name": "readPinned",
+              "signature": "readPinned(source: PinnedSource, options: { cacheDir: string }) => Promise<string>",
+              "summary": "The text of the pinned file. Reads `<cacheDir>/<sha256>.txt` when it exists, otherwise downloads the file at that commit from the raw-content address of GitHub, checks the sha256 and writes the cache. `cacheDir` is required, so the cache place does not depend on the working directory. Throws `<repo>/<path>: sha256 is <actual>, expected <sha256>` when the bytes do not match, also for a cached file, and `<url>: HTTP <status>` when the download fails."
             }
           ],
           "schemaRow": [
@@ -3900,7 +4185,93 @@
         "en": "Converters and the optional TypeScript peer dependency"
       },
       "description": {
-        "en": "The converters read TypeScript with the TypeScript 7.1 API, which starts a native compiler process. `typescript` is an optional peer dependency that is loaded when a converter runs, and a converter throws an error that names the package to install when it is missing."
+        "en": "The converters read TypeScript with the TypeScript 7.1 API, which starts a native compiler process. `typescript` is an optional peer dependency that is loaded when a converter runs, and a converter throws an error that names the package to install when it is missing. `writeFormatted` loads the optional peer dependency `prettier` the same way."
+      },
+      "variants": [
+        {
+          "since": "0.0.0",
+          "content": {
+            "value": {
+              "requires": {
+                "peerDependency": "typescript",
+                "range": ">=7.1.0-beta",
+                "optional": true,
+                "install": "pnpm add -D typescript@7.1.0-beta"
+              },
+              "exports": [
+                {
+                  "name": "readStringTuples",
+                  "signature": "readStringTuples(source: string) => Promise<Record<string, string[]>>",
+                  "summary": "The string literal tuples exported by a TypeScript source, by name: `export declare const X: readonly [...]` and `export const X = [...] as const`. Parses only, so imports do not have to resolve."
+                },
+                {
+                  "name": "readStringTuplesFromFile",
+                  "signature": "readStringTuplesFromFile(path: string) => Promise<Record<string, string[]>>",
+                  "summary": "Reads the file and returns `readStringTuples` of it."
+                },
+                {
+                  "name": "interfaceToJsonSchema",
+                  "signature": "interfaceToJsonSchema({ path, type, tsconfig?, additionalProperties?, descriptions? }) => Promise<JsonSchema>",
+                  "summary": "An interface or type alias as a JSON Schema 2020-12 document. Referenced types become `$defs`. Union members and enum values keep the order of the source, `0 | number` keeps both members, and a tuple becomes `prefixItems`. JSDoc becomes `description`, and `descriptions: false` removes every `description`. Type errors in the input are not reported."
+                },
+                {
+                  "name": "readJsonSchemaFile",
+                  "signature": "readJsonSchemaFile(path: string) => Promise<JsonSchema>",
+                  "summary": "Reads a JSON Schema file. Does not need TypeScript."
+                }
+              ]
+            }
+          }
+        },
+        {
+          "since": "0.10.0-alpha.1",
+          "content": {
+            "value": {
+              "requires": {
+                "peerDependency": "typescript",
+                "range": ">=7.1.0-beta",
+                "optional": true,
+                "install": "pnpm add -D typescript@7.1.0-beta"
+              },
+              "exports": [
+                {
+                  "name": "readStringTuples",
+                  "signature": "readStringTuples(source: string) => Promise<Record<string, string[]>>",
+                  "summary": "The string literal tuples exported by a TypeScript source, by name: `export declare const X: readonly [...]` and `export const X = [...] as const`. Parses only, so imports do not have to resolve."
+                },
+                {
+                  "name": "readStringTuplesFromFile",
+                  "signature": "readStringTuplesFromFile(path: string) => Promise<Record<string, string[]>>",
+                  "summary": "Reads the file and returns `readStringTuples` of it."
+                },
+                {
+                  "name": "interfaceToJsonSchema",
+                  "signature": "interfaceToJsonSchema({ path, type, tsconfig?, additionalProperties?, descriptions? }) => Promise<JsonSchema>",
+                  "summary": "An interface or type alias as a JSON Schema 2020-12 document. Referenced types become `$defs`. Union members and enum values keep the order of the source, `0 | number` keeps both members, and a tuple becomes `prefixItems`. JSDoc becomes `description`, and `descriptions: false` removes every `description`. Type errors in the input are not reported."
+                },
+                {
+                  "name": "readJsonSchemaFile",
+                  "signature": "readJsonSchemaFile(path: string) => Promise<JsonSchema>",
+                  "summary": "Reads a JSON Schema file. Does not need TypeScript."
+                }
+              ],
+              "optionalPeers": [
+                {
+                  "peerDependency": "prettier",
+                  "range": ">=3.0.0",
+                  "install": "pnpm add -D prettier@3",
+                  "usedBy": [
+                    "writeFormatted"
+                  ]
+                }
+              ]
+            }
+          }
+        }
+      ],
+      "tool": "fact-kit",
+      "source": {
+        "kind": "published"
       },
       "content": {
         "value": {
@@ -3931,12 +4302,18 @@
               "signature": "readJsonSchemaFile(path: string) => Promise<JsonSchema>",
               "summary": "Reads a JSON Schema file. Does not need TypeScript."
             }
+          ],
+          "optionalPeers": [
+            {
+              "peerDependency": "prettier",
+              "range": ">=3.0.0",
+              "install": "pnpm add -D prettier@3",
+              "usedBy": [
+                "writeFormatted"
+              ]
+            }
           ]
         }
-      },
-      "tool": "fact-kit",
-      "source": {
-        "kind": "published"
       }
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fact-kit-facts",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Facts about fact-kit: the spec of its index format, commands and API",
   "license": "MIT",
   "type": "module",