@wrtnlabs/evidence 0.0.0

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

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