@wrtnlabs/evidence 0.0.0

package/lib/adapters/swagger/EvidenceSwaggerAdapter.js

@@ -0,0 +1,489 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceSwaggerAdapter = void 0;
+const _assertGuard_1 = __importStar(require("typia/lib/internal/_assertGuard"));
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = __importDefault(require("node:path"));
+const typia_1 = __importDefault(require("typia"));
+const EvidenceInventory_1 = require("../../graph/EvidenceInventory");
+const EvidenceSourceLoader_1 = require("../../loaders/EvidenceSourceLoader");
+const EvidenceTagParser_1 = require("../../parsers/EvidenceTagParser");
+const SourcePath_1 = require("../../internal/SourcePath");
+const SourceText_1 = require("../../internal/SourceText");
+const SwaggerDescription_1 = require("./SwaggerDescription");
+const SwaggerDocumentLoader_1 = require("./SwaggerDocumentLoader");
+const SwaggerRemoteReader_1 = require("./SwaggerRemoteReader");
+/**
+ * Extracts Swagger/OpenAPI operations and their description-based annotation hosts.
+ *
+ * Local snapshots and explicitly configured remote documents pass through the
+ * same normalization and materialization path. Each method/path operation retains
+ * its own identity even without a description, while supported description spans
+ * map annotations back to source coordinates. Document failures remain incomplete.
+ */
+class EvidenceSwaggerAdapter {
+    /**
+     * Artifact discriminator selecting API-operation extraction.
+     *
+     * Operations use method/path targets within each independent document population.
+     */
+    type = "swagger";
+    /**
+     * Normalizes captured JSON/YAML documents into operation inventories.
+     *
+     * Each document failure is retained alongside successfully loaded documents.
+     * Input is cloned, and final inventory validation preserves incompleteness rather
+     * than treating failed normalization as a document with no operations.
+     */
+    async analyze(snapshot) {
+        const input = structuredClone((() => {
+            const _ip0 = input => "string" === typeof input["absolute"];
+            const _ip1 = input => "string" === typeof input["display"];
+            const _ip2 = input => "string" === typeof input["path"];
+            const _ap0 = (input, _path, _exceptionable = true) => "string" === typeof input["absolute"] || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".absolute",
+                expected: "string",
+                value: input["absolute"]
+            }, _errorFactory);
+            const _ap1 = (input, _path, _exceptionable = true) => "string" === typeof input["display"] || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".display",
+                expected: "string",
+                value: input["display"]
+            }, _errorFactory);
+            const _ap2 = (input, _path, _exceptionable = true) => "string" === typeof input["path"] || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".path",
+                expected: "string",
+                value: input["path"]
+            }, _errorFactory);
+            const _ae0 = "(\"case-mismatch\" | \"invalid-encoding\" | \"not-file\" | \"path-unreadable\" | \"root-unreadable\" | \"source-changed\" | \"symlink-cycle\")";
+            const _ao0 = (input, _path, _exceptionable = true) => (("object" === typeof input.root && null !== input.root || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".root",
+                expected: "IEvidenceSourceRoot",
+                value: input.root
+            }, _errorFactory)) && _ao1(input.root, _path + ".root", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".root",
+                expected: "IEvidenceSourceRoot",
+                value: input.root
+            }, _errorFactory)) && ((Array.isArray(input.files) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".files",
+                expected: "Array<IEvidenceSourceFile>",
+                value: input.files
+            }, _errorFactory)) && input.files.every((elem, _index5) => ("object" === typeof elem && null !== elem || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".files[" + _index5 + "]",
+                expected: "IEvidenceSourceFile",
+                value: elem
+            }, _errorFactory)) && _ao2(elem, _path + ".files[" + _index5 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".files[" + _index5 + "]",
+                expected: "IEvidenceSourceFile",
+                value: elem
+            }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".files",
+                expected: "Array<IEvidenceSourceFile>",
+                value: input.files
+            }, _errorFactory)) && ((Array.isArray(input.dependencies) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".dependencies",
+                expected: "Array<IEvidenceSourceDependency>",
+                value: input.dependencies
+            }, _errorFactory)) && input.dependencies.every((elem, _index6) => ("object" === typeof elem && null !== elem || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".dependencies[" + _index6 + "]",
+                expected: "IEvidenceSourceDependency",
+                value: elem
+            }, _errorFactory)) && _ao4(elem, _path + ".dependencies[" + _index6 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".dependencies[" + _index6 + "]",
+                expected: "IEvidenceSourceDependency",
+                value: elem
+            }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".dependencies",
+                expected: "Array<IEvidenceSourceDependency>",
+                value: input.dependencies
+            }, _errorFactory)) && ((Array.isArray(input.diagnostics) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".diagnostics",
+                expected: "Array<IEvidenceSourceDiagnostic>",
+                value: input.diagnostics
+            }, _errorFactory)) && input.diagnostics.every((elem, _index7) => ("object" === typeof elem && null !== elem || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".diagnostics[" + _index7 + "]",
+                expected: "IEvidenceSourceDiagnostic",
+                value: elem
+            }, _errorFactory)) && _ao5(elem, _path + ".diagnostics[" + _index7 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".diagnostics[" + _index7 + "]",
+                expected: "IEvidenceSourceDiagnostic",
+                value: elem
+            }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".diagnostics",
+                expected: "Array<IEvidenceSourceDiagnostic>",
+                value: input.diagnostics
+            }, _errorFactory)) && ("boolean" === typeof input.complete || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".complete",
+                expected: "boolean",
+                value: input.complete
+            }, _errorFactory));
+            const _ao1 = (input, _path, _exceptionable = true) => ("string" === typeof input.declared || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".declared",
+                expected: "string",
+                value: input.declared
+            }, _errorFactory)) && _ap0(input, _path, true && _exceptionable) && (undefined === input.physical || "string" === typeof input.physical || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".physical",
+                expected: "(string | undefined)",
+                value: input.physical
+            }, _errorFactory)) && _ap1(input, _path, true && _exceptionable);
+            const _ao2 = (input, _path, _exceptionable = true) => ("string" === typeof input.id || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".id",
+                expected: "string",
+                value: input.id
+            }, _errorFactory)) && ("string" === typeof input.physicalPath || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".physicalPath",
+                expected: "string",
+                value: input.physicalPath
+            }, _errorFactory)) && ("string" === typeof input.content || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".content",
+                expected: "string",
+                value: input.content
+            }, _errorFactory)) && ("string" === typeof input.digest || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".digest",
+                expected: "string",
+                value: input.digest
+            }, _errorFactory)) && ((Array.isArray(input.addresses) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".addresses",
+                expected: "Array<IEvidenceSourceAddress>",
+                value: input.addresses
+            }, _errorFactory)) && input.addresses.every((elem, _index8) => ("object" === typeof elem && null !== elem || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".addresses[" + _index8 + "]",
+                expected: "IEvidenceSourceAddress",
+                value: elem
+            }, _errorFactory)) && _ao3(elem, _path + ".addresses[" + _index8 + "]", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".addresses[" + _index8 + "]",
+                expected: "IEvidenceSourceAddress",
+                value: elem
+            }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".addresses",
+                expected: "Array<IEvidenceSourceAddress>",
+                value: input.addresses
+            }, _errorFactory));
+            const _ao3 = (input, _path, _exceptionable = true) => _ap0(input, _path, true && _exceptionable) && ("string" === typeof input.relative || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".relative",
+                expected: "string",
+                value: input.relative
+            }, _errorFactory)) && _ap1(input, _path, true && _exceptionable) && (undefined === input.selected || "boolean" === typeof input.selected || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".selected",
+                expected: "(boolean | undefined)",
+                value: input.selected
+            }, _errorFactory));
+            const _ao4 = (input, _path, _exceptionable = true) => _ap2(input, _path, true && _exceptionable) && ("boolean" === typeof input.recursive || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".recursive",
+                expected: "boolean",
+                value: input.recursive
+            }, _errorFactory));
+            const _ao5 = (input, _path, _exceptionable = true) => ("case-mismatch" === input.code || "invalid-encoding" === input.code || "not-file" === input.code || "path-unreadable" === input.code || "root-unreadable" === input.code || "source-changed" === input.code || "symlink-cycle" === input.code || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".code",
+                expected: _ae0,
+                value: input.code
+            }, _errorFactory)) && _ap2(input, _path, true && _exceptionable) && ("string" === typeof input.message || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".message",
+                expected: "string",
+                value: input.message
+            }, _errorFactory));
+            const _io0 = input => "object" === typeof input.root && null !== input.root && _io1(input.root) && (Array.isArray(input.files) && input.files.every(elem => "object" === typeof elem && null !== elem && _io2(elem))) && (Array.isArray(input.dependencies) && input.dependencies.every(elem => "object" === typeof elem && null !== elem && _io4(elem))) && (Array.isArray(input.diagnostics) && input.diagnostics.every(elem => "object" === typeof elem && null !== elem && _io5(elem))) && "boolean" === typeof input.complete;
+            const _io1 = input => "string" === typeof input.declared && _ip0(input) && (undefined === input.physical || "string" === typeof input.physical) && _ip1(input);
+            const _io2 = input => "string" === typeof input.id && "string" === typeof input.physicalPath && "string" === typeof input.content && "string" === typeof input.digest && (Array.isArray(input.addresses) && input.addresses.every(elem => "object" === typeof elem && null !== elem && _io3(elem)));
+            const _io3 = input => _ip0(input) && "string" === typeof input.relative && _ip1(input) && (undefined === input.selected || "boolean" === typeof input.selected);
+            const _io4 = input => _ip2(input) && "boolean" === typeof input.recursive;
+            const _io5 = input => ("case-mismatch" === input.code || "invalid-encoding" === input.code || "not-file" === input.code || "path-unreadable" === input.code || "root-unreadable" === input.code || "source-changed" === input.code || "symlink-cycle" === input.code) && _ip2(input) && "string" === typeof input.message;
+            const __is = input => "object" === typeof input && null !== input && _io0(input);
+            let _errorFactory;
+            return (input, errorFactory) => {
+                if (false === __is(input)) {
+                    _errorFactory = errorFactory;
+                    ((input, _path, _exceptionable = true) => ("object" === typeof input && null !== input || _assertGuard_1._assertGuard(true, {
+                        method: "typia.assert",
+                        path: _path + "",
+                        expected: "IEvidenceSourceSnapshot",
+                        value: input
+                    }, _errorFactory)) && _ao0(input, _path + "", true) || _assertGuard_1._assertGuard(true, {
+                        method: "typia.assert",
+                        path: _path + "",
+                        expected: "IEvidenceSourceSnapshot",
+                        value: input
+                    }, _errorFactory))(input, "$input", true);
+                }
+                return input;
+            };
+        })()(snapshot));
+        const inventory = this.inventory(input);
+        if (input.files.length === 0)
+            return new EvidenceInventory_1.EvidenceInventory([inventory]).snapshot();
+        // Keep every document's outcome: one failed normalization must not discard
+        // useful diagnostics from peers or be interpreted as an empty operation set.
+        const loaded = await Promise.allSettled(input.files.map((source) => SwaggerDocumentLoader_1.SwaggerDocumentLoader.load(source)));
+        loaded.forEach((entry, index) => {
+            const source = input.files[index];
+            if (source === undefined)
+                return;
+            if (entry.status === "rejected") {
+                const reason = entry.reason;
+                inventory.complete = false;
+                inventory.diagnostics.push({
+                    code: "swagger-normalization-failed",
+                    severity: "error",
+                    message: `The Swagger document could not be normalized: ${this.message(reason)}`,
+                    repair: "Correct the JSON/YAML document and use a Swagger 2.0 or supported OpenAPI 3.x shape.",
+                    location: { file: source.physicalPath },
+                });
+            }
+            else
+                this.materialize(inventory, source, entry.value.operations);
+        });
+        return new EvidenceInventory_1.EvidenceInventory([inventory]).snapshot();
+    }
+    /**
+     * Loads one exact local document or explicitly configured HTTP(S) URL.
+     *
+     * Local paths resolve from the configuration-relative root and use source-loader
+     * dependency tracking. Remote bytes become a synthetic source snapshot without
+     * filesystem dependencies. Access and normalization failures return incomplete
+     * inventory diagnostics for the requested document.
+     */
+    async load(configFile, file, root = ".") {
+        let display = file;
+        try {
+            if (file === "" || file.trim() !== file)
+                throw new Error("A Swagger source must not be empty or padded.");
+            const remote = SwaggerRemoteReader_1.SwaggerRemoteReader.parse(file);
+            if (remote === undefined)
+                return await this.analyze(await EvidenceSourceLoader_1.EvidenceSourceLoader.file(configFile, file, root));
+            display = SwaggerRemoteReader_1.SwaggerRemoteReader.display(remote);
+            const read = await SwaggerRemoteReader_1.SwaggerRemoteReader.read(remote);
+            const absoluteRoot = SourcePath_1.SourcePath.root(configFile, root);
+            return await this.analyze({
+                root: {
+                    declared: root,
+                    absolute: absoluteRoot,
+                    display: SourcePath_1.SourcePath.display(node_path_1.default.dirname(node_path_1.default.resolve(configFile)), absoluteRoot),
+                },
+                files: [
+                    {
+                        id: `swagger:remote:${(0, node_crypto_1.createHash)("sha256").update(file).digest("hex")}`,
+                        physicalPath: display,
+                        content: read.content,
+                        digest: read.digest,
+                        addresses: [
+                            {
+                                absolute: display,
+                                relative: display,
+                                display,
+                            },
+                        ],
+                    },
+                ],
+                dependencies: [],
+                diagnostics: [],
+                complete: true,
+            });
+        }
+        catch (cause) {
+            return this.failure(display, cause);
+        }
+    }
+    /**
+     * Seeds an operation inventory with snapshot provenance and discovery failures.
+     *
+     * Operation and annotation collections remain empty until document normalization
+     * establishes supported API structure and source mappings.
+     */
+    inventory(input) {
+        return {
+            schemaVersion: 1,
+            sources: input.files,
+            annotationRanges: [],
+            units: [],
+            addresses: [],
+            hosts: [],
+            declarations: [],
+            reviews: [],
+            diagnostics: input.diagnostics.map((diagnostic) => ({
+                code: `source-${diagnostic.code}`,
+                severity: "error",
+                message: diagnostic.message,
+                repair: "Restore access to the selected Swagger source before evaluating coverage.",
+                location: { file: diagnostic.path },
+            })),
+            dependencies: input.dependencies,
+            complete: input.complete,
+        };
+    }
+    /**
+     * Creates semantic operation units and mapped description carriers.
+     *
+     * Source identity qualifies each operation token so separate documents do not
+     * merge accidentally. Operations remain represented even when no description
+     * supplies an annotation, preserving per-host coverage requirements.
+     */
+    materialize(inventory, source, operations) {
+        const text = new SourceText_1.SourceText(source.content);
+        for (const operation of operations) {
+            const range = operation.location?.range ?? text.range(0, 0);
+            const unitId = `swagger:${source.id}:${operation.target}`;
+            const site = {
+                id: `${unitId}:site`,
+                file: source.physicalPath,
+                range,
+                content: [range],
+            };
+            const unit = {
+                id: unitId,
+                type: "swagger",
+                symbol: "operation",
+                identity: [operation.target],
+                name: operation.target,
+                contentDigest: operation.digest,
+                sites: [site],
+                withdrawals: [],
+            };
+            inventory.units.push(unit);
+            inventory.addresses.push({
+                unitId,
+                file: "swagger:",
+                segments: [operation.target],
+            });
+            const mapping = operation.location?.description;
+            const host = {
+                id: `${unitId}:description`,
+                file: source.physicalPath,
+                range: mapping?.range ?? range,
+                origins: source.addresses.map((address) => address.absolute),
+                siteId: site.id,
+                unitIds: [unit.id],
+                attachment: "attached",
+            };
+            inventory.hosts.push(host);
+            if (mapping !== undefined)
+                this.parse(inventory, source, host, mapping);
+            else if (operation.description !== undefined &&
+                SwaggerDescription_1.SwaggerDescription.hasMetadata(operation.description)) {
+                inventory.complete = false;
+                inventory.diagnostics.push({
+                    code: "swagger-description-location",
+                    severity: "error",
+                    message: `The description for '${operation.target}' contains Evidence metadata without a verifiable source scalar.`,
+                    repair: "Write the operation description as a direct JSON/YAML string or scalar alias so its annotation positions can be verified.",
+                    location: { file: source.physicalPath, range },
+                    hostId: host.id,
+                });
+            }
+        }
+    }
+    parse(inventory, source, host, mapping) {
+        const documentation = {
+            hostId: host.id,
+            text: mapping.text,
+            offsets: mapping.offsets,
+            ends: mapping.ends,
+            tagBoundaries: false,
+            allowWithdrawal: false,
+        };
+        const parsed = EvidenceTagParser_1.EvidenceTagParser.parse(source.content, host, documentation);
+        inventory.declarations.push(...parsed.declarations);
+        inventory.reviews.push(...parsed.reviews);
+        inventory.diagnostics.push(...parsed.diagnostics);
+        inventory.annotationRanges.push(...parsed.declarations.map((entry) => entry.location), ...parsed.reviews.map((entry) => entry.location), ...parsed.diagnostics
+            .map((entry) => entry.location)
+            .filter((entry) => entry !== undefined));
+    }
+    failure(file, cause) {
+        return new EvidenceInventory_1.EvidenceInventory([
+            {
+                schemaVersion: 1,
+                sources: [],
+                annotationRanges: [],
+                units: [],
+                addresses: [],
+                hosts: [],
+                declarations: [],
+                reviews: [],
+                diagnostics: [
+                    {
+                        code: "swagger-source-failed",
+                        severity: "error",
+                        message: `The Swagger source could not be loaded: ${this.message(cause)}`,
+                        repair: "Correct the exact local path or HTTP(S) URL and restore access to the document.",
+                        location: { file },
+                    },
+                ],
+                dependencies: [],
+                complete: false,
+            },
+        ]).snapshot();
+    }
+    message(cause) {
+        return cause instanceof Error ? cause.message : String(cause);
+    }
+}
+exports.EvidenceSwaggerAdapter = EvidenceSwaggerAdapter;

