@cplieger/deadset-ts 8.0.0-dev.15 → 8.0.0-dev.17

package/dist/src/unimplemented-callees.js

@@ -8,8 +8,6 @@
  */
 import { isArrowFunction, isAsExpression, isCallExpression, isClassDeclaration, isClassExpression, isFunctionDeclaration, isFunctionExpression, isHeritageClause, isIdentifier, isMethodDeclaration, isNewExpression, isObjectLiteralExpression, isParameterDeclaration, isParenthesizedExpression, isPropertyAccessExpression, isPropertyAssignment, isPropertyDeclaration, isSatisfiesExpression, isTypeReferenceNode, isVariableDeclaration, } from "@typescript/native/ast";
 import { SymbolFlags } from "@typescript/native/sync";
-import { nodeKey } from "./inventory.js";
-import { renderPosition } from "./position.js";
 import { UNANSWERED } from "./query.js";
 /** The value an `as` expression asserts a type of, through every `as` and parenthesis around it. */
 function castOperand(node) {
@@ -61,252 +59,274 @@ function literalsOf(argument) {
     ];
 }
 /**
- * The reads the object-literal arguments of one project's own files make of the members of
- * the types they are checked against, where the callee has no implementation in the target.
+ * The reads the object-literal arguments of a side's files make of the members of the types
+ * they are checked against, where the callee has no implementation in the target, and the
+ * reads of every member of each target type an outside value is handed over as. A type the
+ * checker leaves unanswered holds what its answer could have read.
  */
