@wrtnlabs/evidence 0.0.0

package/lib/adapters/ruby/RubyAttributeMode.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Classifies the accessor capability declared by a supported Ruby attribute macro.
+ *
+ * RubyFileScanner emits one declaration for each generated reader or writer. RubyAdapter
+ * uses this distinction to detect redefinitions without executing the macro.
+ */
+export type RubyAttributeMode = "read" | "write";

package/lib/adapters/ruby/RubyAttributeMode.js

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

package/lib/adapters/ruby/RubyContainerKind.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Identifies the supported Ruby container form backed by a constant path.
+ *
+ * RubyAdapter compares this form when reconciling reopened declarations. A class
+ * and module with the same identity cannot form one semantic container.
+ */
+export type RubyContainerKind = "class" | "module";

package/lib/adapters/ruby/RubyContainerKind.js

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

package/lib/adapters/ruby/RubyDeclarationForm.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Enumerates Ruby source forms retained until public units are materialized.
+ *
+ * RubyFileScanner assigns the form to each lexical record. RubyAdapter uses it
+ * with runtime names and ownership to apply form-specific reopening and replacement rules.
+ */
+export type RubyDeclarationForm = "alias" | "attribute" | "class" | "constant" | "method" | "module" | "module-function" | "singleton-method";

package/lib/adapters/ruby/RubyDeclarationForm.js

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

package/lib/adapters/ruby/RubyFileScanner.d.ts

