@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/swift/EvidenceSwiftOwnership.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceSwiftOwnership = void 0;
+/**
+ * Reconciles extensions against nominal declarations in one configured Swift
+ * module.
+ *
+ * The pass resolves selected local aliases without importing compiler metadata,
+ * then propagates visibility from the verified nominal owner to extension
+ * members.
+ */
+var EvidenceSwiftOwnership;
+(function (EvidenceSwiftOwnership) {
+    /**
+     * Resolves local aliases and extension-introduced types before propagating
+     * visibility.
+     *
+     * Repeated passes handle declarations whose owner is another pending
+     * extension; unresolved cycles remain incomplete instead of gaining an
+     * invented owner.
+     */
+    function resolve(analyses) {
+        const declarations = analyses.flatMap((analysis) => analysis.declarations);
+        const ids = new Map(declarations.map((declaration) => [declaration.id, declaration]));
+        const pending = new Set(declarations.filter((declaration) => declaration.extension));
+        let progress = true;
+        while (progress && pending.size !== 0) {
+            progress = false;
+            const types = new Map();
+            for (const declaration of declarations)
+                if (declaration.symbol === "type" &&
+                    !declaration.extension &&
+                    ![...pending].some((extension) => descends(declaration, extension.id, ids))) {
+                    const key = JSON.stringify(declaration.identity);
+                    types.set(key, [...(types.get(key) ?? []), declaration]);
+                }
+            for (const declaration of pending) {
+                const target = nominal(declaration.target ?? [], types, declaration.site.file, new Set());
+                if (target === undefined)
+                    continue;
+                const old = declaration.address;
+                declaration.address = [...target.address];
+                declaration.identity = [...target.identity];
+                declaration.name = target.name;
+                declaration.public = target.public;
+                if (target.ownerDeclarationId === undefined)
+                    delete declaration.ownerDeclarationId;
+                else
+                    declaration.ownerDeclarationId = target.ownerDeclarationId;
+                for (const child of declarations)
+                    if (descends(child, declaration.id, ids)) {
+                        child.address = [
+                            ...target.address,
+                            ...child.address.slice(old.length),
+                        ];
+                        child.identity = [...child.address];
+                    }
+                pending.delete(declaration);
+                progress = true;
+            }
+        }
+        for (const declaration of pending) {
+            declaration.public = false;
+            const analysis = analyses.find((entry) => entry.source.physicalPath === declaration.site.file);
+            if (analysis === undefined)
+                continue;
+            analysis.complete = false;
+            analysis.diagnostics.push({
+                code: "swift-extension-ownership",
+                severity: "error",
+                message: `Extension '${declaration.address.join(".")}' requires one accessible selected local nominal type; external, ambiguous, cyclic, and generic ownership is unavailable.`,
+                repair: "Include the accessible local nominal owner in the configured Swift module or implement external type ownership before checking coverage.",
+                location: {
+                    file: analysis.source.physicalPath,
+                    range: declaration.site.range,
+                },
+            });
+        }
+        for (const declaration of declarations)
+            declaration.public &&= visible(declaration, ids, new Set());
+    }
+    EvidenceSwiftOwnership.resolve = resolve;
+    /**
+     * Resolves a unique accessible declaration and a finite chain of selected
+     * type aliases.
+     *
+     * A visited path set rejects cycles before they can grant an extension an
+     * invented owner.
+     */
+    function nominal(path, types, file, visited) {
+        const key = JSON.stringify(path);
+        if (visited.has(key))
+            return undefined;
+        visited.add(key);
+        const accessible = (types.get(key) ?? []).filter((declaration) => !declaration.filePrivate || declaration.site.file === file);
+        const local = accessible.filter((declaration) => declaration.filePrivate && declaration.site.file === file);
+        const matches = local.length !== 0 ? local : accessible;
+        if (matches.length !== 1)
+            return undefined;
+        const declaration = matches[0];
+        if (declaration === undefined)
+            return undefined;
+        if (!declaration.alias)
+            return ["class", "struct", "actor", "enum", "protocol"].includes(declaration.form)
+                ? declaration
+                : undefined;
+        if (declaration.target === undefined)
+            return undefined;
+        const scope = declaration.identity.slice(0, -1);
+        for (let length = scope.length; length >= 0; --length) {
+            const resolved = nominal([...scope.slice(0, length), ...declaration.target], types, declaration.site.file, new Set(visited));
+            if (resolved !== undefined)
+                return resolved;
+        }
+        return undefined;
+    }
+    /**
+     * Uses explicit declaration parents to distinguish literal names from
+     * containment.
+     *
+     * This preserves names that contain punctuation without interpreting them as
+     * paths.
+     */
+    function descends(declaration, parentId, ids) {
+        let owner = declaration.ownerDeclarationId;
+        const visited = new Set();
+        while (owner !== undefined && !visited.has(owner)) {
+            if (owner === parentId)
+                return true;
+            visited.add(owner);
+            owner = ids.get(owner)?.ownerDeclarationId;
+        }
+        return false;
+    }
+    /**
+     * Clamps descendant exposure to the effective public owner.
+     *
+     * Recursive ownership also rejects a malformed parent cycle from the
+     * published surface.
+     */
+    function visible(declaration, ids, visited) {
+        if (!declaration.public || visited.has(declaration.id))
+            return false;
+        visited.add(declaration.id);
+        const owner = declaration.ownerDeclarationId === undefined
+            ? undefined
+            : ids.get(declaration.ownerDeclarationId);
+        return owner === undefined || visible(owner, ids, visited);
+    }
+})(EvidenceSwiftOwnership || (exports.EvidenceSwiftOwnership = EvidenceSwiftOwnership = {}));

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

@@ -0,0 +1,102 @@
+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 IEvidenceSwiftDeclaration {
+    /**
+     * 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/IEvidenceSwiftDocumentation.d.ts

@@ -0,0 +1,37 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidenceSwiftDocumentationAttachment } from "./IEvidenceSwiftDocumentationAttachment";
+/**
+ * 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 IEvidenceSwiftDocumentation {
+    /**
+     * 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: IEvidenceSwiftDocumentationAttachment[];
+}

package/lib/adapters/swift/IEvidenceSwiftDocumentationAttachment.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 IEvidenceSwiftDocumentationAttachment {
+    /**
+     * 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/IEvidenceSwiftFileAnalysis.d.ts

@@ -0,0 +1,47 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceSwiftDeclaration } from "./IEvidenceSwiftDeclaration";
+import type { IEvidenceSwiftDocumentation } from "./IEvidenceSwiftDocumentation";
+/**
+ * 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 IEvidenceSwiftFileAnalysis {
+    /**
+     * 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: IEvidenceSwiftDeclaration[];
+    /**
+     * Classified documentation and unsupported annotation carriers.
+     *
+     * Unattached tag-bearing carriers remain available for diagnostic hosts.
+     */
+    documentation: IEvidenceSwiftDocumentation[];
+    /**
+     * 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/typescript/EvidenceTypeScriptAdapter.d.ts

@@ -1,29 +1,39 @@
-import { EcmaScriptAdapter } from "../ecmascript/EcmaScriptAdapter";
+import { EvidenceEcmaScriptAdapter } from "../ecmascript/EvidenceEcmaScriptAdapter";
 /**
- * Extracts static TypeScript and TSX exports into a language-neutral evidence inventory.
+ * Extracts static TypeScript and TSX exports into a language-neutral evidence
+ * inventory.
  *
- * The shared ECMAScript adapter reconciles declarations, overloads, and supported
- * local re-exports across the selected snapshot. Declaration JSDoc supplies
- * evidence hosts. File-qualified public paths retain aliases without duplicating
- * semantic units; instance members use a prototype segment, while static members
- * are addressed directly on the class.
+ * The shared ECMAScript adapter reconciles declarations, overloads, and
+ * supported local re-exports across the selected snapshot. Declaration JSDoc
+ * supplies evidence hosts. File-qualified public paths retain aliases without
+ * duplicating semantic units; instance members use a prototype segment, while
+ * static members are addressed directly on the class.
  *
  * Analysis reads declared source without a compiler Program. Package exports,
  * path aliases, ambient modules, global augmentations, and CommonJS export
  * assignments are outside this adapter's supported publication boundary.
  *
  * @example
- * const adapter: EvidenceTypeScriptAdapter = new EvidenceTypeScriptAdapter();
- * const inventory: IEvidenceInventory = await adapter.analyze(snapshot);
- * // api.ts#Client.prototype.send names an instance method.
- * // api.ts#Client.create names a static member.
+ *   const adapter: EvidenceTypeScriptAdapter =
+ *     new EvidenceTypeScriptAdapter();
+ *   const inventory: IEvidenceInventory = await adapter.analyze(snapshot);
+ *   // api.ts#Client.prototype.send names an instance method.
+ *   // api.ts#Client.create names a static member.
  */
-export declare class EvidenceTypeScriptAdapter extends EcmaScriptAdapter {
+export declare class EvidenceTypeScriptAdapter extends EvidenceEcmaScriptAdapter<"typescript"> {
     /**
-     * Configures the shared extractor for TypeScript grammar and publication rules.
+     * Configures the shared extractor for TypeScript grammar and publication
+     * rules.
      *
-     * Construction does not parse source. The inherited `analyze` operation selects
-     * TypeScript or TSX syntax from each file in the supplied snapshot.
+     * Construction does not parse source. The inherited `analyze` operation
+     * selects TypeScript or TSX syntax from each file in the supplied snapshot.
      */
     constructor();
+    /**
+     * TypeScript discriminator for the shared ECMAScript extraction pipeline.
+     *
+     * The literal return type lets adapter registries preserve this entry point's
+     * artifact identity without narrowing a shared base instance at runtime.
+     */
+    get type(): "typescript";
 }

package/lib/adapters/typescript/EvidenceTypeScriptAdapter.js

@@ -1,35 +1,47 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EvidenceTypeScriptAdapter = void 0;
-const EcmaScriptAdapter_1 = require("../ecmascript/EcmaScriptAdapter");
+const EvidenceEcmaScriptAdapter_1 = require("../ecmascript/EvidenceEcmaScriptAdapter");
 /**
- * Extracts static TypeScript and TSX exports into a language-neutral evidence inventory.
+ * Extracts static TypeScript and TSX exports into a language-neutral evidence
+ * inventory.
  *
- * The shared ECMAScript adapter reconciles declarations, overloads, and supported
- * local re-exports across the selected snapshot. Declaration JSDoc supplies
- * evidence hosts. File-qualified public paths retain aliases without duplicating
- * semantic units; instance members use a prototype segment, while static members
- * are addressed directly on the class.
+ * The shared ECMAScript adapter reconciles declarations, overloads, and
+ * supported local re-exports across the selected snapshot. Declaration JSDoc
+ * supplies evidence hosts. File-qualified public paths retain aliases without
+ * duplicating semantic units; instance members use a prototype segment, while
+ * static members are addressed directly on the class.
  *
  * Analysis reads declared source without a compiler Program. Package exports,
  * path aliases, ambient modules, global augmentations, and CommonJS export
  * assignments are outside this adapter's supported publication boundary.
  *
  * @example
- * const adapter: EvidenceTypeScriptAdapter = new EvidenceTypeScriptAdapter();
- * const inventory: IEvidenceInventory = await adapter.analyze(snapshot);
- * // api.ts#Client.prototype.send names an instance method.
- * // api.ts#Client.create names a static member.
+ *   const adapter: EvidenceTypeScriptAdapter =
+ *     new EvidenceTypeScriptAdapter();
+ *   const inventory: IEvidenceInventory = await adapter.analyze(snapshot);
+ *   // api.ts#Client.prototype.send names an instance method.
+ *   // api.ts#Client.create names a static member.
  */
-class EvidenceTypeScriptAdapter extends EcmaScriptAdapter_1.EcmaScriptAdapter {
+class EvidenceTypeScriptAdapter extends EvidenceEcmaScriptAdapter_1.EvidenceEcmaScriptAdapter {
     /**
-     * Configures the shared extractor for TypeScript grammar and publication rules.
+     * Configures the shared extractor for TypeScript grammar and publication
+     * rules.
      *
-     * Construction does not parse source. The inherited `analyze` operation selects
-     * TypeScript or TSX syntax from each file in the supplied snapshot.
+     * Construction does not parse source. The inherited `analyze` operation
+     * selects TypeScript or TSX syntax from each file in the supplied snapshot.
      */
     constructor() {
-        super("typescript", "TypeScript");
+        super("TypeScript");
+    }
+    /**
+     * TypeScript discriminator for the shared ECMAScript extraction pipeline.
+     *
+     * The literal return type lets adapter registries preserve this entry point's
+     * artifact identity without narrowing a shared base instance at runtime.
+     */
+    get type() {
+        return "typescript";
     }
 }
 exports.EvidenceTypeScriptAdapter = EvidenceTypeScriptAdapter;

package/lib/adapters/zig/EvidenceZigAdapter.d.ts

@@ -1,16 +1,124 @@
-import { ZigAdapter } from "./ZigAdapter";
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
 /**
- * Extracts explicit Zig pub declarations and fields of public containers.
+ * Materializes explicit Zig container declarations and their documentation
+ * hosts.
  *
- * The pinned grammar recognizes the configured Zig source syntax. Lexical
- * container paths establish public addresses, and bounded same-container aliases
- * retain canonical source identity. Attached documentation belongs to the original
- * declaration even when another public path exposes it.
- *
- * Namespace imports, usingnamespace, namespace comptime execution, computed public
- * types, and build-generated declarations are not evaluated. Unsupported forms
- * that can change the public surface must leave incomplete analysis rather than
- * a convenient subset of the declarations.
+ * File scanning establishes lexical visibility, supported aliases, and source
+ * attachment before publication. The adapter reconciles those declaration
+ * records into units and public addresses, then applies documentation and
+ * withdrawals through their real owners. It preserves unsupported source forms
+ * as incomplete findings rather than evaluating comptime code to guess a public
+ * surface.
  */
-export declare class EvidenceZigAdapter extends ZigAdapter {
+export declare class EvidenceZigAdapter implements IEvidenceAdapter<"zig"> {
+    /**
+     * Zig discriminator for the pinned declared-source extraction rules.
+     *
+     * It fixes grammar and container semantics for both graph roles; it does not
+     * authorize build execution or inferred declarations outside selected
+     * source.
+     */
+    get type(): "zig";
+    /**
+     * Extracts a fresh Zig inventory from a validated copy of the snapshot.
+     *
+     * Semantic publication precedes documentation so aliases keep the original
+     * owner and withdrawals. Completeness includes every scan's outcome, and the
+     * invocation releases parser resources on all completion paths.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
+    private scan;
+    /**
+     * Reconciles aliases into units while retaining every physical declaration
+     * address.
+     *
+     * Canonical identity deduplicates alias projections, whereas each supported
+     * public accessor contributes an address and its original source site remains
+     * reviewable.
+     */
+    private materializeUnits;
+    /**
+     * Resolves withdrawals before publishing attached documentation hosts.
+     *
+     * Processing withdrawals first prevents a hidden owner or descendant from
+     * retaining a claim host after its semantic unit becomes ineligible.
+     */
+    private materializeDocumentation;
+    /**
+     * Materializes public declaration sites that carry no documentation.
+     *
+     * These hosts preserve uncovered eligible units after attachment and
+     * withdrawal processing, grouping declarations that share one physical source
+     * site.
+     */
+    private materializeUndocumentedHosts;
+    /**
+     * Groups published semantic owners by their physical declaration site.
+     *
+     * A documentation carrier can affect several units at one site; each group
+     * becomes one host with deduplicated published unit identities.
+     */
+    private attachmentGroups;
+    /**
+     * Creates a host for an attached or explicitly unsupported documentation
+     * carrier.
+     *
+     * Unattached tag-bearing source receives an unsupported host so diagnostics
+     * retain a physical location instead of being discarded during
+     * materialization.
+     */
+    private host;
+    /**
+     * Parses Evidence tags after the adapter establishes their documentation
+     * host.
+     *
+     * Host identity and unit membership are required by tag parsing, so parsing
+     * cannot occur while alias and withdrawal eligibility remain unresolved.
+     */
+    private parse;
+    /**
+     * Detects Evidence or withdrawal annotations outside masked examples.
+     *
+     * The result decides whether an unattached carrier must survive as a host for
+     * diagnostics or withdrawal processing rather than being ignored as prose.
+     */
+    private annotation;
+    /**
+     * Detects claims that remain relevant when a carrier's unit is withdrawn.
+     *
+     * Evidence claims are excluded here, leaving acknowledgement and review tags
+     * available for validation without publishing a hidden declaration host.
+     */
+    private claimAnnotation;
+    /**
+     * Recognizes supported annotation names at documentation line boundaries.
+     *
+     * Matching only line-leading tags prevents ordinary prose mentions from
+     * materializing diagnostics or claim hosts.
+     */
+    private annotationPattern;
+    /**
+     * Follows explicit parent ownership to propagate withdrawal eligibility.
+     *
+     * A visited set breaks malformed parent cycles while any withdrawal on an
+     * ancestor hides the complete descendant surface from host publication.
+     */
+    private withdrawn;
+    /**
+     * Builds a canonical unit identity without merging declarations across files.
+     *
+     * Source identity prefixes the lexical declaration path so aliases can unify
+     * within their selected file while physically distinct files stay
+     * independent.
+     */
+    private unitId;
+    /**
+     * Records a declaration conflict and marks the analysis incomplete.
+     *
+     * The adapter preserves the conflict diagnostic rather than selecting one
+     * ambiguous physical declaration as the sole canonical public unit.
+     */
+    private problem;
 }