@ttsc/evidence 0.25.0

package/lib/internal/loadSwaggerOperations.js

@@ -0,0 +1,156 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSwaggerOperations = void 0;
+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 normalizeSwaggerDocument_1 = require("./normalizeSwaggerDocument");
+const MAX_DOCUMENT_BYTES = 16 * 1024 * 1024;
+const REMOTE_TIMEOUT_MILLISECONDS = 30_000;
+const METHODS = [
+    "get",
+    "post",
+    "put",
+    "delete",
+    "options",
+    "head",
+    "patch",
+    "trace",
+    "query",
+];
+/**
+ * Loads and normalizes every configured Swagger source for the native rule.
+ *
+ * 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.
+ *
+ * @internal
+ */
+const loadSwaggerOperations = async (request) => {
+    const loaded = await Promise.all(request.sources.map(async (source) => {
+        let digest = "";
+        try {
+            const read = await readSource(request.root, source);
+            digest = read.digest;
+            const input = (0, yaml_1.parse)(read.text);
+            const document = (0, normalizeSwaggerDocument_1.normalizeSwaggerDocument)(input);
+            return {
+                source,
+                operations: operationsOf(document),
+                digest,
+            };
+        }
+        catch (error) {
+            return {
+                source,
+                message: errorMessage(error),
+                digest,
+            };
+        }
+    }));
+    return {
+        documents: loaded.filter(isInventory),
+        problems: loaded.filter(isProblem),
+    };
+};
+exports.loadSwaggerOperations = loadSwaggerOperations;
+const readSource = async (root, source) => {
+    if (source.startsWith("http://") || source.startsWith("https://"))
+        return { text: await readRemoteSource(source), digest: "" };
+    if (source.includes("://"))
+        throw new Error("only http: and https: URLs are supported");
+    // A local document may sit anywhere on the filesystem, including above the
+    // project or on an absolute path. The native decoder is what validates the
+    // spelling; this side only has to resolve it the same way, which
+    // `path.resolve` already does for both forms.
+    const location = node_path_1.default.resolve(root, source);
+    const stat = await promises_1.default.stat(location);
+    if (!stat.isFile())
+        throw new Error("the local Swagger source is not a file");
+    if (stat.size > MAX_DOCUMENT_BYTES)
+        throw new Error(`the Swagger document exceeds the ${MAX_DOCUMENT_BYTES} byte limit`);
+    // Hashed before decoding, over the bytes as they were read. The native side
+    // hashes the file's bytes too, so the two agree by construction; hashing the
+    // decoded string instead would agree only for inputs where the round trip
+    // happens to be exact.
+    const content = await promises_1.default.readFile(location);
+    return {
+        text: decodeUtf8(content),
+        digest: (0, node_crypto_1.createHash)("sha256").update(content).digest("hex"),
+    };
+};
+const readRemoteSource = async (source) => {
+    const response = await fetch(source, {
+        signal: AbortSignal.timeout(REMOTE_TIMEOUT_MILLISECONDS),
+    });
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status} ${response.statusText || "response"}`);
+    if (response.body === null)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    while (true) {
+        const next = await reader.read();
+        if (next.done)
+            break;
+        length += next.value.byteLength;
+        if (length > MAX_DOCUMENT_BYTES) {
+            await reader.cancel();
+            throw new Error(`the Swagger document exceeds the ${MAX_DOCUMENT_BYTES} byte limit`);
+        }
+        chunks.push(next.value);
+    }
+    const content = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        content.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return decodeUtf8(content);
+};
+const decodeUtf8 = (content) => new TextDecoder("utf-8", { fatal: true }).decode(content);
+const operationsOf = (document) => {
+    const operations = [];
+    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));
+        }
+        for (const method of Object.keys(item.additionalOperations ?? {}))
+            operations.push(operationOf(method, operationPath));
+    }
+    operations.sort((left, right) => {
+        const leftTarget = `${left.method}:${left.path}`;
+        const rightTarget = `${right.method}:${right.path}`;
+        return leftTarget.localeCompare(rightTarget);
+    });
+    for (let index = 1; index < operations.length; index++) {
+        const previous = operations[index - 1];
+        const current = operations[index];
+        if (`${previous.method}:${previous.path}` ===
+            `${current.method}:${current.path}`)
+            throw new Error(`OpenAPI operation '${current.method} ${current.path}' is declared more than once`);
+    }
+    return operations;
+};
+const operationOf = (method, operationPath) => {
+    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 ||
+        method.includes(":"))
+        throw new Error(`OpenAPI method '${method}' cannot form a '<METHOD>:<path>' target`);
+    return {
+        method: method.toUpperCase(),
+        path: operationPath,
+    };
+};
+const isInventory = (value) => "operations" in value;
+const isProblem = (value) => "message" in value;
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);

package/lib/internal/normalizeSwaggerDocument.d.ts

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

package/lib/internal/normalizeSwaggerDocument.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeSwaggerDocument = void 0;
+const utils_1 = require("@typia/utils");
+/** @internal */
+const normalizeSwaggerDocument = (input) => utils_1.OpenApiConverter.upgradeDocument(input);
+exports.normalizeSwaggerDocument = normalizeSwaggerDocument;

package/lib/structures/ITtscEvidenceDocumentedConfig.d.ts

@@ -0,0 +1,32 @@
+import type { TtscEvidenceGraphTypeScriptSymbol } from "../typings/TtscEvidenceGraphTypeScriptSymbol";
+/**
+ * Options of the `evidence/documented` rule.
+ *
+ * The rule requires a JSDoc block on every selected export, because a JSDoc
+ * block is the only place an `@evidence` tag is ever read from. A symbol
+ * without one cannot cite anything: the citation has no location to live in,
+ * and the graph's obligation silently shifts onto whichever sibling does have a
+ * block.
+ *
+ * Presence is the whole check. The rule never judges what the prose says, how
+ * long it is, or whether it is sincere — a rule that tried would only teach
+ * authors to write filler that satisfies it.
+ */
+export interface ITtscEvidenceDocumentedConfig {
+    /**
+     * Symbol kind or kinds that must carry a JSDoc block.
+     *
+     * Omit this property to select every kind a claim can use as a declaration
+     * host. That default is deliberate: the population which must be able to hold
+     * a tag is exactly the population a claim can select as a host, so a narrower
+     * default would leave some potential host unable to cite while the rule
+     * reported success.
+     *
+     * A single value selects one kind; a non-empty array selects the union. The
+     * exact declaration forms behind each kind are documented by
+     * {@link TtscEvidenceGraphTypeScriptSymbol}.
+     *
+     * @default ["type", "function", "property"]
+     */
+    symbol?: TtscEvidenceGraphTypeScriptSymbol | TtscEvidenceGraphTypeScriptSymbol[];
+}

package/lib/structures/ITtscEvidenceDocumentedConfig.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/structures/ITtscEvidenceGraphClaim.d.ts

@@ -0,0 +1,14 @@
+import type { ITtscEvidenceGraphMarkdownClaim } from "./ITtscEvidenceGraphMarkdownClaim";
+import type { ITtscEvidenceGraphPrismaClaim } from "./ITtscEvidenceGraphPrismaClaim";
+import type { ITtscEvidenceGraphTypeScriptClaim } from "./ITtscEvidenceGraphTypeScriptClaim";
+/**
+ * One population of artifacts asserting that it implements, verifies, or
+ * documents its referenced evidence.
+ *
+ * A claim owns the outgoing side of every evidence edge it declares: its files
+ * host the `@evidence` citations, and each referenced evidence population must
+ * be acknowledged completely. Separate claims remain separate obligations,
+ * preventing two teams' partial use of the same evidence from being reported as
+ * one complete use.
+ */
+export type ITtscEvidenceGraphClaim = ITtscEvidenceGraphMarkdownClaim | ITtscEvidenceGraphPrismaClaim | ITtscEvidenceGraphTypeScriptClaim;

package/lib/structures/ITtscEvidenceGraphClaim.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/structures/ITtscEvidenceGraphClaimBase.d.ts

@@ -0,0 +1,102 @@
+import type { ITtscEvidenceGraphReference } from "./ITtscEvidenceGraphReference";
+/**
+ * What every claim declares: which artifact kind makes the claim, where its
+ * population lives, and which evidence it must cite completely.
+ *
+ * A claim owns the outgoing side of every evidence edge it declares. The
+ * properties here are the ones that mean the same thing in Markdown, Prisma,
+ * and TypeScript; only the symbol selector differs, because its eligible host
+ * kinds are a property of the language rather than of the claim.
+ *
+ * Swagger is deliberately absent. An API operation grounds a claim but cannot
+ * host `@evidence`, so it extends {@link ITtscEvidenceGraphReferenceBase}
+ * instead and never this one.
+ */
+export interface ITtscEvidenceGraphClaimBase<Type extends string> {
+    /** Identifies the artifact kind making this claim. */
+    type: Type;
+    /**
+     * Optional human-readable label shown with diagnostics for this claim. It
+     * does not identify evidence nodes or establish relationships between
+     * configuration entries.
+     */
+    name?: string;
+    /**
+     * Excludes this claim from graph loading and evaluation.
+     *
+     * The configuration shape is still validated, but this claim contributes no
+     * populations, references, coverage obligations, completion hints, or watched
+     * inputs. Omit this property or set it to `false` to enable the claim.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Directory this claim's {@link files} patterns resolve against.
+     *
+     * Omit this property to resolve against the active `ttsc` project root, which
+     * is where every population resolved before this property existed.
+     *
+     * The value names one directory, never a glob. It may sit inside the project,
+     * above it (`../../docs`), or on an absolute path. A drive-relative Windows
+     * path such as `C:docs` is refused, because it resolves against whatever
+     * directory that drive currently sits on rather than against a stable base.
+     *
+     * Diagnostics name the resolved base, and the resolved patterns are published
+     * to the `ttsc` host as watched inputs.
+     */
+    root?: string;
+    /**
+     * Glob patterns for the files that must cite the referenced evidence,
+     * resolved against {@link root} or against the project root when none is
+     * declared.
+     *
+     * These are globs, not regular expressions. `*` matches within one path
+     * segment, `**` crosses any number of path segments, and `?` matches one
+     * character. Both `/` and `\` are accepted as separators, while path identity
+     * remains case-sensitive on every operating system.
+     *
+     * Patterns are evaluated from left to right. A pattern prefixed with `!`
+     * removes its matches; a later positive pattern can include them again. The
+     * array must contain at least one positive pattern.
+     *
+     * A bare directory such as `src` or `src/` does not include its children;
+     * write `src/**` when the whole subtree belongs to this claim.
+     */
+    files: string[];
+    /**
+     * Glob patterns for the files that may host this claim's `@evidenceExclude`
+     * declarations.
+     *
+     * Omit this property to accept an exclusion wherever it is otherwise
+     * eligible, which is how every claim behaved before this property existed.
+     *
+     * Declare it to gather them. An exclusion is the one acknowledgement that
+     * reports an obligation discharged without anything being built, so reading
+     * every exclusion a claim owns is a review that has to happen; scattered
+     * through the population it means reading the population, and named here it
+     * means opening these files. An exclusion selected from any other file is
+     * reported where it sits, naming these patterns, and discharges nothing, so
+     * its target still owes positive `@evidence`.
+     *
+     * The patterns narrow and never widen. They use the grammar and the root
+     * {@link files} uses, and a carrier must already be selected by {@link files}
+     * to host anything.
+     *
+     * This is independent of `noEvidenceExclude`, which decides whether one
+     * reference accepts an exclusion at all. A claim whose every reference
+     * refuses them gains nothing here.
+     */
+    evidenceExcludeCarriers?: string[];
+    /**
+     * One evidence population or independently complete evidence populations that
+     * this claim must cite.
+     *
+     * A single reference requires this claim's files to acknowledge every
+     * evidence unit it materializes. An array creates a separate 100% obligation
+     * for every element: acknowledgements toward one reference never count toward
+     * another, and partially covered references cannot be pooled. The array must
+     * not be empty.
+     */
+    reference: ITtscEvidenceGraphReference | ITtscEvidenceGraphReference[];
+}

