@wrtnlabs/evidence 0.0.0

package/lib/adapters/typescript/EvidenceTypeScriptAdapter.d.ts

@@ -0,0 +1,29 @@
+import { EcmaScriptAdapter } from "../ecmascript/EcmaScriptAdapter";
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare class EvidenceTypeScriptAdapter extends EcmaScriptAdapter {
+    /**
+     * 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.
+     */
+    constructor();
+}

package/lib/adapters/typescript/EvidenceTypeScriptAdapter.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceTypeScriptAdapter = void 0;
+const EcmaScriptAdapter_1 = require("../ecmascript/EcmaScriptAdapter");
+/**
+ * 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.
+ *
+ * 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.
+ */
+class EvidenceTypeScriptAdapter extends EcmaScriptAdapter_1.EcmaScriptAdapter {
+    /**
+     * 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.
+     */
+    constructor() {
+        super("typescript", "TypeScript");
+    }
+}
+exports.EvidenceTypeScriptAdapter = EvidenceTypeScriptAdapter;

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

@@ -0,0 +1,16 @@
+import { ZigAdapter } from "./ZigAdapter";
+/**
+ * Extracts explicit Zig pub declarations and fields of public containers.
+ *
+ * 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.
+ */
+export declare class EvidenceZigAdapter extends ZigAdapter {
+}

package/lib/adapters/zig/EvidenceZigAdapter.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceZigAdapter = void 0;
+const ZigAdapter_1 = require("./ZigAdapter");
+/**
+ * Extracts explicit Zig pub declarations and fields of public containers.
+ *
+ * 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.
+ */
+class EvidenceZigAdapter extends ZigAdapter_1.ZigAdapter {
+}
+exports.EvidenceZigAdapter = EvidenceZigAdapter;

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

@@ -0,0 +1,73 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+/**
+ * Represents one explicit Zig declaration before public aliases are reconciled.
+ *
+ * A record separates semantic identity from the exported path because Zig
+ * aliases can expose one declaration at more than one address.
+ */
+export interface IZigDeclaration {
+    /**
+     * Identifies this extracted declaration at one physical site and exposed path.
+     *
+     * Alias reconciliation uses the key to connect documentation attachments before
+     * it merges alias projections into their canonical semantic unit.
+     */
+    id: string;
+    /**
+     * Names the declaration in its defining Zig source container.
+     *
+     * The adapter preserves this canonical name when an alias publishes the same
+     * declaration under a different final public accessor segment.
+     */
+    name: string;
+    /**
+     * Classifies the declaration with Evidence's shared programming symbol.
+     *
+     * Unit materialization retains this classification when it merges physical
+     * sites and assigns the declaration's stable semantic identity.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Records the declaration's canonical lexical ownership path.
+     *
+     * This path defines semantic identity independently of aliases that expose
+     * the declaration through additional public accessors.
+     */
+    identity: string[];
+    /**
+     * Lists public accessor segments that reach this physical declaration.
+     *
+     * Alias projections may differ from {@link identity}; publication uses these
+     * segments to create every supported file-qualified public address.
+     */
+    address: string[];
+    /**
+     * Preserves the declaration's physical source site and fingerprint content.
+     *
+     * Materialization clones this site into the semantic unit so source review
+     * retains its location even after the parser session has closed.
+     */
+    site: IEvidenceUnitSite;
+    /**
+     * Indicates whether the selected source exposes this declaration publicly.
+     *
+     * The adapter publishes only public records, while non-public boundaries can
+     * still be retained during extraction when needed for scanner classification.
+     */
+    public: boolean;
+    /**
+     * Marks a projection that contributes an additional public alias site.
+     *
+     * Alias projections do not create another unit; they allow target lookup and
+     * documentation hosts to retain every supported public spelling.
+     */
+    alias: boolean;
+    /**
+     * Identifies the explicit declaration that lexically owns this member.
+     *
+     * Omission marks a file-level declaration; otherwise materialization maps the
+     * owner to a unit parent so withdrawals propagate through the container tree.
+     */
+    ownerDeclarationId?: string;
+}

package/lib/adapters/zig/IZigDeclaration.js

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

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

@@ -0,0 +1,35 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IZigDocumentationAttachment } from "./IZigDocumentationAttachment";
+/**
+ * Represents a Zig documentation carrier or tag-bearing unsupported carrier.
+ *
+ * The record retains source-mapped `///` text and ineligible annotation carriers
+ * until alias reconciliation determines the supported documentation host.
+ */
+export interface IZigDocumentation {
+    /**
+     * 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: IZigDocumentationAttachment[];
+}

package/lib/adapters/zig/IZigDocumentation.js

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

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

@@ -0,0 +1,21 @@
+/**
+ * Associates parsed Zig documentation with one declaration site.
+ *
+ * The adapter stores this relation beside documentation mappings so semantic
+ * assembly can preserve the original comment attachment.
+ */
+export interface IZigDocumentationAttachment {
+    /**
+     * Identifies the declaration that owns the documentation mapping.
+     *
+     * Consumers use the extraction identity before assigning documentation to a
+     * semantic unit.
+     */
+    declarationId: string;
+    /**
+     * Identifies the physical declaration site that receives the comment.
+     *
+     * This keeps attachment precise when one semantic unit has several sites.
+     */
+    siteId: string;
+}

package/lib/adapters/zig/IZigDocumentationAttachment.js

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

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

@@ -0,0 +1,47 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IZigDeclaration } from "./IZigDeclaration";
+import type { IZigDocumentation } from "./IZigDocumentation";
+/**
+ * Holds the node-free Zig extraction retained after a parse session closes.
+ *
+ * Alias reconciliation works from this serializable record after the parser is
+ * closed, retaining the physical sites that support each exported address.
+ */
+export interface IZigFileAnalysis {
+    /**
+     * Retains the selected source snapshot that produced this extraction.
+     *
+     * Its physical path and public addresses anchor all later diagnostics, sites,
+     * and public-address materialization for this file.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Lists declarations extracted from the file, including non-public boundaries.
+     *
+     * Alias reconciliation filters public records for publication while retaining
+     * source-level ownership information needed to interpret their relationships.
+     */
+    declarations: IZigDeclaration[];
+    /**
+     * Holds classified documentation and unsupported annotation carriers.
+     *
+     * The adapter parses these records after public units are known so tags cannot
+     * attach to a declaration that never reaches the selected public surface.
+     */
+    documentation: IZigDocumentation[];
+    /**
+     * Records failures encountered while establishing the public surface.
+     *
+     * These diagnostics reach the final inventory to prevent unsupported source
+     * forms from reducing the coverage population without a reported failure.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * States whether scanning classified every surface-affecting Zig form.
+     *
+     * The inventory treats false as a failed boundary, preserving uncertainty
+     * rather than allowing an unclassified alias to reduce the public population.
+     */
+    complete: boolean;
+}

package/lib/adapters/zig/IZigFileAnalysis.js

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

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

@@ -0,0 +1,114 @@
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
+/**
+ * Materializes explicit Zig container declarations and their documentation hosts.
+ *
+ * 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 ZigAdapter implements IEvidenceAdapter {
+    /**
+     * 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.
+     */
+    readonly 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;
+}