@wrtnlabs/evidence 0.0.0

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

@@ -0,0 +1,26 @@
+import type { IRemoteSwaggerSource } from "./IRemoteSwaggerSource";
+/** Validates and reads explicitly configured HTTP(S) Swagger sources.
+ *
+ * Remote input is intentionally bounded before parsing so a configured URL
+ * cannot turn schema discovery into an unbounded memory or time consumer.
+ */
+export declare namespace SwaggerRemoteReader {
+    /** Parses a configured remote source only when it has a URL scheme.
+     *
+     * Returning `undefined` leaves ordinary paths to the local-source loader;
+     * explicit remote URLs must be HTTP(S) and cannot use fragments.
+     */
+    function parse(source: string): URL | undefined;
+    /** Reads one remote document and fingerprints the exact accepted bytes.
+     *
+     * The content-length preflight and streamed byte count enforce the same limit
+     * when a server omits or lies about its response header.
+     */
+    function read(url: URL): Promise<IRemoteSwaggerSource>;
+    /** Renders a safe source label for diagnostics.
+     *
+     * Query values may carry credentials or arbitrary user data, so their
+     * presence is retained while their contents are never exposed.
+     */
+    function display(url: URL): string;
+}

package/lib/adapters/swagger/SwaggerRemoteReader.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwaggerRemoteReader = void 0;
+const node_crypto_1 = require("node:crypto");
+const MAX_DOCUMENT_BYTES = 16 * 1024 * 1024;
+const REMOTE_TIMEOUT_MILLISECONDS = 30_000;
+/** Validates and reads explicitly configured HTTP(S) Swagger sources.
+ *
+ * Remote input is intentionally bounded before parsing so a configured URL
+ * cannot turn schema discovery into an unbounded memory or time consumer.
+ */
+var SwaggerRemoteReader;
+(function (SwaggerRemoteReader) {
+    /** Parses a configured remote source only when it has a URL scheme.
+     *
+     * Returning `undefined` leaves ordinary paths to the local-source loader;
+     * explicit remote URLs must be HTTP(S) and cannot use fragments.
+     */
+    function parse(source) {
+        if (!/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(source))
+            return undefined;
+        const url = new URL(source);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            throw new Error("Only HTTP(S) URLs can name a remote Swagger source.");
+        if (url.hash !== "")
+            throw new Error("A remote Swagger document URL must not contain a fragment.");
+        return url;
+    }
+    SwaggerRemoteReader.parse = parse;
+    /** Reads one remote document and fingerprints the exact accepted bytes.
+     *
+     * The content-length preflight and streamed byte count enforce the same limit
+     * when a server omits or lies about its response header.
+     */
+    async function read(url) {
+        const response = await fetch(url, {
+            signal: AbortSignal.timeout(REMOTE_TIMEOUT_MILLISECONDS),
+        });
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status} ${response.statusText === "" ? "response" : response.statusText}`);
+        const declared = Number(response.headers.get("content-length"));
+        if (Number.isFinite(declared) && declared > MAX_DOCUMENT_BYTES)
+            throw new Error(`The Swagger document exceeds the ${MAX_DOCUMENT_BYTES} byte limit.`);
+        if (response.body === null)
+            return decode(new Uint8Array());
+        const reader = response.body.getReader();
+        const chunks = [];
+        let length = 0;
+        let next = await reader.read();
+        while (next.done === false) {
+            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);
+            next = await reader.read();
+        }
+        const bytes = new Uint8Array(length);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return decode(bytes);
+    }
+    SwaggerRemoteReader.read = read;
+    /** Renders a safe source label for diagnostics.
+     *
+     * Query values may carry credentials or arbitrary user data, so their
+     * presence is retained while their contents are never exposed.
+     */
+    function display(url) {
+        const query = url.search === "" ? "" : "?<redacted>";
+        return `${url.origin}${url.pathname}${query}`;
+    }
+    SwaggerRemoteReader.display = display;
+})(SwaggerRemoteReader || (exports.SwaggerRemoteReader = SwaggerRemoteReader = {}));
+/** Decodes accepted bytes and keeps a byte-exact cache identity.
+ *
+ * Digesting before text parsing makes cache ownership independent of Unicode
+ * normalization performed by later document processing.
+ */
+function decode(bytes) {
+    return {
+        content: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+        digest: (0, node_crypto_1.createHash)("sha256").update(bytes).digest("hex"),
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { IEvidenceAddress } from "../../structures/IEvidenceAddress";
+/** Parses one whitespace-free Swagger operation target.
+ *
+ * Swagger has no physical source-file address, so accepted selectors are placed
+ * in the synthetic `swagger:` file namespace as one atomic segment.
+ */
+export declare namespace SwaggerTarget {
+    /** Converts a public `METHOD:/path` selector to an Evidence address.
+     *
+     * Validation here matches loader targets so a citation cannot select an
+     * operation shape the adapter would never materialize.
+     */
+    function parse(target: string): IEvidenceAddress;
+}

package/lib/adapters/swagger/SwaggerTarget.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwaggerTarget = void 0;
+/** Parses one whitespace-free Swagger operation target.
+ *
+ * Swagger has no physical source-file address, so accepted selectors are placed
+ * in the synthetic `swagger:` file namespace as one atomic segment.
+ */
+var SwaggerTarget;
+(function (SwaggerTarget) {
+    /** Converts a public `METHOD:/path` selector to an Evidence address.
+     *
+     * Validation here matches loader targets so a citation cannot select an
+     * operation shape the adapter would never materialize.
+     */
+    function parse(target) {
+        if (/\s/u.test(target))
+            throw new Error("Remove whitespace from the Swagger operation target.");
+        const separator = target.indexOf(":");
+        const method = separator < 0 ? "" : target.slice(0, separator);
+        const path = separator < 0 ? "" : target.slice(separator + 1);
+        if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/u.test(method) ||
+            method !== method.toUpperCase() ||
+            !path.startsWith("/"))
+            throw new Error("Use an uppercase METHOD:/path target such as POST:/members.");
+        return { file: "swagger:", segments: [target] };
+    }
+    SwaggerTarget.parse = parse;
+})(SwaggerTarget || (exports.SwaggerTarget = SwaggerTarget = {}));

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

@@ -0,0 +1,11 @@
+import type { Scalar } from "yaml";
+import type { IYamlScalarMapping } from "./IYamlScalarMapping";
+/**
+ * Maps a decoded YAML string scalar back to its original UTF-16 token.
+ *
+ * Swagger documentation extraction needs this mapping because YAML escape
+ * decoding changes text length while Evidence diagnostics must address source.
+ */
+export declare namespace YamlScalarMapper {
+    function map(content: string, node: Scalar<string>): IYamlScalarMapping | undefined;
+}

package/lib/adapters/swagger/YamlScalarMapper.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YamlScalarMapper = void 0;
+const SourceText_1 = require("../../internal/SourceText");
+/**
+ * Maps a decoded YAML string scalar back to its original UTF-16 token.
+ *
+ * Swagger documentation extraction needs this mapping because YAML escape
+ * decoding changes text length while Evidence diagnostics must address source.
+ */
+var YamlScalarMapper;
+(function (YamlScalarMapper) {
+    function map(content, node) {
+        const tuple = node.range;
+        if (tuple === undefined || tuple === null)
+            return undefined;
+        const source = new SourceText_1.SourceText(content);
+        const range = source.range(tuple[0], tuple[1]);
+        const text = node.value;
+        const offsets = [];
+        const ends = [];
+        let cursor = tuple[0];
+        let escapedStart = cursor;
+        let escapedEnd = cursor;
+        let escapedUnits = 0;
+        if (node.type === "QUOTE_DOUBLE" || node.type === "QUOTE_SINGLE")
+            ++cursor;
+        for (let index = 0; index < text.length; ++index) {
+            if (escapedUnits > 0) {
+                offsets.push(escapedStart);
+                ends.push(escapedEnd);
+                escapedStart = escapedEnd;
+                --escapedUnits;
+                continue;
+            }
+            if (node.type === "QUOTE_DOUBLE" && content[cursor] === "\\") {
+                const escape = escaped(content, cursor, tuple[1]);
+                const unitEnd = escape[1] === 1
+                    ? escape[0]
+                    : cursor + Math.floor((escape[0] - cursor) / escape[1]);
+                offsets.push(cursor);
+                ends.push(unitEnd);
+                escapedStart = unitEnd;
+                escapedEnd = escape[0];
+                escapedUnits = escape[1] - 1;
+                cursor = escape[0];
+                continue;
+            }
+            const found = content.indexOf(text[index] ?? "", cursor);
+            if (found >= cursor && found < tuple[1]) {
+                offsets.push(found);
+                ends.push(found + 1);
+                cursor = found + 1;
+            }
+            else {
+                const start = Math.min(cursor, tuple[1]);
+                const end = Math.min(start + 1, tuple[1]);
+                offsets.push(start);
+                ends.push(end);
+                cursor = end;
+            }
+        }
+        offsets.push(Math.min(cursor, tuple[1]));
+        return { text, range, offsets, ends };
+    }
+    YamlScalarMapper.map = map;
+})(YamlScalarMapper || (exports.YamlScalarMapper = YamlScalarMapper = {}));
+function escaped(content, start, limit) {
+    const marker = content[start + 1];
+    const length = marker === "x" ? 4 : marker === "u" ? 6 : marker === "U" ? 10 : 2;
+    const end = Math.min(start + length, limit);
+    if (marker !== "U")
+        return [end, 1];
+    const value = Number.parseInt(content.slice(start + 2, end), 16);
+    return [end, Number.isFinite(value) && value > 0xffff ? 2 : 1];
+}

package/lib/adapters/swift/EvidenceSwiftAdapter.d.ts

@@ -0,0 +1,15 @@
+import { SwiftAdapter } from "./SwiftAdapter";
+/**
+ * Extracts explicit public and open Swift declarations within one selected module.
+ *
+ * Local nominal extensions and protocol requirements participate in ownership
+ * reconciliation before publication. Overloads group by base name, static members
+ * use an explicit static segment, and attached DocC retains the declaration site
+ * that owns each annotation. Separately configured module roots remain independent.
+ *
+ * External or constrained extensions, macro and custom-attribute expansion,
+ * conditional compilation, and generated or inherited members are outside this
+ * declared-source boundary.
+ */
+export declare class EvidenceSwiftAdapter extends SwiftAdapter {
+}

package/lib/adapters/swift/EvidenceSwiftAdapter.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceSwiftAdapter = void 0;
+const SwiftAdapter_1 = require("./SwiftAdapter");
+/**
+ * Extracts explicit public and open Swift declarations within one selected module.
+ *
+ * Local nominal extensions and protocol requirements participate in ownership
+ * reconciliation before publication. Overloads group by base name, static members
+ * use an explicit static segment, and attached DocC retains the declaration site
+ * that owns each annotation. Separately configured module roots remain independent.
+ *
+ * External or constrained extensions, macro and custom-attribute expansion,
+ * conditional compilation, and generated or inherited members are outside this
+ * declared-source boundary.
+ */
+class EvidenceSwiftAdapter extends SwiftAdapter_1.SwiftAdapter {
+}
+exports.EvidenceSwiftAdapter = EvidenceSwiftAdapter;

package/lib/adapters/swift/ISwiftDeclaration.d.ts

@@ -0,0 +1,91 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+/**
+ * Represents one explicit Swift declaration before module-wide extension reconciliation.
+ *
+ * Extensions, aliases, and nominal declarations are recorded separately so the
+ * adapter can attach members to their real type without losing their source site.
+ */
+export interface ISwiftDeclaration {
+    /**
+     * Extraction identity of the physical declaration.
+     *
+     * Documentation attachments use this scanner-local key before semantic units are materialized.
+     */
+    id: string;
+    /**
+     * Literal declaration name, with overloads grouped by base name.
+     *
+     * The adapter uses identity and symbol to distinguish families beyond this display name.
+     */
+    name: string;
+    /**
+     * Common programming selector.
+     *
+     * It supplies Evidence's language-independent category for population selection.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Module-relative semantic ownership segments.
+     *
+     * Ownership resolution rewrites extension members to the resolved nominal path.
+     */
+    identity: string[];
+    /**
+     * File-qualified accessor segments.
+     *
+     * The adapter publishes these segments with the configured source address.
+     */
+    address: string[];
+    /**
+     * Original source site used for fingerprints and attached hosts.
+     *
+     * Reconciled declarations retain their distinct physical sites in one unit.
+     */
+    site: IEvidenceUnitSite;
+    /**
+     * Effective public/open visibility after ownership resolution.
+     *
+     * A public member still becomes unavailable when an enclosing owner is inaccessible.
+     */
+    public: boolean;
+    /**
+     * Marks a record that reopens a nominal type instead of defining one.
+     *
+     * Extension records contribute their source position and documentation, while
+     * their members acquire identity from the resolved nominal target.
+     */
+    extension: boolean;
+    /**
+     * Names the statically recognized target of an extension or type alias.
+     *
+     * Omission preserves an unresolved boundary so the adapter can diagnose it
+     * instead of inventing a public owner from textual spelling.
+     */
+    target?: string[];
+    /**
+     * States whether `target` names a type alias rather than its final nominal type.
+     *
+     * The ownership resolver follows aliases deliberately, avoiding a merge with
+     * an unrelated type that happens to share the alias's source spelling.
+     */
+    alias: boolean;
+    /**
+     * Declaration kind controlling member visibility defaults.
+     *
+     * The scanner uses it for protocol and extension behavior without reparsing the node.
+     */
+    form: string;
+    /**
+     * Whether nominal lookup is restricted to this physical file.
+     *
+     * Local aliases and extensions cannot resolve a fileprivate target in another file.
+     */
+    filePrivate: boolean;
+    /**
+     * Explicit lexical owner, retained independently of accessor text.
+     *
+     * Parent traversal uses this key so literal name segments do not imply containment.
+     */
+    ownerDeclarationId?: string;
+}

package/lib/adapters/swift/ISwiftDeclaration.js

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

package/lib/adapters/swift/ISwiftDocumentation.d.ts

@@ -0,0 +1,35 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { ISwiftDocumentationAttachment } from "./ISwiftDocumentationAttachment";
+/**
+ * Represents a Swift documentation carrier or tag-bearing unsupported carrier.
+ *
+ * Its physical range stays independent of nominal reconciliation, preserving a
+ * DocC host at the extension site that originally carries the annotation.
+ */
+export interface ISwiftDocumentation {
+    /**
+     * Identifies this physical documentation carrier within its source analysis.
+     *
+     * Attachments use this key before the adapter materializes semantic units.
+     */
+    id: string;
+    /**
+     * Locates the half-open UTF-16 span occupied by the documentation carrier.
+     *
+     * Review fingerprints exclude this range from its attached declaration content.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Describes delimiters and annotation rules for parsing this carrier.
+     *
+     * Documentation mapping preserves these rules while masking ineligible examples.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /**
+     * Lists physical declaration sites directly attached to this carrier.
+     *
+     * Unsupported tagged carriers remain unattached for diagnostic host creation.
+     */
+    attachments: ISwiftDocumentationAttachment[];
+}

package/lib/adapters/swift/ISwiftDocumentation.js

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

package/lib/adapters/swift/ISwiftDocumentationAttachment.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Associates parsed DocC with one Swift declaration site.
+ *
+ * The scanner keeps this relation separate from comment mappings so semantic
+ * assembly can attach documentation without losing its source range.
+ */
+export interface ISwiftDocumentationAttachment {
+    /**
+     * Identifies the declaration that owns the attached DocC mapping.
+     *
+     * This extraction identity remains stable while the adapter constructs units
+     * and their documentation references.
+     */
+    declarationId: string;
+    /**
+     * Identifies the declaration site at which the DocC comment appears.
+     *
+     * The site disambiguates extensions and other declarations contributing to
+     * the same semantic unit.
+     */
+    siteId: string;
+}

package/lib/adapters/swift/ISwiftDocumentationAttachment.js

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

package/lib/adapters/swift/ISwiftFileAnalysis.d.ts

@@ -0,0 +1,43 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { ISwiftDeclaration } from "./ISwiftDeclaration";
+import type { ISwiftDocumentation } from "./ISwiftDocumentation";
+/**
+ * Holds the node-free Swift extraction retained after a parse session closes.
+ *
+ * Module-wide nominal and alias resolution consumes these records after parsing,
+ * so they retain source sites and boundaries without borrowing tree nodes.
+ */
+export interface ISwiftFileAnalysis {
+    /**
+     * Original selected source snapshot.
+     *
+     * Materialization uses its physical path and configured addresses for units and hosts.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Extracted declarations, including non-public boundaries.
+     *
+     * Ownership reconciliation needs inaccessible records to determine the public surface.
+     */
+    declarations: ISwiftDeclaration[];
+    /**
+     * Classified documentation and unsupported annotation carriers.
+     *
+     * Unattached tag-bearing carriers remain available for diagnostic hosts.
+     */
+    documentation: ISwiftDocumentation[];
+    /**
+     * Failures encountered while establishing the public surface.
+     *
+     * The adapter propagates them instead of treating omitted declarations as absent.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * States whether all surface-affecting Swift forms were classified.
+     *
+     * This failure signal is preserved through extension reconciliation so absent
+     * declarations cannot disappear from the coverage denominator.
+     */
+    complete: boolean;
+}

package/lib/adapters/swift/ISwiftFileAnalysis.js

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

package/lib/adapters/swift/SwiftAdapter.d.ts

@@ -0,0 +1,108 @@
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
+/**
+ * Reconciles Swift extension ownership and DocC within one configured module.
+ *
+ * The scanner records explicit declarations before snapshot-wide ownership
+ * resolution links extensions and nominal types. Materialization includes the
+ * root identity so equal declarations in separate module selections stay distinct.
+ * Documentation then attaches to the reconciled owners, while source dependencies
+ * retain every physical file needed to invalidate the analysis.
+ */
+export declare class SwiftAdapter implements IEvidenceAdapter {
+    /**
+     * Swift discriminator for explicit public and open source declarations.
+     *
+     * The module boundary comes from the snapshot root. This value selects Swift
+     * grammar and visibility rules without inferring generated members.
+     */
+    readonly type = "swift";
+    /**
+     * Builds a module-scoped Swift inventory from a captured source population.
+     *
+     * Extension ownership resolves before units are published. Inaccessible input,
+     * unsupported ownership, and syntax failures remain incomplete findings; the
+     * invocation releases its parser regardless of the materialization outcome.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
+    private scan;
+    /**
+     * Reconciles overload families and retains each physical declaration address.
+     *
+     * Conflicting public identities remain incomplete instead of being merged by source order.
+     */
+    private materializeUnits;
+    /**
+     * Allows a protocol requirement and its explicit extension property implementation to share a unit.
+     *
+     * Other repeated non-function declarations remain conflicts because they do not establish this pairing.
+     */
+    private protocolDefault;
+    /**
+     * Resolves withdrawals before publishing attached annotation hosts.
+     *
+     * Hidden units remain unavailable to ordinary tags while their withdrawal location stays diagnostic context.
+     */
+    private materializeDocumentation;
+    /**
+     * Retains public declaration sites even when they carry no documentation.
+     *
+     * Host policies can therefore distinguish an eligible untagged site from missing extraction.
+     */
+    private materializeUndocumentedHosts;
+    /**
+     * Groups published semantic owners by their physical declaration site.
+     *
+     * One documentation carrier can attach to several selected units at the same source occurrence.
+     */
+    private attachmentGroups;
+    /**
+     * Creates an attached or explicitly unsupported documentation carrier.
+     *
+     * Unsupported annotation carriers retain repair guidance rather than being discarded.
+     */
+    private host;
+    /**
+     * Parses Evidence tags only after the adapter establishes their host.
+     *
+     * Host ownership determines the source context in which authored targets resolve.
+     */
+    private parse;
+    /**
+     * Detects Evidence or withdrawal annotations outside masked examples.
+     *
+     * The result decides whether an otherwise unsupported carrier needs a diagnostic host.
+     */
+    private annotation;
+    /**
+     * Detects acknowledgements and reviews on withdrawn carriers.
+     *
+     * Withdrawal directives themselves are excluded so they can be processed as visibility state.
+     */
+    private claimAnnotation;
+    /**
+     * Recognizes supported annotation names at documentation line boundaries.
+     *
+     * Restricting the match avoids treating inline prose or example fragments as annotations.
+     */
+    private annotationPattern;
+    /**
+     * Follows explicit parent ownership to propagate withdrawal.
+     *
+     * The visited set rejects cycles while preserving the nearest valid hidden ancestor.
+     */
+    private withdrawn;
+    /**
+     * Separates programming kinds while unifying module-scoped overload identities.
+     *
+     * The module root keeps equal source-relative declarations in different selections distinct.
+     */
+    private unitId;
+    /**
+     * Marks a declaration conflict as incomplete analysis.
+     *
+     * The diagnostic remains associated with the source analysis that supplied the conflict.
+     */
+    private problem;
+}