package/lib/structures/ITtscEvidenceGraphClaimBase.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/structures/ITtscEvidenceGraphConfig.d.ts

@@ -0,0 +1,19 @@
+import type { ITtscEvidenceGraphClaim } from "./ITtscEvidenceGraphClaim";
+/**
+ * The root declaration of a project's evidence graph.
+ *
+ * An evidence graph makes grounds for code and documentation explicit: one side
+ * claims to implement, verify, or document something, and the other side is the
+ * evidence it must cite with a reason. The configuration defines those
+ * boundaries without hardcoding a repository's folder layout or its notion of
+ * proof.
+ */
+export interface ITtscEvidenceGraphConfig {
+    /**
+     * Claim populations whose files must cite their referenced evidence. Each
+     * claim owns its reference obligations; coverage is never pooled across
+     * claims. Provide at least one claim; an empty array is invalid because it
+     * would enable the rule without establishing any evidence obligation.
+     */
+    claims: ITtscEvidenceGraphClaim[];
+}

package/lib/structures/ITtscEvidenceGraphConfig.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/structures/ITtscEvidenceGraphMarkdownClaim.d.ts

@@ -0,0 +1,40 @@
+import type { TtscEvidenceGraphMarkdownSymbol } from "../typings/TtscEvidenceGraphMarkdownSymbol";
+import type { ITtscEvidenceGraphClaimBase } from "./ITtscEvidenceGraphClaimBase";
+/**
+ * A population of Markdown documents claiming its referenced evidence.
+ *
+ * Markdown uses HTML comments as invisible but reviewable declaration hosts.
+ * Both `@evidence <target> <reason>` and `@evidenceExclude <target> <reason>`
+ * require a target and a non-empty explanation.
+ *
+ * An exclusion still has to appear in a selected claim file and on a selected
+ * host kind. Its particular host is not part of the acknowledgement identity,
+ * so moving it between eligible sections cannot change the target scope this
+ * claim excludes. The target scope, not the declaration's host position,
+ * determines which selected descendants are acknowledged.
+ *
+ * @example
+ *   <!-- @evidence docs/orders.md#create-order This section adopts the creation contract. -->
+ */
+export interface ITtscEvidenceGraphMarkdownClaim extends ITtscEvidenceGraphClaimBase<"markdown"> {
+    /**
+     * Glob patterns for the Markdown files that must cite the referenced
+     * evidence. Every matching regular file is parsed as Markdown regardless of
+     * extension, so exclude non-Markdown assets rather than relying on a suffix.
+     */
+    files: string[];
+    /**
+     * Markdown node kind or kinds eligible to host this claim's declarations.
+     *
+     * Omit this property to select documents and H1 through H4 sections. A single
+     * value selects one kind; a non-empty array selects the union of its kinds.
+     *
+     * A `"file"` declaration appears before the document's first ATX heading. A
+     * heading declaration belongs to the nearest preceding ATX heading, whose
+     * exact level must be selected. This makes an H3 declaration distinct from
+     * its enclosing H2 section.
+     *
+     * @default ["file", "h1", "h2", "h3", "h4"]
+     */
+    symbol?: TtscEvidenceGraphMarkdownSymbol | TtscEvidenceGraphMarkdownSymbol[];
+}

