@wrtnlabs/evidence 0.0.0 → 0.1.0

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

@@ -0,0 +1,443 @@
+import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidencePythonFileAnalysis } from "./IEvidencePythonFileAnalysis";
+/**
+ * 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 EvidencePythonFileScanner {
+    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 the currently effective unit for each semantic identity in this file.
+     *
+     * Runtime rebindings replace the record, while property families and stub
+     * overloads retain their language-established declaration sites.
+     */
+    private readonly units;
+    /**
+     * Effective class-dictionary unit for each owner and runtime binding name.
+     *
+     * Evidence symbols and public address projections can differ for a method,
+     * property, alias, or nested class even though Python assigns them through
+     * one class namespace. The map lets a later statement remove the replaced
+     * unit and its descendants before publication.
+     */
+    private readonly classBindings;
+    /**
+     * Owns instance-field units produced by each class's effective constructor.
+     *
+     * A later `__init__` replaces the complete initializer body. Keeping its
+     * generated units together lets the scanner discard fields that only the dead
+     * constructor assigned before it scans the surviving body.
+     */
+    private readonly constructorUnits;
+    /**
+     * 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(): IEvidencePythonFileAnalysis;
+    /**
+     * 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;
+    /**
+     * Records an augmented assignment as a property update.
+     *
+     * A same-kind class property keeps its earlier declaration sites. When the
+     * update reuses a name previously occupied by another supported kind, the
+     * class dictionary replacement removes that obsolete unit before the property
+     * is added.
+     */
+    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;
+    /**
+     * Associates one generated field with its class's effective constructor.
+     *
+     * Initializing the owner defensively keeps field extraction self-contained if
+     * another supported constructor spelling reaches it in a future grammar.
+     */
+    private rememberConstructorUnit;
+    /**
+     * Adds the effective declaration site for one semantic unit.
+     *
+     * Runtime occurrences receive distinct IDs and replace the previous record so
+     * their documentation cannot survive a rebinding. Explicit property families
+     * and function overloads in stub files merge their physical sites.
+     */
+    private addUnit;
+    /**
+     * Removes the class binding displaced by one later suite statement.
+     *
+     * Python stores methods, attributes, aliases, and nested classes in the same
+     * executed class dictionary. Unless the new declaration extends an
+     * established overload or accessor family, replacing a binding also removes
+     * every unit structurally owned by the obsolete nested declaration.
+     */
+    private replaceClassBinding;
+    /**
+     * Removes top-level declaration kinds displaced at one retained local root.
+     *
+     * Augmented assignment reuses the current binding token because it reads and
+     * updates that value. A property update can extend an earlier property, while
+     * a function, type, or class at the same root no longer describes the final
+     * public value and takes its structurally owned descendants with it.
+     */
+    private replaceRootBinding;
+    /**
+     * Deletes selected units, their descendants, and stale class-slot ownership.
+     *
+     * Unit IDs are occurrence-specific for runtime declarations, so walking
+     * `parentId` removes exactly the obsolete declaration tree without disturbing
+     * a later declaration that reuses the same semantic name.
+     */
+    private removeUnitTrees;
+    /**
+     * Records the unit currently occupying one executed class binding.
+     *
+     * The owner uses an occurrence-specific unit ID, preventing a replacement
+     * class from sharing binding state with an obsolete class of the same name.
+     */
+    private rememberClassBinding;
+    /**
+     * Creates the collision key for one Python class dictionary entry.
+     *
+     * Runtime ownership, rather than the Evidence symbol or projected `prototype`
+     * segment, determines whether two declarations replace the same value.
+     */
+    private classBindingKey;
+    /**
+     * 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;
+}