@ttsc/evidence 0.25.0 → 0.26.0

package/README.md

@@ -27,19 +27,31 @@ error TS16411: [evidence/graph] Missing acknowledgement for 'docs/discount.md#co
   (Markdown H2 'Coupon Stacking' at docs/discount.md:3)
   in Claim 1 reference 1 (markdown, symbols: h2, h3).
 
-  Use @evidence on a selected typescript host or @evidenceExclude on an eligible carrier.
+  Cite the artifact that answers for this unit with @evidence on a selected
+  typescript host, building that artifact first when none does, or write
+  @evidenceExclude on an eligible carrier when nothing here owes it. Never
+  leave an untrue tag standing just to pass this check; it removes the error,
+  not the problem.
 
 error TS16411: [evidence/graph] Missing acknowledgement for 'POST:/orders/{orderId}/coupons'
   (Swagger operation 'POST /orders/{orderId}/coupons' at api/openapi.json)
   in Claim 1 reference 2 (swagger operations).
 
-  Use @evidence on a selected typescript host or @evidenceExclude on an eligible carrier.
+  Cite the artifact that answers for this unit with @evidence on a selected
+  typescript host, building that artifact first when none does, or write
+  @evidenceExclude on an eligible carrier when nothing here owes it. Never
+  leave an untrue tag standing just to pass this check; it removes the error,
+  not the problem.
 
 error TS16411: [evidence/graph] Missing acknowledgement for 'useCouponStacking'
   (TypeScript function 'useCouponStacking' at src/lib/coupons/hooks.ts:12)
   in Claim 1 reference 3 (typescript, symbols: function).
 
