Module source_attributes 

Byte-level scanners for the two Erlang attributes that drive HeaderFileMissing and BehaviourModuleMissing.

Both attributes have stable, line-oriented shapes:

• -behaviour(custom_ct_hook). (also spelled -behavior(...) in OTP-style sources)
• -include("rel/path.hrl"). and -include_lib("app/include/file.hrl").

We scan the source byte by byte, balancing strings, char literals, and % line comments. Anything more complex (macro-substituted attributes, parse_transform-injected values) is not visible to the scanner: those cases are left to a follow-up --deep-helper-resolution pass.

Structs

BehaviourRef

One scanned -behaviour(M) declaration, with the line number for the user-facing report.

ExportedType

A type a module exports, and the line its entry sits on.

FunctionSignature

One name(Args) occurrence: a clause head when followed by -> or when, a call otherwise. Arity is the top-level argument count.

ImportedFunction

A function brought into a module’s namespace by -import(Module, [f/a, ...]). The module is retained so a patch-added import can be resolved as the cross-module reference m:f/a it actually is.

IncludeRef

One scanned -include(...) or -include_lib(...) declaration, with the line number for the user-facing report.

MacroDef

ScannedUse

One scanned ?MACRO or #record use, with its line for the report.

Surface

A set of keys the source lists, together with whether the list is the whole truth. lookup is the only way to ask about a key: there is no contains, iter, or Deref to the listed set, so a reader cannot take a plain bool from an incomplete surface by accident.

Enums

ExportedTypes

A module’s -export_type([t/a, ...]) list, either readable in full or not: nothing looks a type up in it, the axis walks it, so the list is read as a whole rather than key by key.

Presence

Whether a key is in a Surface.

TypesUnreadable

Why an exported-type list cannot be read from source. -compile(export_all) exports functions, not types, so it has no arm here.

Unreadable

Why an export surface cannot be fully read from source.

Functions

behaviour_resolves

Resolve behaviour against the target tree using the same test_helper_search_paths globs as the SUITE helper resolver.

declares_parse_transform

True when the module declares a parse_transform, which can inject functions the scanner cannot see: the caller suppresses local-call flagging for such a module.

extract_behaviours

Extract every -behaviour(M) / -behavior(M) declaration in src. Macro-valued and parse-transform-injected attributes are invisible to the syntactic walk.

extract_callbacks

A behaviour module’s -callback name(Args) -> Ret. signatures, keyed by (function, arity). Same walker and grammar as extract_specs.

extract_defined_macro_values

Every -define in src with its normalized body, keyed by name. A name defined more than once (-ifdef branches, or coexisting object-like and function-like forms) keeps every definition, so the caller can withhold instead of guessing which one is live.

extract_defined_macros

Macro names defined via -define(NAME, ...) or -define(NAME(Args), ...). Conditional nesting is ignored: a macro with any -define counts as present, so the resolver never false-flags a defined macro (the rare inactive-branch define is the one documented miss).

extract_defined_records

Record names defined via -record(name, {...}).

extract_defined_types

The types a module declares. Walks form starts, not parenthesised attribute bodies: -type t() :: term(). is not an -attr(...) form, though the equivalent -type(t() :: term()). is also legal.

extract_exported_types

The types a module exports. An entry whose name fails newtype validation is dropped: it would not compile, so nothing resolves against it.

extract_exports

Functions a module exports via -export([f/a, ...]). The surface is unreadable under -compile(export_all) (or nowarn_export_all), a declared parse_transform (which can inject exports), or an -export entry naming a macro the scanner cannot expand.

extract_function_signatures

Every scanned name(Args) occurrence, classified into definitions and calls. Qualified (mod:f(), macro (?f(), and fun name( forms are skipped, as are reserved words. Variables (Var(...)) and attribute or spec forms (-export(...), -spec ... term()) hold no local calls, so they are consumed without emitting a signature.

extract_function_signatures_with_context

extract_function_signatures for an added-lines blob, with each blob line’s hunk-walked classification. The byte-level attribute tracking alone misreads a blob whose attribute opener or terminator sits on a dropped context line; ctx is authoritative at each line start and the intra-line transitions still apply within a line.

extract_imports

The functions imported via -import(mod, [f/a, ...]), each carrying its source module. An entry whose module or name fails newtype validation is dropped: it would not compile, so nothing resolves against it.

extract_includes

Extract every -include("…") and -include_lib("app/…") declaration in src. Only literal string arguments are recognised; -include(?MACRO) is skipped.

extract_macro_uses

Every ?MACRO reference in src, comments and strings skipped. ??NAME (stringify) counts as a use of NAME.

extract_optional_callbacks

The (function, arity) pairs a behaviour lists in -optional_callbacks([f/a, ...]).

extract_record_uses

Every #record use in src (creation, match, update, field access), comments and strings skipped. #{...} maps have no name and are ignored.

extract_specs

A module’s -spec name(Args) -> Ret. signatures, keyed by (function, arity). Parsing is backhopper-erlang-scan’s parse_callable_signature: the same grammar the snapshot pipeline uses, so the live axis and the snapshot axis cannot disagree on what a spec is or which arity it has. Module-qualified forms parse to None and are simply absent, which withholds downstream.

has_macro_expanded_attribute

True when the source declares a macro-expanded attribute form (-?PROTOCOL_TYPE(t()).), which can expand to any attribute: rabbit_framing declares its whole type surface this way. No attribute-derived set from such a file is knowable.

is_predefined_macro

erlc predefines these, so a reference to one is never undefined.

resolve_include

Try to find the on-target path the include directive points at. Returns Ok(found) on resolution, Err(attempted_paths) when none of the candidate target paths exist.

Type Aliases

ExportSurface

A module’s exported f/a surface.

SpecTable

A module’s -spec signatures, keyed by (function, arity).