@wrtnlabs/evidence 0.0.0

package/lib/adapters/ruby/RubyFileScanner.js

@@ -0,0 +1,990 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RubyFileScanner = void 0;
+const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
+const RubySyntax_1 = require("./RubySyntax");
+const SourceText_1 = require("../../internal/SourceText");
+/**
+ * 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.
+ */
+class RubyFileScanner {
+    session;
+    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.
+     */
+    declarations = [];
+    /**
+     * Stores recognized documentation carriers by their source-range identity.
+     *
+     * Attachments are accumulated while declarations are scanned and later become
+     * evidence documentation mappings.
+     */
+    documentation = new Map();
+    /**
+     * Collects failures that make static Ruby surface extraction incomplete.
+     *
+     * The adapter emits these records instead of silently omitting dynamic forms.
+     */
+    diagnostics = [];
+    /**
+     * Deduplicates diagnostics encountered through overlapping syntax traversals.
+     *
+     * One unsupported directive should retain one actionable source location.
+     */
+    reported = new Set();
+    /**
+     * 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.
+     */
+    constantVisibility = new Map();
+    /**
+     * Converts parser offsets to source ranges that survive parser cleanup.
+     *
+     * Declaration sites and attached documentation both use this one source view.
+     */
+    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.
+     */
+    complete = true;
+    /**
+     * 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.
+     */
+    serial = 0;
+    /**
+     * 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, source) {
+        this.session = session;
+        this.source = source;
+        this.text = new SourceText_1.SourceText(source.content);
+        this.collectDocumentation();
+        this.collectLiteralAnnotations();
+    }
+    /**
+     * 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() {
+        const root = {
+            kind: "top",
+            identity: [],
+            side: "instance",
+            visibility: "private",
+            moduleFunction: false,
+        };
+        this.scanBody(this.session.root, root);
+        return {
+            source: this.source,
+            declarations: this.declarations,
+            documentation: Array.from(this.documentation.values()),
+            diagnostics: this.diagnostics,
+            complete: this.complete,
+        };
+    }
+    /**
+     * Scans statements in one Ruby lexical body.
+     *
+     * Context carries ordered visibility and owner state into each statement.
+     */
+    scanBody(body, context) {
+        for (const statement of body.namedChildren)
+            this.scanStatement(statement, context);
+    }
+    /**
+     * Dispatches one statement to the supported Ruby surface classifier.
+     *
+     * Unrecognized nested surface changes are preserved as incomplete diagnostics.
+     */
+    scanStatement(statement, context) {
+        switch (statement.type) {
+            case "comment":
+            case "heredoc_body":
+            case "empty_statement":
+                return;
+            case "class":
+                this.scanContainer(statement, context, "class");
+                return;
+            case "module":
+                this.scanContainer(statement, context, "module");
+                return;
+            case "singleton_class":
+                this.scanSingletonClass(statement, context);
+                return;
+            case "method":
+                this.scanMethod(statement, statement, context);
+                return;
+            case "singleton_method":
+                this.scanSingletonMethod(statement, statement, context);
+                return;
+            case "assignment":
+                this.scanAssignment(statement, context);
+                return;
+            case "alias":
+                this.scanAlias(statement, statement, context);
+                return;
+            case "undef":
+                if (context.kind !== "top")
+                    this.problem("ruby-method-removal", "Ruby undef removes methods from the selected declared surface.", "Replace the removal with an explicit final declaration or add load-order-aware analysis.", statement);
+                return;
+            case "identifier":
+                this.scanBareDirective(statement, context);
+                return;
+            case "call":
+                this.scanCall(statement, context);
+                return;
+            default:
+                if (this.containsSurfaceChange(statement))
+                    this.problem("ruby-conditional-surface", `Ruby '${statement.type}' conditionally changes the selected public surface.`, "Move declarations and public-surface macros into an unconditional class or module body, or add control-flow analysis.", statement);
+        }
+    }
+    /**
+     * Extracts a class or module and traverses its owned lexical body.
+     *
+     * Owner identity and visibility state are derived before child declarations.
+     */
+    scanContainer(statement, context, kind) {
+        if (context.kind === "singleton") {
+            this.problem("ruby-singleton-constant", "A class or module declaration inside a singleton class has unsupported constant ownership.", "Declare the constant in an ordinary class or module body.", statement);
+            return;
+        }
+        const path = RubySyntax_1.RubySyntax.constantPath(statement.childForFieldName("name"));
+        if (path === undefined) {
+            this.problem("ruby-container-name", `A Ruby ${kind} has no statically readable constant path.`, "Use a named constant or constant path for the declaration.", statement);
+            return;
+        }
+        const identity = this.resolvePath(path, context);
+        const visibility = this.constantVisibility.get(this.identityKey(identity)) ?? "public";
+        this.addDeclaration(statement, statement, "type", kind, identity.at(-1) ?? "", identity.at(-1) ?? "", identity, identity, visibility, true, identity.slice(0, -1), [this.session.range(statement)], undefined, undefined, kind, kind === "class" ? RubySyntax_1.RubySyntax.superclass(statement) : undefined);
+        const body = statement.childForFieldName("body");
+        if (body === null)
+            return;
+        const nested = {
+            kind,
+            identity,
+            side: "instance",
+            visibility: "public",
+            moduleFunction: false,
+            containerKind: kind,
+        };
+        this.scanBody(body, nested);
+    }
+    /**
+     * Extracts a singleton-class scope with singleton member ownership.
+     *
+     * Unsupported singleton owners are reported because their address is dynamic.
+     */
+    scanSingletonClass(statement, context) {
+        if (context.kind === "singleton") {
+            this.problem("ruby-nested-singleton", "A singleton class opened from another singleton class targets an unsupported eigenclass level.", "Declare class or module singleton methods directly with def self.name.", statement);
+            return;
+        }
+        const value = statement.childForFieldName("value");
+        const identity = value?.type === "self" && context.kind !== "top"
+            ? context.identity
+            : this.resolveOptionalPath(RubySyntax_1.RubySyntax.constantPath(value), context);
+        if (identity === undefined || identity.length === 0) {
+            if (this.containsSurfaceChange(statement))
+                this.problem("ruby-singleton-owner", "A singleton class with public declarations has no statically selected constant owner.", "Open class << self inside a supported class or module, or use a literal constant path.", statement);
+            return;
+        }
+        const body = statement.childForFieldName("body");
+        if (body === null)
+            return;
+        const singleton = {
+            kind: "singleton",
+            identity,
+            side: "singleton",
+            visibility: "public",
+            moduleFunction: false,
+            ...(context.containerKind === undefined
+                ? {}
+                : { containerKind: context.containerKind }),
+        };
+        this.scanBody(body, singleton);
+    }
+    /**
+     * Extracts an instance method under the current Ruby scope.
+     *
+     * Scope visibility and module-function state determine its published form.
+     */
+    scanMethod(method, wrapper, context, forcedVisibility, forcedModuleFunction = false) {
+        if (context.kind === "top")
+            return;
+        const name = RubySyntax_1.RubySyntax.methodName(method.childForFieldName("name"));
+        if (name === undefined) {
+            this.problem("ruby-method-name", "A Ruby method has no statically readable name.", "Use an identifier, setter, or operator method name.", method);
+            return;
+        }
+        const moduleFunction = context.kind === "module" &&
+            context.side === "instance" &&
+            (forcedModuleFunction || context.moduleFunction);
+        const visibility = moduleFunction
+            ? "private"
+            : (forcedVisibility ??
+                (name === "initialize" ? "private" : context.visibility));
+        const declaration = this.addMethod(method, wrapper, context, name, visibility, context.side === "singleton" ? "singleton-method" : "method");
+        if (moduleFunction)
+            this.cloneModuleFunction(declaration);
+    }
+    /**
+     * Extracts a statically named singleton method.
+     *
+     * The receiver must resolve to the current selected owner.
+     */
+    scanSingletonMethod(method, wrapper, context, forcedVisibility) {
+        if (context.kind === "singleton") {
+            this.problem("ruby-nested-singleton", "def self.name inside a singleton class targets an unsupported eigenclass level.", "Use an ordinary def name inside class << self.", method);
+            return;
+        }
+        const object = method.childForFieldName("object");
+        const identity = object?.type === "self" && context.kind !== "top"
+            ? context.identity
+            : this.resolveOptionalPath(RubySyntax_1.RubySyntax.constantPath(object), context);
+        if (identity === undefined || identity.length === 0) {
+            if (context.kind !== "top" || object?.type !== "self")
+                this.problem("ruby-singleton-owner", "A singleton method has no statically selected class or module owner.", "Use def self.name inside a supported class or module, or use a literal constant path.", method);
+            return;
+        }
+        const name = RubySyntax_1.RubySyntax.methodName(method.childForFieldName("name"));
+        if (name === undefined) {
+            this.problem("ruby-method-name", "A Ruby singleton method has no statically readable name.", "Use an identifier, setter, or operator method name.", method);
+            return;
+        }
+        const owner = {
+            kind: "singleton",
+            identity,
+            side: "singleton",
+            visibility: forcedVisibility ?? "public",
+            moduleFunction: false,
+            ...(context.containerKind === undefined
+                ? {}
+                : { containerKind: context.containerKind }),
+        };
+        this.addMethod(method, wrapper, owner, name, forcedVisibility ?? "public", "singleton-method");
+    }
+    /**
+     * Adds a method declaration with its semantic and runtime names.
+     *
+     * The method centralizes site construction for ordinary and synthetic forms.
+     */
+    addMethod(method, wrapper, context, name, visibility, form) {
+        const address = this.memberAddress(context.identity, context.side, name);
+        return this.addDeclaration(method, wrapper, "function", form, name, name, address, address, visibility, true, context.identity, [this.session.range(method)], context.side, undefined, context.containerKind);
+    }
+    /**
+     * Extracts supported constant assignments from the current scope.
+     *
+     * Dynamic targets are failures because they cannot supply stable addresses.
+     */
+    scanAssignment(statement, context) {
+        const left = statement.childForFieldName("left");
+        const path = RubySyntax_1.RubySyntax.constantPath(left);
+        if (path === undefined) {
+            if (left !== null &&
+                left.descendantsOfType("constant").length !== 0 &&
+                context.kind !== "singleton")
+                this.problem("ruby-constant-assignment", "A compound Ruby assignment contains constants that cannot be separated safely.", "Declare each public constant with one direct assignment.", statement);
+            return;
+        }
+        if (context.kind === "singleton") {
+            this.problem("ruby-singleton-constant", "A constant assignment inside a singleton class has unsupported ownership.", "Declare the constant in an ordinary class or module body.", statement);
+            return;
+        }
+        const identity = this.resolvePath(path, context);
+        const visibility = this.constantVisibility.get(this.identityKey(identity)) ?? "public";
+        this.addDeclaration(statement, statement, "property", "constant", identity.at(-1) ?? "", identity.at(-1) ?? "", identity, identity, visibility, true, identity.slice(0, -1), [this.session.range(statement)], undefined, undefined, context.containerKind);
+        if (RubySyntax_1.RubySyntax.generatedConstant(statement.childForFieldName("right")))
+            this.problem("ruby-generated-constant", `Ruby constant '${identity.join("::")}' receives a runtime-generated class or module.`, "Use an explicit class or module declaration, or add generator-aware analysis for its members.", statement);
+    }
+    /**
+     * Dispatches a Ruby call that may alter the declared surface.
+     *
+     * Only known static directives are interpreted; the rest preserve boundaries.
+     */
+    scanCall(call, context) {
+        const name = RubySyntax_1.RubySyntax.callName(call);
+        if (name === undefined)
+            return;
+        if (!RubySyntax_1.RubySyntax.hasReceiver(call)) {
+            if (name === "public" || name === "private" || name === "protected") {
+                this.scanVisibilityCall(call, context, name);
+                return;
+            }
+            if (name === "public_class_method" || name === "private_class_method") {
+                this.scanClassVisibilityCall(call, context, name === "public_class_method" ? "public" : "private");
+                return;
+            }
+            if (name === "public_constant" || name === "private_constant") {
+                this.scanConstantVisibilityCall(call, context, name === "public_constant" ? "public" : "private");
+                return;
+            }
+            if (name === "attr_reader" ||
+                name === "attr_writer" ||
+                name === "attr_accessor") {
+                this.scanAttribute(call, call, context);
+                return;
+            }
+            if (name === "alias_method") {
+                this.scanAliasCall(call, context);
+                return;
+            }
+            if (name === "module_function") {
+                this.scanModuleFunction(call, context);
+                return;
+            }
+        }
+        if (this.surfaceCall(name))
+            this.problem("ruby-dynamic-surface", `Ruby call '${name}' can change the public surface without a statically complete declaration.`, "Replace it with explicit declarations or add a bounded adapter rule for this metaprogramming form.", call);
+    }
+    /**
+     * Handles a directive written without an explicit receiver.
+     *
+     * Such calls inherit the current lexical scope and visibility state.
+     */
+    scanBareDirective(statement, context) {
+        const name = statement.text;
+        if (name === "public" || name === "private" || name === "protected") {
+            context.visibility = name;
+            context.moduleFunction = false;
+        }
+        else if (name === "module_function") {
+            if (context.kind !== "module" || context.side !== "instance")
+                this.problem("ruby-module-function-owner", "module_function is only supported in an ordinary module body.", "Move the directive into a module or declare singleton methods explicitly.", statement);
+            else {
+                context.visibility = "private";
+                context.moduleFunction = true;
+            }
+        }
+    }
+    /**
+     * Applies a supported method-visibility directive in the current scope.
+     *
+     * Literal targets update prior selected declarations in Ruby source order.
+     */
+    scanVisibilityCall(call, context, visibility) {
+        const arguments_ = RubySyntax_1.RubySyntax.callArguments(call);
+        const wrapped = arguments_[0];
+        if (arguments_.length === 1 && wrapped !== undefined) {
+            if (wrapped.type === "method") {
+                this.scanMethod(wrapped, call, context, visibility);
+                return;
+            }
+            if (wrapped.type === "singleton_method") {
+                this.scanSingletonMethod(wrapped, call, context);
+                const name = RubySyntax_1.RubySyntax.methodName(wrapped.childForFieldName("name"));
+                if (name !== undefined)
+                    this.changeMethodVisibility(context.identity, context.kind === "singleton" ? "singleton" : "instance", name, visibility, call);
+                return;
+            }
+            if (wrapped.type === "call" &&
+                ["attr_reader", "attr_writer", "attr_accessor"].includes(RubySyntax_1.RubySyntax.callName(wrapped) ?? "")) {
+                this.scanAttribute(wrapped, call, context, visibility);
+                return;
+            }
+        }
+        if (arguments_.length === 0) {
+            context.visibility = visibility;
+            context.moduleFunction = false;
+            return;
+        }
+        const names = RubySyntax_1.RubySyntax.literalNames(arguments_);
+        if (names === undefined || names.length === 0) {
+            this.dynamicDirective(call, "method visibility");
+            return;
+        }
+        const side = context.kind === "singleton" ? "singleton" : "instance";
+        for (const name of names)
+            this.changeMethodVisibility(context.identity, side, name, visibility, call);
+    }
+    /**
+     * Applies a class-method visibility directive to singleton members.
+     *
+     * Dynamic names are rejected because the selected member cannot be identified.
+     */
+    scanClassVisibilityCall(call, context, visibility) {
+        if (context.kind !== "class" && context.kind !== "module") {
+            this.problem("ruby-class-visibility-owner", "Class-method visibility is only supported in an ordinary class or module body.", "Use private or public inside class << self, or move the directive into the owning class or module body.", call);
+            return;
+        }
+        const arguments_ = RubySyntax_1.RubySyntax.callArguments(call);
+        const wrapped = arguments_[0];
+        if (arguments_.length === 1 && wrapped?.type === "singleton_method") {
+            this.scanSingletonMethod(wrapped, call, context, visibility);
+            return;
+        }
+        const names = RubySyntax_1.RubySyntax.literalNames(arguments_);
+        if (names === undefined || names.length === 0) {
+            this.dynamicDirective(call, "class-method visibility");
+            return;
+        }
+        for (const name of names)
+            this.changeMethodVisibility(context.identity, "singleton", name, visibility, call);
+    }
+    /**
+     * Applies a constant-visibility directive to selected constants.
+     *
+     * Visibility is retained for both prior records and later same-name declarations.
+     */
+    scanConstantVisibilityCall(call, context, visibility) {
+        if (context.kind === "singleton") {
+            this.dynamicDirective(call, "constant visibility");
+            return;
+        }
+        const names = RubySyntax_1.RubySyntax.literalNames(RubySyntax_1.RubySyntax.callArguments(call));
+        if (names === undefined ||
+            names.length === 0 ||
+            names.some((name) => !/^[A-Z][A-Za-z0-9_]*$/u.test(name))) {
+            this.dynamicDirective(call, "constant visibility");
+            return;
+        }
+        for (const name of names)
+            this.changeConstantVisibility([...context.identity, name], visibility, call);
+    }
+    /**
+     * 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.
+     */
+    scanAttribute(call, wrapper, context, forcedVisibility) {
+        if (context.kind === "top")
+            return;
+        const callName = RubySyntax_1.RubySyntax.callName(call);
+        if (callName !== "attr_reader" &&
+            callName !== "attr_writer" &&
+            callName !== "attr_accessor")
+            return;
+        const arguments_ = RubySyntax_1.RubySyntax.callArguments(call);
+        const names = arguments_.map((argument) => RubySyntax_1.RubySyntax.literalName(argument));
+        if (names.length === 0 ||
+            names.some((name) => name === undefined || name.length === 0)) {
+            this.problem("ruby-dynamic-attribute", `Ruby ${callName} contains a nonliteral attribute name.`, "Use literal symbol or string names in attr_reader, attr_writer, or attr_accessor.", call);
+            return;
+        }
+        if (context.kind === "module" && context.moduleFunction)
+            this.problem("ruby-module-function-attribute", "An attribute declaration under module_function mode has unsupported copy semantics.", "Declare explicit instance and singleton accessors, or reset visibility before the attribute declaration.", call);
+        const visibility = forcedVisibility ?? context.visibility;
+        const modes = callName === "attr_reader"
+            ? ["read"]
+            : callName === "attr_writer"
+                ? ["write"]
+                : ["read", "write"];
+        const method = call.childForFieldName("method");
+        for (let index = 0; index < arguments_.length; ++index) {
+            const argument = arguments_[index];
+            const name = names[index];
+            if (argument === undefined || name === undefined)
+                continue;
+            for (const mode of modes) {
+                const runtimeName = mode === "write" ? `${name}=` : name;
+                const address = this.memberAddress(context.identity, context.side, name);
+                this.addDeclaration(argument, wrapper, "property", "attribute", name, runtimeName, address, address, visibility, true, context.identity, [
+                    ...(method === null ? [] : [this.session.range(method)]),
+                    this.session.range(argument),
+                ], context.side, mode, context.containerKind);
+            }
+        }
+    }
+    /**
+     * Resolves an `alias` statement against a preceding selected method.
+     *
+     * Ruby alias names must be literal so the new public address is stable.
+     */
+    scanAlias(statement, wrapper, context) {
+        if (context.kind === "top")
+            return;
+        const name = RubySyntax_1.RubySyntax.methodName(statement.childForFieldName("name"));
+        const target = RubySyntax_1.RubySyntax.methodName(statement.childForFieldName("alias"));
+        if (name === undefined || target === undefined) {
+            this.problem("ruby-alias-name", "A Ruby alias has a name that cannot be resolved statically.", "Use literal method names in the alias statement.", statement);
+            return;
+        }
+        this.addAlias(statement, wrapper, context, name, target);
+    }
+    /**
+     * Resolves an `alias_method` call with two literal method names.
+     *
+     * It delegates to the common alias path after enforcing static argument count.
+     */
+    scanAliasCall(call, context) {
+        if (context.kind === "top")
+            return;
+        const names = RubySyntax_1.RubySyntax.literalNames(RubySyntax_1.RubySyntax.callArguments(call));
+        if (names?.length !== 2) {
+            this.problem("ruby-alias-name", "alias_method requires two statically readable method names.", "Use two literal symbol or string method names.", call);
+            return;
+        }
+        const name = names[0];
+        const target = names[1];
+        if (name !== undefined && target !== undefined)
+            this.addAlias(call, call, context, name, target);
+    }
+    /**
+     * 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.
+     */
+    addAlias(statement, wrapper, context, name, targetName) {
+        const candidates = this.methodDeclarations(context.identity, context.side, targetName).filter((declaration) => declaration.symbol === "function");
+        if (candidates.length !== 1) {
+            this.problem("ruby-alias-target", `Ruby alias '${name}' cannot identify one selected prior method '${targetName}'.`, "Define the target method once earlier in the same selected file before aliasing it.", statement);
+            return;
+        }
+        const target = candidates[0];
+        if (target === undefined)
+            return;
+        const address = this.memberAddress(context.identity, context.side, name);
+        this.addDeclaration(statement, wrapper, "function", "alias", name, name, address, address, target.visibility, true, context.identity, [this.session.range(statement)], context.side, undefined, context.containerKind);
+    }
+    /**
+     * 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.
+     */
+    scanModuleFunction(call, context) {
+        if (context.kind !== "module" || context.side !== "instance") {
+            this.problem("ruby-module-function-owner", "module_function is only supported in an ordinary module body.", "Move the directive into a module or declare singleton methods explicitly.", call);
+            return;
+        }
+        const arguments_ = RubySyntax_1.RubySyntax.callArguments(call);
+        const wrapped = arguments_[0];
+        if (arguments_.length === 1 && wrapped?.type === "method") {
+            this.scanMethod(wrapped, call, context, "private", true);
+            return;
+        }
+        if (arguments_.length === 0) {
+            context.visibility = "private";
+            context.moduleFunction = true;
+            return;
+        }
+        const names = RubySyntax_1.RubySyntax.literalNames(arguments_);
+        if (names === undefined || names.length === 0) {
+            this.dynamicDirective(call, "module_function");
+            return;
+        }
+        for (const name of names) {
+            const candidates = this.methodDeclarations(context.identity, "instance", name).filter((declaration) => declaration.symbol === "function");
+            if (candidates.length !== 1) {
+                this.problem("ruby-module-function-target", `module_function cannot identify one selected prior method '${name}'.`, "Define the method once earlier in the same selected file or use an explicit singleton method.", call);
+                continue;
+            }
+            const target = candidates[0];
+            if (target === undefined)
+                continue;
+            target.visibility = "private";
+            this.cloneModuleFunction(target);
+        }
+    }
+    /**
+     * 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.
+     */
+    cloneModuleFunction(target) {
+        const address = this.memberAddress(target.ownerIdentity ?? [], "singleton", target.runtimeName);
+        const clone = {
+            ...target,
+            id: `ruby:${this.source.id}:declaration:${this.serial++}:module-function`,
+            form: "module-function",
+            identity: address,
+            address,
+            visibility: "public",
+            side: "singleton",
+            site: structuredClone(target.site),
+        };
+        this.declarations.push(clone);
+        for (const documentation of this.documentation.values())
+            for (const attachment of documentation.attachments.filter((candidate) => candidate.declarationId === target.id))
+                documentation.attachments.push({
+                    declarationId: clone.id,
+                    siteId: attachment.siteId,
+                });
+    }
+    /**
+     * Changes visibility on matching prior method declarations.
+     *
+     * Missing targets are errors because a directive must not silently alter an
+     * unknown population member.
+     */
+    changeMethodVisibility(ownerIdentity, side, name, visibility, call) {
+        const candidates = this.methodDeclarations(ownerIdentity, side, name);
+        if (candidates.length === 0) {
+            this.problem("ruby-visibility-target", `Ruby visibility directive cannot identify a selected prior ${side} method '${name}'.`, "Define the method earlier in the same selected file or add load-order-aware resolution.", call);
+            return;
+        }
+        for (const candidate of candidates)
+            candidate.visibility = visibility;
+    }
+    /**
+     * 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.
+     */
+    changeConstantVisibility(identity, visibility, call) {
+        const key = this.identityKey(identity);
+        const candidates = this.declarations.filter((declaration) => (declaration.form === "class" ||
+            declaration.form === "module" ||
+            declaration.form === "constant") &&
+            this.identityKey(declaration.identity) === key);
+        if (candidates.length === 0) {
+            this.problem("ruby-constant-visibility-target", `Ruby constant visibility cannot identify selected prior constant '${identity.join("::")}'.`, "Declare the constant earlier in the same selected file or add load-order-aware resolution.", call);
+            return;
+        }
+        this.constantVisibility.set(key, visibility);
+        for (const candidate of candidates)
+            candidate.visibility = visibility;
+    }
+    /**
+     * 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.
+     */
+    methodDeclarations(ownerIdentity, side, runtimeName) {
+        const owner = this.identityKey(ownerIdentity);
+        return this.declarations.filter((declaration) => declaration.definition &&
+            declaration.side === side &&
+            declaration.runtimeName === runtimeName &&
+            this.identityKey(declaration.ownerIdentity ?? []) === owner &&
+            (declaration.symbol === "function" || declaration.form === "attribute"));
+    }
+    /**
+     * 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.
+     */
+    addDeclaration(item, siteNode, symbol, form, name, runtimeName, identity, address, visibility, definition, ownerIdentity, content, side, attributeMode, containerKind, superclass) {
+        const documentation = this.attachedDocumentation(siteNode);
+        const site = {
+            id: this.siteId(siteNode),
+            file: this.source.physicalPath,
+            range: this.text.range(documentation?.range?.start?.offset ?? siteNode.startIndex, siteNode.endIndex),
+            content,
+        };
+        const declaration = {
+            id: `ruby:${this.source.id}:declaration:${this.serial++}:${form}:${item.startIndex}`,
+            name,
+            runtimeName,
+            symbol,
+            form,
+            identity,
+            address,
+            site,
+            visibility,
+            definition,
+            ...(ownerIdentity.length === 0 ? {} : { ownerIdentity }),
+            ...(side === undefined ? {} : { side }),
+            ...(attributeMode === undefined ? {} : { attributeMode }),
+            ...(containerKind === undefined ? {} : { containerKind }),
+            ...(superclass === undefined ? {} : { superclass }),
+        };
+        this.declarations.push(declaration);
+        if (documentation !== undefined)
+            this.attach(documentation, declaration.id, site.id);
+        return declaration;
+    }
+    /**
+     * 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.
+     */
+    attachedDocumentation(node) {
+        const documentation = Array.from(this.documentation.values())
+            .filter((candidate) => candidate.syntax !== undefined &&
+            this.lineLeading(candidate.range) &&
+            candidate.range.end.offset <= node.startIndex &&
+            (candidate.syntax.opening.startsWith("=begin") ||
+                candidate.range.start.column === node.startPosition.column + 1))
+            .sort((left, right) => right.range.end.offset - left.range.end.offset)[0];
+        if (documentation === undefined)
+            return undefined;
+        const between = this.source.content.slice(documentation.range.end.offset, node.startIndex);
+        return between.trim() !== "" || /\r?\n[ \t]*\r?\n/u.test(between)
+            ? undefined
+            : documentation;
+    }
+    /**
+     * Checks whether a documentation range begins after only whitespace on its line.
+     *
+     * Inline comments cannot attach to the following Ruby declaration.
+     */
+    lineLeading(range) {
+        const lineStart = Math.max(this.source.content.lastIndexOf("\n", range.start.offset - 1), this.source.content.lastIndexOf("\r", range.start.offset - 1)) + 1;
+        return (this.source.content.slice(lineStart, range.start.offset).trim() === "");
+    }
+    /**
+     * 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.
+     */
+    collectDocumentation() {
+        const comments = this.session.root
+            .descendantsOfType("comment")
+            .sort((left, right) => left.startIndex - right.startIndex);
+        for (let index = 0; index < comments.length; ++index) {
+            const first = comments[index];
+            if (first === undefined)
+                continue;
+            const syntax = RubySyntax_1.RubySyntax.commentSyntax(first);
+            if (syntax === undefined)
+                continue;
+            let last = first;
+            if (first.text.startsWith("#"))
+                while (index + 1 < comments.length) {
+                    const next = comments[index + 1];
+                    if (next === undefined)
+                        break;
+                    const between = this.source.content.slice(last.endIndex, next.startIndex);
+                    if (!next.text.startsWith("#") ||
+                        next.startPosition.column !== first.startPosition.column ||
+                        /\r?\n[ \t]*\r?\n/u.test(between) ||
+                        between.trim() !== "")
+                        break;
+                    last = next;
+                    ++index;
+                }
+            this.ensureDocumentationRange(this.text.range(first.startIndex, last.endIndex), syntax);
+        }
+    }
+    /**
+     * Collects tag-bearing string and heredoc content as documentation mappings.
+     *
+     * These literal carriers support Evidence annotations even without comments.
+     */
+    collectLiteralAnnotations() {
+        const contents = [
+            ...this.session.root.descendantsOfType("string_content"),
+            ...this.session.root.descendantsOfType("heredoc_content"),
+        ];
+        for (const content of contents) {
+            if (!this.annotation(content.text))
+                continue;
+            const range = this.session.range(content);
+            const id = `ruby:${this.source.id}:documentation:${range.start.offset}:${range.end.offset}`;
+            this.documentation.set(id, {
+                id,
+                range,
+                mapping: EvidenceDocumentation_1.EvidenceDocumentation.read(this.source.content, id, range, {
+                    opening: "",
+                    closing: "",
+                    tagBoundaries: true,
+                    allowWithdrawal: false,
+                }),
+                attachments: [],
+            });
+        }
+    }
+    /**
+     * Returns the documentation record for one exact source range and syntax.
+     *
+     * Reuse prevents duplicate mappings when several collection paths meet.
+     */
+    ensureDocumentationRange(range, syntax) {
+        const key = `${range.start.offset}:${range.end.offset}`;
+        let documentation = this.documentation.get(key);
+        if (documentation === undefined) {
+            documentation = {
+                id: `ruby:${this.source.id}:documentation:${key}`,
+                range,
+                syntax,
+                attachments: [],
+            };
+            this.documentation.set(key, documentation);
+        }
+        return documentation;
+    }
+    /**
+     * Attaches documentation to a declaration site without duplicate relations.
+     *
+     * Repeated scan paths can identify the same carrier and declaration pair.
+     */
+    attach(documentation, declarationId, siteId) {
+        if (!documentation.attachments.some((attachment) => attachment.declarationId === declarationId &&
+            attachment.siteId === siteId))
+            documentation.attachments.push({ declarationId, siteId });
+    }
+    /**
+     * 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.
+     */
+    containsSurfaceChange(node) {
+        const queue = [node];
+        for (let index = 0; index < queue.length; ++index) {
+            const current = queue[index];
+            if (current === undefined)
+                continue;
+            if (current.type === "class" ||
+                current.type === "module" ||
+                current.type === "singleton_class" ||
+                current.type === "method" ||
+                current.type === "singleton_method" ||
+                current.type === "alias" ||
+                current.type === "undef")
+                return true;
+            if (current.type === "assignment" &&
+                RubySyntax_1.RubySyntax.constantPath(current.childForFieldName("left")) !== undefined)
+                return true;
+            const callName = RubySyntax_1.RubySyntax.callName(current);
+            if (callName !== undefined && this.surfaceCall(callName))
+                return true;
+            queue.push(...current.namedChildren);
+        }
+        return false;
+    }
+    /**
+     * Checks whether a call name is known to mutate Ruby declaration surface.
+     *
+     * This explicit list bounds static support and identifies dynamic directives.
+     */
+    surfaceCall(name) {
+        return [
+            "alias_method",
+            "attr",
+            "attr_accessor",
+            "attr_reader",
+            "attr_writer",
+            "autoload",
+            "class_eval",
+            "const_set",
+            "define_method",
+            "define_singleton_method",
+            "extend",
+            "include",
+            "module_eval",
+            "module_function",
+            "prepend",
+            "private",
+            "private_class_method",
+            "private_constant",
+            "protected",
+            "public",
+            "public_class_method",
+            "public_constant",
+            "refine",
+            "remove_const",
+            "remove_method",
+            "undef_method",
+            "using",
+        ].includes(name);
+    }
+    /**
+     * 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.
+     */
+    dynamicDirective(node, description) {
+        this.problem("ruby-dynamic-directive", `Ruby ${description} uses names that cannot be resolved statically.`, "Use literal symbol or string names in the selected class or module body.", node);
+    }
+    /**
+     * Resolves a constant path against the current lexical owner when relative.
+     *
+     * Absolute paths and top-level paths retain their source segments unchanged.
+     */
+    resolvePath(path, context) {
+        return path.absolute || context.kind === "top"
+            ? path.segments
+            : [...context.identity, ...path.segments];
+    }
+    /**
+     * Resolves a constant path when a supported path is present.
+     *
+     * Absence remains undefined so callers can distinguish it from top-level paths.
+     */
+    resolveOptionalPath(path, context) {
+        return path === undefined ? undefined : this.resolvePath(path, context);
+    }
+    /**
+     * Creates a public member address for instance or singleton ownership.
+     *
+     * Singleton members use the explicit `self` segment to avoid identity clashes.
+     */
+    memberAddress(owner, side, name) {
+        return side === "instance" ? [...owner, name] : [...owner, "self", name];
+    }
+    /**
+     * Serializes a lexical identity for map keys and equality checks.
+     *
+     * JSON preserves segment boundaries that a joined string could blur.
+     */
+    identityKey(identity) {
+        return JSON.stringify(identity);
+    }
+    /**
+     * Checks whether raw Ruby carrier text contains an Evidence annotation tag.
+     *
+     * The predicate is shared by comments, strings, and heredocs.
+     */
+    annotation(raw) {
+        return /(?:^|[\r\n])[ \t]*(?:#[ \t]*)?@(evidenceExcludeReview|evidenceReview|evidenceExclude|evidence|link|internal|hidden|ignore)\b/u.test(raw);
+    }
+    /**
+     * Serializes a parser node range as a stable source-local key.
+     *
+     * The immutable selected source makes its offsets suitable for record identity.
+     */
+    nodeKey(node) {
+        return `${node.startIndex}:${node.endIndex}`;
+    }
+    /**
+     * Creates the stable declaration-site identity for a Ruby parser node.
+     *
+     * The source ID scopes a range that could recur in another selected file.
+     */
+    siteId(node) {
+        return `ruby:${this.source.id}:site:${this.nodeKey(node)}`;
+    }
+    /**
+     * Records one static-analysis failure and marks the file incomplete.
+     *
+     * A source-range key suppresses repeated diagnostics from overlapping checks.
+     */
+    problem(code, message, repair, node) {
+        const key = `${code}:${node.startIndex}:${node.endIndex}`;
+        if (this.reported.has(key))
+            return;
+        this.reported.add(key);
+        this.complete = false;
+        this.diagnostics.push({
+            code,
+            severity: "error",
+            message,
+            repair,
+            location: {
+                file: this.source.physicalPath,
+                range: this.session.range(node),
+            },
+        });
+    }
+}
+exports.RubyFileScanner = RubyFileScanner;