-  Use @evidence on a selected typescript host or @evidenceExclude on an eligible carrier.
+  Cite the artifact that answers for this unit with @evidence on a selected
+  typescript host, building that artifact first when none does, or write
+  @evidenceExclude on an eligible carrier when nothing here owes it. Never
+  leave an untrue tag standing just to pass this check; it removes the error,
+  not the problem.
 
 Found 3 errors.
 ```
@@ -96,9 +108,10 @@ One sentence: the components under `src` implement the docs, so every H2 and H3
 | Rule | Takes | What it does |
 | --- | --- | --- |
 | `evidence/graph` | [`ITtscEvidenceGraphConfig`](https://github.com/samchon/ttsc/blob/master/packages/evidence/src/structures/ITtscEvidenceGraphConfig.ts) | The graph itself. Project-scoped, so its entry declares no `files`. |
-| `evidence/documented` | nothing | Requires a JSDoc block on every selected export, since a block is the only place a citation can live. |
+| `evidence/documented` | [`ITtscEvidenceDocumentedConfig`](https://github.com/samchon/ttsc/blob/master/packages/evidence/src/structures/ITtscEvidenceDocumentedConfig.ts) | Requires a JSDoc block on every selected export, since a block is the only place a citation can live. Members count, so a class field, a method, a parameter property, and an interface member each need their own. `symbol` narrows the kinds; it defaults to all three. |
 | `evidence/singular` | nothing | Keeps one public identity per file, named after the file. |
 | `evidence/todo` | nothing | Fails on every remaining JSDoc `@todo`, with its own text. |
+| `evidence/review` | nothing | Requires an `@evidenceReview` beside every `@evidence` and an `@evidenceExcludeReview` beside every `@evidenceExclude`, naming the same target and stating what was checked. |
 
 Each takes `"error"`, `"warning"`, or `"off"`.
 
@@ -214,7 +227,11 @@ A unit is addressed the way a consumer reaches it, so `export * as functional` n
 | TypeScript | `type`, `function`, `property` | all three | `type` |
 | Swagger | none, every operation is selected | not applicable | every operation |
 
-Units keep their hierarchy, so a target acknowledges itself and every selected descendant: citing a heading covers its subsections, an interface covers its properties, and `prisma:Sale` covers the columns beneath it. An ancestor stays addressable even when its own kind is not selected.
+Units keep their hierarchy, so a target acknowledges itself and every selected descendant: citing a heading covers its subsections, an interface or a class covers the members it declares, and `prisma:Sale` covers the columns beneath it. An ancestor stays addressable even when its own kind is not selected.
+
+A class is a `type`, its methods are `function`, and its fields are `property`. A member written as a callable joins the methods instead: `handler = () => {}` and `charge: () => void` are both `function`. An interface and an object-shaped type alias are classified by the same rule, so `run(): void` on either is a `function` just as a class method is, and an overload run is one unit. The test is on how the member is written, not on what its type resolves to, because this rule reads no type checker, so `charge: Handler` stays a `property` even where `Handler` is an alias of `() => void`.
+
+A class member that is `private` or `protected` materializes no unit, whichever syntax declared it. A constructor parameter carrying any property modifier declares a field, and it classifies exactly as the same field written in the class body would, so a `private` or `protected` one materializes nothing just as the body form does not. The property modifiers are TypeScript's own five: `public`, `protected`, `private`, `readonly`, and `override`. The last is the one to know about, because its meaning is about the base class rather than about the field, so it does not read as a field declaration. On a class extending one that declares `rate`, `constructor(override rate: number)` is a public instance field and a selected `property` unit.
 
 A declaration whose documentation carries `@internal`, `@hidden`, or `@ignore` leaves the population entirely. It owes nothing and can carry nothing, and citing one is reported rather than silently ignored.
 
@@ -243,7 +260,7 @@ It is the only acknowledgement that settles an obligation without anything being
 
 ### Strict references
 
-Ordinary coverage is permissive, which is right for a document several modules honor and too weak for a proof obligation, where one exclusion or one host citing everything discharges the whole population. Three properties tighten a single reference, and they never pool across references.
+Ordinary coverage is permissive, which is right for a document several modules honor and too weak for a proof obligation, where one exclusion or one host citing everything discharges the whole population. Four properties tighten a single reference, and they never pool across references.
 
 ```ts
 {
@@ -259,6 +276,7 @@ Ordinary coverage is permissive, which is right for a document several modules h
 - `noEvidenceExclude` refuses exclusions, so the target still owes positive evidence. A published accessor no hook consumes is an omission rather than a decision.
 - `uniqueEvidence` allows at most one host per unit, so one host is answerable for it rather than several.
 - `singleEvidencePerSymbol` requires exactly one unit from every selected host, so a host citing nothing and a host citing everything both fail.
+- `requireReview` makes every acknowledgement owe a matching review carrying a fingerprint of the cited content, so the review fails again once that content changes. A citation is answered by `@evidenceReview` and an exclusion by `@evidenceExcludeReview`; neither answers the other. Every reference kind accepts it, because each bridge digests a unit's content where that content is understood.
 
 Counting is by identity rather than by text. Repeated tags for one unit count once, an overload set stays one host, and citing a parent of two selected units counts as two.
 

package/lib/index.d.ts

@@ -8,7 +8,7 @@ export * from "./typings/index";
  * {@link ITtscEvidenceGraphConfig} that describes which documents and TypeScript
  * symbols must remain connected.
  *
- * The plugin contributes four rules, enabled independently.
+ * The plugin contributes five rules, enabled independently.
  *
  * - `"evidence/graph"` — the configured evidence graph. Every declaration target
  *   must resolve, and every selected evidence unit must be acknowledged. Takes
@@ -24,6 +24,11 @@ export * from "./typings/index";
  *   file, exported or not. Each tag is an unrealized contract reported with its
  *   own text, so the diagnostics read as the ledger of what remains to realize.
  *   Takes no options, so it carries a bare severity.
+ * - `"evidence/review"` — an `@evidenceReview` beside every `@evidence` and an
+ *   `@evidenceExcludeReview` beside every `@evidenceExclude`, naming the same
+ *   target. The citation states why this declaration answers for a target; the
+ *   review states what was verified, which is a different question nothing else
+ *   asks. Takes no options, so it carries a bare severity.
  *
  * @example <caption>Configure the plugin in `lint.config.ts`</caption>
  *   import { type ITtscEvidenceGraphConfig, evidence } from "@ttsc/evidence";
@@ -59,7 +64,7 @@ export declare const evidence: {
         readonly namespace: "evidence";
         readonly version: string;
     };
-    rules: readonly ["graph", "singular", "documented", "todo"];
+    rules: readonly ["graph", "singular", "documented", "todo", "review"];
     source: string;
 };
 export default evidence;

