@wrtnlabs/evidence 0.0.0 → 0.1.0

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

@@ -1,26 +0,0 @@
-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

@@ -1,89 +0,0 @@
-"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

@@ -1,14 +0,0 @@
-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

@@ -1,29 +0,0 @@
-"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

@@ -1,11 +0,0 @@
-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

@@ -1,76 +0,0 @@
-"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/ISwiftDeclaration.d.ts

@@ -1,91 +0,0 @@
-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/ISwiftDocumentation.d.ts

@@ -1,35 +0,0 @@
-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/ISwiftDocumentationAttachment.d.ts

@@ -1,22 +0,0 @@
-/**
- * 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/ISwiftFileAnalysis.d.ts

@@ -1,43 +0,0 @@
-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/SwiftAdapter.d.ts

@@ -1,108 +0,0 @@
-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;
-}