@loomcli/core 0.4.0 → 0.6.0

package/dist/extension.d.ts

@@ -1,4 +1,6 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Finding } from './diagnostic-text.js';
+import type { FactSite } from './facts.js';
 import type { ArgumentNode, CommandNode, OptionNode } from './inspect.js';
 import type { AttachedCommand } from './types.js';
 /** The three declaration kinds an extension can name, each with its own node in the graph. */
@@ -15,8 +17,14 @@ interface AnyExtension {
     readonly target: ExtensionTarget;
     readonly collect: boolean;
 }
-/** What a value must show to be taken for a descriptor before its `collect` flag is checked. */
-type DescriptorShape = Pick<AnyExtension, 'identity' | 'target'>;
+/**
+ * What a value must show to be taken for a descriptor before admission checks its identity and its
+ * `collect` flag. The identity stays unread here, so admission reads it once.
+ */
+interface DescriptorShape {
+    readonly identity: unknown;
+    readonly target: ExtensionTarget;
+}
 /** One carried value: the input its author supplied and the descriptor that produced it. */
 interface CarriedValue {
     descriptor: AnyExtension;
@@ -83,6 +91,8 @@ type ExtensionRead<Schema extends StandardSchemaV1, Collect extends boolean> = C
  * collection order, and an empty list where the node carries none.
  */
 declare function readExtension<Target extends ExtensionTarget, Schema extends StandardSchemaV1, Collect extends boolean = false>(node: NodeFor<Target>, descriptor: Extension<Target, Schema, Collect>): ExtensionRead<Schema, Collect>;
+/** How a diagnostic names the declarations one target covers, such as "Commands". */
+declare function appliesTo(target: ExtensionTarget): string;
 /** The declaration one `extensions` slot belongs to, as its own diagnostics name it. */
 interface ExtensionSubject {
     /** The subject after a preposition, such as `on Command "get"`. */
@@ -90,8 +100,15 @@ interface ExtensionSubject {
     /** The subject at the start of a sentence, such as `Command "get"`. */
     sentence: string;
 }
+/**
+ * A descriptor admission accepted: its shape and a Boolean `collect` flag. Its identity is the key
+ * a registry holds it under, so nothing reads it from the descriptor again.
+ */
+type AdmittedDescriptor = DescriptorShape & {
+    readonly collect: boolean;
+};
 /** Every descriptor one build has met, so a second descriptor under one identity is visible. */
-type DescriptorRegistry = Map<string, AnyExtension>;
+type DescriptorRegistry = Map<string, AdmittedDescriptor>;
 /**
  * The record each declaration published during one build, keyed by the declaration itself. The
  * records live here rather than on the declaration, because one build's outputs belong to that
@@ -100,15 +117,33 @@ type DescriptorRegistry = Map<string, AnyExtension>;
 type ExtensionRecords = Map<object, Readonly<Record<string, unknown>>>;
 /**
  * Whether a value has a descriptor's shape: a callable object carrying an identity and a declared
- * target. Its `collect` flag is checked where a build registers it.
+ * target. Admission checks its identity and its `collect` flag where a build registers it.
  */
 declare function isDescriptor(value: unknown): value is DescriptorShape;
-/** Admits one descriptor and records it, so a later descriptor of its identity is compared to it. */
-declare function registerDescriptor(descriptors: DescriptorRegistry, descriptor: DescriptorShape): void;
-/** Everything one `extensions` slot needs to answer: whose it is, and what it may carry. */
+/**
+ * How one descriptor is admitted: the declaration that carries it, the plugin that holds it in a
+ * sentence, and its identity when a registry already read it once.
+ */
+interface Admission {
+    place?: Finding | undefined;
+    holder?: string | undefined;
+    identity?: string | undefined;
+}
+/**
+ * Admits one descriptor and records it under the identity admission read, so a later descriptor of
+ * that identity is compared to it.
+ */
+declare function registerDescriptor(descriptors: DescriptorRegistry, descriptor: DescriptorShape, admission?: Admission): void;
+/**
+ * Where one `extensions` list sits: the call that declared it, and the dotted path among that
+ * call's arguments to the list, which is empty for `extend()`, whose arguments are the list.
+ */
+type ExtensionSite = Pick<FactSite, 'at' | 'declaration'>;
+/** Everything one `extensions` slot needs to answer: whose it is, where, and what it may carry. */
 interface ExtensionSlot {
     declared: unknown;
     descriptors: DescriptorRegistry;
+    site: ExtensionSite;
     subject: ExtensionSubject;
     target: ExtensionTarget;
 }
@@ -151,5 +186,5 @@ declare function buildExtensions(slot: ExtensionSlot): Readonly<Record<string, u
 declare function storeCommandLayers(slot: Omit<ExtensionSlot, 'declared' | 'target'> & {
     layers: readonly unknown[];
 }): ExtensionStore;
-export type { AnyExtension, DeepReadonly, DescriptorRegistry, Extension, ExtensionRecords, ExtensionStore, ExtensionSubject, ExtensionTarget, ExtensionValue, };
-export { buildExtensions, extendStore, extension, isDescriptor, publishStore, readExtension, registerDescriptor, storeCommandLayers, validateLayer, };
+export type { AdmittedDescriptor, AnyExtension, DeepReadonly, DescriptorRegistry, Extension, ExtensionRecords, ExtensionSite, ExtensionStore, ExtensionSubject, ExtensionTarget, ExtensionValue, };
+export { appliesTo, buildExtensions, extendStore, extension, isDescriptor, publishStore, readExtension, registerDescriptor, storeCommandLayers, validateLayer, };

package/dist/extension.js

@@ -1,5 +1,13 @@
-import { DeclarationError, reasonOf } from './errors.js';
-import { isPlainObject } from './facts.js';
+import { escapeControlCharacters } from './controls.js';
+import { asSentence, DeclarationError, quoted, reasonOf } from './errors.js';
+import { partOf } from './facts.js';
+import { checkIdentity, identityFault, isIdentity } from './identity.js';
+import { flagNotBoolean } from './input-rules.js';
+import { isPlainObject } from './plain.js';
+import { asyncExtensionSchema, extensionOutput, extensionTarget as extensionTargetRule, extensionValueTwice, extensionWithoutSchema, foreignValue, invalidExtensionValue, notAList, twoPackageCopies, } from './plugin-rules.js';
+import { isThenable } from './thenable.js';
+/** The fix every fault from two copies of one package shares. */
+const copiesCorrection = 'Install one copy of the package that defines it.';
 /** Authored values register here, so the public brand publishes no state to reach or replace. */
 const values = new WeakMap();
 /**
@@ -20,6 +28,7 @@ class ExtensionCarrier {
     }
 }
 function extension(identity, config) {
+    checkIdentity('extension', identity);
     // `Object.assign` returns the same function object, so the value carries the descriptor itself.
     function create(input) {
         return new ExtensionCarrier({ descriptor, input });
@@ -44,14 +53,19 @@ const noValues = Object.freeze([]);
  * collection order, and an empty list where the node carries none.
  */
 function readExtension(node, descriptor) {
+    const { identity } = descriptor;
     const record = node.extensions;
-    const owner = owners.get(record)?.get(descriptor.identity);
+    const owner = owners.get(record)?.get(identity);
     if (owner !== undefined && owner !== descriptor) {
-        throw new DeclarationError(`Extension "${descriptor.identity}" was read through a descriptor that did not define the stored value. Install one copy of the package that defines it.`);
+        // A read happens inside a plugin's own code, so no declaration call stands for it.
+        throw new DeclarationError(twoPackageCopies, {
+            correction: copiesCorrection,
+            sentence: `Extension ${quoted(identity)} was read through a descriptor that did not define the stored value.`,
+        });
     }
     // A collecting extension a declaration carries no value of reads as an empty list.
     const absent = descriptor.collect ? noValues : undefined;
-    const stored = owner === undefined ? absent : record[descriptor.identity];
+    const stored = owner === undefined ? absent : record[identity];
     // Last resort: no typed path exists.
     // The graph stores every output under a string identity, so the record reads back as `unknown`.
     // No key relates one entry to a descriptor's schema or to its runtime `collect` flag.
@@ -67,6 +81,10 @@ const applies = {
     command: 'Commands',
     option: 'options',
 };
+/** How a diagnostic names the declarations one target covers, such as "Commands". */
+function appliesTo(target) {
+    return applies[target];
+}
 /**
  * The children one container contributes, or nothing when its own shape is not plain data. An
  * accessor, a symbol key, and a non-enumerable own property are not plain data, and an `undefined`
@@ -178,13 +196,12 @@ function plainData(value) {
 }
 /**
  * Whether a value has a descriptor's shape: a callable object carrying an identity and a declared
- * target. Its `collect` flag is checked where a build registers it.
+ * target. Admission checks its identity and its `collect` flag where a build registers it.
  */
 function isDescriptor(value) {
     return (value !== null &&
         (typeof value === 'object' || typeof value === 'function') &&
         'identity' in value &&
-        typeof value.identity === 'string' &&
         'target' in value &&
         (value.target === 'argument' || value.target === 'command' || value.target === 'option'));
 }
@@ -196,29 +213,53 @@ function hasCollectFlag(descriptor) {
 function collects(descriptor) {
     return descriptor.collect;
 }
+/** The findings for the declaration one fault marks, when a declaration stands for it. */
+function marking(place, note) {
+    return place === undefined ? [] : [{ ...place, note }];
+}
 /**
- * The descriptor a registry holds for one identity once this one is admitted. One identity means
- * one descriptor, wherever on the graph that descriptor appears, and a descriptor is checked when
- * a build first meets it: its `collect` flag is `true` or `false`, which the factory always
- * publishes and a hand-built descriptor may not. It reads the registry and changes nothing.
+ * The descriptor a registry holds for one identity once this one is admitted, and that identity.
+ * One identity means one descriptor, wherever on the graph that descriptor appears, and a
+ * descriptor is checked when a build first meets it: its identity follows the identity grammar and
+ * its `collect` flag is `true` or `false`, which the factory always ensures and a hand-built
+ * descriptor may not. The identity is read once, so a getter cannot answer the check with one value
+ * and the registry with another. It reads the registry and changes nothing.
  */
-function admitDescriptor(descriptors, descriptor) {
-    const known = descriptors.get(descriptor.identity);
+function admitDescriptor(descriptors, descriptor, { holder, place, ...admission }) {
+    const identity = admission.identity ?? descriptor.identity;
+    if (!isIdentity(identity)) {
+        const subject = holder === undefined
+            ? 'An extension declares the identity'
+            : `${holder} holds the extension identity`;
+        throw identityFault(subject, identity, place === undefined ? [] : [place]);
+    }
+    const known = descriptors.get(identity);
     if (known === undefined) {
         if (!hasCollectFlag(descriptor)) {
-            throw new DeclarationError(`Extension "${descriptor.identity}" declares collect that is not a Boolean. Supply true or false, or build the descriptor with extension(identity, config).`);
+            throw new DeclarationError(flagNotBoolean, {
+                correction: 'Use true or false.',
+                findings: marking(place, `extension ${quoted(identity)}`),
+                sentence: `Extension ${quoted(identity)} declares collect that is not a Boolean.`,
+            });
         }
-        return descriptor;
+        return { descriptor, identity };
     }
     if (known !== descriptor) {
-        throw new DeclarationError(`Extension "${descriptor.identity}" is defined twice. Install one copy of the package that defines it.`);
+        throw new DeclarationError(twoPackageCopies, {
+            correction: copiesCorrection,
+            findings: marking(place, `another ${quoted(identity)}`),
+            sentence: `Extension ${quoted(identity)} is defined twice.`,
+        });
     }
-    return known;
+    return { descriptor: known, identity };
 }
-/** Admits one descriptor and records it, so a later descriptor of its identity is compared to it. */
-function registerDescriptor(descriptors, descriptor) {
-    const admitted = admitDescriptor(descriptors, descriptor);
-    descriptors.set(admitted.identity, admitted);
+/**
+ * Admits one descriptor and records it under the identity admission read, so a later descriptor of
+ * that identity is compared to it.
+ */
+function registerDescriptor(descriptors, descriptor, admission = {}) {
+    const admitted = admitDescriptor(descriptors, descriptor, admission);
+    descriptors.set(admitted.identity, admitted.descriptor);
 }
 /** Whether a value answers the Standard Schema v1 contract this build calls synchronously. */
 function isSchema(value) {
@@ -231,108 +272,149 @@ function isSchema(value) {
         'validate' in standard &&
         typeof standard.validate === 'function');
 }
-/**
- * One schema message as a sentence of its own. A schema author writes the message with or without a
- * full stop, so the diagnostic supplies one only where the message carries none.
- */
-function sentence(text) {
-    return text.endsWith('.') ? text : `${text}.`;
-}
-/** The message one rejected value reports, with the placeholder a silent schema earns. */
+/** The message one rejected value reports, escaped, with the placeholder a silent schema earns. */
 function issueText(issues) {
     const first = Array.isArray(issues) ? issues[0] : undefined;
     if (first !== null && typeof first === 'object' && 'message' in first) {
         const { message } = first;
         if (typeof message === 'string') {
-            return message;
+            return escapeControlCharacters(message);
         }
     }
     // The sentence the caller composes ends the diagnostic, so this text carries no full stop.
     return 'The schema rejected this value without an explanation';
 }
-/**
- * Whether one schema answered with a promise. A thenable object and a promise from another realm
- * are as unwaitable here as a native one, so the test is the contract and not the class.
- */
-function isThenable(value) {
-    return 'then' in value && typeof value.then === 'function';
+/** One entry of a list a fault marks: the site's call, with the mark on the entry. */
+function entryFinding(site, index, note) {
+    const finding = { ...site.declaration, mark: partOf(site, index) };
+    return note === undefined ? finding : { ...finding, note };
 }
 /** The schema one descriptor answers with, which a JavaScript author can leave out. */
-function schemaOf(subject, descriptor) {
+function schemaOf(subject, { carried, place }) {
+    const { descriptor } = carried;
     const schema = 'schema' in descriptor ? descriptor.schema : undefined;
     if (!isSchema(schema)) {
-        throw new DeclarationError(`${subject.sentence} holds extension "${descriptor.identity}", which declares no schema. Supply a Standard Schema v1 object that answers synchronously.`);
+        throw new DeclarationError(extensionWithoutSchema, {
+            correction: 'Supply a Standard Schema v1 object that answers synchronously.',
+            findings: [place],
+            sentence: `${subject.sentence} holds extension ${quoted(descriptor.identity)}, which declares no schema.`,
+        });
     }
     return schema;
 }
+/** The fix every rejected extension value shares. */
+const correctValue = 'Correct the value.';
 /** The result one schema answered with, or the rejection its own throw is. */
-function validated(subject, carried, schema) {
+function validated(subject, entry, schema) {
+    const { carried, place } = entry;
     try {
         return schema['~standard'].validate(carried.input);
     }
     catch (error) {
         // A schema that throws rejected the value the only way it could, so it reads as a rejection.
-        throw new DeclarationError(`${subject.sentence} holds an invalid "${carried.descriptor.identity}" value: ${sentence(reasonOf(error))} Correct the value.`);
+        throw new DeclarationError(invalidExtensionValue, {
+            correction: correctValue,
+            findings: [place],
+            sentence: `${subject.sentence} holds an invalid ${quoted(carried.descriptor.identity)} value: ${asSentence(reasonOf(error))}`,
+        }, { cause: error });
     }
 }
 /** Validates one carried value and answers the plain-data output the node stores under it. */
-function validateValue(subject, carried) {
+function validateValue(subject, entry) {
+    const { carried, place } = entry;
     const { identity } = carried.descriptor;
-    const result = validated(subject, carried, schemaOf(subject, carried.descriptor));
+    const result = validated(subject, entry, schemaOf(subject, entry));
     if (result === null || typeof result !== 'object' || isThenable(result)) {
-        throw new DeclarationError(`Extension "${identity}" validates asynchronously. Supply a schema that answers synchronously.`);
+        throw new DeclarationError(asyncExtensionSchema, {
+            correction: 'Supply a schema that answers synchronously.',
+            findings: [place],
+            sentence: `Extension ${quoted(identity)} validates asynchronously.`,
+        });
     }
     const issues = 'issues' in result ? result.issues : undefined;
     if (issues !== undefined) {
-        throw new DeclarationError(`${subject.sentence} holds an invalid "${identity}" value: ${sentence(issueText(issues))} Correct the value.`);
+        throw new DeclarationError(invalidExtensionValue, {
+            correction: correctValue,
+            findings: [place],
+            sentence: `${subject.sentence} holds an invalid ${quoted(identity)} value: ${asSentence(issueText(issues))}`,
+        });
     }
     const output = plainData('value' in result ? result.value : undefined);
     if (!output) {
-        throw new DeclarationError(`Extension "${identity}" produced a value that is not plain data ${subject.phrase}. Return strings, numbers, booleans, null, arrays, and plain objects.`);
+        throw new DeclarationError(extensionOutput, {
+            correction: 'Return strings, numbers, booleans, null, arrays, and plain objects.',
+            findings: [place],
+            sentence: `Extension ${quoted(identity)} produced a value that is not plain data ${subject.phrase}.`,
+        });
     }
     return output.data;
 }
 /** An `extensions` slot holds a list of values, so anything else is the same declaration fault. */
-function readList(subject, declared) {
+function readList(slot) {
+    const { declared, site, subject } = slot;
     if (declared === undefined) {
         return [];
     }
     if (!Array.isArray(declared)) {
-        throw new DeclarationError(`${subject.sentence} holds a value that is not an extension value. Supply the value returned by calling an extension.`);
+        throw new DeclarationError(notAList, {
+            correction: 'Supply a list of values returned by calling an extension.',
+            findings: [{ ...site.declaration, mark: site.at }],
+            sentence: `${subject.sentence} declares extensions that are not an array.`,
+        });
     }
     return declared;
 }
 /** The value one entry carries, under the rules its own slot's target sets. */
-function carriedValue(subject, target, entry) {
+function carriedValue(slot, entry, index) {
+    const { site, subject, target } = slot;
     const carried = typeof entry === 'object' && entry !== null ? values.get(entry) : undefined;
     if (!carried) {
-        throw new DeclarationError(`${subject.sentence} holds a value that is not an extension value. Supply the value returned by calling an extension.`);
-    }
-    if (carried.descriptor.target !== target) {
-        throw new DeclarationError(`${subject.sentence} holds extension "${carried.descriptor.identity}", which applies to ${applies[carried.descriptor.target]}. Supply an extension that applies to ${applies[target]}.`);
-    }
-    return carried;
+        throw new DeclarationError(foreignValue, {
+            correction: 'Supply the value returned by calling an extension.',
+            findings: [entryFinding(site, index)],
+            sentence: `${subject.sentence} holds a value that is not an extension value.`,
+        });
+    }
+    const { descriptor } = carried;
+    const place = entryFinding(site, index, `extension ${quoted(descriptor.identity)}`);
+    if (descriptor.target !== target) {
+        throw new DeclarationError(extensionTargetRule, {
+            correction: `Supply an extension that applies to ${applies[target]}.`,
+            findings: [place],
+            sentence: `${subject.sentence} holds extension ${quoted(descriptor.identity)}, which applies to ${applies[descriptor.target]}.`,
+        });
+    }
+    return { carried, place };
 }
 /**
  * One layer's values, each validated once, synchronously, in authoring order. A layer holds at
  * most one value of an extension, collecting or not, so a second one is a declaration fault.
  */
 function validateLayer(slot) {
-    const { subject } = slot;
+    const { site, subject } = slot;
     const layer = [];
-    const seen = new Set();
+    // Each identity's position in the list, so a repeat marks both values.
+    const seen = new Map();
     // The layer's descriptors register together once every value is valid.
     // A rejected layer, such as a hook's `extend()` call the hook catches, leaves the registry as it was.
     const staged = new Map(slot.descriptors);
-    for (const entry of readList(subject, slot.declared)) {
-        const carried = carriedValue(subject, slot.target, entry);
-        const { descriptor } = carried;
-        registerDescriptor(staged, descriptor);
-        if (seen.has(descriptor.identity)) {
-            throw new DeclarationError(`${subject.sentence} holds extension "${descriptor.identity}" twice. Supply one value.`);
+    for (const [index, value] of readList(slot).entries()) {
+        const entry = carriedValue(slot, value, index);
+        const { descriptor } = entry.carried;
+        registerDescriptor(staged, descriptor, { place: entryFinding(site, index) });
+        const first = seen.get(descriptor.identity);
+        if (first !== undefined) {
+            throw new DeclarationError(extensionValueTwice, {
+                correction: 'Supply one value.',
+                findings: [
+                    entryFinding(site, first, 'the first value'),
+                    entryFinding(site, index, 'the second value'),
+                ],
+                sentence: `${subject.sentence} holds extension ${quoted(descriptor.identity)} twice.`,
+            });
         }
-        seen.add(descriptor.identity);
-        layer.push({ descriptor, output: validateValue(subject, carried) });
+        seen.set(descriptor.identity, index);
+        layer.push({ descriptor, output: validateValue(subject, entry) });
     }
     for (const [identity, descriptor] of staged) {
         slot.descriptors.set(identity, descriptor);
@@ -395,4 +477,4 @@ function storeCommandLayers(slot) {
     }
     return store;
 }
-export { buildExtensions, extendStore, extension, isDescriptor, publishStore, readExtension, registerDescriptor, storeCommandLayers, validateLayer, };
+export { appliesTo, buildExtensions, extendStore, extension, isDescriptor, publishStore, readExtension, registerDescriptor, storeCommandLayers, validateLayer, };

package/dist/facts.d.ts

@@ -1,39 +1,99 @@
+import type { DiagnosticRule, Finding } from './diagnostic-text.js';
+import { DeclarationError } from './errors.js';
+/**
+ * Where one fact was declared: the subject its sentence names, the call that declared it, and the
+ * dotted path among that call's arguments to the object that holds the fact, which a finding marks.
+ */
+export interface FactSite {
+    readonly subject: string;
+    readonly declaration: Omit<Finding, 'mark' | 'note'>;
+    readonly at: string;
+}
+/** The finding for the call one site holds, marking one part of it, with a note when given. */
+export declare function siteFinding(site: FactSite, mark: string, note?: string): Finding;
+/**
+ * Where one key of a declaration's options object sits, rebuilt with that key alone, as
+ * `plugin(identity, { middleware })` or `new Application(name, { plugins })`, at `1.<key>`. A fault
+ * about one slot shows the slot, not every other one the author declared beside it.
+ */
+export declare function slotSite(declaration: {
+    call: string;
+    named: unknown;
+    subject: string;
+}, key: string, value: unknown): FactSite;
+/**
+ * The dotted path to one part inside the value a site holds, such as `1.middleware.activate` for
+ * `activate` under a site at `1.middleware`. A site at the call's own arguments has an empty path.
+ */
+export declare function partOf(site: Pick<FactSite, 'at'>, ...keys: readonly (number | string)[]): string;
+/** The finding that marks one part inside the value a site holds, with a note when given. */
+export declare function partFinding(site: FactSite, keys: readonly (number | string)[], note?: string): Finding;
+/**
+ * One fact's fault, which marks the fact inside the call that declared it. Every rule about one key
+ * of a declaration's config object reports through it, so each marks the key the same way.
+ */
+export declare function factFault(rule: DiagnosticRule, site: FactSite, parts: {
+    fact: string;
+    sentence: string;
+    correction: string;
+}): DeclarationError;
+/**
+ * One yes-or-no declaration key that holds a value other than a Boolean, such as `required` or
+ * `hidden`. Every such key reports under one rule, in one sentence and with one correction.
+ */
+export declare function flagFault(site: FactSite, flag: string): DeclarationError;
+/**
+ * Where one input was declared: the site of its config object, and the dotted path to its declared
+ * name, which a fault about the name or about the whole input marks.
+ */
+export interface InputSite extends FactSite {
+    readonly named: string;
+}
+/** The site of an input a call declared as `call(name, config)`, such as `option()`. */
+export declare function callSite(subject: string, declaration: Omit<Finding, 'mark' | 'note'>): InputSite;
+/**
+ * The site of one option a plugin declared, rebuilt as `plugin(identity, { options })` from the
+ * options the plugin holds. The option's entry in the record stands for its name.
+ */
+export declare function pluginOptionSite(plugin: {
+    identity: string;
+    options: unknown;
+}, name: string, subject: string): InputSite;
+/**
+ * One line of prose: a string that holds a character other than whitespace and no line terminator.
+ * Every one-line fact reads this rule, and so does the label a configuration source answers with.
+ */
+export declare function isProseLine(value: unknown): value is string;
 /**
  * The `description` core fact: one line of prose every projection reads. A value that is not a
  * string fails the same way a blank one does, because the author reads one rule for one fact.
  * An omitted description is absent, not a fault, so it passes through as `undefined`.
  */
-export declare function checkDescription(subject: string, value: unknown): string | undefined;
+export declare function checkDescription(site: FactSite, value: unknown): string | undefined;
 /**
  * The `hidden` core fact: whether a listing omits this member. It is a Boolean, because a listing
  * asks one question of it, and an omitted declaration reads `false`. Routing selects and parsing
  * binds without reading it, so a hidden member behaves as any other.
  */
-export declare function checkHidden(subject: string, value: unknown): boolean;
+export declare function checkHidden(site: FactSite, value: unknown): boolean;
 /**
  * The `deprecated` core fact: the one-line migration message a listing shows beside the member.
  * It answers the rule a description answers, because both are one line of prose a projection
  * prints. A bare `true` is rejected with every other value that is not prose: a deprecation with
  * no migration path leaves an operator or an agent with nothing to do.
  */
-export declare function checkDeprecated(subject: string, value: unknown): string | undefined;
+export declare function checkDeprecated(site: FactSite, value: unknown): string | undefined;
 /**
  * The declarations that carry neither listing fact: an argument, which cannot leave the grammar it
  * sits in, and the root, which is every page's entry point. The types remove both keys there, and
  * a JavaScript author, or a TypeScript author whose argument config is inferred from a value,
  * reaches this rule instead.
  */
-export declare function checkNoListingFacts(subject: string, declared: object): void;
+export declare function checkNoListingFacts(site: FactSite, declared: object): void;
 /**
  * The `version` core fact, which the Application alone carries. Core reads it as an opaque string,
  * because the convention is the package manifest's own field and no scheme is imposed on it. An
  * omitted version is `0.0.0`, which means unversioned, and core keeps no record of which one the
  * author wrote.
  */
-export declare function checkVersion(value: unknown): string;
-/**
- * A structural value core reads as plain data: an object literal, and never a declaration that
- * carries state of its own. The options slots read it to reject a value that is not an options
- * object, and inspection reads it to copy a declared value faithfully.
- */
-export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function checkVersion(site: FactSite, value: unknown): string;