package/lib/structures/ITtscEvidenceGraphMarkdownClaim.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/structures/ITtscEvidenceGraphMarkdownReference.d.ts

@@ -0,0 +1,76 @@
+import type { TtscEvidenceGraphMarkdownSymbol } from "../typings/TtscEvidenceGraphMarkdownSymbol";
+import type { ITtscEvidenceGraphReferenceBase } from "./ITtscEvidenceGraphReferenceBase";
+/**
+ * A population of documentary evidence that the owning claim must cite.
+ *
+ * A document is useful as evidence only when a reviewer can identify the scope
+ * that supports a claim. This reference makes the obligation levels explicit
+ * while allowing one file or heading target to acknowledge its selected
+ * descendants. Citations remain anchored in the outline, so an editorial change
+ * cannot silently preserve a claim whose grounds disappeared.
+ */
+export interface ITtscEvidenceGraphMarkdownReference extends ITtscEvidenceGraphReferenceBase<"markdown"> {
+    /**
+     * Directory this population's {@link files} patterns resolve against, and the
+     * base its evidence targets are addressed from.
+     *
+     * Omit this property to resolve against the active `ttsc` project root, which
+     * is where every population resolved before this property existed.
+     *
+     * The value names one directory, never a glob. It may sit inside the project
+     * (`docs`), above it (`../../docs`), or on an absolute path
+     * (`/srv/contracts`, `C:/contracts`). A drive-relative Windows path such as
+     * `C:docs` is refused, because it resolves against whatever directory that
+     * drive currently sits on rather than against a stable base.
+     *
+     * Moving the root moves the addresses with it. With `root: "../../docs"` and
+     * `files: ["requirements/**"]`, a section is cited as
+     * `requirements/pricing.md#discounts` rather than through this project's
+     * distance from the documents — which is what lets two packages sharing one
+     * requirements set write the same citation, and why a shared population
+     * declares its root once instead of spelling `..` inside every pattern.
+     *
+     * Diagnostics name the resolved base, and the resolved patterns are published
+     * to the `ttsc` host as watched inputs, so editing a document above the
+     * project still invalidates the graph.
+     */
+    root?: string;
+    /**
+     * Glob patterns for Markdown documents in this evidence population, resolved
+     * against {@link root} or against the project root when none is declared.
+     * Every matching regular file is parsed as Markdown regardless of extension,
+     * so exclude images and other non-Markdown assets from the patterns.
+     *
+     * These are globs, not regular expressions. `*` matches within one path
+     * segment, `**` crosses any number of path segments, and `?` matches one
+     * character. Both `/` and `\` are accepted as separators, while path identity
+     * remains case-sensitive on every operating system.
+     *
+     * Patterns are evaluated from left to right. A pattern prefixed with `!`
+     * removes its matches; a later positive pattern can include them again. The
+     * array must contain at least one positive pattern.
+     *
+     * For example, `docs/*.md` selects Markdown files directly under `docs`,
+     * while `specs/v?.md` selects names such as `v1.md` but not `v10.md`.
+     *
+     * A bare directory such as `docs` or `docs/` does not include its children;
+     * write `docs/**` when the whole subtree belongs to this reference.
+     */
+    files: string[];
+    /**
+     * Markdown node kind or kinds eligible to become evidence units.
+     *
+     * Omit this property to select documents and H1 through H4 sections. A single
+     * value selects one obligation kind; a non-empty array selects the union.
+     * Selected units remain independent obligations until an ancestor target
+     * acknowledges their shared scope. Ancestors of selected units are
+     * addressable even when their own kind is omitted from this selector.
+     *
+     * File units use the path inside {@link root} as their target. Heading units
+     * use `<path>#<anchor>` as documented by
+     * {@link TtscEvidenceGraphMarkdownSymbol}.
+     *
+     * @default ["file", "h1", "h2", "h3", "h4"]
+     */
+    symbol?: TtscEvidenceGraphMarkdownSymbol | TtscEvidenceGraphMarkdownSymbol[];
+}

