@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/prisma/PrismaTarget.d.ts

@@ -1,10 +0,0 @@
-import type { IEvidenceAddress } from "../../structures/IEvidenceAddress";
-/**
- * Parses one file-independent Prisma model or member target.
- *
- * Prisma references use the `prisma:` prefix because their parser-established
- * identities can span files, leaving the returned file key as a fixed namespace.
- */
-export declare namespace PrismaTarget {
-    function parse(target: string): IEvidenceAddress;
-}

package/lib/adapters/prisma/PrismaTarget.js

@@ -1,23 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PrismaTarget = void 0;
-const PrismaSyntax_1 = require("./PrismaSyntax");
-/**
- * Parses one file-independent Prisma model or member target.
- *
- * Prisma references use the `prisma:` prefix because their parser-established
- * identities can span files, leaving the returned file key as a fixed namespace.
- */
-var PrismaTarget;
-(function (PrismaTarget) {
-    function parse(target) {
-        if (!target.startsWith("prisma:"))
-            throw new Error("Start a Prisma target with 'prisma:'.");
-        const segments = target.slice("prisma:".length).split(".");
-        if ((segments.length !== 1 && segments.length !== 2) ||
-            segments.some((segment) => !PrismaSyntax_1.PrismaSyntax.identifier(segment)))
-            throw new Error("Use prisma:Model or prisma:Model.member with valid Prisma identifiers.");
-        return { file: "prisma:", segments };
-    }
-    PrismaTarget.parse = parse;
-})(PrismaTarget || (exports.PrismaTarget = PrismaTarget = {}));

package/lib/adapters/python/IPythonAll.d.ts

@@ -1,24 +0,0 @@
-import type { PythonAllState } from "./PythonAllState";
-/**
- * Records the statically known portion of a module's `__all__` declaration.
- *
- * PythonExportResolver uses this state to choose between explicit exports and
- * Python's underscore convention. Dynamic mutation stays incomplete because
- * executing module code would make coverage depend on runtime state.
- */
-export interface IPythonAll {
-    /**
-     * Whether `__all__` is absent, fully static, or changed dynamically.
-     *
-     * A dynamic state suppresses inference from arbitrary runtime mutations while
-     * allowing the scanner to retain the failure diagnostic.
-     */
-    state: PythonAllState;
-    /**
-     * Export names recovered from supported literal assignment and concatenation.
-     *
-     * The array preserves declaration order; the resolver later converts it to a
-     * set when it combines explicit exports with imported bindings.
-     */
-    names: string[];
-}

package/lib/adapters/python/IPythonBinding.d.ts

@@ -1,52 +0,0 @@
-import type { PythonBindingKind } from "./PythonBindingKind";
-/**
- * Describes one source-ordered module binding used for static export resolution.
- *
- * The resolver selects the latest compatible binding for a name and follows
- * imports without executing Python. Unsupported or ambiguous paths become
- * diagnostics rather than silently reducing the public population.
- */
-export interface IPythonBinding {
-    /**
-     * Binding form that determines how the resolver follows this entry.
-     *
-     * Local bindings point at scanned declaration roots; import forms require a
-     * source-snapshot module target.
-     */
-    kind: PythonBindingKind;
-    /**
-     * Source-order key for Python's later-binding-wins behavior.
-     *
-     * It is derived from the statement position with a local tie-breaker for
-     * entries in the same import statement.
-     */
-    order: number;
-    /**
-     * Name introduced in the containing module namespace.
-     *
-     * Omission represents an unusable or incomplete binding and prevents it from
-     * being selected as a public export.
-     */
-    localName?: string;
-    /**
-     * Declaration root selected by a local binding.
-     *
-     * Imports omit this field because their target must be resolved against
-     * another module before a declaration can be materialized.
-     */
-    root?: string;
-    /**
-     * Name requested from an imported module by a named import.
-     *
-     * Namespace and star imports omit it: their member name comes from the
-     * subsequent attribute lookup or the requesting public name.
-     */
-    importedName?: string;
-    /**
-     * Static absolute or relative module spelling from the import statement.
-     *
-     * Omission keeps an incomplete binding from resolving outside the scanned
-     * source snapshot.
-     */
-    specifier?: string;
-}

package/lib/adapters/python/IPythonClassContext.d.ts