-export function unimplementedCalleeReads(project, held, chains, root, testFiles) {
-    const queries = project.queries;
-    const own = project.ownPaths();
-    const passing = [];
-    const implementing = [];
-    const asserted = [];
-    const constructed = [];
-    const handing = [];
-    for (const file of project.ownSourceFiles()) {
-        const fileId = held.declarations.get(nodeKey(file, file));
-        if (fileId === undefined) {
-            continue;
-        }
-        const visit = (node, from) => {
-            const holder = held.declarations.get(nodeKey(file, node)) ?? from;
-            if ((isCallExpression(node) || isNewExpression(node)) &&
-                (node.arguments ?? []).some((argument) => isObjectLiteralExpression(argument))) {
-                passing.push({ file, from: holder, call: node });
-            }
-            if (isNewExpression(node)) {
-                constructed.push({ file, from: holder, call: node });
-            }
-            if ((isCallExpression(node) || isNewExpression(node)) &&
-                (node.arguments ?? []).some((argument) => isFunctionLike(argument) || isIdentifier(argument))) {
-                handing.push(node);
-            }
-            if (isAsExpression(node) && !isAsExpression(node.parent)) {
-                asserted.push({ file, from: holder, node, operand: castOperand(node) });
-            }
-            if (isClassDeclaration(node) || isClassExpression(node)) {
-                for (const clause of node.heritageClauses ?? []) {
-                    if (isHeritageClause(clause)) {
-                        implementing.push(...clause.types.map((one) => isTypeReferenceNode(one) ? one.typeName : one.expression));
+export const unimplementedCallees = {
+    start() {
+        const passing = [];
+        const implementing = [];
+        const asserted = [];
+        const constructed = [];
+        const handing = [];
+        return {
+            visit(node, { file, from }) {
+                if ((isCallExpression(node) || isNewExpression(node)) &&
+                    (node.arguments ?? []).some((argument) => isObjectLiteralExpression(argument))) {
+                    passing.push({ file, from, call: node });
+                }
+                if (isNewExpression(node)) {
+                    constructed.push({ file, from, call: node });
+                }
+                if ((isCallExpression(node) || isNewExpression(node)) &&
+                    (node.arguments ?? []).some((argument) => isFunctionLike(argument) || isIdentifier(argument))) {
+                    handing.push(node);
+                }
+                if (isAsExpression(node) && !isAsExpression(node.parent)) {
+                    asserted.push({ file, from, node, operand: castOperand(node) });
+                }
+                if (isClassDeclaration(node) || isClassExpression(node)) {
+                    for (const clause of node.heritageClauses ?? []) {
+                        if (isHeritageClause(clause)) {
+                            implementing.push(...clause.types.map((one) => isTypeReferenceNode(one) ? one.typeName : one.expression));
+                        }
                     }
                 }
-            }
-            // An object literal typed as an interface implements that interface's methods.
-            if (isVariableDeclaration(node) &&
-                node.type !== undefined &&
-                isTypeReferenceNode(node.type) &&
-                node.initializer !== undefined &&
-                isObjectLiteralExpression(node.initializer)) {
-                implementing.push(node.type.typeName);
-            }
-            if ((isSatisfiesExpression(node) || isAsExpression(node)) &&
-                isObjectLiteralExpression(node.expression) &&
-                isTypeReferenceNode(node.type)) {
-                implementing.push(node.type.typeName);
-            }
-            node.forEachChild((child) => {
-                visit(child, holder);
-            });
-        };
-        file.forEachChild((child) => {
-            visit(child, fileId);
-        });
-    }
-    if (passing.length === 0 && asserted.length === 0 && constructed.length === 0) {
-        return [];
-    }
-    const resolved = (symbol) => {
-        if (symbol === UNANSWERED || symbol === undefined) {
-            return undefined;
-        }
-        if ((symbol.flags & SymbolFlags.Alias) === 0) {
-            return symbol;
-        }
-        const target = queries.aliased(symbol);
-        return target === UNANSWERED ? undefined : target;
-    };
-    const declarationsOf = (symbol) => (symbol?.declarations ?? []).flatMap((handle) => {
-        const node = project.declarationAt(handle)?.node;
-        return node === undefined ? [] : [node];
-    });
-    const implemented = new Set(queries.symbolsAt(implementing).flatMap((symbol) => declarationsOf(resolved(symbol))));
-    /** Whether a declaration is a function or a class of the target, or a variable or property it initializes. */
-    const ownFunction = (node) => own.has(node.getSourceFile().fileName) &&
-        (isFunctionLike(node) ||
-            ((isVariableDeclaration(node) || isPropertyAssignment(node) || isPropertyDeclaration(node)) &&
-                isFunctionLike(node.initializer)));
-    /**
-     * Whether a function or a class of the target reaches one parameter of a function of the
-     * target, passed for it by a call that names the function. A call through another name
-     * is not followed, so its callee keeps no implementation and its literal reads more.
-     */
-    const reachedParameters = new Map();
-    const parameterReached = (parameter) => {
-        const known = reachedParameters.get(parameter);
-        if (known !== undefined) {
-            return known;
-        }
-        const fn = parameter.parent;
-        const fnName = nameOf(fn) ?? (isVariableDeclaration(fn.parent) ? nameOf(fn.parent) : undefined);
-        const at = fn.parameters?.indexOf(parameter) ?? -1;
-        const passed = handing.flatMap((call) => {
-            const callee = call.expression;
-            const name = isPropertyAccessExpression(callee) ? callee.name : callee;
-            if (fnName === undefined || !isIdentifier(name) || name.text !== fnName) {
-                return [];
-            }
-            const signature = queries.resolvedSignature(call);
-            const handle = signature === UNANSWERED || signature === undefined ? undefined : signature.declaration;
-            const argument = handle === undefined || project.declarationAt(handle)?.node !== fn
-                ? undefined
-                : (call.arguments ?? [])[at];
-            return argument === undefined || at < 0 ? [] : [argument];
-        });
-        const named = passed.filter((argument) => isIdentifier(argument));
-        const reached = passed.some((argument) => isFunctionLike(argument)) ||
-            queries
-                .symbolsAt(named)
-                .some((symbol) => declarationsOf(resolved(symbol)).some((node) => ownFunction(node)));
-        reachedParameters.set(parameter, reached);
-        return reached;
-    };
-    /** Whether some function, class or object literal of the target stands for a signature. */
-    const standsFor = (passed) => {
-        const signature = queries.resolvedSignature(passed.call);
-        const handle = signature === UNANSWERED || signature === undefined ? undefined : signature.declaration;
-        const declaration = handle === undefined ? undefined : project.declarationAt(handle)?.node;
-        if (declaration === undefined) {
-            return true;
-        }
-        if (hasBody(declaration) || overloadImplemented(declaration)) {
-            return own.has(handle?.path ?? "");
-        }
-        const holder = declaration.parent;
-        if (holder !== undefined && implemented.has(holder)) {
-            return true;
-        }
-        const callee = passed.call.expression;
-        const name = isPropertyAccessExpression(callee) ? callee.name : callee;
-        const [named] = queries.symbolsAt([name]);
-        return declarationsOf(resolved(named)).some((node) => isParameterDeclaration(node)
-            ? own.has(node.getSourceFile().fileName) && parameterReached(node)
-            : ownFunction(node) && !isFunctionLike(node));
-    };
-    const literals = [];
-    for (const passed of passing) {
-        if (standsFor(passed)) {
-            continue;
-        }
-        for (const argument of passed.call.arguments ?? []) {
-            literals.push(...literalsOf(argument).map((literal) => ({ passed, literal })));
-        }
-    }
-    const contexts = queries.contextualTypes(literals.map((one) => one.literal));
-    const found = [];
-    literals.forEach(({ passed, literal }, at) => {
-        const context = contexts[at];
-        if (context === UNANSWERED || context === undefined) {
-            return;
-        }
-        const parts = queries.constituents(context);
-        const position = renderPosition(passed.file, root, literal.getStart());
-        for (const part of parts === UNANSWERED ? [context] : parts) {
-            const properties = queries.propertiesOf(part);
-            for (const property of properties === UNANSWERED ? [] : properties) {
-                for (const to of chains.declarationsOf(property)) {
-                    found.push({
-                        from: passed.from,
-                        to,
-                        position,
-                        use: "read",
-                        resolution: "contextual",
-                        test: testFiles.has(position.path),
+                // An object literal typed as an interface implements that interface's methods.
+                if (isVariableDeclaration(node) &&
+                    node.type !== undefined &&
+                    isTypeReferenceNode(node.type) &&
+                    node.initializer !== undefined &&
+                    isObjectLiteralExpression(node.initializer)) {
+                    implementing.push(node.type.typeName);
+                }
+                if ((isSatisfiesExpression(node) || isAsExpression(node)) &&
+                    isObjectLiteralExpression(node.expression) &&
+                    isTypeReferenceNode(node.type)) {
+                    implementing.push(node.type.typeName);
+                }
+            },
+            reads({ project, chains }) {
+                const queries = project.queries;
+                const own = project.ownPaths();
+                const found = [];
+                if (passing.length === 0 && asserted.length === 0 && constructed.length === 0) {
+                    return found;
+                }
+                const resolved = (symbol) => {
+                    if (symbol === UNANSWERED || symbol === undefined) {
+                        return undefined;
+                    }
+                    if ((symbol.flags & SymbolFlags.Alias) === 0) {
+                        return symbol;
+                    }
+                    const target = queries.aliased(symbol);
+                    return target === UNANSWERED ? undefined : target;
+                };
+                const declarationsOf = (symbol) => (symbol?.declarations ?? []).flatMap((handle) => {
+                    const node = project.declarationAt(handle)?.node;
+                    return node === undefined ? [] : [node];
+                });
+                const implemented = new Set(queries.symbolsAt(implementing).flatMap((symbol) => declarationsOf(resolved(symbol))));
+                /** Whether a declaration is a function or a class of the target, or a variable or property it initializes. */
+                const ownFunction = (node) => own.has(node.getSourceFile().fileName) &&
+                    (isFunctionLike(node) ||
+                        ((isVariableDeclaration(node) ||
+                            isPropertyAssignment(node) ||
+                            isPropertyDeclaration(node)) &&
+                            isFunctionLike(node.initializer)));
+                /**
+                 * Whether a function or a class of the target reaches one parameter of a function of the
+                 * target, passed for it by a call that names the function. A call through another name
+                 * is not followed, so its callee keeps no implementation and its literal reads more.
+                 */
+                const reachedParameters = new Map();
+                const parameterReached = (parameter) => {
+                    const known = reachedParameters.get(parameter);
+                    if (known !== undefined) {
+                        return known;
+                    }
+                    const fn = parameter.parent;
+                    const fnName = nameOf(fn) ?? (isVariableDeclaration(fn.parent) ? nameOf(fn.parent) : undefined);
+                    const at = fn.parameters?.indexOf(parameter) ?? -1;
+                    const passed = handing.flatMap((call) => {
+                        const callee = call.expression;
+                        const name = isPropertyAccessExpression(callee) ? callee.name : callee;
+                        if (fnName === undefined || !isIdentifier(name) || name.text !== fnName) {
+                            return [];
+                        }
+                        const signature = queries.resolvedSignature(call);
+                        const handle = signature === UNANSWERED || signature === undefined
+                            ? undefined
+                            : signature.declaration;
+                        const argument = handle === undefined || project.declarationAt(handle)?.node !== fn
+                            ? undefined
+                            : (call.arguments ?? [])[at];
+                        return argument === undefined || at < 0 ? [] : [argument];
                     });
+                    const named = passed.filter((argument) => isIdentifier(argument));
+                    const reached = passed.some((argument) => isFunctionLike(argument)) ||
+                        queries
+                            .symbolsAt(named)
+                            .some((symbol) => declarationsOf(resolved(symbol)).some((node) => ownFunction(node)));
+                    reachedParameters.set(parameter, reached);
+                    return reached;
+                };
+                /** Whether some function, class or object literal of the target stands for a signature. */
+                const standsFor = (passed) => {
+                    const signature = queries.resolvedSignature(passed.call);
+                    // A callee the checker cannot resolve may be code the target cannot see.
+                    if (signature === UNANSWERED) {
+                        return false;
+                    }
+                    const handle = signature?.declaration;
+                    const declaration = handle === undefined ? undefined : project.declarationAt(handle)?.node;
+                    if (declaration === undefined) {
+                        return true;
+                    }
+                    if (hasBody(declaration) || overloadImplemented(declaration)) {
+                        return own.has(handle?.path ?? "");
+                    }
+                    const holder = declaration.parent;
+                    if (holder !== undefined && implemented.has(holder)) {
+                        return true;
+                    }
+                    const callee = passed.call.expression;
+                    const name = isPropertyAccessExpression(callee) ? callee.name : callee;
+                    const [named] = queries.symbolsAt([name]);
+                    return declarationsOf(resolved(named)).some((node) => isParameterDeclaration(node)
+                        ? own.has(node.getSourceFile().fileName) && parameterReached(node)
+                        : ownFunction(node) && !isFunctionLike(node));
+                };
+                const literals = [];
+                for (const passed of passing) {
+                    if (standsFor(passed)) {
+                        continue;
+                    }
+                    for (const argument of passed.call.arguments ?? []) {
+                        literals.push(...literalsOf(argument).map((literal) => ({ passed, literal })));
+                    }
                 }
-            }
-        }
-    });
-    found.push(...handedOver());
-    return found;
-    /** Whether a type is an object no file of the project declares, a platform object's among them. */
-    function outsideValue(type) {
-        if (!type.isObjectType()) {
-            return false;
-        }
-        const symbol = queries.symbolOfType(type);
-        const declared = symbol === UNANSWERED ? undefined : symbol;
-        return declared?.declarations.every((handle) => !own.has(handle.path)) === true;
-    }
-    /** Whether a type is an object type a file of the project declares. */
-    function ownObject(type) {
-        const known = type === UNANSWERED ? undefined : type;
-        if (!known?.isObjectType()) {
-            return false;
-        }
-        const symbol = queries.symbolOfType(known);
-        const declared = symbol === UNANSWERED ? undefined : symbol;
-        return declared?.declarations.some((handle) => own.has(handle.path)) === true;
-    }
-    /** The reads of every member of each target type an outside value is handed over as. */
-    function handedOver() {
-        const operandTypes = queries.typesAt(asserted.map((one) => one.operand));
-        const fromCasts = asserted.filter((_one, at) => {
-            const type = operandTypes[at];
-            return type !== UNANSWERED && type !== undefined && outsideValue(type);
-        });
-        const newTypes = queries.typesAt(constructed.map((one) => one.call));
-        // A construct signature whose declared result is one of its type parameters names no
-        // type the target declares, so only a result the signature itself names is handed over.
-        const fromConstructors = constructed
-            .filter((one, at) => {
-            if (!ownObject(newTypes[at]) || standsFor(one)) {
-                return false;
-            }
-            const signature = queries.resolvedSignature(one.call);
-            const result = signature === UNANSWERED || signature === undefined
-                ? undefined
-                : queries.returnTypeOf(signature);
-            return result !== UNANSWERED && result !== undefined && !result.isTypeParameter();
-        })
-            .map((one) => ({ file: one.file, from: one.from, node: one.call }));
-        const handed = [...fromCasts, ...fromConstructors];
-        const types = queries.typesAt(handed.map((one) => one.node));
-        const reads = [];
-        handed.forEach((one, at) => {
-            const type = types[at];
-            if (type === UNANSWERED || type === undefined) {
-                return;
-            }
-            const position = renderPosition(one.file, root, one.node.getStart());
-            const parts = queries.constituents(type);
-            for (const part of parts === UNANSWERED ? [type] : parts) {
-                if (!ownObject(part)) {
-                    continue;
+                const contexts = queries.contextualTypes(literals.map((one) => one.literal));
+                literals.forEach(({ passed, literal }, at) => {
+                    const context = contexts[at];
+                    if (context === UNANSWERED) {
+                        found.push({ kind: "held", from: passed.from, names: propertyNames(literal) });
+                        return;
+                    }
+                    if (context === undefined) {
+                        return;
+                    }
+                    const parts = queries.constituents(context);
+                    for (const part of parts === UNANSWERED ? [context] : parts) {
+                        const properties = queries.propertiesOf(part);
+                        if (properties === UNANSWERED) {
+                            found.push({ kind: "held", from: passed.from, names: propertyNames(literal) });
+                            continue;
+                        }
+                        for (const property of properties) {
+                            for (const to of chains.declarationsOf(property)) {
+                                found.push({
+                                    kind: "named",
+                                    from: passed.from,
+                                    to,
+                                    file: passed.file,
+                                    at: literal,
+                                    use: "read",
+                                    via: "contextual",
+                                });
+                            }
+                        }
+                    }
+                });
+                handedOver();
+                return found;
+                /** Whether a type is an object no file of the project declares, a platform object's among them. */
+                function outsideValue(type) {
+                    if (!type.isObjectType()) {
+                        return false;
+                    }
+                    const symbol = queries.symbolOfType(type);
+                    const declared = symbol === UNANSWERED ? undefined : symbol;
+                    return declared?.declarations.every((handle) => !own.has(handle.path)) === true;
                 }
-                const properties = queries.propertiesOf(part);
-                for (const property of properties === UNANSWERED ? [] : properties) {
-                    for (const to of chains.declarationsOf(property)) {
-                        reads.push({
-                            from: one.from,
-                            to,
-                            position,
-                            use: "read",
-                            resolution: "contextual",
-                            test: testFiles.has(position.path),
-                        });
+                /** Whether a type is an object type a file of the project declares. */
+                function ownObject(type) {
+                    const known = type === UNANSWERED ? undefined : type;
+                    if (!known?.isObjectType()) {
+                        return false;
                     }
+                    const symbol = queries.symbolOfType(known);
+                    const declared = symbol === UNANSWERED ? undefined : symbol;
+                    return declared?.declarations.some((handle) => own.has(handle.path)) === true;
                 }
-            }
-        });
-        return reads;
-    }
+                /** The reads of every member of each target type an outside value is handed over as. */
+                function handedOver() {
+                    const operandTypes = queries.typesAt(asserted.map((one) => one.operand));
+                    // An operand the checker cannot type may be an outside value.
+                    const fromCasts = asserted.filter((_one, at) => {
+                        const type = operandTypes[at];
+                        return type === UNANSWERED || (type !== undefined && outsideValue(type));
+                    });
+                    const newTypes = queries.typesAt(constructed.map((one) => one.call));
+                    // A construct signature whose declared result is one of its type parameters names no
+                    // type the target declares, so only a result the signature itself names is handed over.
+                    const fromConstructors = constructed
+                        .filter((one, at) => {
+                        if (!ownObject(newTypes[at]) || standsFor(one)) {
+                            return false;
+                        }
+                        const signature = queries.resolvedSignature(one.call);
+                        const result = signature === UNANSWERED || signature === undefined
+                            ? undefined
+                            : queries.returnTypeOf(signature);
+                        return result !== UNANSWERED && result !== undefined && !result.isTypeParameter();
+                    })
+                        .map((one) => ({ file: one.file, from: one.from, node: one.call }));
+                    const handed = [...fromCasts, ...fromConstructors];
+                    const types = queries.typesAt(handed.map((one) => one.node));
+                    handed.forEach((one, at) => {
+                        const type = types[at];
+                        if (type === UNANSWERED) {
+                            found.push({ kind: "held", from: one.from, members: true });
+                            return;
+                        }
+                        if (type === undefined) {
+                            return;
+                        }
+                        const parts = queries.constituents(type);
+                        for (const part of parts === UNANSWERED ? [type] : parts) {
+                            if (!ownObject(part)) {
+                                continue;
+                            }
+                            const properties = queries.propertiesOf(part);
+                            if (properties === UNANSWERED) {
+                                found.push({ kind: "held", from: one.from, types: [part] });
+                                continue;
+                            }
+                            for (const property of properties) {
+                                for (const to of chains.declarationsOf(property)) {
+                                    found.push({
+                                        kind: "named",
+                                        from: one.from,
+                                        to,
+                                        file: one.file,
+                                        at: one.node,
+                                        use: "read",
+                                        via: "contextual",
+                                    });
+                                }
+                            }
+                        }
+                    });
+                }
+            },
+        };
+    },
+};
+/** The names an object literal's own properties spell. */
+function propertyNames(literal) {
+    return literal.properties.flatMap((property) => nameOf(property) ?? []);
 }

package/dist/src/verbs/analyze.js

@@ -1,8 +1,9 @@
 import { CONTRACT_VERSION, EXIT_CLEAN } from "../contract/contract.generated.js";
-import { runAnalysis, runBaselineWrite, unansweredCounts, } from "../analysis.js";
+import { productionMode, runAnalysis, runBaselineWrite, unansweredCounts, } from "../analysis.js";
 import { kindOf } from "../config.js";
 import { CONFORMANCE, DECLARED_GAPS } from "../conformance.js";
 import { analyzerProvenance, verdictOf } from "../findings-pass.js";
+import { factsDocument } from "../facts.js";
 import { dirnamePath, joinPath, normalizePath, relativePath, resolvePath } from "../paths.js";
 import { moduleIdentity } from "../load/discover.js";
 import { partialNotes } from "../partial.js";
@@ -21,7 +22,7 @@ import { diagnose, message } from "../product.js";
 import { ownVersion } from "./version.js";
 /** The options `analyze` takes beside the ones every verb takes. */
 export const ANALYZE_OPTIONS = {
-    plain: ["report", "baseline-write", "exit-code", "template"],
+    plain: ["report", "facts", "baseline-write", "exit-code", "template"],
     repeatable: ["format"],
 };
 /** The two values `--exit-code` takes; on, the default, puts the run's verdict in the exit code. */
@@ -211,8 +212,13 @@ export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repe
     const { config, provenance } = resolve(inputs());
     const invoked = host.workingDirectory();
     const baseline = option("baseline-write");
+    const facts = option("facts");
+    if (facts === "") {
+        throw new UsageError("--facts names the path the facts document is written to, and named none");
+    }
     const documents = {
         report: resolvePath(invoked, reportPath),
+        facts: facts === undefined ? undefined : resolvePath(invoked, facts),
         formats: formatsOf(repeated("format"), config.reporters.formats),
         baseline: baseline === undefined ? undefined : resolvePath(invoked, baseline),
     };
@@ -222,7 +228,7 @@ export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repe
     const version = ownVersion(host);
     let recorded;
     const root = runRelative(invoked, targetRoot);
-    const mode = { production: true };
+    const mode = productionMode(config);
     let analysis;
     if (documents.baseline === undefined) {
         analysis = runAnalysis(openClient(config), host, scoped, config, provenance, mode);
@@ -281,6 +287,12 @@ export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repe
         throw productFault(`built a report that breaks the report schema at ${refused.pointer || "the document"}: ${refused.keyword}: ${refused.reason}`);
     }
     writeDocument(host, documents.report, "name a path the run can write", () => json(report));
+    const factsPath = documents.facts;
+    if (factsPath !== undefined) {
+        writeDocument(host, factsPath, "name a path the run can write", () => [
+            factsDocument(version, run.generated, run.bindings),
+        ]);
+    }
     const options = {
         readSource: (path) => host.readFile(joinPath(targetRoot, path)),
         template,

package/dist/src/verbs/describe.js

@@ -1,12 +1,13 @@
-import { CONTRACT_VERSION, EXIT_CLEAN, EXIT_USAGE, SCHEMA_VERSIONS, } from "../contract/contract.generated.js";
+import { CONTRACT_VERSION, EXIT_CLEAN, EXIT_USAGE, FACTS_VERSION, SCHEMA_VERSIONS, } from "../contract/contract.generated.js";
 import { CONFORMANCE } from "../conformance.js";
 import {} from "./verb.js";
 import { diagnose, LANGUAGE, PRODUCT } from "../product.js";
 import { ownVersion } from "./version.js";
 /**
  * The document `describe` writes: the analyzer, the Contract version it implements, the
- * report schema versions it reads, the languages it claims, and its recorded result over
- * the conformance corpus, a member the document omits where no run is recorded.
+ * report schema versions it reads, the languages it claims, the facts version it writes,
+ * and its recorded result over the conformance corpus, a member the document omits where
+ * no run is recorded.
  */
 export function describeDocument(version, recorded) {
     const document = {
@@ -15,6 +16,7 @@ export function describeDocument(version, recorded) {
         contract_version: CONTRACT_VERSION,
         schema_versions_accepted: SCHEMA_VERSIONS,
         languages: [LANGUAGE],
+        facts_version_written: FACTS_VERSION,
         ...(recorded === undefined
             ? {}
             : {