package/lib/structures/ITtscEvidenceGraphMarkdownReference.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/structures/ITtscEvidenceGraphPrismaClaim.d.ts

@@ -0,0 +1,65 @@
+import type { TtscEvidenceGraphPrismaSymbol } from "../typings/TtscEvidenceGraphPrismaSymbol";
+import type { ITtscEvidenceGraphClaimBase } from "./ITtscEvidenceGraphClaimBase";
+/**
+ * A Prisma schema claiming its referenced evidence.
+ *
+ * A schema is authored, not generated, so it can carry its own citations. This
+ * is what turns "this table exists" into "this table exists because of that
+ * requirement", and it is the direction a data model most needs: a column
+ * nobody asked for is invisible until someone reads the whole schema against
+ * the whole specification.
+ *
+ * Ownership declarations live in `///` documentation comments immediately above
+ * their model or field. Both `@evidence <target> <reason>` and
+ * `@evidenceExclude <target> <reason>` require a target and a non-empty
+ * explanation.
+ *
+ * A triple-slash comment and a block comment both host a citation, because
+ * Prisma documents a declaration with either and both reach the generated
+ * client types. A double-slash line comment is discarded by Prisma itself and
+ * hosts nothing — a citation written in one is reported rather than ignored,
+ * because a tag that silently does nothing is the exact failure this rule
+ * exists to remove.
+ *
+ * A comment documents the declaration that immediately follows it, which is
+ * Prisma's own rule. A blank line before a top-level block detaches the comment
+ * entirely, and a comment above a block attribute or a closing brace documents
+ * nothing; a citation in any of those positions is reported.
+ *
+ * A matching claim file has one exclusion-only exception: an unattached
+ * top-level `/// @evidenceExclude` run is a file-level carrier. This supports a
+ * lint-only `.schema` ledger outside Prisma generation. `@evidence` in the same
+ * position remains invalid.
+ *
+ * ```prisma
+ * /// @evidence docs/requirements.md#pricing Sale price derives from this section.
+ * model Sale {
+ *   /// @evidence docs/requirements.md#coupons The stacking limit is stored here.
+ *   coupon_limit Int
+ * }
+ * ```
+ */
+export interface ITtscEvidenceGraphPrismaClaim extends ITtscEvidenceGraphClaimBase<"prisma"> {
+    /**
+     * Glob patterns for the Prisma schema files that must cite the referenced
+     * evidence. Every matching regular file is parsed as part of one schema
+     * regardless of extension, which is what lets a lint-only `.schema` ledger
+     * join the population Prisma generation never reads.
+     */
+    files: string[];
+    /**
+     * Prisma node kind or kinds eligible to host this claim's ownership evidence.
+     *
+     * Omit this property to select models, columns, and relations. A single value
+     * selects one kind; a non-empty array selects the union of its kinds.
+     *
+     * The default is the widest one, because on the claiming side a selector
+     * narrows where ownership evidence may sit rather than what must be covered.
+     * Narrow it to `"model"` when only tables owe an answer and a column-level
+     * citation should be reported as out of scope. A file-level exclusion carrier
+     * is eligible independently of this selector.
+     *
+     * @default ["model", "column", "relation"]
+     */
+    symbol?: TtscEvidenceGraphPrismaSymbol | TtscEvidenceGraphPrismaSymbol[];
+}