@@ -1,36 +0,0 @@
-/**
- * Carries the structural ownership needed while scanning one Python class body.
- *
- * Nested functions and properties inherit these segments to keep their unit IDs
- * stable, while exported addresses can still distinguish a class member from an
- * instance member through the suffix selected by the scanner.
- */
-export interface IPythonClassContext {
-    /**
-     * Full semantic path used to construct child unit identities.
-     *
-     * Every element names one enclosing declaration, in source nesting order.
-     */
-    identity: string[];
-    /**
-     * Public-address segments preceding a member declared in this class.
-     *
-     * The scanner appends a member's own segments without using this path as its
-     * semantic identity, because aliases may publish that identity elsewhere.
-     */
-    suffix: string[];
-    /**
-     * Module-level root binding under which this class is declared.
-     *
-     * Export resolution associates the root with a local binding before it emits
-     * public file-qualified addresses.
-     */
-    root: string;
-    /**
-     * Unit ID of the enclosing class declaration.
-     *
-     * Members use this parent so ancestor withdrawal directives hide the complete
-     * class surface during documentation materialization.
-     */
-    parentId: string;
-}

package/lib/adapters/python/IPythonDocumentation.d.ts

@@ -1,47 +0,0 @@
-import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
-import type { IEvidenceDocumentation } from "../../structures/IEvidenceDocumentation";
-import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
-import type { IPythonDocumentationAttachment } from "./IPythonDocumentationAttachment";
-/**
- * Retains one Python docstring or adjacent comment run after parsing.
- *
- * The scanner keeps source coordinates and either a precomputed mapping or the
- * syntax needed to derive one. PythonAdapter attaches the text only after it
- * knows which declarations are part of the public export surface.
- */
-export interface IPythonDocumentation {
-    /**
-     * Stable identifier for this text region within its source file.
-     *
-     * It becomes the evidence-host ID when the text is supported and attached.
-     */
-    id: string;
-    /**
-     * Byte and coordinate range occupied by the original documentation text.
-     *
-     * Annotation ranges exclude this source slice from a unit fingerprint when
-     * it contains Evidence directives.
-     */
-    range: IEvidenceSourceRange;
-    /**
-     * Delimiter rules for mapping a raw docstring or comment run on demand.
-     *
-     * Omission means `mapping` already carries the normalized documentation;
-     * neither form may be absent when the adapter parses evidence tags.
-     */
-    syntax?: IEvidenceCommentSyntax;
-    /**
-     * Normalized documentation text when scanning already established its shape.
-     *
-     * The adapter clones this mapping before tag parsing because attachment and
-     * withdrawal phases must not mutate scanner-owned analysis data.
-     */
-    mapping?: IEvidenceDocumentation;
-    /**
-     * Declaration positions and candidate units that this text can document.
-     *
-     * One text region can attach to several accessors at one position; export and
-     * withdrawal filtering determine its final visible host membership.
-     */
-    attachments: IPythonDocumentationAttachment[];
-}

package/lib/adapters/python/IPythonDocumentationAttachment.d.ts

@@ -1,31 +0,0 @@
-/**
- * Connects one parsed Python documentation region to a declaration position.
- *
- * Scanning retains this compact relationship after its Tree-sitter session
- * closes. PythonAdapter later filters it by public reachability before creating
- * evidence hosts, so a private declaration's docstring cannot document an
- * exported unit by accident.
- */
-export interface IPythonDocumentationAttachment {
-    /**
-     * Scanner-local identity of the declaration position that owns this text.
-     *
-     * Hosts use the same identity to avoid publishing a second undocumented host
-     * for a declaration that already has an attached docstring or comment run.
-     */
-    positionId: string;
-    /**
-     * Stable declaration-site identity shared by every unit at this position.
-     *
-     * A property getter and setter may have distinct units but one source site;
-     * the host records that common site once.
-     */
-    siteId: string;
-    /**
-     * Candidate unit receiving directives parsed from this documentation.
-     *
-     * The adapter discards this attachment unless export resolution publishes the
-     * unit, preserving Python's public-surface boundary.
-     */
-    unitId: string;
-}

package/lib/adapters/python/IPythonFileAnalysis.d.ts