package/lib/adapters/swagger/IRemoteSwaggerSource.d.ts

@@ -0,0 +1,19 @@
+/** Bounded UTF-8 response read from one configured Swagger URL.
+ *
+ * Remote loading owns the bytes and their digest together so later parsing and
+ * caching describe the exact response that passed the size limit.
+ */
+export interface IRemoteSwaggerSource {
+    /** Decoded response content.
+     *
+     * The reader accepts only valid UTF-8, so loaders may parse this text without
+     * applying a replacement-character normalization.
+     */
+    content: string;
+    /** SHA-256 identity of the received bytes.
+     *
+     * This remains byte-based because semantically equal decoded strings can have
+     * arrived from different invalid or normalized encodings.
+     */
+    digest: string;
+}

package/lib/adapters/swagger/IRemoteSwaggerSource.js

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

package/lib/adapters/swagger/ISwaggerCacheEntry.d.ts

@@ -0,0 +1,18 @@
+import type { ISwaggerLoadResult } from "./ISwaggerLoadResult";
+/** Remembered normalization outcome for one exact document digest.
+ *
+ * The cache records failures as well as results so a malformed unchanged source
+ * has deterministic behavior without repeating conversion work.
+ */
+export interface ISwaggerCacheEntry {
+    /** Successful operation inventory, when normalization completed.
+     *
+     * Omission means this entry represents the failure below.
+     */
+    result?: ISwaggerLoadResult;
+    /** Stable failure message for the cached input.
+     *
+     * Omission means the result is safe to clone for a caller.
+     */
+    problem?: string;
+}

