@wrtnlabs/evidence 0.0.0 → 0.1.0

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

@@ -1,367 +0,0 @@
-import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
-import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
-import type { IPythonFileAnalysis } from "./IPythonFileAnalysis";
-/**
- * Extracts Python declarations and static module bindings from one source file.
- *
- * This scanner classifies source-local public surface and documentation while a
- * later snapshot-wide resolver follows imports and publishes public addresses.
- */
-export declare class PythonFileScanner {
-    private readonly session;
-    private readonly source;
-    /**
-     * Records the file's statically understood `__all__` state and names.
-     *
-     * Dynamic mutations make the analysis incomplete rather than allowing the
-     * export resolver to infer a smaller public surface.
-     */
-    private readonly all;
-    /**
-     * Collects ordered module bindings used by later export resolution.
-     *
-     * Binding order preserves Python shadowing semantics for imports and locals.
-     */
-    private readonly bindings;
-    /**
-     * Owns units indexed by their semantic identity within this source file.
-     *
-     * Repeated declaration sites contribute to the same record before it is
-     * returned as a serializable file analysis.
-     */
-    private readonly units;
-    /**
-     * Tracks declaration positions used to identify enclosing public hosts.
-     *
-     * Position records retain nesting information after parser nodes are released.
-     */
-    private readonly positions;
-    /**
-     * Holds parsed comment and string documentation by extraction identity.
-     *
-     * Attachments are added as declarations are recognized instead of inferred
-     * later from line adjacency.
-     */
-    private readonly documentation;
-    /**
-     * Indexes contiguous comment runs by their final one-based source line.
-     *
-     * A declaration can attach only to an immediately preceding standalone run.
-     */
-    private readonly commentDocumentation;
-    /**
-     * Collects diagnostics that describe unsupported public-surface constructs.
-     *
-     * They are returned with the file analysis so the adapter can retain failure
-     * context after closing the parse session.
-     */
-    private readonly diagnostics;
-    /**
-     * Remembers reported source decisions to avoid duplicate diagnostics.
-     *
-     * Several traversal predicates can encounter one unsupported node.
-     */
-    private readonly reported;
-    /**
-     * Tracks string ranges already consumed as a concatenated docstring.
-     *
-     * This prevents adjacent string literals from producing overlapping mappings.
-     */
-    private readonly docstringParts;
-    /**
-     * Converts parser offsets into source ranges for units and documentation.
-     *
-     * The scanner owns this helper because all returned records must outlive nodes.
-     */
-    private readonly text;
-    /**
-     * States whether every surface-affecting construct was statically classified.
-     *
-     * Unsupported dynamic forms set this false so missing declarations cannot
-     * reduce the inventory population.
-     */
-    private complete;
-    /**
-     * Binds the active parser session to the selected source snapshot.
-     *
-     * Comment runs are collected eagerly because later traversal intentionally
-     * skips comments while classifying executable declarations.
-     */
-    constructor(session: EvidenceParseSession, source: IEvidenceSourceFile);
-    /**
-     * Produces the serializable extraction result for this Python source file.
-     *
-     * The first pass establishes `__all__`; the second records declarations and
-     * bindings, so public-name decisions do not depend on statement encounter order.
-     */
-    scan(): IPythonFileAnalysis;
-    /**
-     * Classifies one static `__all__` assignment or augmentation.
-     *
-     * Returns whether the statement owns `__all__` handling so other surface
-     * checks do not report the same mutation as an unrelated dynamic construct.
-     */
-    private scanAll;
-    /**
-     * Records bindings introduced by one supported module-scope import.
-     *
-     * Returns whether the statement was an import so declaration scanning can
-     * continue without treating it as an unsupported surface expression.
-     */
-    private scanImport;
-    /**
-     * Extracts a class declaration and its supported class-level members.
-     *
-     * Nested traversal carries the class identity so methods and fields receive
-     * addresses relative to their owning public type.
-     */
-    private scanClass;
-    /**
-     * Extracts a module-level function declaration.
-     *
-     * The wrapper supplies documentation attachment while the definition supplies
-     * the semantic name and source content range.
-     */
-    private scanFunction;
-    /**
-     * Extracts a method declared in a selected class.
-     *
-     * Class context distinguishes instance and supported static-style ownership
-     * before the unit is added to the file-local collection.
-     */
-    private scanMethod;
-    /**
-     * Extracts a statically named module-level type alias.
-     *
-     * The alias is a public type declaration when it is not private by spelling.
-     */
-    private scanTypeAlias;
-    /**
-     * Classifies a module-scope expression that may alter public declarations.
-     *
-     * Supported assignment forms are delegated; unrecognized surface mutations
-     * become diagnostics to preserve inventory completeness.
-     */
-    private scanModuleExpression;
-    /**
-     * Classifies a class-body expression that may define a member.
-     *
-     * Assignment handling receives the class context needed to publish member
-     * addresses and reject unsupported receiver mutation.
-     */
-    private scanClassExpression;
-    /**
-     * Rejects augmented assignments that can dynamically change public surface.
-     *
-     * Python does not provide a static declaration contract for these mutations.
-     */
-    private scanAugmentedAssignment;
-    /**
-     * Extracts supported simple assignments as module or class declarations.
-     *
-     * The surrounding context determines whether the assigned name is a type,
-     * class property, or an unsupported dynamic surface change.
-     */
-    private scanAssignments;
-    /**
-     * Extracts supported instance-field assignments from an initializer body.
-     *
-     * Only statically recognizable receiver attributes become property units.
-     */
-    private scanInstanceFields;
-    /**
-     * Adds a declaration site to its semantic unit and records its local binding.
-     *
-     * Reusing unit identity keeps repeated sites and overload-like declarations
-     * together while preserving each physical source location.
-     */
-    private addUnit;
-    /**
-     * Records a declaration position for later host selection.
-     *
-     * Positions retain parser-independent nesting and source-location metadata.
-     */
-    private registerPosition;
-    /**
-     * Attaches the immediately preceding standalone comment run to a declaration.
-     *
-     * Blank lines and intervening source prevent attachment so unrelated comments
-     * cannot become evidence documentation.
-     */
-    private attachPrecedingComment;
-    /**
-     * Attaches a recognized docstring mapping to a declaration site.
-     *
-     * The method records both declaration and site identities for later assembly.
-     */
-    private attachDocstring;
-    /**
-     * Adds one declaration-site attachment without duplicating the relation.
-     *
-     * Multiple traversal paths can reach a shared documentation mapping.
-     */
-    private attach;
-    /**
-     * Collects contiguous Python comment runs eligible for declaration attachment.
-     *
-     * The final line index allows a constant-time lookup from the next declaration.
-     */
-    private collectCommentRuns;
-    /**
-     * Checks whether a comment begins on an otherwise empty source line.
-     *
-     * Inline comments cannot document the following declaration.
-     */
-    private standaloneComment;
-    /**
-     * Finds string literals that carry Evidence annotation tags.
-     *
-     * Tagged literals are retained even when they are not attachable docstrings.
-     */
-    private collectStringAnnotations;
-    /**
-     * Creates or returns documentation for one string literal range.
-     *
-     * Mapping identity is derived from the stable source range.
-     */
-    private ensureStringDocumentation;
-    /**
-     * Creates documentation for adjacent string literals forming one docstring.
-     *
-     * Consumed parts are remembered to avoid overlapping documentation mappings.
-     */
-    private ensureConcatenatedDocumentation;
-    /**
-     * Returns the documentation carrier for a stable extraction identity.
-     *
-     * The first caller supplies mapping metadata; later callers reuse it.
-     */
-    private ensureDocumentation;
-    /**
-     * Returns documentation keyed by an exact source range.
-     *
-     * Range identity lets comments and string annotations coexist in one map.
-     */
-    private ensureDocumentationRange;
-    /**
-     * Records a local binding with its source-order precedence.
-     *
-     * Export resolution uses the latest binding to model Python shadowing.
-     */
-    private bindLocal;
-    /**
-     * Finds the currently winning local root for a module name.
-     *
-     * This mirrors the same ordered binding rule used by export resolution.
-     */
-    private currentLocalRoot;
-    /**
-     * Creates a stable local-root token from a name and parser position.
-     *
-     * Distinct rebindings need distinct roots even when they share a name.
-     */
-    private rootToken;
-    /**
-     * Reports an `__all__` mutation that cannot be statically enumerated.
-     *
-     * Public names remain incomplete rather than being guessed from runtime code.
-     */
-    private dynamicAll;
-    /**
-     * Detects nested mutations of the module's `__all__` binding.
-     *
-     * Control flow around this state prevents a complete static export population.
-     */
-    private containsAllMutation;
-    /**
-     * Detects nested constructs that conditionally alter module public surface.
-     *
-     * The scanner reports these boundaries instead of following executable flow.
-     */
-    private containsModuleSurface;
-    /**
-     * Detects class-body constructs that dynamically alter member surface.
-     *
-     * Dynamic class execution cannot safely become selected declarations.
-     */
-    private containsClassSurface;
-    /**
-     * Checks whether a module name is eligible for public extraction.
-     *
-     * Private spellings are excluded unless `__all__` later explicitly exposes them.
-     */
-    private selectedModuleName;
-    /**
-     * Checks whether a conditional import would introduce a selected public name.
-     *
-     * Such imports make the exported surface depend on runtime control flow.
-     */
-    private conditionalImportSelected;
-    /**
-     * Detects assignments through a receiver that can create instance fields.
-     *
-     * Receiver-aware scanning distinguishes supported initializer fields from
-     * arbitrary mutation in nested executable code.
-     */
-    private containsReceiverAssignment;
-    /**
-     * Returns literal attribute names assigned through one receiver expression.
-     *
-     * Only these names can be represented as static property declarations.
-     */
-    private receiverAttributes;
-    /**
-     * Returns non-private identifiers from a syntax subtree.
-     *
-     * The helper centralizes Python underscore filtering for surface predicates.
-     */
-    private publicIdentifiers;
-    /**
-     * Checks whether an assignment introduces a selected public identifier.
-     *
-     * The caller uses this to decide whether dynamic control flow is reportable.
-     */
-    private selectedAssignment;
-    /**
-     * Extracts literal identifier spellings from a parser subtree.
-     *
-     * Unnamed or computed targets are intentionally absent from this static view.
-     */
-    private identifiers;
-    /**
-     * Checks Python's conventional underscore-based private spelling.
-     *
-     * `__all__` remains the explicit mechanism for exposing such a binding.
-     */
-    private private;
-    /**
-     * Checks whether raw comment or string text contains an Evidence tag.
-     *
-     * Tagged carriers are retained even when ordinary documentation attachment fails.
-     */
-    private annotation;
-    /**
-     * Serializes a parser node's source range as a local identity component.
-     *
-     * Offsets remain stable for the immutable source snapshot.
-     */
-    private nodeKey;
-    /**
-     * Creates the stable declaration-site identity for a parser node.
-     *
-     * The source ID scopes otherwise reusable range offsets.
-     */
-    private siteId;
-    /**
-     * Creates the stable host-position identity for a parser node.
-     *
-     * Position records use a distinct namespace from declaration sites.
-     */
-    private positionId;
-    /**
-     * Records one unsupported source construct and marks scanning incomplete.
-     *
-     * A source-range key prevents duplicate diagnostics from overlapping checks.
-     */
-    private problem;
-}