@@ -0,0 +1,332 @@
+import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IRubyFileAnalysis } from "./IRubyFileAnalysis";
+/**
+ * Extracts bounded Ruby declarations, visibility changes, and documentation carriers.
+ *
+ * The scanner follows Ruby's ordered class and module directives while retaining
+ * declaration records for later inventory assembly and documentation attachment.
+ */
+export declare class RubyFileScanner {
+    private readonly session;
+    private readonly source;
+    /**
+     * Collects declarations in source order for visibility and alias resolution.
+     *
+     * Ruby directives can alter only prior declarations, so this list preserves
+     * the order required to reject ambiguous or forward targets.
+     */
+    private readonly declarations;
+    /**
+     * Stores recognized documentation carriers by their source-range identity.
+     *
+     * Attachments are accumulated while declarations are scanned and later become
+     * evidence documentation mappings.
+     */
+    private readonly documentation;
+    /**
+     * Collects failures that make static Ruby surface extraction incomplete.
+     *
+     * The adapter emits these records instead of silently omitting dynamic forms.
+     */
+    private readonly diagnostics;
+    /**
+     * Deduplicates diagnostics encountered through overlapping syntax traversals.
+     *
+     * One unsupported directive should retain one actionable source location.
+     */
+    private readonly reported;
+    /**
+     * Remembers explicit constant visibility by lexical identity.
+     *
+     * Later declarations of the same constant inherit the most recent supported
+     * visibility directive in their selected source context.
+     */
+    private readonly constantVisibility;
+    /**
+     * Converts parser offsets to source ranges that survive parser cleanup.
+     *
+     * Declaration sites and attached documentation both use this one source view.
+     */
+    private readonly text;
+    /**
+     * States whether all surface-affecting Ruby constructs were classified.
+     *
+     * Unsupported dynamic behavior marks the file incomplete to protect coverage
+     * from a falsely reduced public population.
+     */
+    private complete;
+    /**
+     * Supplies unique declaration-record suffixes within this source file.
+     *
+     * Synthetic aliases and module-function copies require identities distinct
+     * from the source declaration they derive from.
+     */
+    private serial;
+    /**
+     * Binds this scanner to the current parser session and selected Ruby source.
+     *
+     * Documentation is collected before declarations so adjacent comments are
+     * available when a site is emitted.
+     */
+    constructor(session: EvidenceParseSession, source: IEvidenceSourceFile);
+    /**
+     * Produces the serializable extraction result for one Ruby source file.
+     *
+     * The root body is traversed with top-level scope state after documentation
+     * collection, preserving ordered visibility and attachment behavior.
+     */
+    scan(): IRubyFileAnalysis;
+    /**
+     * Scans statements in one Ruby lexical body.
+     *
+     * Context carries ordered visibility and owner state into each statement.
+     */
+    private scanBody;
+    /**
+     * Dispatches one statement to the supported Ruby surface classifier.
+     *
+     * Unrecognized nested surface changes are preserved as incomplete diagnostics.
+     */
+    private scanStatement;
+    /**
+     * Extracts a class or module and traverses its owned lexical body.
+     *
+     * Owner identity and visibility state are derived before child declarations.
+     */
+    private scanContainer;
+    /**
+     * Extracts a singleton-class scope with singleton member ownership.
+     *
+     * Unsupported singleton owners are reported because their address is dynamic.
+     */
+    private scanSingletonClass;
+    /**
+     * Extracts an instance method under the current Ruby scope.
+     *
+     * Scope visibility and module-function state determine its published form.
+     */
+    private scanMethod;
+    /**
+     * Extracts a statically named singleton method.
+     *
+     * The receiver must resolve to the current selected owner.
+     */
+    private scanSingletonMethod;
+    /**
+     * Adds a method declaration with its semantic and runtime names.
+     *
+     * The method centralizes site construction for ordinary and synthetic forms.
+     */
+    private addMethod;
+    /**
+     * Extracts supported constant assignments from the current scope.
+     *
+     * Dynamic targets are failures because they cannot supply stable addresses.
+     */
+    private scanAssignment;
+    /**
+     * Dispatches a Ruby call that may alter the declared surface.
+     *
+     * Only known static directives are interpreted; the rest preserve boundaries.
+     */
+    private scanCall;
+    /**
+     * Handles a directive written without an explicit receiver.
+     *
+     * Such calls inherit the current lexical scope and visibility state.
+     */
+    private scanBareDirective;
+    /**
+     * Applies a supported method-visibility directive in the current scope.
+     *
+     * Literal targets update prior selected declarations in Ruby source order.
+     */
+    private scanVisibilityCall;
+    /**
+     * Applies a class-method visibility directive to singleton members.
+     *
+     * Dynamic names are rejected because the selected member cannot be identified.
+     */
+    private scanClassVisibilityCall;
+    /**
+     * Applies a constant-visibility directive to selected constants.
+     *
+     * Visibility is retained for both prior records and later same-name declarations.
+     */
+    private scanConstantVisibilityCall;
+    /**
+     * Expands a static Ruby attribute directive into property declarations.
+     *
+     * Reader and writer modes retain their runtime spelling and scope visibility;
+     * dynamic attribute names leave the scan incomplete.
+     */
+    private scanAttribute;
+    /**
+     * Resolves an `alias` statement against a preceding selected method.
+     *
+     * Ruby alias names must be literal so the new public address is stable.
+     */
+    private scanAlias;
+    /**
+     * Resolves an `alias_method` call with two literal method names.
+     *
+     * It delegates to the common alias path after enforcing static argument count.
+     */
+    private scanAliasCall;
+    /**
+     * Adds an alias declaration after finding exactly one prior function target.
+     *
+     * Ambiguity is rejected because Ruby load order cannot be inferred beyond the
+     * selected file's ordered declaration records.
+     */
+    private addAlias;
+    /**
+     * Applies supported `module_function` forms to instance methods.
+     *
+     * The directive privatizes the source method and creates a public singleton
+     * copy only when its target can be identified statically.
+     */
+    private scanModuleFunction;
+    /**
+     * Creates the public singleton copy required by `module_function`.
+     *
+     * Documentation attachments are copied to the new declaration site relation
+     * so both Ruby entry points retain the source evidence mapping.
+     */
+    private cloneModuleFunction;
+    /**
+     * Changes visibility on matching prior method declarations.
+     *
+     * Missing targets are errors because a directive must not silently alter an
+     * unknown population member.
+     */
+    private changeMethodVisibility;
+    /**
+     * Changes visibility on matching constants and stores it for later records.
+     *
+     * Ruby permits the directive after declaration, so both existing and future
+     * selected records need the resolved lexical visibility.
+     */
+    private changeConstantVisibility;
+    /**
+     * Returns definition records matching one owner, side, and runtime method name.
+     *
+     * Attributes participate because their generated readers and writers are
+     * valid targets for Ruby visibility directives.
+     */
+    private methodDeclarations;
+    /**
+     * Builds and records one Ruby declaration with its source site and metadata.
+     *
+     * The site begins at attached documentation when present, preserving the
+     * source region Evidence associates with the declaration.
+     */
+    private addDeclaration;
+    /**
+     * Finds the nearest attachable documentation carrier before a declaration.
+     *
+     * Only line-leading comments without intervening content attach, preventing
+     * an unrelated earlier comment from becoming the declaration's evidence host.
+     */
+    private attachedDocumentation;
+    /**
+     * Checks whether a documentation range begins after only whitespace on its line.
+     *
+     * Inline comments cannot attach to the following Ruby declaration.
+     */
+    private lineLeading;
+    /**
+     * Collects supported Ruby comment carriers and contiguous hash-comment runs.
+     *
+     * Adjacent aligned comments become one mapping; blank lines and indentation
+     * changes deliberately break the run.
+     */
+    private collectDocumentation;
+    /**
+     * Collects tag-bearing string and heredoc content as documentation mappings.
+     *
+     * These literal carriers support Evidence annotations even without comments.
+     */
+    private collectLiteralAnnotations;
+    /**
+     * Returns the documentation record for one exact source range and syntax.
+     *
+     * Reuse prevents duplicate mappings when several collection paths meet.
+     */
+    private ensureDocumentationRange;
+    /**
+     * Attaches documentation to a declaration site without duplicate relations.
+     *
+     * Repeated scan paths can identify the same carrier and declaration pair.
+     */
+    private attach;
+    /**
+     * Detects nested syntax that can change Ruby's declared public surface.
+     *
+     * Dynamic execution boundaries are reported instead of interpreted as static
+     * declarations within a conditional or metaprogrammed body.
+     */
+    private containsSurfaceChange;
+    /**
+     * Checks whether a call name is known to mutate Ruby declaration surface.
+     *
+     * This explicit list bounds static support and identifies dynamic directives.
+     */
+    private surfaceCall;
+    /**
+     * Reports a directive whose names or target cannot be statically resolved.
+     *
+     * The diagnostic marks the file incomplete so unsupported runtime behavior
+     * cannot lower coverage requirements.
+     */
+    private dynamicDirective;
+    /**
+     * Resolves a constant path against the current lexical owner when relative.
+     *
+     * Absolute paths and top-level paths retain their source segments unchanged.
+     */
+    private resolvePath;
+    /**
+     * Resolves a constant path when a supported path is present.
+     *
+     * Absence remains undefined so callers can distinguish it from top-level paths.
+     */
+    private resolveOptionalPath;
+    /**
+     * Creates a public member address for instance or singleton ownership.
+     *
+     * Singleton members use the explicit `self` segment to avoid identity clashes.
+     */
+    private memberAddress;
+    /**
+     * Serializes a lexical identity for map keys and equality checks.
+     *
+     * JSON preserves segment boundaries that a joined string could blur.
+     */
+    private identityKey;
+    /**
+     * Checks whether raw Ruby carrier text contains an Evidence annotation tag.
+     *
+     * The predicate is shared by comments, strings, and heredocs.
+     */
+    private annotation;
+    /**
+     * Serializes a parser node range as a stable source-local key.
+     *
+     * The immutable selected source makes its offsets suitable for record identity.
+     */
+    private nodeKey;
+    /**
+     * Creates the stable declaration-site identity for a Ruby parser node.
+     *
+     * The source ID scopes a range that could recur in another selected file.
+     */
+    private siteId;
+    /**
+     * Records one static-analysis failure and marks the file incomplete.
+     *
+     * A source-range key suppresses repeated diagnostics from overlapping checks.
+     */
+    private problem;
+}