package/lib/structures/ITtscEvidenceGraphPrismaClaim.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/structures/ITtscEvidenceGraphPrismaReference.d.ts

@@ -0,0 +1,75 @@
+import type { TtscEvidenceGraphPrismaSymbol } from "../typings/TtscEvidenceGraphPrismaSymbol";
+import type { ITtscEvidenceGraphReferenceBase } from "./ITtscEvidenceGraphReferenceBase";
+/**
+ * A population of Prisma schema declarations that the owning claim must cite.
+ *
+ * A data model is a set of decisions about what the product stores, and this
+ * reference makes each of them something a claim has to answer for. A provider
+ * cites the model it persists, a DTO cites the column it exposes, and a table
+ * nothing cites becomes a build failure rather than a discovery made later.
+ *
+ * Every matched file is parsed together as one schema, because a Prisma schema
+ * folder is a single namespace whose files reference each other. The parse is
+ * Prisma's own, so a schema it rejects is reported as a parse failure rather
+ * than as an empty population.
+ */
+export interface ITtscEvidenceGraphPrismaReference extends ITtscEvidenceGraphReferenceBase<"prisma"> {
+    /**
+     * Directory this population's {@link files} patterns resolve against.
+     *
+     * Omit this property to resolve against the active `ttsc` project root, which
+     * is where every population resolved before this property existed.
+     *
+     * The value names one directory, never a glob. It may sit inside the project
+     * (`prisma`), above it (`../../prisma`), or on an absolute path
+     * (`/srv/schema`, `C:/schema`). A drive-relative Windows path such as
+     * `C:prisma` is refused, because it resolves against whatever directory that
+     * drive currently sits on rather than against a stable base.
+     *
+     * A Prisma target carries no path, so a declared root changes which files
+     * belong to the schema set and where a diagnostic points, never how a model
+     * is cited. Diagnostics name the resolved base, and the resolved patterns are
+     * published to the `ttsc` host as watched inputs.
+     */
+    root?: string;
+    /**
+     * Glob patterns for the Prisma schema files in this evidence population,
+     * resolved against {@link root} or against the project root when none is
+     * declared. Every matching regular file is parsed as part of one schema
+     * regardless of extension.
+     *
+     * These are globs, not regular expressions. `*` matches within one path
+     * segment, `**` crosses any number of path segments, and `?` matches one
+     * character. Both `/` and `\` are accepted as separators, while path identity
+     * remains case-sensitive on every operating system.
+     *
+     * Patterns are evaluated from left to right. A pattern prefixed with `!`
+     * removes its matches; a later positive pattern can include them again. The
+     * array must contain at least one positive pattern.
+     *
+     * A bare directory such as `prisma` or `prisma/` does not include its
+     * children; write `prisma/schema/**` when the whole folder belongs to this
+     * reference.
+     */
+    files: string[];
+    /**
+     * Prisma node kind or kinds eligible to become evidence units.
+     *
+     * Omit this property to select models alone. A single value selects one
+     * obligation kind; a non-empty array selects the union.
+     *
+     * The default is deliberately the coarsest one. Selecting every column puts
+     * `id`, `created_at`, and every relation back-reference into the denominator,
+     * which is a large obligation to discharge honestly and an easy one to
+     * discharge with filler. Select `"column"` or `"relation"` when a claim
+     * really does owe an answer per member, and use `@evidenceExclude` for the
+     * members it deliberately does not use.
+     *
+     * A model remains addressable as an aggregate scope even when only its
+     * members are selected, so one citation on the model can discharge all of
+     * them.
+     *
+     * @default ["model"]
+     */
+    symbol?: TtscEvidenceGraphPrismaSymbol | TtscEvidenceGraphPrismaSymbol[];
+}