@@ -1,63 +0,0 @@
-import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
-import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
-import type { IPythonAll } from "./IPythonAll";
-import type { IPythonBinding } from "./IPythonBinding";
-import type { IPythonDocumentation } from "./IPythonDocumentation";
-import type { IPythonHostPosition } from "./IPythonHostPosition";
-import type { IPythonOwnedUnit } from "./IPythonOwnedUnit";
-/**
- * Preserves one Python file's serializable extraction after parsing.
- *
- * PythonAdapter combines these records before resolving imports and exports, so
- * parser-owned nodes never escape their session and failures remain visible.
- */
-export interface IPythonFileAnalysis {
-    /**
-     * Selected source whose declarations and diagnostics this analysis owns.
-     *
-     * Its physical path anchors units, annotation ranges, and diagnostic locations.
-     */
-    source: IEvidenceSourceFile;
-    /**
-     * Static knowledge of the module's explicit export list.
-     *
-     * The resolver falls back to underscore-based visibility only when this state permits it.
-     */
-    all: IPythonAll;
-    /**
-     * Source-ordered namespace bindings available to export resolution.
-     *
-     * Later entries may replace earlier names under Python binding semantics.
-     */
-    bindings: IPythonBinding[];
-    /**
-     * Lexically scanned declarations awaiting public-path publication.
-     *
-     * Entries can be removed when no supported export reaches their root.
-     */
-    units: IPythonOwnedUnit[];
-    /**
-     * Declaration sites that may receive a documentation host.
-     *
-     * Positions keep shared accessors from producing duplicate hosts.
-     */
-    positions: IPythonHostPosition[];
-    /**
-     * Parsed docstrings and adjacent comment runs from this file.
-     *
-     * Attachment is deferred until the exported population is known.
-     */
-    documentation: IPythonDocumentation[];
-    /**
-     * Source failures encountered while classifying this file.
-     *
-     * They are carried into the inventory so incomplete extraction cannot certify coverage.
-     */
-    diagnostics: IEvidenceDiagnostic[];
-    /**
-     * Whether scanning classified every surface-changing construct in this file.
-     *
-     * A false value propagates to the completed inventory even if other files succeed.
-     */
-    complete: boolean;
-}

package/lib/adapters/python/IPythonHostPosition.d.ts

@@ -1,33 +0,0 @@
-import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
-/**
- * Identifies one Python declaration site eligible to own documentation.
- *
- * The scanner retains positions separately from units because one source site
- * can expose several accessors while producing only one evidence host.
- */
-export interface IPythonHostPosition {
-    /**
-     * Scanner-local key for this attachable declaration position.
-     *
-     * Documentation attachments use it to suppress a fallback undocumented host.
-     */
-    id: string;
-    /**
-     * Stable declaration-site identity shared by all units at this position.
-     *
-     * It becomes the host site when a published attachment survives withdrawal filtering.
-     */
-    siteId: string;
-    /**
-     * Source extent that contributes this site's review content.
-     *
-     * Coordinates remain available after Tree-sitter resources close.
-     */
-    range: IEvidenceSourceRange;
-    /**
-     * Candidate semantic units declared at this source position.
-     *
-     * Export reachability decides which members are actually represented by the host.
-     */
-    unitIds: string[];
-}

package/lib/adapters/python/IPythonModule.d.ts

@@ -1,42 +0,0 @@
-import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
-import type { IPythonAll } from "./IPythonAll";
-import type { IPythonBinding } from "./IPythonBinding";
-import type { IPythonOwnedUnit } from "./IPythonOwnedUnit";
-/**
- * Provides one selected Python module to the bounded export resolver.
- *
- * It combines file-local extraction with a mutable name index, allowing imports
- * and re-exports to resolve without reopening parser sessions or executing code.
- */
-export interface IPythonModule {
-    /**
-     * Source identity and path used to resolve relative module specifiers.
-     *
-     * The resolver never follows a module that is absent from the selected snapshot.
-     */
-    source: IEvidenceSourceFile;
-    /**
-     * Explicit-export state governing this module's public names.
-     *
-     * Dynamic `__all__` keeps the enclosing inventory incomplete.
-     */
-    all: IPythonAll;
-    /**
-     * Local and imported bindings in their source order.
-     *
-     * These records encode Python's overwrite behavior for a requested name.
-     */
-    bindings: IPythonBinding[];
-    /**
-     * Scanned declaration roots that may be published through a reachable binding.
-     *
-     * Their semantic identities remain independent of the aliases that expose them.
-     */
-    units: IPythonOwnedUnit[];
-    /**
-     * Names currently being resolved through this module.
-     *
-     * The set detects import cycles before recursive traversal can invent a complete result.
-     */
-    names: Set<string>;
-}