package/lib/index.js

@@ -30,7 +30,7 @@ __exportStar(require("./typings/index"), exports);
  * {@link ITtscEvidenceGraphConfig} that describes which documents and TypeScript
  * symbols must remain connected.
  *
- * The plugin contributes four rules, enabled independently.
+ * The plugin contributes five rules, enabled independently.
  *
  * - `"evidence/graph"` — the configured evidence graph. Every declaration target
  *   must resolve, and every selected evidence unit must be acknowledged. Takes
@@ -46,6 +46,11 @@ __exportStar(require("./typings/index"), exports);
  *   file, exported or not. Each tag is an unrealized contract reported with its
  *   own text, so the diagnostics read as the ledger of what remains to realize.
  *   Takes no options, so it carries a bare severity.
+ * - `"evidence/review"` — an `@evidenceReview` beside every `@evidence` and an
+ *   `@evidenceExcludeReview` beside every `@evidenceExclude`, naming the same
+ *   target. The citation states why this declaration answers for a target; the
+ *   review states what was verified, which is a different question nothing else
+ *   asks. Takes no options, so it carries a bare severity.
  *
  * @example <caption>Configure the plugin in `lint.config.ts`</caption>
  *   import { type ITtscEvidenceGraphConfig, evidence } from "@ttsc/evidence";
@@ -81,7 +86,7 @@ exports.evidence = {
         namespace: "evidence",
         version: package_json_1.version,
     },
-    rules: ["graph", "singular", "documented", "todo"],
+    rules: ["graph", "singular", "documented", "todo", "review"],
     source: node_path_1.default.resolve(__dirname, "..", "native"),
 };
 exports.default = exports.evidence;

package/lib/internal/canonicalDigest.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/internal/canonicalDigest.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withoutKeys = exports.canonicalJson = exports.canonicalDigest = void 0;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Digests one parsed declaration under a serialization that does not depend on
+ * how it was written.
+ *
+ * A review fingerprint answers whether the thing a reviewer read has changed,
+ * so two inputs that describe the same declaration have to produce one value.
+ * `JSON.stringify` emits keys in insertion order, and insertion order here is a
+ * function of the input dialect and of a converter's internals: a Swagger 2.0
+ * document and an OpenAPI 3.1 document that normalize to the same operation
+ * would otherwise hash differently, and a converter change would expire every
+ * review in a project.
+ *
+ * Object keys are therefore sorted and arrays are not, because an array's order
+ * is part of what it says: OpenAPI parameter order and `required` membership
+ * are both arrays, and reordering the second is a real edit a reviewer must
+ * see. Sorting them would hide it.
+ *
+ * `undefined` is dropped from objects and rendered as `null` inside arrays,
+ * which is what `JSON.stringify` does, so an absent property and a present one
+ * holding `undefined` cannot be told apart. That is the same thing to every
+ * consumer downstream of the parser.
+ *
+ * @internal
+ */
+const canonicalDigest = (value) => (0, node_crypto_1.createHash)("sha256").update((0, exports.canonicalJson)(value)).digest("hex");
+exports.canonicalDigest = canonicalDigest;
+/**
+ * Renders a parsed value with object keys in sorted order and no incidental
+ * whitespace.
+ *
+ * @internal
+ */
+const canonicalJson = (value) => render(value, new Set());
+exports.canonicalJson = canonicalJson;
+/**
+ * Renders one value, refusing to descend into a container already on the path
+ * above it.
+ *
+ * A source document can be cyclic: a YAML anchor referring to its own parent
+ * loads, upgrades, and would then recurse until the stack ends. The failure
+ * that produced was a diagnostic blaming an upgrade that had succeeded, so the
+ * cycle is answered here with a marker instead. Two documents that differ only
+ * in where a cycle closes still differ, because the marker is emitted at the
+ * position the cycle closes at.
+ */
+const render = (value, seen) => {
+    if (value === null || typeof value !== "object")
+        return stringify(value);
+    if (seen.has(value))
+        return '"[circular]"';
+    seen.add(value);
+    try {
+        if (Array.isArray(value))
+            return `[${value.map((element) => render(element ?? null, seen)).join(",")}]`;
+        const entries = Object.entries(value).filter(([, element]) => element !== undefined);
+        entries.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+        return `{${entries
+            .map(([key, element]) => `${JSON.stringify(key)}:${render(element, seen)}`)
+            .join(",")}}`;
+    }
+    finally {
+        seen.delete(value);
+    }
+};
+const stringify = (value) => {
+    const rendered = JSON.stringify(value);
+    return rendered ?? "null";
+};
+/**
+ * Drops named properties from a parsed declaration before it is digested.
+ *
+ * Documentation is the reason this exists, and a container of units is the
+ * other: a model's fields are units of their own, so hashing them into the
+ * model would make one field's edit expire a review of every sibling.
+ *
+ * A review of a declaration is written in that declaration's own comment, so a
+ * digest covering the comment moves the moment the review is written and the
+ * review is stale before the next build reads it. That is the non-terminating
+ * repair loop the whole feature exists to avoid, and it is why the one content
+ * field the Prisma payload carries in full is the one field that must not be
+ * hashed.
+ *
+ * @internal
+ */
+const withoutKeys = (value, ...keys) => {
+    const copy = {
+        ...value,
+    };
+    for (const key of keys)
+        delete copy[key];
+    return copy;
+};
+exports.withoutKeys = withoutKeys;

package/lib/internal/loadPrismaModels.js

@@ -8,6 +8,7 @@ const node_crypto_1 = require("node:crypto");
 const promises_1 = __importDefault(require("node:fs/promises"));
 const node_module_1 = require("node:module");
 const node_path_1 = __importDefault(require("node:path"));