package/lib/adapters/swagger/ISwaggerCacheEntry.js

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

package/lib/adapters/swagger/ISwaggerLoadResult.d.ts

@@ -0,0 +1,13 @@
+import type { ISwaggerOperation } from "./ISwaggerOperation";
+/** Normalized operations from one Swagger or OpenAPI document.
+ *
+ * The loader converts accepted source versions to this version-neutral shape
+ * before the adapter materializes public operation units.
+ */
+export interface ISwaggerLoadResult {
+    /** Operations ordered by their public targets.
+     *
+     * Each target occurs at most once; duplicates are rejected during loading.
+     */
+    operations: ISwaggerOperation[];
+}

package/lib/adapters/swagger/ISwaggerLoadResult.js

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

package/lib/adapters/swagger/ISwaggerOperation.d.ts

@@ -0,0 +1,42 @@
+import type { ISwaggerOperationLocation } from "./ISwaggerOperationLocation";
+/** One normalized Swagger operation and its semantic fingerprint input.
+ *
+ * This separates the public operation address from content used to detect a
+ * schema change, while retaining optional source coordinates for diagnostics.
+ */
+export interface ISwaggerOperation {
+    /**
+     * Stores the uppercase HTTP method forming the public target prefix.
+     *
+     * Normalization keeps OpenAPI method spelling independent from target matching.
+     */
+    method: string;
+    /**
+     * Stores the absolute OpenAPI path forming the public target suffix.
+     *
+     * Its literal path spelling remains distinct from the HTTP method identity.
+     */
+    path: string;
+    /**
+     * Provides the stable public address in `METHOD:/path` form.
+     *
+     * Evidence tags resolve operations through this combined method-and-path identity.
+     */
+    target: string;
+    /** Digest of canonical operation semantics.
+     *
+     * Description metadata and reference indirection are normalized before this
+     * value is computed, keeping review state tied to API meaning.
+     */
+    digest: string;
+    /** Original description text, when the operation supplies one.
+     *
+     * Omission distinguishes no description from an explicitly empty string.
+     */
+    description?: string;
+    /** Source coordinates for the operation and mapped description, when known.
+     *
+     * Converted or aliased YAML may not have a direct scalar location.
+     */
+    location?: ISwaggerOperationLocation;
+}

package/lib/adapters/swagger/ISwaggerOperation.js

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

package/lib/adapters/swagger/ISwaggerOperationLocation.d.ts

@@ -0,0 +1,21 @@
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IYamlScalarMapping } from "./IYamlScalarMapping";
+/** Source spans for one normalized Swagger operation and its description.
+ *
+ * Locations are optional on operations because OpenAPI conversion can preserve
+ * semantics for values that do not map to one source token.
+ */
+export interface ISwaggerOperationLocation {
+    /**
+     * Locates the full operation node used as the physical unit site.
+     *
+     * The range keeps diagnostics and fingerprints tied to the original document.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Maps description characters when the scalar has a source-backed location.
+     *
+     * Omission means converted or aliased content has no direct scalar token.
+     */
+    description?: IYamlScalarMapping;
+}

package/lib/adapters/swagger/ISwaggerOperationLocation.js

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