package/lib/structures/ITtscEvidenceGraphPrismaReference.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/structures/ITtscEvidenceGraphReference.d.ts

@@ -0,0 +1,14 @@
+import type { ITtscEvidenceGraphMarkdownReference } from "./ITtscEvidenceGraphMarkdownReference";
+import type { ITtscEvidenceGraphPrismaReference } from "./ITtscEvidenceGraphPrismaReference";
+import type { ITtscEvidenceGraphSwaggerReference } from "./ITtscEvidenceGraphSwaggerReference";
+import type { ITtscEvidenceGraphTypeScriptReference } from "./ITtscEvidenceGraphTypeScriptReference";
+/**
+ * One population of evidence units that a claim must cite completely.
+ *
+ * A reference selects what counts as evidence: Markdown documents and heading
+ * sections, Swagger or OpenAPI operations, or selected exported TypeScript
+ * symbols. Every unit it materializes must be acknowledged by the owning claim,
+ * so a reference is the denominator of one coverage obligation, never a pooled
+ * global set.
+ */
+export type ITtscEvidenceGraphReference = ITtscEvidenceGraphMarkdownReference | ITtscEvidenceGraphPrismaReference | ITtscEvidenceGraphSwaggerReference | ITtscEvidenceGraphTypeScriptReference;

package/lib/structures/ITtscEvidenceGraphReference.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });