@ttsc/evidence 0.25.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeongho Nam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,279 @@
+# `@ttsc/evidence`
+
+![banner of @ttsc/evidence](https://ttsc.dev/og-evidence.png)
+
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/ttsc/blob/master/LICENSE) [![NPM Version](https://img.shields.io/npm/v/@ttsc/evidence.svg)](https://www.npmjs.com/package/@ttsc/evidence) [![NPM Downloads](https://img.shields.io/npm/dm/@ttsc/evidence.svg)](https://www.npmjs.com/package/@ttsc/evidence) [![Build Status](https://github.com/samchon/ttsc/actions/workflows/build.yml/badge.svg)](https://github.com/samchon/ttsc/actions/workflows/build.yml) [![Guide Documents](https://img.shields.io/badge/Guide-Documents-forestgreen)](https://ttsc.dev/docs/evidence) [![Discord Badge](https://img.shields.io/badge/discord-samchon-d91965?style=flat&labelColor=5866f2&logo=discord&logoColor=white&link=https://discord.gg/E94XhzrUCZ)](https://discord.gg/E94XhzrUCZ)
+
+Evidence Graph, your spec as a compile error no coding agent can skip.
+
+```tsx
+/**
+ * @evidence docs/discount.md#coupon-stacking
+ *           States the per-issuer stacking limit
+ *           this section defines, in the buyer's words.
+ * @evidence POST:/orders/{orderId}/coupons
+ *           Explains the rejection this endpoint returns
+ *           for an over-stacked coupon set.
+ * @evidence {@link hooks.useCouponStacking} Renders the limit this hook resolves.
+ */
+export function CouponStackingNotice(props: IProps): JSX.Element;
+```
+
+`@evidence <target> <reason>` names one unit of the spec and why this declaration answers for it. A target is a document section, an API operation, a database schema model, or a TypeScript symbol as an inline link.
+
+```bash
+$ npx ttsc
+error TS16411: [evidence/graph] Missing acknowledgement for 'docs/discount.md#coupon-stacking'
+  (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.
+
+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.
+
+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.
+
+Found 3 errors.
+```
+
+Without those tags, the build fails once per obligation, because one reference never covers another.
+
+An AI coding agent has to clear them to finish, and clearing them means citing each target and writing down why its code answers for it. Coverage reaches 100% on its own, as the residue of the errors it closed.
+
+![Coverage and token spend across all four subjects](https://raw.githubusercontent.com/samchon/ttsc/gh-pages/benchmark/png/evidence-summary.png)
+
+## Setup
+
+### Install
+
+```bash
+npm install -D typescript ttsc @ttsc/lint
+npm install -D @ttsc/evidence
+```
+
+This is a rule contributor to [`@ttsc/lint`](https://github.com/samchon/ttsc/tree/master/packages/lint) 0.22 or newer, so it runs on [`ttsc`](https://github.com/samchon/ttsc) rather than on stock `tsc` with ESLint.
+
+### Configure
+
+```ts
+// lint.config.ts
+import { evidence, type ITtscEvidenceGraphConfig } from "@ttsc/evidence";
+import type { ITtscLintConfig } from "@ttsc/lint";
+
+const graph: ITtscEvidenceGraphConfig = {
+  claims: [
+    {
+      type: "typescript",
+      files: ["src/components/**/*.tsx"],
+      symbol: "function",
+      reference: {
+        type: "markdown",
+        files: ["docs/**/*.md"],
+        symbol: ["h2", "h3"],
+      },
+    },
+  ],
+};
+
+export default {
+  plugins: { evidence },
+  rules: { "evidence/graph": ["error", graph] },
+} satisfies ITtscLintConfig;
+```
+
+One sentence: the components under `src` implement the docs, so every H2 and H3 under `docs` must be cited by a component. Violations arrive in the same stream as type errors, so there is no CI job to add.
+
+### Rules
+
+| 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/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. |
+
+Each takes `"error"`, `"warning"`, or `"off"`.
+
+## Claims and references
+
+A claim is the population that owes a citation, a reference is what it owes, and every claim and reference pair is its own 100% obligation. Listing two references means both must be satisfied, and a citation toward one never counts toward the other. They all join the same `claims` array.
+
+| Kind | Units | Claim | Reference | Cites in |
+| --- | --- | --- | --- | --- |
+| Markdown | file, H1 to H4 sections | yes | yes | an HTML comment |
+| Prisma | model, column, relation | yes | yes | a `///` comment |
+| TypeScript | types, functions, properties | yes | yes | JSDoc |
+| Swagger / OpenAPI | each operation under `paths` | no | yes | nothing, it cannot host a tag |
+
+Every population takes glob patterns in `files`, resolved against the `ttsc` project root. Add `root` to resolve against another directory instead, inside the project, above it, or absolute, which is how several packages in a monorepo share one requirements set and write the same citation.
+
+### Documents
+
+```ts
+{
+  type: "markdown",
+  files: ["docs/requirements/**/*.md"],
+  reference: {
+    type: "markdown",
+    files: ["docs/meetings/**/*.md"],
+    symbol: ["h2", "h3"],
+  },
+}
+```
+
+Markdown grounds Markdown, so a decision taken in a meeting and never written into the requirements fails the build. Deleting a requirement breaks every document that leaned on it, which is what stops a ghost spec from outliving its own source.
+
+```md
+## Coupon Stacking {#coupon-stacking}
+
+<!-- @evidence docs/meetings/2026-01-12.md#discount-policy Carries the limit agreed in that meeting. -->
+```
+
+A citation sits in an HTML comment, so rendered prose stays clean, and a heading declares its own anchor with the `{#id}` suffix. A section citation sits under its heading; a whole-file citation sits at the top.
+
+### Database schema
+
+```ts
+{
+  type: "prisma",
+  files: ["prisma/schema/**/*.prisma"],
+  symbol: "model",
+  reference: {
+    type: "markdown",
+    files: ["docs/requirements/**/*.md"],
+    symbol: "h2",
+  },
+}
+```
+
+Every model justifies itself against a requirement, so a table nobody asked for has nothing to cite. Reverse the pair to make a provider owe the model it reads.
+
+```prisma
+/// @evidence docs/requirements/pricing.md#discount-policy Discount columns exist for this policy.
+model Sale {
+  /// @evidence docs/requirements/pricing.md#coupon-stacking The stacking limit is stored here.
+  coupon_limit Int
+}
+```
+
+A model is addressed as `prisma:Sale` and a member as `prisma:Sale.price`, never through the file it sits in, so moving a model between files cannot break a citation. Every matched file is parsed as one schema.
+
+### API operations
+
+```ts
+{
+  type: "typescript",
+  files: ["src/controllers/**/*.ts"],
+  reference: {
+    type: "swagger",
+    file: "https://raw.githubusercontent.com/samchon/shopping/refs/heads/master/packages/api/swagger.json",
+  },
+}
+```
+
+Each operation under `paths` is one obligation, so an operation the spec adds and nobody implemented is a compile error on the next build. The singular `file` names one local path or one `http:` URL, never a glob; use a `reference` array for several documents.
+
+An operation is cited as `POST:/orders`, one whitespace-free token, so the method and the path stay one target. Swagger grounds a claim and never makes one, because an operation has nowhere to host a tag.
+
+### Symbols
+
+```ts
+{
+  type: "typescript",
+  files: ["src/lib/*/hooks.ts"],
+  symbol: "function",
+  reference: {
+    type: "typescript",
+    package: "@ORGANIZATION/PROJECT-api",
+    files: ["src/functional/**/*.ts"],
+    symbol: ["function"],
+  },
+}
+```
+
+`files` selects modules and the population is what those modules publish, so a barrel carries in the surface it forwards. A `package` population is read from disk rather than from the program, because a symbol nothing imports is absent from the program and is exactly the one an obligation needs to name.
+
+A unit is addressed the way a consumer reaches it, so `export * as functional` nests a segment and `export { A as B }` answers to `B`. Only TypeScript may cite TypeScript: `{@link}` resolves through the citing module's own imports, and no document has an import scope to resolve in.
+
+### Symbol selectors
+
+`symbol` picks which units a reference materializes, and on a claim it restricts which declarations may host a tag.
+
+| Kind | Values | Default on a claim | Default on a reference |
+| --- | --- | --- | --- |
+| Markdown | `file`, `h1`, `h2`, `h3`, `h4` | all five | all five |
+| Prisma | `model`, `column`, `relation` | all three | `model` |
+| 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.
+
+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.
+
+### Exclusions
+
+```md
+<!-- @evidenceExclude docs/requirements/pricing.md#coupon-stacking
+     This release ships a single coupon. Stacking waits for the settlement policy. -->
+```
+
+`@evidenceExclude <target> <reason>` records that a claim intentionally does not use a scope. It follows the same hierarchy as `@evidence`, affects only the claim it is written in, and one obligation may exclude a scope only once.
+
+It is the only acknowledgement that settles an obligation without anything being built, so it exists to be vetoed. "Not applicable" is a conclusion rather than a reason.
+
+```ts
+{
+  type: "typescript",
+  files: ["src/components/**/*.tsx", "src/components/EXCLUSIONS.ts"],
+  evidenceExcludeCarriers: ["src/components/EXCLUSIONS.ts"],
+  symbol: "function",
+  reference: { type: "markdown", files: ["docs/**/*.md"], symbol: "h2" },
+}
+```
+
+`evidenceExcludeCarriers` confines them to a named ledger. Scattered through the population, reading every exclusion means reading the population; gathered in one file it means opening one file. An exclusion written anywhere else is reported where it sits and discharges nothing.
+
+### 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.
+
+```ts
+{
+  type: "typescript",
+  package: "@ORGANIZATION/PROJECT-api",
+  files: ["src/functional/**/*.ts"],
+  symbol: ["function"],
+  noEvidenceExclude: true,
+  singleEvidencePerSymbol: true,
+}
+```
+
+- `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.
+
+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.
+
+## Sponsors
+
+[![Sponsors](https://raw.githubusercontent.com/samchon/sponsor-images/refs/heads/master/public/circle.svg)](https://github.com/sponsors/samchon)
+
+Thanks for your support.
+
+Your [donation](https://github.com/sponsors/samchon) encourages `@ttsc/evidence` development.
+
+## References
+
+- [`ttsc`](https://github.com/samchon/ttsc): the TypeScript-Go toolchain this plugin runs on.
+- [`@ttsc/lint`](https://github.com/samchon/ttsc/tree/master/packages/lint): the lint engine that links this rule into the compiler.
+- [Guide Documents](https://ttsc.dev/docs/evidence)
+- [Benchmark Diagram](https://ttsc.dev/docs/benchmark/evidence)
+- [`samchon/evidence-benchmark-results`](https://github.com/samchon/evidence-benchmark-results)

package/lib/index.d.ts

@@ -0,0 +1,65 @@
+export * from "./structures/index";
+export * from "./typings/index";
+/**
+ * The `@ttsc/lint` contributor that checks a project's evidence graph.
+ *
+ * Import this value into `lint.config.ts` and register it under the
+ * `"evidence"` plugin name. You can then enable `"evidence/graph"` and pass an
+ * {@link ITtscEvidenceGraphConfig} that describes which documents and TypeScript
+ * symbols must remain connected.
+ *
+ * The plugin contributes four rules, enabled independently.
+ *
+ * - `"evidence/graph"` — the configured evidence graph. Every declaration target
+ *   must resolve, and every selected evidence unit must be acknowledged. Takes
+ *   an {@link ITtscEvidenceGraphConfig}. It also offers the configured targets
+ *   as editor completions, on the cycles where it passes: the host publishes a
+ *   rule's completions only while that rule reports nothing.
+ * - `"evidence/singular"` — one public identity per TypeScript file, named after
+ *   the file. Takes no options, so it carries a bare severity.
+ * - `"evidence/documented"` — a JSDoc block on every selected export, which is
+ *   the only place an `@evidence` tag is ever read from. Takes an
+ *   {@link ITtscEvidenceDocumentedConfig}.
+ * - `"evidence/todo"` — no remaining JSDoc `@todo` tag anywhere in a checked
+ *   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.
+ *
+ * @example <caption>Configure the plugin in `lint.config.ts`</caption>
+ *   import { type ITtscEvidenceGraphConfig, evidence } from "@ttsc/evidence";
+ *   import type { ITtscLintConfig } from "@ttsc/lint";
+ *
+ *   const graph: ITtscEvidenceGraphConfig = {
+ *     claims: [
+ *       {
+ *         type: "typescript",
+ *         files: ["src/**"],
+ *         reference: {
+ *           type: "markdown",
+ *           files: ["docs/*.md"],
+ *         },
+ *       },
+ *     ],
+ *   };
+ *
+ *   export default {
+ *     plugins: {
+ *       evidence: evidence,
+ *     },
+ *     files: ["src/**"],
+ *     rules: {
+ *       "evidence/graph": ["error", graph],
+ *       "evidence/singular": "error",
+ *     },
+ *   } satisfies ITtscLintConfig;
+ */
+export declare const evidence: {
+    meta: {
+        readonly name: "@ttsc/evidence";
+        readonly namespace: "evidence";
+        readonly version: string;
+    };
+    rules: readonly ["graph", "singular", "documented", "todo"];
+    source: string;
+};
+export default evidence;

package/lib/index.js

@@ -0,0 +1,87 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evidence = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const package_json_1 = require("../package.json");
+__exportStar(require("./structures/index"), exports);
+__exportStar(require("./typings/index"), exports);
+/**
+ * The `@ttsc/lint` contributor that checks a project's evidence graph.
+ *
+ * Import this value into `lint.config.ts` and register it under the
+ * `"evidence"` plugin name. You can then enable `"evidence/graph"` and pass an
+ * {@link ITtscEvidenceGraphConfig} that describes which documents and TypeScript
+ * symbols must remain connected.
+ *
+ * The plugin contributes four rules, enabled independently.
+ *
+ * - `"evidence/graph"` — the configured evidence graph. Every declaration target
+ *   must resolve, and every selected evidence unit must be acknowledged. Takes
+ *   an {@link ITtscEvidenceGraphConfig}. It also offers the configured targets
+ *   as editor completions, on the cycles where it passes: the host publishes a
+ *   rule's completions only while that rule reports nothing.
+ * - `"evidence/singular"` — one public identity per TypeScript file, named after
+ *   the file. Takes no options, so it carries a bare severity.
+ * - `"evidence/documented"` — a JSDoc block on every selected export, which is
+ *   the only place an `@evidence` tag is ever read from. Takes an
+ *   {@link ITtscEvidenceDocumentedConfig}.
+ * - `"evidence/todo"` — no remaining JSDoc `@todo` tag anywhere in a checked
+ *   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.
+ *
+ * @example <caption>Configure the plugin in `lint.config.ts`</caption>
+ *   import { type ITtscEvidenceGraphConfig, evidence } from "@ttsc/evidence";
+ *   import type { ITtscLintConfig } from "@ttsc/lint";
+ *
+ *   const graph: ITtscEvidenceGraphConfig = {
+ *     claims: [
+ *       {
+ *         type: "typescript",
+ *         files: ["src/**"],
+ *         reference: {
+ *           type: "markdown",
+ *           files: ["docs/*.md"],
+ *         },
+ *       },
+ *     ],
+ *   };
+ *
+ *   export default {
+ *     plugins: {
+ *       evidence: evidence,
+ *     },
+ *     files: ["src/**"],
+ *     rules: {
+ *       "evidence/graph": ["error", graph],
+ *       "evidence/singular": "error",
+ *     },
+ *   } satisfies ITtscLintConfig;
+ */
+exports.evidence = {
+    meta: {
+        name: "@ttsc/evidence",
+        namespace: "evidence",
+        version: package_json_1.version,
+    },
+    rules: ["graph", "singular", "documented", "todo"],
+    source: node_path_1.default.resolve(__dirname, "..", "native"),
+};
+exports.default = exports.evidence;

package/lib/internal/loadPrismaModels.d.ts

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

package/lib/internal/loadPrismaModels.js

@@ -0,0 +1,197 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPrismaModels = void 0;
+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 MAX_SCHEMA_BYTES = 16 * 1024 * 1024;
+const ANSI_PATTERN = /\x1b\[[0-9;]*m/gu;
+/**
+ * The separator between a path and its hash inside the composite digest.
+ *
+ * NUL, because a path may contain a space while a hex digest contains nothing
+ * outside `[0-9a-f]` — an ambiguous separator would let two different sets
+ * compose one key, which is the single thing a cache key may not do. The native
+ * side writes the same byte.
+ *
+ * Both sides spell it as an escape rather than as a literal on purpose. This
+ * was a literal control character once, and the two implementations then
+ * disagreed on a byte neither source showed, in the one place where a
+ * disagreement produces no error and no wrong answer — only a cache that never
+ * hits again.
+ */
+const SEPARATOR = "\u0000";
+/**
+ * Loads and classifies every configured Prisma schema set for the native rule.
+ *
+ * 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.
+ *
+ * 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
+ * a file cannot be parsed alone and the reuse key belongs to the ordered set.
+ *
+ * @internal
+ */
+const loadPrismaModels = async (request) => {
+    const parser = resolveParser(request.root);
+    const loaded = await Promise.all(request.sets.map(async (set) => {
+        let digest = "";
+        try {
+            const read = await readSet(request.root, set.files);
+            digest = read.digest;
+            return {
+                id: set.id,
+                models: modelsOf(parser, read.files),
+                digest,
+            };
+        }
+        catch (error) {
+            return {
+                id: set.id,
+                message: errorMessage(error),
+                digest,
+            };
+        }
+    }));
+    return {
+        documents: loaded.filter(isInventory),
+        problems: loaded.filter(isProblem),
+    };
+};
+exports.loadPrismaModels = loadPrismaModels;
+/**
+ * Resolves the schema parser, preferring the one the consumer's project can
+ * see.
+ *
+ * The preference is not politeness. A parser build validates the schema it
+ * parses, and Prisma's own rules move between major versions — a Prisma 7 build
+ * rejects a `datasource` block containing `url`, which every Prisma 6 schema
+ * has. Parsing a consumer's schema with a parser they did not choose therefore
+ * turns a valid schema into a build failure, so their copy wins whenever one
+ * exists and the pinned dependency is only the fallback.
+ *
+ * Which one answered is carried on the parser, because a rejection produced by
+ * the fallback needs to say so; a reader whose schema is fine has no other way
+ * to learn that the verdict came from a version they never installed.
+ */
+const resolveParser = (root) => {
+    const failures = [];
+    for (const origin of ["project", "plugin"]) {
+        try {
+            const resolver = origin === "project"
+                ? (0, node_module_1.createRequire)(node_path_1.default.join(root, "package.json"))
+                : (0, node_module_1.createRequire)(__filename);
+            const manifest = resolver("@prisma/prisma-schema-wasm/package.json");
+            const wasm = resolver("@prisma/prisma-schema-wasm");
+            if (typeof wasm.get_datamodel !== "function")
+                throw new Error("the module exposes no get_datamodel export");
+            return {
+                get_datamodel: wasm.get_datamodel,
+                version: manifest.version ?? "unknown",
+                origin,
+            };
+        }
+        catch (error) {
+            failures.push(`${origin}: ${errorMessage(error)}`);
+        }
+    }
+    throw new Error(`no Prisma schema parser could be resolved (${failures.join("; ")})`);
+};
+const readSet = async (root, sources) => {
+    const files = [];
+    // Hashed as it goes, over the bytes as they were read and in the order the
+    // caller sent. The native side composes the same digest from the same
+    // per-file hashes, so the two agree by construction; hashing the decoded text
+    // instead would agree only where the round trip happens to be exact.
+    const composite = (0, node_crypto_1.createHash)("sha256");
+    for (const source of sources) {
+        // A schema file may sit above the project or on an absolute path, because a
+        // population resolves against the root its configuration declares rather
+        // than against the project. The caller sends the paths its own walk
+        // produced, so this side only resolves them the same way.
+        const location = node_path_1.default.resolve(root, source);
+        const stat = await promises_1.default.stat(location);
+        if (!stat.isFile())
+            throw new Error(`the Prisma schema source '${source}' is not a file`);
+        if (stat.size > MAX_SCHEMA_BYTES)
+            throw new Error(`the Prisma schema '${source}' exceeds the ${MAX_SCHEMA_BYTES} byte limit`);
+        const content = await promises_1.default.readFile(location);
+        files.push([source, decodeUtf8(content)]);
+        composite.update(source, "utf8");
+        composite.update(SEPARATOR);
+        composite.update((0, node_crypto_1.createHash)("sha256").update(content).digest("hex"));
+        composite.update("\n");
+    }
+    return { files, digest: composite.digest("hex") };
+};
+const decodeUtf8 = (content) => new TextDecoder("utf-8", { fatal: true }).decode(content);
+/**
+ * Runs the parser over one whole set and classifies what it declares.
+ *
+ * `get_datamodel` is used rather than the full DMMF deliberately. Measured on a
+ * 200-model schema, the datamodel answers in 11 ms and 369 KB while the full
+ * DMMF takes 262 ms and 16 MB — and that payload has to cross a process
+ * boundary as JSON. Nothing in the extra 16 MB is a unit this graph can cite.
+ */
+const modelsOf = (parser, files) => {
+    let payload;
+    try {
+        payload = parser.get_datamodel(JSON.stringify({ prismaSchema: files }));
+    }
+    catch (error) {
+        throw new Error(`${parserFailure(error)} (parsed by @prisma/prisma-schema-wasm@${parser.version} resolved from the ${parser.origin})`);
+    }
+    const datamodel = JSON.parse(payload);
+    const models = [];
+    for (const model of datamodel.models ?? []) {
+        if (typeof model.name !== "string" || model.name.length === 0)
+            continue;
+        models.push({
+            name: model.name,
+            documentation: typeof model.documentation === "string" ? model.documentation : "",
+            fields: (model.fields ?? [])
+                .filter((field) => typeof field.name === "string" && field.name.length !== 0)
+                .map((field) => ({
+                name: field.name,
+                // Prisma classifies a relation field as `object`; everything a table
+                // actually stores is `scalar`. An `enum`-typed field stores a value
+                // and is therefore a column, which is why the test is for `object`
+                // rather than for `scalar`.
+                symbol: field.kind === "object" ? "relation" : "column",
+                documentation: typeof field.documentation === "string" ? field.documentation : "",
+            })),
+        });
+    }
+    return models;
+};
+/**
+ * Unwraps the parser's own error into the sentence its author has to act on.
+ *
+ * A rejection arrives as an `Error` whose message is a JSON envelope carrying
+ * an error code and an ANSI-coloured report — and that report is the one place
+ * a location survives at all, because a successful parse carries no positions.
+ * Both halves are preserved: the colour codes are stripped because a diagnostic
+ * stream is not a terminal, and the text is not, because it names the line.
+ */
+const parserFailure = (error) => {
+    const raw = errorMessage(error);
+    try {
+        const envelope = JSON.parse(raw);
+        if (typeof envelope.message === "string")
+            return envelope.message.replace(ANSI_PATTERN, "").trim();
+    }
+    catch {
+        // Not an envelope; the raw message is the whole of what is known.
+    }
+    return raw.replace(ANSI_PATTERN, "").trim();
+};
+const isInventory = (value) => "models" in value;
+const isProblem = (value) => "message" in value;
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);

package/lib/internal/loadSwaggerOperations.d.ts

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