+const canonicalDigest_1 = require("./canonicalDigest");
 const MAX_SCHEMA_BYTES = 16 * 1024 * 1024;
 const ANSI_PATTERN = /\x1b\[[0-9;]*m/gu;
 /**
@@ -30,8 +31,9 @@ const SEPARATOR = "\u0000";
  *
  * The native contributor is Go and Prisma's parser is a WebAssembly module with
  * a JavaScript entry point. This function is the narrow process boundary
- * between them: it accepts only file locations and returns only model, column,
- * and relation identities with their doc comments.
+ * between them: it accepts only file locations and returns model, column, and
+ * relation identities with their doc comments and a digest of each
+ * declaration's content.
  *
  * One **set** is one request. A Prisma schema folder is several files that form
  * a single namespace — a model in one file may point at a model in another — so
@@ -156,6 +158,10 @@ const modelsOf = (parser, files) => {
         models.push({
             name: model.name,
             documentation: typeof model.documentation === "string" ? model.documentation : "",
+            // The model's own declaration is everything the parser reports about it
+            // except its fields, which are units in their own right, and except its
+            // documentation, which is where a review of it is written.
+            digest: (0, canonicalDigest_1.canonicalDigest)((0, canonicalDigest_1.withoutKeys)(model, "documentation", "fields")),
             fields: (model.fields ?? [])
                 .filter((field) => typeof field.name === "string" && field.name.length !== 0)
                 .map((field) => ({
@@ -166,6 +172,7 @@ const modelsOf = (parser, files) => {
                 // rather than for `scalar`.
                 symbol: field.kind === "object" ? "relation" : "column",
                 documentation: typeof field.documentation === "string" ? field.documentation : "",
+                digest: (0, canonicalDigest_1.canonicalDigest)((0, canonicalDigest_1.withoutKeys)(field, "documentation")),
             })),
         });
     }

package/lib/internal/loadSwaggerOperations.js

@@ -8,6 +8,7 @@ const node_crypto_1 = require("node:crypto");
 const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
 const yaml_1 = require("yaml");
+const canonicalDigest_1 = require("./canonicalDigest");
 const normalizeSwaggerDocument_1 = require("./normalizeSwaggerDocument");
 const MAX_DOCUMENT_BYTES = 16 * 1024 * 1024;
 const REMOTE_TIMEOUT_MILLISECONDS = 30_000;
@@ -27,7 +28,9 @@ const METHODS = [
  *
  * The native contributor is Go, while the version converter is JavaScript. This
  * function is the narrow process boundary between them: it accepts only source
- * locations and returns only operation identities.
+ * locations and returns operation identities, each carrying a digest of the
+ * operation's content taken here because this is the only side that sees the
+ * document.
  *
  * @internal
  */
@@ -117,14 +120,16 @@ const readRemoteSource = async (source) => {
 const decodeUtf8 = (content) => new TextDecoder("utf-8", { fatal: true }).decode(content);
 const operationsOf = (document) => {
     const operations = [];
+    const components = (document.components ??
+        {});
     for (const [operationPath, item] of Object.entries(document.paths ?? {})) {
         for (const method of METHODS) {
             const operation = item[method];
             if (operation !== undefined)
-                operations.push(operationOf(method, operationPath));
+                operations.push(operationOf(method, operationPath, operation, components));
         }
-        for (const method of Object.keys(item.additionalOperations ?? {}))
-            operations.push(operationOf(method, operationPath));
+        for (const [method, operation] of Object.entries(item.additionalOperations ?? {}))
+            operations.push(operationOf(method, operationPath, operation, components));
     }
     operations.sort((left, right) => {
         const leftTarget = `${left.method}:${left.path}`;
@@ -140,7 +145,7 @@ const operationsOf = (document) => {
     }
     return operations;
 };
-const operationOf = (method, operationPath) => {
+const operationOf = (method, operationPath, operation, components) => {
     if (!operationPath.startsWith("/"))
         throw new Error(`OpenAPI path '${operationPath}' must start with '/' to form an operation target`);
     if (/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/u.test(method) === false ||
@@ -149,8 +154,94 @@ const operationOf = (method, operationPath) => {
     return {
         method: method.toUpperCase(),
         path: operationPath,
+        digest: (0, canonicalDigest_1.canonicalDigest)(withResolvedReferences(operation, components)),
     };
 };
+/**
+ * Replaces every local `$ref` into `components` with what it names.
+ *
+ * The converter preserves references rather than inlining them, so an operation
+ * is often no more than `{"$ref": "#/components/schemas/IMember"}` where its
+ * request and response bodies should be. A digest over the operation as written
+ * therefore covers the name of a contract and not the contract, and changing
+ * every property of a DTO expires no review of the endpoint that carries it.
+ * That is the failure this feature exists to remove, on the artifact kind whose
+ * whole content lives behind a reference.
+ *
+ * Any pointer under `#/components/` is followed, not only one into `schemas`,
+ * because a request body, a response, a parameter, and a header are all
+ * declarable there and each is part of the operation a reviewer read. A pointer
+ * anywhere else is left as written: `#/paths/...` would fold one operation's
+ * content into another's and reintroduce the cross-expiry this replaces.
+ *
+ * Siblings of a `$ref` are kept and override what it resolves to, which is what
+ * OpenAPI 3.1 says they do. A reference already open on the path above is left
+ * as written, so a recursive schema terminates while two operations reaching
+ * one cycle by different routes still differ. An undeclared reference is left
+ * as written too: a broken document is not a digest question, and inventing an
+ * empty schema for it would make two different broken documents agree.
+ */
+const withResolvedReferences = (value, components, open = new Set()) => {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map((element) => withResolvedReferences(element, components, open));
+    const entries = Object.entries(value);
+    const reference = value["$ref"];
+    if (typeof reference !== "string" || open.has(reference))
+        return Object.fromEntries(entries.map(([key, element]) => [
+            key,
+            withResolvedReferences(element, components, open),
+        ]));
+    const target = componentAt(components, reference);
+    if (target === undefined)
+        return Object.fromEntries(entries.map(([key, element]) => [
+            key,
+            withResolvedReferences(element, components, open),
+        ]));
+    open.add(reference);
+    try {
+        const resolved = withResolvedReferences(target, components, open);
+        const siblings = entries
+            .filter(([key]) => key !== "$ref")
+            .map(([key, element]) => [
+            key,
+            withResolvedReferences(element, components, open),
+        ]);
+        if (siblings.length === 0)
+            return resolved;
+        if (resolved === null || typeof resolved !== "object")
+            return Object.fromEntries(siblings);
+        return {
+            ...resolved,
+            ...Object.fromEntries(siblings),
+        };
+    }
+    finally {
+        open.delete(reference);
+    }
+};
+const COMPONENT_REFERENCE_PREFIX = "#/components/";
+/** Reads one `#/components/<section>/<name>` pointer, or nothing. */
+const componentAt = (components, reference) => {
+    if (!reference.startsWith(COMPONENT_REFERENCE_PREFIX))
+        return undefined;
+    const segments = reference
+        .slice(COMPONENT_REFERENCE_PREFIX.length)
+        .split("/")
+        .map((segment) => decodeURIComponent(segment).replaceAll("~1", "/").replaceAll("~0", "~"));
+    let current = components;
+    for (const segment of segments) {
+        if (current === null ||
+            typeof current !== "object" ||
+            Array.isArray(current))
+            return undefined;
+        if (!(segment in current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+};
 const isInventory = (value) => "operations" in value;
 const isProblem = (value) => "message" in value;
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);

package/lib/structures/ITtscEvidenceGraphReferenceBase.d.ts

@@ -70,4 +70,52 @@ export interface ITtscEvidenceGraphReferenceBase<Type extends string> {
      * @default false
      */
     singleEvidencePerSymbol?: boolean;
+    /**
+     * Whether every acknowledgement of this population must carry a reviewed,
+     * unexpired review of its own kind.
+     *
+     * The reason on a citation says why this declaration answers for a target.
+     * Nothing asks what was actually checked, so an unverified citation and a
+     * verified one are byte-identical in the source. This asks, and it makes the
+     * answer expire: the review carries a `#`-prefixed fingerprint of the cited
+     * scope's content, and when that content changes the fingerprint stops
+     * matching and the build fails again with the new value in the diagnostic.
+     *
+     * Expiry is the point. Without it a review is written once and stays green
+     * forever, and on a second pass over a large citation set there is no way to
+     * tell which reviews were written against content that has since moved.
+     *
+     * What this proves is narrow and worth stating plainly. It proves a
+     * separately addressed statement exists and was written against the cited
+     * content as it now stands. It does not prove anyone read that content,
+     * because the diagnostic states the expected fingerprint, and it does not
+     * judge whether the prose is sincere.
+     *
+     * The fingerprint covers the cited unit and its structural subtree, so it is
+     * a property of the address a citation names rather than of the reference
+     * that demanded it. One tag therefore carries one fingerprint no matter how
+     * many references it acknowledges.
+     *
+     * Expect a citation of a TypeScript symbol to expire on any change inside
+     * that declaration, including one behind a withdrawal tag. A declaration's
+     * digest is its own text and a nested member sits inside it, so the subtree
+     * cannot be carved out the way a Markdown section's subsections can. Cite the
+     * narrowest symbol that actually answers for the requirement if that breadth
+     * is unwelcome.
+     *
+     * The withdrawal tags are named in the tag guide rather than here, on
+     * purpose: `stripInternal` is on for this package, so writing one of them
+     * inside a published doc comment deletes the property it documents from the
+     * emitted declarations. That is how this very property went missing once.
+     *
+     * Every reference kind accepts this. A Swagger or Prisma reference used to be
+     * refused at decode, because those loaders reported unit identities and
+     * nothing else; each bridge now digests a unit's content on the side that
+     * understands it, which for an operation is its normalized definition and for
+     * a Prisma model or member is its parsed declaration without the
+     * documentation comment a review of it is written in.
+     *
+     * @default false
+     */
+    requireReview?: boolean;
 }

package/lib/structures/ITtscEvidenceGraphTypeScriptClaim.d.ts

@@ -5,9 +5,9 @@ import type { ITtscEvidenceGraphClaimBase } from "./ITtscEvidenceGraphClaimBase"
  *
  * JSDoc puts an evidence edge on the public declaration making the claim,
  * rather than on the file around it. Supported hosts are exported interfaces,
- * type aliases, namespaces, functions, data variables, type properties, and the
- * public class callable forms documented by
- * {@link TtscEvidenceGraphTypeScriptSymbol}.
+ * type aliases, classes, namespaces, functions, data variables, and every
+ * public member an interface, an object-shaped type alias, or a class declares,
+ * in each of the forms documented by {@link TtscEvidenceGraphTypeScriptSymbol}.
  *
  * Both `@evidence <target> <reason>` and `@evidenceExclude <target> <reason>`
  * require a target and a non-empty explanation. Ownership evidence must sit on

package/lib/structures/ITtscEvidenceGraphTypeScriptReference.d.ts

@@ -65,10 +65,10 @@ export interface ITtscEvidenceGraphTypeScriptReference extends ITtscEvidenceGrap
     /**
      * Symbol kind or kinds eligible to become evidence units.
      *
-     * Omit this property to select exported interfaces, type aliases, and
-     * namespaces. A single value selects one obligation kind; a non-empty array
-     * selects the union. Selected units remain independent obligations until an
-     * ancestor type or namespace target acknowledges their shared scope.
+     * Omit this property to select exported interfaces, type aliases, classes,
+     * and namespaces. A single value selects one obligation kind; a non-empty
+     * array selects the union. Selected units remain independent obligations
+     * until an ancestor type or namespace target acknowledges their shared scope.
      * Ancestors of selected units are addressable even when their own kind is
      * omitted from this selector.
      *

package/lib/typings/ITtscLintContributorRules.d.ts

@@ -30,5 +30,28 @@ declare module "@ttsc/lint" {
          * `files` setting of `lint.config.ts`.
          */
         "evidence/todo"?: TtscLintRuleSetting;
+        /**
+         * Requires a review beside every acknowledgement.
+         *
+         * Every `@evidence` and `@evidenceExclude` on a public identity must be
+         * answered by an `@evidenceReview` naming the same target. The citation
+         * states why this declaration answers for that target; the review states
+         * what was verified. Those are different questions, and only the first one
+         * is written unless something asks for the second.
+         *
+         * A review is an annotation of a citation, never an acknowledgement of a
+         * unit. It discharges no coverage, contributes no host to `uniqueEvidence`,
+         * and counts toward no `singleEvidencePerSymbol` total, so enabling this
+         * rule cannot change a single `evidence/graph` diagnostic.
+         *
+         * The optional `#`-prefixed fingerprint token is carried without being
+         * interpreted here. `evidence/graph` validates it against the cited content
+         * under a reference's `requireReview`, which is what makes a review expire
+         * when the thing it reviewed moves.
+         *
+         * The rule takes no options; per-directory scoping belongs in the outer
+         * `files` setting of `lint.config.ts`.
+         */
+        "evidence/review"?: TtscLintRuleSetting;
     }
 }