package/lib/adapters/python/IPythonOwnedUnit.d.ts

@@ -1,30 +0,0 @@
-import type { IEvidenceUnit } from "../../structures/IEvidenceUnit";
-/**
- * Associates one scanned Python declaration with module binding information.
- *
- * Export resolution matches `roots` before it publishes the unit, then prefixes
- * `suffix` with each reachable public path. This prevents an internal alias
- * from changing the declaration's semantic ID.
- */
-export interface IPythonOwnedUnit {
-    /**
-     * Evidence unit with semantic identity, source position, and parent relation.
-     *
-     * The adapter publishes only units reachable from a supported module export.
-     */
-    unit: IEvidenceUnit;
-    /**
-     * Module-level binding names that can resolve to this declaration.
-     *
-     * A declaration can have more than one root when Python syntax establishes
-     * aliases without creating a separate semantic unit.
-     */
-    roots: string[];
-    /**
-     * Address segments beneath the matching module root.
-     *
-     * Instance members include the adapter's prototype marker while class members
-     * remain direct children of their class address.
-     */
-    suffix: string[];
-}

package/lib/adapters/python/IPythonResolution.d.ts

@@ -1,21 +0,0 @@
-import type { IPythonResolvedBinding } from "./IPythonResolvedBinding";
-/**
- * Represents the bounded static result of one Python name lookup.
- *
- * The resolver distinguishes reachable bindings from a cyclic path so callers
- * can retain an incomplete diagnostic instead of treating recursion as absence.
- */
-export interface IPythonResolution {
-    /**
-     * Declaration roots or namespaces reached by the requested name.
-     *
-     * Multiple entries preserve aliases and star-import alternatives until publication deduplicates units.
-     */
-    bindings: IPythonResolvedBinding[];
-    /**
-     * Whether resolving this lookup encountered an active import cycle.
-     *
-     * A cycle prevents the resolver from certifying that omitted exports are private.
-     */
-    cyclic: boolean;
-}

package/lib/adapters/python/IPythonResolvedBinding.d.ts

@@ -1,20 +0,0 @@
-/**
- * Identifies a declaration root or module namespace reached through imports.
- *
- * PythonExportResolver carries this lightweight result across files before it
- * converts a reachable root into public addresses and a published unit.
- */
-export interface IPythonResolvedBinding {
-    /**
-     * Selected source module containing this resolved target.
-     *
-     * It keys later root lookup and ensures traversal remains inside the snapshot.
-     */
-    sourceId: string;
-    /**
-     * Local declaration root when the lookup resolves to a declaration.
-     *
-     * Omission represents a module namespace, whose next attribute lookup supplies the root.
-     */
-    root?: string;
-}

package/lib/adapters/python/PythonAdapter.d.ts

@@ -1,43 +0,0 @@
-import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
-import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
-import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
-/**
- * Extracts Python declarations through bounded static export and re-export analysis.
- *
- * File scanning records candidate units, bindings, and docstring ownership before
- * PythonExportResolver determines which identities are publicly reachable. Only
- * published owners receive eligible documentation hosts; parser and export
- * failures remain incomplete inventory diagnostics instead of shrinking coverage.
- */
-export declare class PythonAdapter implements IEvidenceAdapter {
-    /**
-     * Artifact family selecting Python parsing and public-surface rules.
-     *
-     * The common adapter contract uses this discriminator independently of query selectors.
-     */
-    readonly type = "python";
-    /**
-     * Builds an owned inventory from the supplied Python source snapshot.
-     *
-     * The method validates and clones input, scans with a bounded parser runtime,
-     * resolves public exports, and materializes annotations on their published owners.
-     * Native resources close in cleanup even when extraction fails.
-     */
-    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
-    private scan;
-    /**
-     * Attaches parsed documentation only after exported identity selection is known.
-     *
-     * Withdrawal directives are collected before visible hosts are finalized, so
-     * hidden parents cannot leave descendants as eligible evidence carriers.
-     */
-    private materializeDocumentation;
-    private materializeUndocumentedHosts;
-    private host;
-    private parse;
-    private annotation;
-    private claimAnnotation;
-    private annotationPattern;
-    private mapping;
-    private withdrawn;
-}