fallow_types/

extract.rs

//! Module extraction types.

use std::path::PathBuf;
use std::sync::Arc;

use oxc_span::Span;

pub use crate::complexity_contribution::{
    ComplexityContribution, ComplexityContributionKind, ComplexityMetric,
};
use crate::discover::FileId;
use crate::suppress::{Suppression, UnknownSuppressionKind};

/// Extracted module information from a single file.
///
/// The `Arc<[T]>` fields are immutable after extraction and are shared by
/// refcount with the resolver's per-file output, so the resolve/graph path
/// does not deep-copy per-file extraction payloads.
#[derive(Debug, Clone)]
pub struct ModuleInfo {
    /// Unique identifier for this file.
    pub file_id: FileId,
    /// All export declarations in this module.
    pub exports: Arc<[ExportInfo]>,
    /// All import declarations in this module.
    pub imports: Vec<ImportInfo>,
    /// All re-export declarations (e.g., `export { foo } from './bar'`).
    pub re_exports: Vec<ReExportInfo>,
    /// All dynamic `import()` calls with string literal sources.
    pub dynamic_imports: Vec<DynamicImportInfo>,
    /// Dynamic import patterns.
    pub dynamic_import_patterns: Vec<DynamicImportPattern>,
    /// All `require()` calls.
    pub require_calls: Vec<RequireCallInfo>,
    /// Package names statically referenced through package path resolution.
    pub package_path_references: Box<[String]>,
    /// Package names that a module augmentation (`declare module 'pkg'` in a
    /// module file) names. They credit the package as a type-only use.
    pub type_package_references: Box<[String]>,
    /// Binary names found in `node_modules/.bin/<name>` paths in string
    /// literals and template quasis. The analysis maps each name to the
    /// package that declares the binary.
    pub bin_path_references: Box<[String]>,
    /// Package names from direct `require.resolve('pkg')` calls, each with the
    /// byte offset of its call. A name from a resolver function, a loop
    /// binding or a static table has no site, because it is a heuristic
    /// credit. The unlisted-dependency check reports a site like an import.
    pub package_resolve_sites: Box<[(String, u32)]>,
    /// Static member access expressions (e.g., `Status.Active`).
    pub member_accesses: Arc<[MemberAccess]>,
    /// Typed semantic facts produced by extraction for cross-layer analysis.
    ///
    /// This carries facts that were previously encoded as synthetic
    /// `member_accesses` strings. Extraction and analysis now use typed facts.
    pub semantic_facts: Arc<[SemanticFact]>,
    /// Identifiers used in whole-object access patterns.
    pub whole_object_uses: Arc<[String]>,
    /// Whether this module uses CommonJS exports.
    pub has_cjs_exports: bool,
    /// Whether this module declares an Angular component `templateUrl`.
    pub has_angular_component_template_url: bool,
    /// xxh3 hash of the file content for incremental caching.
    pub content_hash: u64,
    /// Number of parser diagnostics the parse of this file produced. Non-zero
    /// means imports, exports and references after the first error may be
    /// missing (`source-parse-degraded`, which never withholds a finding).
    /// Zero for non-JS extraction paths, which do not run the oxc parser.
    pub parse_error_count: u32,
    /// `true` when the parser abandoned the file instead of recovering. The
    /// extracted module is then a fragment of the real one at best.
    pub parse_panicked: bool,
    /// `true` when the file nests too deep to parse, so it was not parsed.
    pub parse_nesting_too_deep: bool,
    /// Inline suppression directives parsed from comments.
    pub suppressions: Vec<Suppression>,
    /// Suppression tokens that did not parse to any known `IssueKind`.
    /// Surfaced as `StaleSuppression` findings via `find_stale` so users see
    /// typos or obsolete kind names instead of having the entire marker
    /// silently discarded. See issue #449.
    pub unknown_suppression_kinds: Vec<UnknownSuppressionKind>,
    /// Local names of import bindings that are never referenced in this file.
    /// Populated via `oxc_semantic` scope analysis. Used at graph-build time
    /// to skip adding references for imports whose binding is never read,
    /// improving unused-export detection precision.
    pub unused_import_bindings: Vec<String>,
    /// Local import bindings that are referenced from TypeScript type positions.
    /// Used to distinguish value-namespace and type-namespace references when a
    /// module exports both `const X` and `type X`.
    pub type_referenced_import_bindings: Vec<String>,
    /// Local import bindings referenced from runtime/value positions.
    pub value_referenced_import_bindings: Vec<String>,
    /// Pre-computed byte offsets where each line starts.
    pub line_offsets: Vec<u32>,
    /// Per-function complexity metrics.
    pub complexity: Vec<FunctionComplexity>,
    /// Feature flag use sites.
    pub flag_uses: Vec<FlagUse>,
    /// Flag-key registries this module exports, and flag reads that name a
    /// member of an imported registry. `None` for the common module with
    /// neither.
    pub flag_registry_facts: Option<Box<FlagRegistryFacts>>,
    /// Heritage metadata for exported classes that declare `implements`.
    pub class_heritage: Vec<ClassHeritageInfo>,
    /// Exported free-function factories that provably return one class instance
    /// (`export function useApi() { return new RESTApi() }`). Origin-module proof
    /// that an exported function returns a class instance, so a cross-module
    /// `const x = useApi(); x.member` consumer can credit the returned class.
    /// See issue #1441 (Part A).
    pub exported_factory_returns: Arc<[FactoryReturnExport]>,
    /// Exported factories that return an OBJECT LITERAL whose property values are
    /// class instances (`export function createUi() { return { orders: factory.ordersPage } }`).
    /// Each entry maps a dotted property path (`orders`, `invoke.dashboard`) to the
    /// returned class's local name within the factory module, so a cross-module
    /// `const ui = createUi(); ui.orders.member` consumer can credit the class. Names
    /// are local to this module; resolution is deferred to analyze time. See issue #1858.
    pub exported_factory_return_object_shapes: Arc<[FactoryReturnObjectShapeExport]>,
    /// Named-type property types declared by this module's top-level interfaces
    /// and type-literal aliases (`interface Opts { c: OptDep }`). Names are
    /// local to this module; resolution is deferred to analyze time. Consumed
    /// by the `unused-class-member` typed-property-hop join and the Playwright
    /// fixture-type resolution. See issue #1785.
    pub type_member_types: Arc<[TypeMemberTypeEntry]>,
    /// Angular `InjectionToken<Interface>` declarations, as
    /// `(token_export_name, interface_name)` pairs. Recorded only for
    /// `new InjectionToken<I>(...)` initializers whose `InjectionToken` is
    /// imported from `@angular/core`. The analyze layer follows the token's
    /// interface type argument to the classes that `implement` it so a template
    /// member call through `inject(TOKEN)` credits the concrete implementation.
    /// See issue #920 (follow-up to #911 / #913).
    pub injection_tokens: Vec<(String, String)>,
    /// Local type-capable declarations.
    pub local_type_declarations: Vec<LocalTypeDeclaration>,
    /// Type references in exported public signatures.
    pub public_signature_type_references: Vec<PublicSignatureTypeReference>,
    /// Aliases of namespace imports re-exported through an object literal.
    pub namespace_object_aliases: Vec<NamespaceObjectAlias>,
    /// Deduped Iconify collection prefixes found in static icon props.
    pub iconify_prefixes: Vec<String>,
    /// Deduped Nuxt UI `i-<collection>-<icon>` icon class suffixes found in
    /// static script-side icon properties.
    pub iconify_icon_names: Vec<String>,
    /// Bare identifiers that may be resolved by framework auto-imports.
    pub auto_import_candidates: Vec<String>,
    /// File-level string directives in source order (e.g. `"use client"`,
    /// `"use server"`, `"use strict"`). Captured from `Program::directives`.
    /// Consumed by the security `client-server-leak` detector to identify
    /// React Server Component client boundaries.
    pub directives: Vec<String>,
    /// Byte-offset starts of dynamic `import()` expressions wrapped in
    /// `next/dynamic(() => import('./X'), { ssr: false })`. The ssr:false option
    /// is Next.js's sanctioned way to pull a client-only module, so a server-only
    /// module reached ONLY through such an import is NOT a client-server leak. The
    /// security `client-server-leak` BFS resolves each dynamic import to a graph
    /// edge; these span starts let the BFS exclude exactly those edges (matched
    /// against the edge's `import_span`). Empty for files with no ssr:false
    /// dynamic import. Captured only by JS/TS extraction.
    pub client_only_dynamic_import_spans: Vec<u32>,
    /// Captured security sink sites (category-blind). Consumed by the
    /// catalogue-driven `tainted_sink` detector. Captured only by JS/TS
    /// extraction; empty for CSS/MDX/etc. See `security_matchers.toml`.
    pub security_sinks: Vec<SinkSite>,
    /// Count of sink-shaped nodes whose callee could not be flattened to a
    /// static path (dynamic dispatch, computed members, aliased bindings).
    /// Surfaced in-band so an empty catalogue result with a non-zero count is
    /// not a clean bill.
    pub security_sinks_skipped: u32,
    /// Compact span-level diagnostics for skipped security sink callees. Kept
    /// next to `security_sinks_skipped` so warm-cache and cold-cache security
    /// output can explain where the blind spots are concentrated without source
    /// snippets.
    pub security_unresolved_callee_sites: Vec<SkippedSecurityCalleeSite>,
    /// Local bindings whose initializer (or destructured object) is a flattened
    /// member-access path. Used by the security `tainted_sink` detector to
    /// back-trace a sink argument to a known untrusted source: the analyze layer
    /// matches each binding's `source_path` against the data-driven source
    /// catalogue (`security_matchers.toml` `[[source]]` rows) and treats the
    /// matching `local` names as source-tainted. Intra-module and name-based
    /// (no scope analysis); a conservative association, never a taint proof.
    pub tainted_bindings: Vec<TaintedBinding>,
    /// Sink arguments that were recognized as sanitizer calls at extraction
    /// time. Used for direct sink calls such as
    /// `el.innerHTML = DOMPurify.sanitize(input)`.
    pub sanitized_sink_args: Vec<SanitizedSinkArg>,
    /// Control patterns observed in this module. Surface context only: their
    /// presence does not establish input identity, execution order, or protection.
    pub security_control_sites: Vec<SecurityControlSite>,
    /// Statically flattenable callee paths invoked in this module, deduped per
    /// unique path (first occurrence wins). Consumed by the
    /// `boundaries.calls.forbidden` detector. Captured unconditionally because
    /// extraction is config-blind; the per-module cost is bounded by the
    /// unique-callee count.
    pub callee_uses: Vec<CalleeUse>,
    /// Per-call references to actual runtime ESM import bindings.
    pub imported_call_sites: Arc<[ImportedCallSite]>,
    /// Value references to runtime ESM import bindings that are not admitted
    /// call sites, plus admitted calls that initialize a top-level declarator.
    /// Sorted by `span_start`. Read by `fallow trace --dependency`.
    pub import_binding_references: Arc<[ImportBindingReference]>,
    /// `"use client"` / `"use server"` directive strings written as expression
    /// statements in `program.body` (misplaced, NOT in the leading
    /// prologue), so the RSC bundler silently ignores them. One entry per
    /// occurrence. Consumed by the `misplaced-directive` detector. Captured
    /// only by JS/TS extraction.
    pub misplaced_directives: Vec<MisplacedDirectiveSite>,
    /// Export LOCAL NAMES of exported functions / const-arrows whose body has an
    /// inline `"use server"` directive (`export async function f() { "use server"
    /// }`), captured in a NON-`"use server"` file. Consumed by the
    /// `unused-server-action` detector to reclassify an unused inline Server
    /// Action export out of `unused-export`. Captured only by JS/TS extraction.
    pub inline_server_action_exports: Vec<String>,
    /// Vue `provide`/`inject` and Svelte `setContext`/`getContext` call sites
    /// keyed by an identifier symbol. Consumed by the `unprovided-inject`
    /// detector to find an inject/getContext whose key is provided nowhere
    /// project-wide. Only identifier-keyed sites are recorded (string-literal
    /// and computed keys abstain). Captured by JS/TS and SFC extraction.
    pub di_key_sites: Vec<DiKeySite>,
    /// `true` when this module contains a `provide(...)` / `*.provide(...)` /
    /// `setContext(...)` call whose key argument is NOT a plain identifier
    /// (spread, computed, member, loop variable). Such a call can provide an
    /// unknowable key, so the `unprovided-inject` detector abstains on ALL
    /// inject findings project-wide when any reachable module sets this flag.
    /// Mirrors the spread-return whole-object abstain used for Pinia stores.
    pub has_dynamic_provide: bool,
    /// `true` when the prologue holds `"use server"` and every value export
    /// is an async function (a Server Action). A `"use client"` import of
    /// such a module becomes an action reference, so the security
    /// `client-server-leak` BFS stops at the module. `false` for every other
    /// module, including a `"use server"` file with a non-action value
    /// export. Captured only by JS/TS extraction.
    pub is_server_action_module: bool,
    /// `true` when TypeScript reads this file as adding to the global scope:
    /// a script file (no top-level import or export), or a module file with a
    /// top-level `declare global` block or string-named `declare module`
    /// block. Read only for declaration files (`.d.ts`, `.d.mts`, `.d.cts`):
    /// a declaration file without global declarations is seeded as an entry
    /// point only when something points to it. Captured only by JS/TS
    /// extraction; `false` for every other module.
    pub has_global_declarations: bool,
    /// Raw `path` values of `/// <reference path="..." />` directives in this
    /// file, in source order. A declaration file named by one stays an entry
    /// point. Captured only by JS/TS extraction.
    pub triple_slash_reference_paths: Box<[String]>,
    /// `true` when the file has a JSX element or fragment and no
    /// `@jsxImportSource` or `@jsxRuntime classic` pragma. A bundler or test
    /// config can then select the automatic JSX runtime for the file, so the
    /// resolver adds the runtime edge from a plugin rule. Captured only by
    /// JS/TS extraction; `false` for every other module.
    pub jsx_runtime_from_config: bool,
    /// Local names of import bindings that ARE referenced somewhere in this file
    /// (script value/type position OR template/markup). The complement of
    /// `unused_import_bindings` among `imports`. Derived by
    /// `prepare_analysis_facts` while both source vectors are still present, so
    /// it remains readable after the owned release path clears them. It is never
    /// cached and is recomputed on every cache load. Consumed by the
    /// `unrendered-component` detector to credit a
    /// Vue/Svelte SFC that some file actually imports-and-uses, distinguishing it
    /// from a component reachable only through a barrel re-export.
    pub referenced_import_bindings: Vec<String>,
    /// Vue `<script setup>` `defineProps` and Svelte 5 `$props()` declared
    /// props. Consumed by the `unused-component-prop` detector to flag a prop
    /// referenced nowhere in its own SFC. Each entry carries `used_in_script` /
    /// `used_in_template`.
    pub component_props: Vec<ComponentProp>,
    /// Cached framework-neutral component input contracts and inspected callers.
    pub component_contracts: Option<Box<ComponentContractFacts>>,
    /// Effect layer, tagged error and `catchTag` facts. Set only for a module
    /// that imports `effect` or an `@effect/*` package.
    pub effect_facts: Option<Box<EffectFacts>>,
    /// `true` when the template spreads the whole props/attrs object
    /// (`v-bind="$attrs"` / `v-bind="$props"` / `v-bind="props"`) or the props
    /// return is destructured with a rest element. Either form can consume a prop
    /// indirectly, so the detector abstains on the whole file.
    pub has_props_attrs_fallthrough: bool,
    /// `true` when the SFC calls `defineExpose(...)`. A prop may be re-exposed,
    /// so the detector conservatively abstains on the whole file.
    pub has_define_expose: bool,
    /// `true` when the SFC calls `defineModel(...)`. Two-way model props are out
    /// of scope for v1, so the detector abstains on the whole file.
    pub has_define_model: bool,
    /// `true` when props were declared through an unharvestable shape, such as a
    /// Vue type-reference argument or an opaque Svelte `$props()` destructure.
    /// The detector abstains on the whole file so a prop is never falsely
    /// flagged.
    pub has_unharvestable_props: bool,
    /// Vue `<script setup>` `defineEmits` declared events. Consumed by the
    /// `unused-component-emit` detector to flag an event emitted nowhere in its
    /// own SFC. Each entry carries `used`.
    pub component_emits: Vec<ComponentEmit>,
    /// Angular component/directive inputs declared via `@Input()` decorators or
    /// signal `input()` / `input.required()` / `model()` initializers. Consumed
    /// by the `unused-component-input` detector to flag an input read nowhere in
    /// its own component. Empty for every non-Angular class.
    pub angular_inputs: Vec<AngularInputMember>,
    /// Angular component/directive outputs declared via `@Output()` decorators or
    /// signal `output()` / `outputFromObservable()` initializers. Consumed by the
    /// `unused-component-output` detector to flag an output emitted nowhere in its
    /// own component. A `model()` is recorded as an input only (see
    /// `AngularOutputMember`). Empty for every non-Angular class.
    pub angular_outputs: Vec<AngularOutputMember>,
    /// Angular `@Component` declarations with their `selector` value(s), harvested
    /// from `@Component({ selector: '...' })` decorators. Consumed by the Angular
    /// arm of the `unrendered-component` detector. Empty for every non-Angular
    /// class and for `@Directive`. See `AngularComponentSelector`.
    pub angular_component_selectors: Vec<AngularComponentSelector>,
    /// Lit / web-component custom elements REGISTERED in this file via
    /// `@customElement('x-foo')` or `customElements.define('x-foo', C)`. Consumed
    /// by the Lit arm of the `unrendered-component` detector, which flags a
    /// registered element whose tag is rendered in NO `html` template
    /// project-wide. Empty for non-Lit / non-web-component files. See
    /// `RegisteredCustomElement`.
    pub registered_custom_elements: Vec<RegisteredCustomElement>,
    /// Custom-element tag names USED (rendered) in this file's `html` tagged
    /// templates, e.g. `` html`<x-foo></x-foo>` `` -> `x-foo`. Only hyphenated
    /// (custom-element) tags are recorded; native HTML tags are excluded by the
    /// hyphen requirement. The detector unions these project-wide into the
    /// rendered-tag set. Empty for files with no `html` templates.
    pub used_custom_element_tags: Vec<String>,
    /// Custom element selector tag names referenced in this file's Angular
    /// templates (inline `@Component({ template })` and the linked external
    /// `templateUrl` `.html` module), e.g. `<app-foo>` -> `app-foo`. Native HTML
    /// tag names are excluded at harvest. The detector unions these project-wide
    /// into the used-selector set. Empty for non-Angular files.
    pub angular_used_selectors: Vec<String>,
    /// Angular component class names referenced as a route entry or bootstrap
    /// target: a route `component: Foo` / `loadComponent: () => import().then(m =>
    /// m.Foo)` value, a `bootstrapApplication(Foo)` argument, or a
    /// `bootstrap: [Foo]` NgModule entry. These are render-equivalent entry points
    /// (Angular instantiates them without a template `<tag>`), so the Angular
    /// `unrendered-component` detector abstains on a component whose class name is
    /// in the project-wide union. A plain `declarations: [...]` / `imports: [...]`
    /// registration is intentionally NOT harvested here (that is the dead case the
    /// rule catches). Empty for non-Angular files.
    pub angular_entry_component_refs: Vec<String>,
    /// `true` when this file dynamically renders an Angular component fallow
    /// cannot attribute to a literal class reference: a
    /// `ViewContainerRef.createComponent(...)` / `*.createComponent(<ident>)`
    /// call, or an `*ngComponentOutlet` template binding. The Angular
    /// `unrendered-component` detector abstains project-wide when ANY reachable
    /// module sets this (mirroring `unprovided-inject`'s `has_dynamic_provide`),
    /// since a component could be rendered by a non-literal class reference.
    pub has_dynamic_component_render: bool,
    /// `true` when `defineEmits` was called with an unharvestable argument (a
    /// type-reference type argument such as `defineEmits<MyEmits>()`, a
    /// non-literal runtime form, or an unbound `defineEmits([...])`). The
    /// detector abstains on the whole file so an emit is never falsely flagged.
    pub has_unharvestable_emits: bool,
    /// `true` when an `emit(<nonLiteral>)` call was seen (the emitted event name
    /// cannot be known statically). The detector abstains on the whole file.
    pub has_dynamic_emit: bool,
    /// `true` when the `defineEmits` return binding was used as a WHOLE value
    /// (passed to a function, returned, or spread), which can emit any event
    /// opaquely. The detector abstains on the whole file.
    pub has_emit_whole_object_use: bool,
    /// SvelteKit `load()` return-object keys harvested from a
    /// `+page.{ts,server.ts,js,server.js}` file's terminal return literal.
    /// Consumed by the `unused-load-data-key` detector. Empty for every file
    /// that is not a page-load producer (gated by basename at harvest time).
    pub load_return_keys: Vec<LoadReturnKey>,
    /// `true` when this file's `load()` body could not be harvested safely (a
    /// spread return, a non-object/non-literal return, more than one top-level
    /// `return`, a computed key, or a wrapped/re-exported `load`). The detector
    /// abstains on the whole file so a key is never falsely flagged.
    pub has_unharvestable_load: bool,
    /// `true` when this file passes the whole `data` object opaquely (script
    /// `const X = data`, `fn(data)` / `fn(...data)`, or template `data={data}` /
    /// `{...data}` in a route component), so a child can read arbitrary keys the
    /// detector cannot see. Name-gated on the `data` binding. Read ONLY by the
    /// `unused-load-data-key` detector, so capturing it for all files is
    /// byte-identity-safe. See FP-1 in the plan.
    pub has_load_data_whole_use: bool,
    /// `true` when this file uses the whole `page.data` / `$page.data` store
    /// object opaquely (e.g. `Object.values(page.data)`, `{...$page.data}`), so a
    /// reflective read could consume any route's key. Drives the
    /// `unused-load-data-key` detector's project-wide abstain. Derived by
    /// `prepare_analysis_facts` from `whole_object_uses` before the owned release
    /// path clears that vector. It is never cached and is recomputed each run from
    /// the cached `whole_object_uses`. Reassignment forms
    /// (`const all = $page.data`) are not whole-object-tracked and stay out of
    /// scope, matching the syntactic analyzer's conservative posture.
    pub has_page_data_store_whole_use: bool,
    /// `true` when a React Router or Remix route consumes the whole
    /// `useLoaderData()` result opaquely. Derived by `prepare_analysis_facts`
    /// from the synthetic route-loader marker before the owned release path
    /// clears `whole_object_uses`. It is recomputed from cached extraction data.
    pub has_route_loader_data_whole_use: bool,
    /// React/JSX component definitions: functions/arrows whose body returns JSX.
    /// Captured only for `.jsx`/`.tsx` files when a React/Preact dependency is
    /// plausible. Consumed by the React `unused-component-prop` arm and the
    /// complexity-fold phase. Empty for non-React files.
    pub component_functions: Vec<ComponentFunction>,
    /// React component props (reuses the shared `ComponentProp` struct). For
    /// React, `used_in_template` is always false and `used_in_script` means
    /// used-in-body. Empty for non-React files.
    pub react_props: Vec<ComponentProp>,
    /// React hook call sites (`useState` / `useEffect` / `useMemo` /
    /// `useCallback` / custom `use*`). Drives hook-density complexity context.
    /// Empty for non-React files.
    pub hook_uses: Vec<HookUse>,
    /// React render edges: one component rendering another. Captured with the
    /// child's written name; child-to-`FileId` resolution is deferred to graph
    /// build. Empty for non-React files.
    pub render_edges: Vec<RenderEdge>,
    /// Svelte custom events dispatched via `dispatch('<name>')` where `dispatch`
    /// is the binding from `const dispatch = createEventDispatcher()`. Consumed
    /// by the `unused-svelte-event` detector to flag an event dispatched here but
    /// listened to nowhere project-wide. Each entry carries the literal event
    /// name and its span. Empty for every non-Svelte file.
    pub svelte_dispatched_events: Vec<DispatchedEvent>,
    /// Svelte custom-event listener names harvested from template `on:<name>`
    /// bindings on COMPONENT tags (PascalCase tag names). Lowercase DOM-element
    /// `on:click` is a DOM event, not a custom event, and is excluded. Unioned
    /// project-wide by the `unused-svelte-event` detector to build the liberal
    /// "listened" set. Empty for every non-Svelte file.
    pub svelte_listened_events: Vec<String>,
    /// `true` when a `dispatch(<nonLiteral>)` call was seen (the dispatched event
    /// name cannot be known statically), or the `dispatch` binding was used as a
    /// whole value (passed / returned). The `unused-svelte-event` detector
    /// abstains on the whole component so an event is never falsely flagged.
    pub has_dynamic_dispatch: bool,
}

impl ModuleInfo {
    /// A fully-zeroed `ModuleInfo` for the given file.
    ///
    /// Fixture builders and non-JS extraction paths start from this and set
    /// only the fields they care about via struct-update syntax:
    /// `ModuleInfo { exports: vec![..], ..ModuleInfo::empty(file_id) }`.
    #[must_use]
    pub fn empty(file_id: FileId) -> Self {
        Self {
            file_id,
            exports: Arc::default(),
            imports: Vec::new(),
            re_exports: Vec::new(),
            dynamic_imports: Vec::new(),
            dynamic_import_patterns: Vec::new(),
            require_calls: Vec::new(),
            package_path_references: Box::default(),
            type_package_references: Box::default(),
            bin_path_references: Box::default(),
            package_resolve_sites: Box::default(),
            member_accesses: Arc::default(),
            semantic_facts: Arc::default(),
            whole_object_uses: Arc::default(),
            has_cjs_exports: false,
            has_angular_component_template_url: false,
            content_hash: 0,
            parse_error_count: 0,
            parse_panicked: false,
            parse_nesting_too_deep: false,
            suppressions: Vec::new(),
            unknown_suppression_kinds: Vec::new(),
            unused_import_bindings: Vec::new(),
            type_referenced_import_bindings: Vec::new(),
            value_referenced_import_bindings: Vec::new(),
            line_offsets: Vec::new(),
            complexity: Vec::new(),
            flag_uses: Vec::new(),
            flag_registry_facts: None,
            class_heritage: Vec::new(),
            exported_factory_returns: Arc::default(),
            exported_factory_return_object_shapes: Arc::default(),
            type_member_types: Arc::default(),
            injection_tokens: Vec::new(),
            local_type_declarations: Vec::new(),
            public_signature_type_references: Vec::new(),
            namespace_object_aliases: Vec::new(),
            iconify_prefixes: Vec::new(),
            iconify_icon_names: Vec::new(),
            auto_import_candidates: Vec::new(),
            directives: Vec::new(),
            client_only_dynamic_import_spans: Vec::new(),
            security_sinks: Vec::new(),
            security_sinks_skipped: 0,
            security_unresolved_callee_sites: Vec::new(),
            tainted_bindings: Vec::new(),
            sanitized_sink_args: Vec::new(),
            security_control_sites: Vec::new(),
            callee_uses: Vec::new(),
            imported_call_sites: Arc::default(),
            import_binding_references: Arc::default(),
            misplaced_directives: Vec::new(),
            inline_server_action_exports: Vec::new(),
            di_key_sites: Vec::new(),
            has_dynamic_provide: false,
            is_server_action_module: false,
            has_global_declarations: false,
            triple_slash_reference_paths: Box::default(),
            jsx_runtime_from_config: false,
            referenced_import_bindings: Vec::new(),
            component_props: Vec::new(),
            component_contracts: None,
            effect_facts: None,
            has_props_attrs_fallthrough: false,
            has_define_expose: false,
            has_define_model: false,
            has_unharvestable_props: false,
            component_emits: Vec::new(),
            angular_inputs: Vec::new(),
            angular_outputs: Vec::new(),
            has_unharvestable_emits: false,
            has_dynamic_emit: false,
            has_emit_whole_object_use: false,
            load_return_keys: Vec::new(),
            has_unharvestable_load: false,
            has_load_data_whole_use: false,
            has_page_data_store_whole_use: false,
            has_route_loader_data_whole_use: false,
            component_functions: Vec::new(),
            react_props: Vec::new(),
            hook_uses: Vec::new(),
            render_edges: Vec::new(),
            svelte_dispatched_events: Vec::new(),
            svelte_listened_events: Vec::new(),
            angular_component_selectors: Vec::new(),
            registered_custom_elements: Vec::new(),
            used_custom_element_tags: Vec::new(),
            angular_used_selectors: Vec::new(),
            angular_entry_component_refs: Vec::new(),
            has_dynamic_component_render: false,
            has_dynamic_dispatch: false,
        }
    }

    /// Derive compact detector facts from resolution payload before sharing.
    ///
    /// Shared analysis sessions keep the source payload for later graph runs,
    /// but detectors still require the same derived facts that the owned
    /// release path computes before clearing that payload.
    #[doc(hidden)]
    pub fn prepare_analysis_facts(&mut self) {
        // The analyze-layer `unrendered-component` detector needs the compact
        // complement of imports and unused bindings after resolution.
        self.referenced_import_bindings = self
            .imports
            .iter()
            .map(|import| import.local_name.clone())
            .filter(|name| !name.is_empty() && !self.unused_import_bindings.contains(name))
            .collect();
        self.referenced_import_bindings.sort_unstable();
        self.referenced_import_bindings.dedup();

        // The `unused-load-data-key` detector needs the project-wide signal
        // after `whole_object_uses` is released from owned artifacts.
        self.has_page_data_store_whole_use = self
            .whole_object_uses
            .iter()
            .any(|name| name == "page.data" || name == "$page.data");
        self.has_route_loader_data_whole_use = self
            .whole_object_uses
            .iter()
            .any(|name| name == "$fallow.routeLoaderData");
    }

    /// Release extraction payload that resolution has already copied into the graph.
    ///
    /// This keeps fields needed by analysis, health, security, LSP, coverage,
    /// and hash drift checks, while dropping vectors that otherwise duplicate
    /// data owned by `ResolvedModule` or already credited into the module graph.
    pub fn release_resolution_payload(&mut self) {
        self.prepare_analysis_facts();
        Self::release_vec(&mut self.dynamic_imports);
        Self::release_vec(&mut self.require_calls);
        Self::release_boxed_slice(&mut self.package_path_references);
        Self::release_boxed_slice(&mut self.type_package_references);
        Self::release_boxed_slice(&mut self.bin_path_references);
        Self::release_arc_slice(&mut self.whole_object_uses);
        Self::release_arc_slice(&mut self.import_binding_references);
        Self::release_vec(&mut self.unused_import_bindings);
        Self::release_vec(&mut self.type_referenced_import_bindings);
        Self::release_vec(&mut self.value_referenced_import_bindings);
        Self::release_vec(&mut self.namespace_object_aliases);
        Self::release_vec(&mut self.auto_import_candidates);
    }

    fn release_vec<T>(values: &mut Vec<T>) {
        *values = Vec::new();
    }

    fn release_boxed_slice<T>(values: &mut Box<[T]>) {
        *values = Box::default();
    }

    /// Drop this module's refcount; the allocation itself is freed only once
    /// the sharing `ResolvedModule` releases its clone too.
    fn release_arc_slice<T>(values: &mut Arc<[T]>) {
        *values = Arc::default();
    }
}

/// Family of a control pattern observed in a file on an import trace.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    PartialOrd,
    Ord,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "kebab-case")]
pub enum SecurityControlKind {
    /// Sanitization or escaping before a sink.
    Sanitization,
    /// Input validation or schema parsing.
    Validation,
    /// Authentication check or middleware.
    Authentication,
    /// Authorization or permission check.
    Authorization,
}

/// An observed control call or guard pattern, without proof that it protects a sink.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, bitcode::Encode, bitcode::Decode)]
pub struct SecurityControlSite {
    /// Control family.
    pub kind: SecurityControlKind,
    /// Flattened callee path or a stable synthetic name for guard-derived
    /// controls.
    pub callee_path: String,
    /// Byte offset of the control span start.
    pub span_start: u32,
    /// Byte offset of the control span end.
    pub span_end: u32,
}

/// Sanitizer output domain. Kept intentionally narrow so a sanitizer for one
/// domain cannot suppress a different sink family.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    PartialOrd,
    Ord,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
)]
pub enum SanitizerScope {
    /// HTML markup sanitized by DOMPurify-compatible APIs.
    Html,
    /// URL or redirect target checked against a literal-backed allowlist.
    Url,
    /// Path value checked against a high-confidence containment guard.
    Path,
    /// SQL identifier quoted with a helper that doubles embedded identifier quotes.
    SqlIdentifier,
}

/// A captured sink argument that is itself a recognized sanitizer call.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, bitcode::Encode, bitcode::Decode)]
pub struct SanitizedSinkArg {
    /// Byte offset of the owning sink span start.
    pub span_start: u32,
    /// The positional argument index on the owning sink.
    pub arg_index: u32,
    /// The sanitizer output domain for this argument.
    pub scope: SanitizerScope,
}

/// A local binding tied to the flattened member-access path it was initialized
/// from. The analyze layer matches `source_path` against the data-driven source
/// catalogue; when it matches, `local` is treated as carrying untrusted input.
///
/// Captured for two shapes: a direct assignment (`const id = req.query.id` ->
/// `{ local: "id", source_path: "req.query" }`, the literal-key tail dropped so
/// the path matches a catalogue prefix) and an object destructure
/// (`const { id } = req.query` -> `{ local: "id", source_path: "req.query" }`).
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, bitcode::Encode, bitcode::Decode)]
pub struct TaintedBinding {
    /// The local binding name introduced by the declarator.
    pub local: String,
    /// The flattened object member-access path the binding was sourced from.
    pub source_path: String,
    /// Byte offset of the source read (the member-access expression the binding
    /// was sourced from), so the analyze layer can anchor a taint trace's source
    /// node at the real read line instead of the module import line. Stored as a
    /// `u32` (not `Span`) to stay bitcode-encodable for the cache. `0` when no
    /// concrete read expression is available (synthetic framework-param /
    /// helper-return bindings), in which case the analyze layer falls back to the
    /// sink site rather than claiming a spurious line.
    pub source_span_start: u32,
}

/// Why a sink-shaped callee could not be flattened into a static catalogue
/// path.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    PartialOrd,
    Ord,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "kebab-case")]
pub enum SkippedSecurityCalleeReason {
    /// A computed member access such as `client[method](input)`.
    ComputedMember,
    /// A dynamic non-member callee such as `(factory())(input)`.
    DynamicDispatch,
    /// An assignment target whose object could not be flattened.
    UnsupportedAssignmentObject,
}

/// Syntactic expression shape for a skipped security callee.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    PartialOrd,
    Ord,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "kebab-case")]
pub enum SkippedSecurityCalleeExpressionKind {
    /// `obj.prop(...)`.
    StaticMemberExpression,
    /// `obj[prop](...)`.
    ComputedMemberExpression,
    /// A bare identifier or private identifier callee.
    Identifier,
    /// Any other call-like expression that cannot be represented compactly.
    Other,
}

/// Span-only diagnostic for a skipped security callee inside one module.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, bitcode::Encode, bitcode::Decode)]
pub struct SkippedSecurityCalleeSite {
    /// Why the callee was skipped.
    pub reason: SkippedSecurityCalleeReason,
    /// Compact expression shape of the skipped callee.
    pub expression_kind: SkippedSecurityCalleeExpressionKind,
    /// Start byte offset of the skipped callee expression.
    pub span_start: u32,
    /// End byte offset of the skipped callee expression.
    pub span_end: u32,
}

/// The syntactic shape of a captured security sink site. Category-blind: the
/// extractor records the shape and the dotted/bare callee path; the analyze
/// layer matches it against the data-driven catalogue. See
/// `crates/security/data/security_matchers.toml`.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
)]
pub enum SinkShape {
    /// A call to a bare identifier (e.g. `eval(x)`).
    Call,
    /// A call to a dotted member path (e.g. `child_process.exec(x)`).
    MemberCall,
    /// An assignment to a member target (e.g. `el.innerHTML = x`).
    MemberAssign,
    /// A tagged template expression (e.g. ``sql`...${x}...` ``).
    TaggedTemplate,
    /// A JSX attribute value (e.g. `dangerouslySetInnerHTML={x}`).
    JsxAttr,
    /// A constructor call (e.g. `new Function("return x")`).
    NewExpression,
    /// A static string literal assigned to a secret-shaped identifier or known
    /// provider credential prefix.
    SecretLiteral,
}

/// The shape of the argument captured at a sink site. Category-blind like
/// [`SinkShape`], but finer-grained: it lets the catalogue matcher require or
/// exclude specific argument shapes. The discriminator is what distinguishes an
/// unsafe SQL string concatenation or template-into-`.execute()` from a
/// safely-parameterized `` sql`${x}` `` tagged template, an object-literal
/// `.execute({ sql, args })` argument, or a literal-aware sink argument.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
)]
pub enum SinkArgKind {
    /// A template literal with at least one `${...}` substitution (e.g.
    /// `` `SELECT ${x}` ``). On a `tagged-template` shape this is the tag's
    /// quasi; on a `call`/`member-call` shape it is the positional argument.
    TemplateWithSubst,
    /// A binary `+` string concatenation (e.g. `"SELECT " + x`).
    Concat,
    /// An object literal (e.g. `.execute({ sql, args })`, the parameterized form).
    Object,
    /// A call expression argument (e.g. `query(buildSql())`).
    Call,
    /// A literal argument admitted by a literal-aware security matcher.
    Literal,
    /// A zero-argument sink captured because the callee itself is the signal.
    NoArg,
    /// Any other non-literal expression (bare identifier, member access, etc.).
    Other,
}

/// Static URL construction shape captured for URL-shaped security sinks.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "kebab-case")]
pub enum SecurityUrlShape {
    /// The sink target has a fixed origin, scheme, or relative root while only
    /// path or query components are dynamic.
    FixedOriginDynamicPath,
    /// The sink target's scheme or origin is dynamic or opaque.
    DynamicOrigin,
}

/// Literal values attached to literal-aware security sink captures.
#[derive(
    Debug,
    Clone,
    PartialEq,
    Eq,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
)]
pub enum SinkLiteralValue {
    /// A string literal value.
    String(String),
    /// An integer numeric literal value.
    Integer(i64),
    /// A boolean literal value.
    Boolean(bool),
    /// A null literal value.
    Null,
}

/// Static object-literal property metadata attached to a captured sink
/// argument. Nested object paths are flattened with dot-separated keys.
#[derive(
    Debug,
    Clone,
    PartialEq,
    Eq,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
)]
pub struct SinkObjectProperty {
    /// Static property name. Nested object properties use dot-separated paths.
    pub key: String,
    /// Literal property value when statically knowable.
    pub value: SinkLiteralValue,
}

/// A captured sink site. The visitor records every existing non-literal call /
/// member-assign / member-call / tagged-template / jsx-attr sink site, and a
/// small allowlist of literal-aware sites where the literal value is the signal.
/// It knows nothing about CWE categories.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, bitcode::Encode, bitcode::Decode)]
pub struct SinkSite {
    /// The syntactic shape of the sink site.
    pub sink_shape: SinkShape,
    /// The flattened dotted/bare callee or member path.
    pub callee_path: String,
    /// The positional argument index. For zero-argument captures this is 0.
    pub arg_index: u32,
    /// Whether the relevant argument is non-literal. Existing non-literal
    /// catalogue rows require this to remain true.
    pub arg_is_non_literal: bool,
    /// The finer-grained shape of the captured argument. Lets the catalogue
    /// require unsafe shapes (concat / template-with-substitution / literal /
    /// no-arg) and exclude safe ones (object literal, the parameterized form).
    /// See [`SinkArgKind`].
    pub arg_kind: SinkArgKind,
    /// Literal argument value for literal-aware rows.
    pub arg_literal: Option<SinkLiteralValue>,
    /// Risky regex fragment for structural ReDoS candidates.
    pub regex_pattern: Option<String>,
    /// Static object-literal properties for option-object rows.
    pub object_properties: Vec<SinkObjectProperty>,
    /// Static top-level object-literal keys, including keys whose values are not
    /// literal. Used by missing-option rows that only need key presence.
    pub object_property_keys: Vec<String>,
    /// Whether [`object_property_keys`](Self::object_property_keys) is complete.
    /// False for non-object arguments and object literals with spread or
    /// non-static keys, where a missing-key claim would be speculative.
    pub object_property_keys_complete: bool,
    /// Identifier names referenced anywhere inside the captured non-literal sink
    /// argument, or contextual names for zero-argument captures such as a
    /// token-like `Math.random()` assignment target. Deduped in source order.
    /// Used by the analyze layer to back-trace the sink argument to a known
    /// untrusted source or to apply narrow context gates. Intra-module,
    /// name-based, conservative; it is never a taint proof.
    pub arg_idents: Vec<String>,
    /// Flattened static member paths referenced inside the captured non-literal
    /// sink argument. Includes both the full path and source-object path for
    /// leaf reads (`process.env.SECRET` records `process.env.SECRET` and
    /// `process.env`) so direct source expressions can be matched without an
    /// intermediate local binding.
    pub arg_source_paths: Vec<String>,
    /// Byte offset of the sink span start. Stored as `u32` (not `Span`) so the
    /// struct is bitcode-encodable and can be persisted directly in the cache.
    pub span_start: u32,
    /// Byte offset of the sink span end.
    pub span_end: u32,
    /// The arg-0 URL string literal of a network-shaped call (`fetch`, `axios.*`,
    /// `got`, ...), captured so the `secret-to-network` category (#890) can carry
    /// a destination-host signal on its candidate: `Some(literal)` when the
    /// destination is a static string literal (almost always intended auth, e.g.
    /// the credential's own provider), `None` when it is dynamic (the suspicious
    /// case). `None` for non-call sinks and calls with no arg 0.
    pub url_arg_literal: Option<String>,
    /// URL construction shape for URL-like sink arguments when the extractor can
    /// classify it syntactically. `None` for non-URL sinks and URL expressions
    /// whose shape is not visible at the sink.
    pub url_shape: Option<SecurityUrlShape>,
}

impl SinkSite {
    /// Reconstruct the source span from the stored byte offsets.
    #[must_use]
    pub fn span(&self) -> Span {
        Span::new(self.span_start, self.span_end)
    }
}

/// Env var-name prefixes that frameworks inline into the client bundle by
/// convention. A read of one of these is normal and safe, so it does NOT count
/// as a secret source (issue #890). Shared by the extract layer (so public env
/// vars never become source signals) and the bespoke `client-server-leak` rule.
pub const PUBLIC_ENV_PREFIXES: &[&str] = &[
    "NEXT_PUBLIC_",
    "VITE_",
    "NUXT_PUBLIC_",
    "REACT_APP_",
    "PUBLIC_",
    "GATSBY_",
    "EXPO_PUBLIC_",
    "STORYBOOK_",
];

/// Exact env var names that are public by convention (no prefix).
pub const PUBLIC_ENV_EXACT: &[&str] = &["NODE_ENV"];

/// Env var-name tokens that usually describe public build or deployment
/// metadata rather than secrets. Secret-shaped names win over these tokens.
pub const PUBLIC_ENV_METADATA_TOKENS: &[&str] =
    &["BRANCH", "ENVIRONMENT", "MODE", "REF", "SHA", "TAG"];

/// Env var-name tokens that should keep a variable source-backed even when the
/// name also contains public metadata tokens such as `REF` or `SHA`.
pub const SECRET_ENV_TOKENS: &[&str] = &[
    "AUTH",
    "CREDENTIAL",
    "CREDENTIALS",
    "KEY",
    "PASS",
    "PASSWORD",
    "PRIVATE",
    "SECRET",
    "TOKEN",
];

fn env_name_has_token(name: &str, tokens: &[&str]) -> bool {
    name.split(|ch: char| !ch.is_ascii_alphanumeric())
        .filter(|part| !part.is_empty())
        .any(|part| tokens.contains(&part))
}

/// Whether an env var name is public-by-convention (build-inlined into the
/// client bundle), and therefore not a secret.
#[must_use]
pub fn is_public_env_var(name: &str) -> bool {
    if PUBLIC_ENV_EXACT.contains(&name) || PUBLIC_ENV_PREFIXES.iter().any(|p| name.starts_with(p)) {
        return true;
    }
    env_name_has_token(name, PUBLIC_ENV_METADATA_TOKENS)
        && !env_name_has_token(name, SECRET_ENV_TOKENS)
}

/// Whether a flattened member path is a PUBLIC env-secret read
/// (`process.env.NEXT_PUBLIC_X`, `import.meta.env.VITE_Y`), which must not be
/// recorded as a secret source. Non-env paths (`req.query.id`) are never public.
#[must_use]
pub fn is_public_env_path(path: &str) -> bool {
    for object in ["process.env.", "import.meta.env."] {
        if let Some(var) = path.strip_prefix(object) {
            return is_public_env_var(var);
        }
    }
    false
}

/// One alias entry tying an exported object's dotted property path to a namespace import.
#[derive(Debug, Clone)]
pub struct NamespaceObjectAlias {
    /// Canonical export name.
    pub via_export_name: String,
    /// Dotted suffix of the property path relative to the export.
    pub suffix: String,
    /// Local name of the namespace import.
    pub namespace_local: String,
}

/// Compute a table of line-start byte offsets from source text.
#[must_use]
#[expect(
    clippy::cast_possible_truncation,
    reason = "source files are practically < 4GB"
)]
pub fn compute_line_offsets(source: &str) -> Vec<u32> {
    let mut offsets = vec![0u32];
    for (i, byte) in source.bytes().enumerate() {
        if byte == b'\n' {
            debug_assert!(
                u32::try_from(i + 1).is_ok(),
                "source file exceeds u32::MAX bytes: line offsets would overflow"
            );
            offsets.push((i + 1) as u32);
        }
    }
    offsets
}

/// Convert a byte offset to a 1-based line number and 0-based byte column.
#[must_use]
#[expect(
    clippy::cast_possible_truncation,
    reason = "line count is bounded by source size"
)]
pub fn byte_offset_to_line_col(line_offsets: &[u32], byte_offset: u32) -> (u32, u32) {
    let line_idx = match line_offsets.binary_search(&byte_offset) {
        Ok(idx) => idx,
        Err(idx) => idx.saturating_sub(1),
    };
    let line = line_idx as u32 + 1;
    let col = byte_offset - line_offsets[line_idx];
    (line, col)
}

/// True when `name` identifies a synthetic template-family complexity unit:
/// the per-file `<template>` unit every framework template scanner emits, or a
/// Svelte `<snippet:NAME>` unit. These units are exercised only through their
/// component, carry no directly measurable test coverage, and are therefore
/// excluded from the CRAP dimension. The `<component>` rollup is NOT part of
/// this family: it is an aggregate over class + template findings, not an
/// extracted unit.
#[must_use]
pub fn is_synthetic_template_unit(name: &str) -> bool {
    name == "<template>" || name.starts_with("<snippet:")
}

/// Placeholder name of a function expression that has no name from its
/// declaration, its binding, a key, or its call context.
pub const ANONYMOUS_FUNCTION_NAME: &str = "<anonymous>";

/// Placeholder name of an arrow function that has no name from its binding, a
/// key, or its call context.
pub const ANONYMOUS_ARROW_NAME: &str = "<arrow>";

/// True when `name` is the placeholder of a function without a name. Two
/// functions that share a placeholder are not the same function.
#[must_use]
pub fn is_anonymous_function_name(name: &str) -> bool {
    name == ANONYMOUS_FUNCTION_NAME || name == ANONYMOUS_ARROW_NAME
}

/// Emitted name of the synthetic module-scope complexity unit.
pub const MODULE_UNIT_NAME: &str = "<module>";

/// True when `name` identifies the synthetic per-file module-scope unit.
///
/// Extraction pushes one root frame per program so decision points outside
/// every function (an environment guard, a top-level `??` / `||` default, an
/// `?.` access on a config object) are counted instead of silently dropped.
/// The unit is emitted only when it actually branches, and it is
/// aggregate-only: it feeds vital signs, file scores, and branching
/// conservation, and never becomes a user-facing finding. "Extract a helper"
/// is not advice that applies to module scope, so the unit reports the
/// quantity without asking anyone to act on it.
///
/// Deliberately NOT part of [`is_synthetic_template_unit`]. That predicate
/// carries template-family CRAP, suppression, and display semantics, and
/// [`FileBranching::from_units`] filters on it: folding `<module>` in would
/// exclude module-scope branching from the branching totals, which is the
/// blind spot this unit exists to close.
#[must_use]
pub fn is_synthetic_module_unit(name: &str) -> bool {
    name == MODULE_UNIT_NAME
}

/// Branching totals for one file: the quantity that survives extraction, and
/// the number of units now holding it.
///
/// A per-function cyclomatic ceiling constrains a partition, not a quantity.
/// `McCabe` gives a function `1 + one increment per decision point`, so across
/// a set of units the summed cyclomatic score is `functions + branch_points`.
/// Moving an `if` from one function into a new one removes an increment from
/// the first and adds it to the second: `branch_points` is unchanged and
/// `functions` rises. Reporting the two terms separately is what distinguishes
/// branching that left from branching that only moved.
///
/// Module scope is accounted for. Extraction pushes a root frame per program
/// and emits it as a synthetic `<module>` unit whenever it branches, so a
/// branch hoisted out of a function to the top level of the module keeps its
/// increment in `branch_points` and adds one to `functions`, exactly as moving
/// it into a new function would. A fall in `branch_points` is therefore a
/// statement about the file's measured decision points, not about a partition.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct FileBranching {
    /// Summed weight of `Cyclomatic` contributions. The conserved quantity.
    pub branch_points: u32,
    /// Number of accounted units. The tax a split adds.
    pub functions: u32,
    /// Highest single-unit cyclomatic score. Reported, never a verdict input:
    /// a split lowers it by construction.
    pub peak_cyclomatic: u16,
    /// Summed weight of `Cognitive` contributions, excluding `PropCount` and
    /// `HookDensity`. Both are cognitive-only with no cyclomatic counterpart,
    /// and `PropCount` records the excess over a floor, so it is superlinear in
    /// a split: one 14-prop component contributes `+10` while the same props
    /// across two 7-prop components contribute `+3` and `+3`. Including them
    /// would move this number with both `branch_points` and nesting flat.
    /// This therefore does NOT equal the sum of `FunctionComplexity::cognitive`.
    pub cognitive: u32,
    /// Summed `nesting` over the same cognitive contributions. Extraction
    /// rebases nesting to zero on every new frame, so a cognitive improvement
    /// that shows up here and not in `branch_points` came from repartitioning,
    /// not from removing branching.
    pub cognitive_nesting_weight: u32,
    /// Whether one of the counted units is the module body. Its branching is
    /// real and belongs in `branch_points`, but it is not a function anyone
    /// split into, so a consumer judging whether a file was split must not
    /// count it towards the function tax.
    pub has_module_unit: bool,
    /// Whether the file carried a synthetic template unit that these counts
    /// exclude. When it did, the numbers describe the file's script only, so a
    /// consumer must not present them as describing the whole file. The
    /// synthetic `<module>` unit is NOT a template unit and does not set this
    /// flag: it is counted like any other unit, because module-scope branching
    /// is part of the script the numbers describe.
    pub has_synthetic_units: bool,
}

impl FileBranching {
    /// Aggregate one file's units.
    ///
    /// Synthetic template units are excluded: they are suppressed entirely when
    /// trivial, which would silently move any denominator that counted them.
    /// Suppression is deliberately not consulted, so a
    /// `fallow-ignore-next-line complexity` comment cannot remove a unit's
    /// branches from the total.
    ///
    /// The synthetic `<module>` unit IS counted. It carries the file's
    /// module-scope decision points, and leaving it out would restore the blind
    /// spot that let a branch disappear from the total by being hoisted out of
    /// every function.
    #[must_use]
    pub fn from_units(units: &[FunctionComplexity]) -> Self {
        let mut totals = Self {
            has_module_unit: units
                .iter()
                .any(|unit| is_synthetic_module_unit(&unit.name)),
            has_synthetic_units: units
                .iter()
                .any(|unit| is_synthetic_template_unit(&unit.name)),
            ..Self::default()
        };
        for unit in units
            .iter()
            .filter(|unit| !is_synthetic_template_unit(&unit.name))
        {
            totals.functions += 1;
            totals.peak_cyclomatic = totals.peak_cyclomatic.max(unit.cyclomatic);
            for contribution in &unit.contributions {
                match contribution.metric {
                    ComplexityMetric::Cyclomatic => {
                        totals.branch_points += u32::from(contribution.weight);
                    }
                    ComplexityMetric::Cognitive => {
                        if matches!(
                            contribution.kind,
                            ComplexityContributionKind::PropCount
                                | ComplexityContributionKind::HookDensity
                        ) {
                            continue;
                        }
                        totals.cognitive += u32::from(contribution.weight);
                        totals.cognitive_nesting_weight += u32::from(contribution.nesting);
                    }
                }
            }
        }
        totals
    }

    /// Summed cyclomatic score implied by the identity `functions + branch_points`.
    ///
    /// Equals the direct sum of `FunctionComplexity::cyclomatic` over the same
    /// units unless a unit saturated `u16`, which is the one way the identity
    /// can break.
    #[must_use]
    pub const fn implied_cyclomatic(&self) -> u32 {
        self.functions + self.branch_points
    }
}

/// The kind of function that has no name of its own, which selects its
/// placeholder name.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
pub enum AnonymousFunctionKind {
    /// A function expression: `<anonymous>`.
    Function,
    /// An arrow function: `<arrow>`.
    Arrow,
}

impl AnonymousFunctionKind {
    /// The placeholder name of this kind.
    #[must_use]
    pub const fn placeholder(self) -> &'static str {
        match self {
            Self::Function => ANONYMOUS_FUNCTION_NAME,
            Self::Arrow => ANONYMOUS_ARROW_NAME,
        }
    }
}

/// Complexity metrics for a single function/method/arrow.
#[derive(Debug, Clone, serde::Serialize, bitcode::Encode, bitcode::Decode)]
pub struct FunctionComplexity {
    /// Function name, or a placeholder (`"<anonymous>"`, `"<arrow>"`) for a
    /// function that has no name.
    pub name: String,
    /// Whether this function is an ECMAScript `#`-private class member.
    ///
    /// Kept separately from `name` because a public string-named method may
    /// legally begin with `#` and remains eligible for runtime coverage.
    pub is_private_member: bool,
    /// `Some` when `name` comes from the call or the function that holds this
    /// function, not from its own declaration, binding, or key. Examples:
    /// `Command.make("setup")` for a callback argument, the `Effect.fn` span
    /// name, or the name of the function that returns `Effect.gen(...)`. The
    /// value is the kind of placeholder that the function had before.
    ///
    /// Coverage producers and runtime identities record such a function
    /// without a name, so they use [`Self::identity_name`].
    pub context_named: Option<AnonymousFunctionKind>,
    /// 1-based line number where the function starts.
    pub line: u32,
    /// 0-based byte column where the function starts.
    pub col: u32,
    /// `McCabe` cyclomatic complexity (1 + decision points).
    pub cyclomatic: u16,
    /// `SonarSource` cognitive complexity (structural + nesting penalty).
    pub cognitive: u16,
    /// Number of lines in the function body.
    pub line_count: u32,
    /// Number of parameters (excluding TypeScript's `this` parameter).
    pub param_count: u8,
    /// Number of React hook calls (`useState` / `useEffect` / `useMemo` /
    /// `useCallback` / custom `use*`) made directly in this function's body.
    /// Non-zero only for React components/hooks; descriptive context surfaced in
    /// the hotspot drill-down, never a tunable threshold (anti-numerology).
    pub react_hook_count: u16,
    /// Maximum JSX element nesting depth reached in this function's body (the
    /// deepest chain of element-inside-element). `0` when the function renders
    /// no JSX. Descriptive context surfaced in the hotspot drill-down, never a
    /// tunable threshold (anti-numerology).
    pub react_jsx_max_depth: u16,
    /// Number of props destructured from this component's first parameter (the
    /// `{ a, b, c }` props object). `0` for non-component functions and for
    /// components taking a bare `props` identifier (not statically countable).
    /// Descriptive context surfaced in the hotspot drill-down, never a tunable
    /// threshold (anti-numerology).
    pub react_prop_count: u16,
    /// Content digest of the function's full-span source slice.
    pub source_hash: Option<String>,
    /// Per-decision-point breakdown explaining WHICH constructs drove the
    /// cyclomatic and cognitive scores. One entry per increment event (an `if`
    /// emits one cyclomatic and one cognitive entry at the same line, because
    /// the two metrics accrue at different granularities). Always computed and
    /// cached; surfaced in JSON only behind `health --complexity-breakdown`.
    pub contributions: Vec<ComplexityContribution>,
}

impl FunctionComplexity {
    /// The name that coverage producers and runtime identities use: the
    /// placeholder for a function with a context name, else `name`.
    #[must_use]
    pub fn identity_name(&self) -> &str {
        match self.context_named {
            Some(kind) => kind.placeholder(),
            None => &self.name,
        }
    }
}

/// Structural CSS metrics for a single style rule, computed from the parsed CSS
/// syntax tree. A rule is recorded only when it crosses a structural floor (an
/// id selector, a complex selector, a `!important` declaration, or deep
/// nesting), so the vector stays bounded on normal stylesheets.
///
/// Not persisted in the extraction cache: `fallow health` computes these
/// on demand from the CSS source, so there is no `bitcode` derive.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct CssRuleMetric {
    /// 1-based line of the rule's first selector.
    pub line: u32,
    /// 1-based column of the rule's first selector.
    pub col: u32,
    /// Specificity component `a` (id selectors), max across the rule's selectors.
    pub specificity_a: u16,
    /// Specificity component `b` (class / attribute / pseudo-class selectors).
    pub specificity_b: u16,
    /// Specificity component `c` (type / pseudo-element selectors).
    pub specificity_c: u16,
    /// Largest selector component count across the rule's selector list.
    pub complexity: u16,
    /// Declaration count in the rule (normal plus `!important`).
    pub declaration_count: u16,
    /// `!important` declaration count in the rule.
    pub important_count: u16,
    /// Style-rule nesting depth (0 = top level).
    pub nesting_depth: u8,
}

/// A style rule's declaration-block fingerprint and location, for cross-file
/// duplicate-block detection. Only rules with a meaningful number of
/// declarations are recorded (small blocks repeat legitimately). Internal
/// staging only: this is consumed in-process by the health layer to build the
/// grouped `duplicate_declaration_blocks` output and is never serialized.
#[derive(Debug, Clone)]
pub struct CssDeclarationBlock {
    /// xxh3 fingerprint over the rule's normalized (sorted, `!important`-tagged)
    /// declaration set.
    pub fingerprint: u64,
    /// 1-based line of the rule's first selector.
    pub line: u32,
    /// Declaration count in the rule (normal plus `!important`).
    pub declaration_count: u16,
}

/// Located raw styling value authored directly in CSS rather than via a
/// custom property or design-token helper. Internal staging for the health
/// layer; public output adds actions and confidence.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CssRawStyleValue {
    /// Value axis, e.g. `color`, `font-size`, `line-height`, `radius`, or `shadow`.
    pub axis: String,
    /// CSS property where the value appears.
    pub property: String,
    /// Rendered declaration value.
    pub value: String,
    /// 1-based line of the containing style rule.
    pub line: u32,
}

/// Located CSS custom-property definition with its rendered value. Internal
/// staging for design-token reuse suggestions in the health layer.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CssCustomPropertyDefinition {
    /// Custom property name, including the leading `--`.
    pub name: String,
    /// Rendered custom property value.
    pub value: String,
    /// 1-based line of the containing style rule.
    pub line: u32,
}

/// Stylesheet-level structural CSS analytics, computed from the parsed CSS
/// syntax tree. Feeds `fallow health` penalty weights and located findings,
/// never a standalone CSS score.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct CssAnalytics {
    /// Total declarations across every style rule (normal plus `!important`).
    pub total_declarations: u32,
    /// Total `!important` declarations across every style rule.
    pub important_declarations: u32,
    /// Number of style rules.
    pub rule_count: u32,
    /// Number of style rules with no declarations.
    pub empty_rule_count: u32,
    /// Deepest style-rule nesting depth observed (0 = no nesting).
    pub max_nesting_depth: u8,
    /// Rules that crossed the structural floor, in source order. Bounded; see
    /// [`Self::notable_truncated`]. The scalar aggregates above always reflect
    /// the full stylesheet regardless of truncation.
    pub notable_rules: Vec<CssRuleMetric>,
    /// `true` when more rules crossed the structural floor than `notable_rules`
    /// retains (compiled utility CSS can emit thousands of `!important` rules),
    /// so consumers can note that per-rule findings were capped.
    pub notable_truncated: bool,
    /// Distinct color VALUES in the stylesheet, sorted (a palette-size /
    /// design-token-sprawl signal). The parser canonicalizes notation, so the
    /// authored format is NOT preserved: `red`, `#f00`, `#ff0000`, and
    /// `rgb(255,0,0)` all collapse to one entry, and every legacy sRGB notation
    /// renders as hex. Notation-MIXING (hex vs rgb vs hsl) is therefore not
    /// detectable from this set; it would need a separate raw-token pass.
    pub colors: Vec<String>,
    /// Distinct `font-size` declaration values in the stylesheet, sorted.
    pub font_sizes: Vec<String>,
    /// Distinct `z-index` declaration values in the stylesheet, sorted.
    pub z_indexes: Vec<String>,
    /// Distinct `box-shadow` declaration values in the stylesheet, sorted. A
    /// high count signals an uncontrolled shadow scale (design-token sprawl).
    pub box_shadows: Vec<String>,
    /// Distinct `border-radius` declaration values in the stylesheet, sorted.
    pub border_radii: Vec<String>,
    /// Distinct `line-height` declaration values in the stylesheet, sorted.
    pub line_heights: Vec<String>,
    /// Bounded located raw styling values that bypass custom properties or
    /// token helpers. These are conservative declaration-level candidates for
    /// audit introduced-vs-base gating.
    #[serde(skip)]
    #[cfg_attr(feature = "schema", schemars(skip))]
    pub raw_style_values: Vec<CssRawStyleValue>,
    /// Located custom-property definitions with values. Internal staging
    /// consumed by the health layer for nearest-token suggestions.
    #[serde(skip)]
    #[cfg_attr(feature = "schema", schemars(skip))]
    pub custom_property_definitions: Vec<CssCustomPropertyDefinition>,
    /// Distinct custom properties (`--x`) DEFINED in the stylesheet, sorted.
    pub defined_custom_properties: Vec<String>,
    /// Distinct custom properties REFERENCED via `var()` in the stylesheet.
    pub referenced_custom_properties: Vec<String>,
    /// Distinct `@keyframes` names DEFINED in the stylesheet, sorted.
    pub defined_keyframes: Vec<String>,
    /// Distinct `@keyframes` names REFERENCED via `animation` / `animation-name`.
    pub referenced_keyframes: Vec<String>,
    /// Distinct custom properties REGISTERED via an `@property` rule, sorted.
    pub registered_custom_properties: Vec<String>,
    /// Distinct cascade layers DECLARED (via `@layer a, b;` statements or named
    /// `@layer a { }` blocks), sorted.
    pub declared_layers: Vec<String>,
    /// Distinct cascade layers POPULATED by a named `@layer a { }` block, sorted.
    /// A layer declared but never populated (and not imported into) is a
    /// cleanup candidate.
    pub populated_layers: Vec<String>,
    /// Distinct font families DECLARED by an `@font-face` rule in the stylesheet,
    /// sorted. A declared family referenced by no `font-family` anywhere is a
    /// dead web-font payload (cleanup candidate).
    pub defined_font_faces: Vec<String>,
    /// Distinct font families REFERENCED via `font-family` / `font` in the
    /// stylesheet, sorted (generic keywords like `serif` excluded).
    pub referenced_font_families: Vec<String>,
    /// Per-rule declaration-block fingerprints for rules at or above the minimum
    /// block size, used to detect duplicate declaration blocks across the
    /// project. Internal staging consumed by the health layer; never serialized
    /// (the public output is the grouped `duplicate_declaration_blocks`).
    #[serde(skip)]
    #[cfg_attr(feature = "schema", schemars(skip))]
    pub declaration_blocks: Vec<CssDeclarationBlock>,
}

/// The kind of feature flag pattern detected.
#[derive(Debug, Clone, Copy, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub enum FlagUseKind {
    /// `process.env.FEATURE_X` pattern.
    EnvVar,
    /// SDK function call like `useFlag('name')`.
    SdkCall,
    /// Config object access like `config.features.x`.
    ConfigObject,
}

/// A feature flag use site.
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode)]
pub struct FlagUse {
    /// Flag identifier.
    pub flag_name: String,
    /// Detection kind.
    pub kind: FlagUseKind,
    /// 1-based line number.
    pub line: u32,
    /// 0-based byte column offset.
    pub col: u32,
    /// Start byte offset of the guarded block.
    pub guard_span_start: Option<u32>,
    /// End byte offset of the guarded block.
    pub guard_span_end: Option<u32>,
    /// SDK/provider name.
    pub sdk_name: Option<String>,
    /// Facts about the site, for the retirement report and the confidence
    /// mapping.
    pub facts: FlagSiteFacts,
}

const _: () = assert!(std::mem::size_of::<FlagUse>() <= 96);

/// Facts about a flag site that the flag retirement report and the
/// confidence mapping read.
///
/// The branch facts describe the `if`, ternary or JSX `&&` that the site
/// guards. A site without a guard has no branch facts.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct FlagSiteFacts(u8);

impl FlagSiteFacts {
    const IDENTICAL_BRANCHES: u8 = 1;
    const EMPTY_BRANCH: u8 = 1 << 1;
    const DEFINITION: u8 = 1 << 2;
    const UNCONFIRMED_SDK: u8 = 1 << 3;

    /// Both branches of the guard are the same code, ignoring whitespace
    /// and comments.
    #[must_use]
    pub const fn identical_branches(self) -> bool {
        self.0 & Self::IDENTICAL_BRANCHES != 0
    }

    /// No branch of the guard holds code, so the flag does nothing. An
    /// empty branch is `{}`, `;`, `null`, `undefined`, `void 0`, `<></>`, or
    /// `false` next to JSX. A missing `else` is an empty branch. Code in one
    /// branch, for the on case or for the off case, clears this fact.
    #[must_use]
    pub const fn empty_branch(self) -> bool {
        self.0 & Self::EMPTY_BRANCH != 0
    }

    /// The site defines the flag, as in `export const x = flag({ key })`,
    /// and does not read it.
    #[must_use]
    pub const fn definition(self) -> bool {
        self.0 & Self::DEFINITION != 0
    }

    /// The site calls a generic SDK name, such as `isEnabled` or
    /// `getValue`, and its file imports no flag SDK or flag module. Other
    /// libraries use the same names, so the site is less certain.
    #[must_use]
    pub const fn unconfirmed_sdk(self) -> bool {
        self.0 & Self::UNCONFIRMED_SDK != 0
    }

    /// These facts with `unconfirmed_sdk` set to `value`.
    #[must_use]
    pub const fn with_unconfirmed_sdk(self, value: bool) -> Self {
        Self::set(self, Self::UNCONFIRMED_SDK, value)
    }

    /// These facts with `definition` set to `value`.
    #[must_use]
    pub const fn with_definition(self, value: bool) -> Self {
        Self::set(self, Self::DEFINITION, value)
    }

    /// These facts with `identical_branches` set to `value`.
    #[must_use]
    pub const fn with_identical_branches(self, value: bool) -> Self {
        Self::set(self, Self::IDENTICAL_BRANCHES, value)
    }

    /// These facts with `empty_branch` set to `value`.
    #[must_use]
    pub const fn with_empty_branch(self, value: bool) -> Self {
        Self::set(self, Self::EMPTY_BRANCH, value)
    }

    const fn set(self, bit: u8, value: bool) -> Self {
        if value {
            Self(self.0 | bit)
        } else {
            Self(self.0 & !bit)
        }
    }
}

/// User flag patterns from the `flags` config section that detection
/// applies during the parse. The default holds the built-in patterns only.
///
/// The parse cache keys on these patterns, so every parse that writes the
/// cache must use the patterns of the resolved config.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct FlagPatterns {
    /// Extra SDK calls: function name, zero-based name argument, provider label.
    pub sdk_patterns: Vec<(String, usize, String)>,
    /// Extra environment variable prefixes.
    pub env_prefixes: Vec<String>,
    /// Whether an access on a config object with a flag-like name is a flag.
    pub config_object_heuristics: bool,
}

impl FlagPatterns {
    /// Whether no user pattern is present.
    #[must_use]
    pub fn is_builtin_only(&self) -> bool {
        self.sdk_patterns.is_empty()
            && self.env_prefixes.is_empty()
            && !self.config_object_heuristics
    }
}

/// A flag-key registry that a module exports: a module-level `as const`
/// object or a TypeScript enum whose members hold string flag keys.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct FlagKeyRegistry {
    /// Name the module exports the registry under.
    pub export_name: String,
    /// Member name and flag key of each string member, in declaration order.
    pub members: Vec<(String, String)>,
}

/// A flag read whose key is a member of an imported registry, as in
/// `useFlag(FLAGS.X)` where `FLAGS` is imported.
///
/// Extraction sees one file only, so project analysis resolves the key
/// through the import of `registry`.
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode)]
pub struct FlagRegistryRead {
    /// Local name of the imported registry binding.
    pub registry: String,
    /// Registry member that holds the flag key.
    pub member: String,
    /// The read site. `flag_name` stays empty until analysis resolves the key.
    pub flag_use: FlagUse,
}

/// A module-level `const` with a flag-style name and a literal value, such
/// as `const FEATURE_NEW_UI = true`, that a guard in the same module tests.
///
/// The flag retirement report reads these. They are not in the per-site
/// flag findings.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct FlagConstant {
    /// Binding name.
    pub name: String,
    /// The literal value as source code: `true`, `0` or `'on'`.
    pub value: String,
    /// 1-based line of the binding.
    pub line: u32,
    /// 0-based byte column of the binding.
    pub col: u32,
    /// Guard tests that read the binding, in source order.
    pub reads: Vec<FlagConstantRead>,
}

/// A guard test that reads a [`FlagConstant`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct FlagConstantRead {
    /// 1-based line.
    pub line: u32,
    /// 0-based byte column.
    pub col: u32,
    /// Facts about the guard.
    pub facts: FlagSiteFacts,
}

/// A flag definition bound to a `const`, as in
/// `export const showBanner = flag({ key: 'show-banner' })`.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct FlagDefinition {
    /// The binding that holds the definition.
    pub binding: String,
    /// 1-based line of the definition call, as on its [`FlagUse`].
    pub line: u32,
    /// 0-based byte column of the definition call, as on its [`FlagUse`].
    pub col: u32,
}

/// Registry facts, and other flag facts outside the per-site findings, that
/// a module gives to feature flag analysis.
#[derive(Debug, Clone, Default, bitcode::Encode, bitcode::Decode)]
pub struct FlagRegistryFacts {
    /// Registries this module exports.
    pub registries: Vec<FlagKeyRegistry>,
    /// Flag reads that name a member of an imported registry.
    pub reads: Vec<FlagRegistryRead>,
    /// Literal `const` flags that a guard in the module tests.
    pub constants: Vec<FlagConstant>,
    /// Flag definitions bound to a `const`.
    pub definitions: Vec<FlagDefinition>,
}

impl FlagRegistryFacts {
    /// Whether the module contributes no fact.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.registries.is_empty()
            && self.reads.is_empty()
            && self.constants.is_empty()
            && self.definitions.is_empty()
    }
}

/// The runtime mechanism used to load a module.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    Hash,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
)]
#[repr(u8)]
pub enum ModuleLoadMechanism {
    /// ECMAScript module loading through imports, re-exports, or import globs.
    EsModule = 0,
    /// CommonJS module loading through `require()` or `require.context`.
    CommonJsRequire = 1,
}

/// When the target of an import edge loads, relative to the importing module.
///
/// The startup weight report follows only `Static` edges to find the code that
/// loads before the entry module runs. The other kinds load later, or outside
/// the importing thread, except `PathReference` and `AssetReference`. These
/// two edges keep their target in use but do not run it: see
/// [`Self::loads_target`]. Only an asset reference also stops reachability:
/// see [`Self::runs_target_code`].
#[derive(
    Debug,
    Clone,
    Copy,
    Default,
    PartialEq,
    Eq,
    PartialOrd,
    Ord,
    Hash,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
#[repr(u8)]
pub enum ImportLoadKind {
    /// The target loads before the importer runs: `import`, `export ... from`,
    /// `require()`, `require.context` and `import.meta.glob(..., { eager: true })`.
    #[default]
    Static = 0,
    /// The target loads on demand through `import('./literal')`.
    Dynamic = 1,
    /// The target is one match of an on-demand pattern: a template `import()`
    /// or a lazy `import.meta.glob`.
    DynamicPattern = 2,
    /// The target runs on another thread or in another process: a
    /// `new URL(..., import.meta.url)` reference (for example a worker URL),
    /// a webpack worker loader request (`worker-loader!./work.js`),
    /// `child_process.fork`, a pino transport or a `module.register` hook.
    OutOfThread = 3,
    /// The importer gets only the path of the target and does not load it:
    /// `require.resolve('./file')` or ``require.resolve(`./file`)``. The edge
    /// keeps the target in use. The consumer of the path can run the target
    /// later, so the imports of the target stay reachable.
    PathReference = 4,
    /// The importer reads the target as text, bytes or a URL through a
    /// webpack asset loader, such as `raw-loader!./file.js`. The bundle never
    /// runs the target as code, so the imports of the target are not
    /// reachable through this edge. The graph sets this kind; extraction
    /// never records it.
    AssetReference = 5,
}

impl ImportLoadKind {
    /// Whether the target loads before the importing module runs.
    #[must_use]
    pub const fn is_eager(self) -> bool {
        matches!(self, Self::Static)
    }

    /// Whether the target loads on demand on the importing thread.
    #[must_use]
    pub const fn is_deferred(self) -> bool {
        matches!(self, Self::Dynamic | Self::DynamicPattern)
    }

    /// Whether the edge runs its target. A path reference and an asset
    /// reference keep the target in use but do not run it, so the edge does
    /// not close a cycle, is not in the entry load closure, does not cross an
    /// architecture boundary and does not carry server code into a client
    /// bundle.
    #[must_use]
    pub const fn loads_target(self) -> bool {
        !matches!(self, Self::PathReference | Self::AssetReference)
    }

    /// Whether the target can run as code at all, through this edge or
    /// through the consumer of a path reference. Only an asset reference never
    /// runs its target, so reachability does not continue through it.
    #[must_use]
    pub const fn runs_target_code(self) -> bool {
        !matches!(self, Self::AssetReference)
    }

    /// Whether an import with this load kind puts a runtime value of the
    /// target on the startup path: the target loads before the importer runs
    /// and the import is not type-only.
    #[must_use]
    pub const fn is_eager_value(self, is_type_only: bool) -> bool {
        self.is_eager() && !is_type_only
    }
}

/// A dynamic import with a partially resolved pattern.
#[derive(Debug, Clone)]
pub struct DynamicImportPattern {
    /// Glob prefix of the import path (e.g., "./locales/"). An
    /// `import.meta.glob` pattern is the full glob. For a template literal, a
    /// string concatenation, or `require.context`, each glob metacharacter of
    /// the literal text is escaped as a one-character class, such as `[[]`.
    pub prefix: String,
    /// Glob suffix of the import path (e.g., ".json"), if any.
    pub suffix: Option<String>,
    /// Globs of the files that the pattern does not load. Vite reads a
    /// negative `import.meta.glob` array entry, such as `'!./a/skip.js'`, as
    /// an exclude for every positive entry of the same call.
    pub excludes: Vec<String>,
    /// Source span in the original file.
    pub span: Span,
    /// Runtime mechanism used to load modules matching this pattern.
    pub mechanism: ModuleLoadMechanism,
}

/// Visibility tag from JSDoc/TSDoc comments that suppresses unused-export detection.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "lowercase")]
#[repr(u8)]
pub enum VisibilityTag {
    /// No visibility tag present.
    #[default]
    None = 0,
    /// `@public` or `@api public` -- part of the public API surface.
    Public = 1,
    /// `@internal` -- exported for internal use (sister packages, build tools).
    Internal = 2,
    /// `@beta` -- public but unstable, may change without notice.
    Beta = 3,
    /// `@alpha` -- early preview, may change drastically without notice.
    Alpha = 4,
    /// `@expected-unused` -- intentionally unused, should warn when it becomes used.
    ExpectedUnused = 5,
}

impl VisibilityTag {
    /// Whether this tag permanently suppresses unused-export detection.
    /// `ExpectedUnused` is handled separately (conditionally suppresses,
    /// reports stale when the export becomes used).
    pub const fn suppresses_unused(self) -> bool {
        matches!(
            self,
            Self::Public | Self::Internal | Self::Beta | Self::Alpha
        )
    }

    /// For serde `skip_serializing_if`.
    pub fn is_none(&self) -> bool {
        matches!(self, Self::None)
    }
}

/// An export declaration.
#[derive(Debug, Clone, serde::Serialize)]
pub struct ExportInfo {
    /// The exported name (named or default).
    pub name: ExportName,
    /// The local binding name, if different from the exported name.
    pub local_name: Option<String>,
    /// Whether this is a type-only export (`export type`).
    pub is_type_only: bool,
    /// Whether this export is registered through a runtime side effect at module load time.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub is_side_effect_used: bool,
    /// Visibility tag from JSDoc/TSDoc comment.
    #[serde(default, skip_serializing_if = "VisibilityTag::is_none")]
    pub visibility: VisibilityTag,
    /// Human-authored reason on `@expected-unused -- <reason>`, when present.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expected_unused_reason: Option<String>,
    /// Whether the leading JSDoc carries a `@deprecated` tag. Orthogonal to
    /// `visibility`: `@public @deprecated` is a normal combination.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub deprecated: bool,
    /// Plain-text `@deprecated` message, capped at
    /// `DEPRECATED_REASON_MAX_CHARS` characters. `None` for a bare tag.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub deprecated_reason: Option<Box<str>>,
    /// Source span of the export declaration.
    #[serde(serialize_with = "serialize_span")]
    pub span: Span,
    /// Members of this export (for enums, classes, and namespaces).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub members: Vec<MemberInfo>,
    /// The local name of the parent class from `extends` clause, if any.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub super_class: Option<String>,
}

/// Additional heritage metadata for an exported class.
#[derive(
    Debug,
    Clone,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
    PartialEq,
    Eq,
)]
pub struct ClassHeritageInfo {
    /// Export name (`default` for default-exported classes).
    pub export_name: String,
    /// Parent class name from the `extends` clause, if any.
    pub super_class: Option<String>,
    /// Interface names from the class `implements` clause.
    pub implements: Vec<String>,
    /// Ordered class type-parameter names used to compose concrete arguments
    /// through multi-hop inheritance.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub type_parameters: Vec<String>,
    /// Typed instance bindings used to resolve member-access chains in external templates.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub instance_bindings: Vec<(String, String)>,
    /// Positional type arguments on the `extends` clause (the `<DerivedClient>`
    /// in `extends BaseService<DerivedClient>`); an empty string marks a
    /// positional arg that is not a plain type reference. Lets the analyze layer
    /// substitute a base class's generic instance-binding field type with the
    /// subclass's concrete type argument (issue #1910).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub super_class_type_args: Vec<String>,
    /// Instance-binding fields whose annotation is exactly a class type
    /// parameter, as `(field_name, type_param_index)`. Lets an inherited generic
    /// property resolve to the subclass's concrete type argument rather than the
    /// constraint (issue #1910).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub generic_instance_bindings: Vec<(String, usize)>,
}

/// An exported free-function factory proven to return one class instance.
///
/// `export function useApi() { return new RESTApi() }` records
/// `FactoryReturnExport { export_name: "useApi", class_local_name: "RESTApi" }`.
/// The `class_local_name` is the factory module's own LOCAL name, resolved at
/// analyze time through that module's imports/exports to the real class export,
/// so a cross-module `const x = useApi(); x.member` consumer credits the class
/// across the boundary. See issue #1441 (Part A).
#[derive(
    Debug,
    Clone,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
    PartialEq,
    Eq,
)]
pub struct FactoryReturnExport {
    /// Public export name (honors `export { useApi as useRestApi }`).
    pub export_name: String,
    /// The returned class's local name within the factory module.
    pub class_local_name: String,
    /// The factory returns a promise of the class (an `async` function, or a
    /// `Promise<Class>` return type). Only an awaited call result is the class.
    #[serde(default)]
    pub is_async: bool,
}

/// One resolved property of an object-literal factory return: a dotted property
/// path mapped to the class the value at that path is an instance of.
///
/// `return { invoke: { orders: factory.ordersPage } }` records
/// `{ property_path: "invoke.orders", class_local_name: "OrdersPage" }`. The class
/// name is the factory module's own LOCAL name, resolved at analyze time through the
/// factory module's imports to the real class export. See issue #1858.
#[derive(
    Debug,
    Clone,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
    PartialEq,
    Eq,
)]
pub struct FactoryReturnObjectProperty {
    /// Dotted property path from the returned object literal (`orders`, `invoke.orders`).
    pub property_path: String,
    /// The property value's class local name within the factory module.
    pub class_local_name: String,
}

/// An exported factory function that returns an object literal whose property
/// values are class instances, joined to its public export name.
///
/// A cross-module `const ui = createUi(); ui.orders.member` consumer emits a
/// `FactoryReturnObjectPropertyAccess` fact; the analyze layer resolves `export_name`
/// through the consumer's imports to this module, matches `property_path`, and credits
/// `member` on the resolved class (gated on it being a class with members). See issue #1858.
#[derive(
    Debug,
    Clone,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
    PartialEq,
    Eq,
)]
pub struct FactoryReturnObjectShapeExport {
    /// Public export name (honors `export { createUi as createOrdersUi }`).
    pub export_name: String,
    /// Resolved `(property_path -> class_local_name)` entries for the returned literal.
    pub properties: Box<[FactoryReturnObjectProperty]>,
}

/// A named-type property whose declared type is a named type reference.
///
/// `interface Opts { c: OptDep }` (or `type Opts = { c: OptDep }`) records
/// `TypeMemberTypeEntry { type_name: "Opts", property: "c", property_type: "OptDep" }`.
/// Both `type_name` and `property_type` are the DECLARING module's own local
/// names; resolution through that module's imports/exports is deferred to
/// analyze time, mirroring `FactoryReturnExport.class_local_name`. Consumed by
/// the `unused-class-member` typed-property-hop join so a consumer's
/// `this.opts.c.optM()` credits `OptDep.optM` across module boundaries.
/// See issue #1785.
#[derive(
    Debug,
    Clone,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
    PartialEq,
    Eq,
)]
pub struct TypeMemberTypeEntry {
    /// Local interface or type-alias name declaring the property.
    pub type_name: String,
    /// Property name declared on the type.
    pub property: String,
    /// The property's declared type name (local to the declaring module).
    pub property_type: String,
}

/// A module-scope declaration that can be used as a TypeScript type.
#[derive(Debug, Clone, serde::Serialize, PartialEq, Eq)]
pub struct LocalTypeDeclaration {
    /// Local declaration name.
    pub name: String,
    /// Declaration identifier span.
    #[serde(serialize_with = "serialize_span")]
    pub span: Span,
}

/// A reference from an exported symbol's public signature to a type name.
#[derive(Debug, Clone, serde::Serialize, PartialEq, Eq)]
pub struct PublicSignatureTypeReference {
    /// Exported symbol whose signature contains the reference.
    pub export_name: String,
    /// Referenced type name. Qualified names are reduced to their root identifier.
    pub type_name: String,
    /// Reference span.
    #[serde(serialize_with = "serialize_span")]
    pub span: Span,
    /// True when the reference comes from a `satisfies` clause. The clause
    /// checks the value but does not change the exported type, so the type is
    /// in use but is not a private type leak.
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    pub from_satisfies: bool,
}

/// A member of an enum, class, or namespace.
#[derive(Debug, Clone, serde::Serialize)]
pub struct MemberInfo {
    /// Member name.
    pub name: String,
    /// The kind of member (enum, class method/property, or namespace member).
    pub kind: MemberKind,
    /// Source span of the member declaration.
    #[serde(serialize_with = "serialize_span")]
    pub span: Span,
    /// Whether this member has decorators (e.g., `@Column()`, `@Inject()`).
    /// Decorated members are used by frameworks at runtime and should not be
    /// flagged as unused class members, unless every decorator on the member
    /// is opted out via `FallowConfig.ignore_decorators`.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub has_decorator: bool,
    /// Full dotted path of each decorator on this member, in source order.
    /// `@step("x")` stores `"step"`; `@ns.foo` stores `"ns.foo"`. Empty for
    /// undecorated members, Angular signal-initializer properties (which set
    /// `has_decorator` without a literal decorator AST node), and decorators
    /// whose expression is not an identifier ladder (the entry is the empty
    /// string in that case, treated as never-matching by the predicate).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub decorator_names: Vec<String>,
    /// True when this is a static class method that returns a fresh instance
    /// of the same class: either via `return new this()` / `return new
    /// <SameClassName>()` in the body's last statement, or via a declared
    /// return type matching the class name. Consumers calling such a static
    /// method receive an instance, so the call result's member accesses are
    /// credited against the class. See issues #346, #387.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub is_instance_returning_static: bool,
    /// True when this is an instance class method whose call result is an
    /// instance of the same class. Qualifies when the declared return type
    /// matches the class name (`setX(): EventBuilder { ... }`) or when the
    /// body's last statement is `return this`. The analyze layer walks fluent
    /// chains (`Class.factory().setX().setY()`) only through methods carrying
    /// this flag, so the chain stops at a non-self-returning method like
    /// `.build()`. See issue #387.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub is_self_returning: bool,
    /// Root identifier of the class `extends` expression, set only when the
    /// member has the `override` modifier: `Container` in
    /// `extends Container<Env>`, `Schema` in `extends Schema.TaggedError<E>()(...)`.
    /// The analysis credits the member when this root names code outside the
    /// project, because that code calls the overridden member.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub override_base: Option<String>,
}

/// The kind of member.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    serde::Serialize,
    serde::Deserialize,
    bitcode::Encode,
    bitcode::Decode,
)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum MemberKind {
    /// A TypeScript enum member.
    EnumMember,
    /// A class method.
    ClassMethod,
    /// A class property.
    ClassProperty,
    /// A member exported from a TypeScript namespace.
    NamespaceMember,
    /// A member declared by a store object (Pinia `state` / `getters` /
    /// `actions` key, or a setup-store returned key). Cross-graph dead-member
    /// detection: a store member never accessed by any consumer project-wide.
    StoreMember,
}

/// A static member access expression (e.g., `Status.Active`, `MyClass.create()`).
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, bitcode::Encode, bitcode::Decode)]
pub struct MemberAccess {
    /// The identifier being accessed (the import name).
    pub object: String,
    /// The member being accessed.
    pub member: String,
}

/// Direct export declarations that TypeScript treats as one merged symbol.
///
/// Spans identify the exact declaration slots without conflating unrelated
/// type/value declarations that happen to share a name.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct DeclarationMergeFact {
    /// Identifier spans for the declarations in this merge group.
    pub export_spans: Vec<(u32, u32)>,
}

/// A default import binding consumed outside a statically known member access.
///
/// Resolution decides whether the target is an object-shaped module such as a
/// CSS Module or a proven static CommonJS object map. Keeping this fact
/// target-agnostic lets aliases and extensionless specifiers use the resolved
/// target path without broadening ordinary default-import behavior.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct DefaultImportWholeObjectUseFact {
    /// Local binding name in the importing module.
    pub local_name: String,
}

/// A typed extraction fact for cross-layer analysis.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum SemanticFact {
    /// A class member referenced from an Angular template, host binding, or
    /// component metadata entry.
    AngularTemplateMemberAccess(AngularTemplateMemberAccessFact),
    /// An Angular component field whose value is an array of a class.
    AngularComponentFieldArrayType(AngularComponentFieldArrayTypeFact),
    /// An Angular component spreads `this` into an object literal, so component
    /// input/output usage is opaque.
    AngularThisSpread(AngularThisSpreadFact),
    /// A member access on a value returned by an imported static factory call.
    FactoryCallMemberAccess(FactoryCallMemberAccessFact),
    /// A member access on a value returned by an imported free-function factory
    /// (`const x = importedFactory(); x.member`). See issue #1441 (Part A).
    FactoryFnMemberAccess(FactoryFnMemberAccessFact),
    /// A member access reached through a property of a value whose declared
    /// type is an imported named type (`this.opts.c.optM()` where `opts` is
    /// typed by an imported interface). See issue #1785.
    TypedPropertyMemberAccess(TypedPropertyMemberAccessFact),
    /// A member access on a fluent chain rooted at an imported static factory.
    FluentChainMemberAccess(FluentChainMemberAccessFact),
    /// A member access on a fluent chain rooted at a `new` expression.
    FluentChainNewMemberAccess(FluentChainNewMemberAccessFact),
    /// A member access on a Playwright fixture object inside a test callback.
    PlaywrightFixtureUse(PlaywrightFixtureUseFact),
    /// A Playwright fixture definition declared by a typed `test.extend<T>()`.
    PlaywrightFixtureDefinition(PlaywrightFixtureDefinitionFact),
    /// A Playwright fixture wrapper alias declared by `mergeTests` or `.extend`.
    PlaywrightFixtureAlias(PlaywrightFixtureAliasFact),
    /// A nested Playwright fixture binding declared by a fixture type alias.
    PlaywrightFixtureType(PlaywrightFixtureTypeFact),
    /// An exported value whose runtime instance targets a local class or interface.
    InstanceExportBinding(InstanceExportBindingFact),
    /// A dynamic custom-element tag render that makes static Lit tag credit opaque.
    DynamicCustomElementRender(DynamicCustomElementRenderFact),
    /// A factory-returned value consumed in a way that can expose ANY property
    /// (`const { a, ...rest } = importedFactory()`, a computed destructure key).
    /// The returned class must be treated as wholly used: crediting only the
    /// visible keys would leave a live member reported as dead.
    ///
    /// Appended, never inserted: `bitcode` encodes an enum by ordinal, so moving an
    /// existing variant would make an old cache decode one fact as another.
    FactoryFnWholeObject(FactoryFnWholeObjectFact),
    /// A member access reached through a property of a value returned by an
    /// imported factory that returns an object literal (`const ui = createUi();
    /// ui.orders.member`). Appended after `FactoryFnWholeObject`, never inserted
    /// (bitcode encodes by ordinal). See issue #1858.
    FactoryReturnObjectPropertyAccess(FactoryReturnObjectPropertyAccessFact),
    /// A `this.<field>.<member>` access tied to its exact enclosing class.
    /// Appended because bitcode encodes enum variants by ordinal.
    ClassThisMemberAccess(ClassThisMemberAccessFact),
    /// A whole-object use of `this.<field>...` tied to its exact enclosing class.
    /// Appended because bitcode encodes enum variants by ordinal.
    ClassThisWholeObjectUse(ClassThisWholeObjectUseFact),
    /// An ordered Vitest module-mock operation with direct imported-`vi`
    /// provenance.
    ///
    /// Appended because bitcode encodes enum variants by ordinal. The ordinary
    /// dynamic-import fact for the same source remains authoritative for graph
    /// reachability and unresolved-import diagnostics.
    VitestModuleMockOperation(VitestModuleMockOperationFact),
    /// Direct declarations that form one legal TypeScript declaration merge.
    /// Appended because bitcode encodes enum variants by ordinal.
    DeclarationMerge(DeclarationMergeFact),
    /// A named type whose direct receiver surface is contributed by another
    /// named type (for example `Pick<Base, ...>` or a union constituent).
    /// Appended because bitcode encodes enum variants by ordinal.
    TypeAliasSurfaceTarget(TypeAliasSurfaceTargetFact),
    /// A string-valued TypeScript enum member available as a static property key.
    /// Appended because bitcode encodes enum variants by ordinal.
    StringEnumMemberValue(StringEnumMemberValueFact),
    /// A computed property access keyed by a static enum member.
    /// Appended because bitcode encodes enum variants by ordinal.
    ComputedEnumKeyUse(ComputedEnumKeyUseFact),
    /// A directly declared non-optional member required by a named interface
    /// or object type.
    /// Appended because bitcode encodes enum variants by ordinal.
    RequiredTypeMember(RequiredTypeMemberFact),
    /// The file's complete CommonJS assignment surface is exactly one
    /// top-level `module.exports = { ... }` object literal whose keys are all
    /// static and which has no transpilation marker or competing assignment.
    /// Appended because bitcode encodes enum variants by ordinal.
    CjsSingleStaticObjectMap,
    /// A default import binding was handed on as a whole object.
    /// Appended because bitcode encodes enum variants by ordinal.
    DefaultImportWholeObjectUse(DefaultImportWholeObjectUseFact),
    /// A property of an exported object contains a local class instance.
    /// Appended because bitcode encodes enum variants by ordinal.
    ExportedObjectInstanceProperty(ExportedObjectInstancePropertyFact),
    /// A proven class member read selected through a namespace import.
    /// Appended because bitcode encodes enum variants by ordinal.
    QualifiedClassMemberAccess(QualifiedClassMemberAccessFact),
    /// A Module Federation runtime call (`registerRemotes`, `loadRemote`,
    /// `init` or `createInstance`) imported from a Federation runtime package.
    /// Appended because bitcode encodes enum variants by ordinal.
    FederationRuntimeRemote(FederationRuntimeRemoteFact),
    /// A dynamic import or an import pattern whose load kind differs from the
    /// default of its list: `Dynamic` for `dynamic_imports` and
    /// `DynamicPattern` for `dynamic_import_patterns`.
    /// Appended because bitcode encodes enum variants by ordinal.
    ImportLoadKindOverride(ImportLoadKindOverrideFact),
    /// A source-owned class-producing property of an exported object factory.
    /// Appended because bitcode encodes enum variants by ordinal.
    FactoryReturnObjectPropertySource(Box<FactoryReturnObjectPropertySourceFact>),
    /// Property read whose bound factory receiver passed source-time lexical and value checks.
    ProvenFactoryReturnObjectPropertyAccess(FactoryReturnObjectPropertyAccessFact),
    /// Caller-owned callback origins for a source-proven returned property.
    CallbackFactoryPropertyAccess(Box<CallbackFactoryPropertyAccessFact>),
    /// A Playwright fixture definition from `<base>.extend<T>()` where `base`
    /// is imported. Analysis applies it only when `base` resolves to a
    /// Playwright test. Appended because bitcode encodes enum variants by ordinal.
    PlaywrightConditionalFixtureDefinition(Box<PlaywrightConditionalFixtureDefinitionFact>),
    /// A local name that the extractor proved holds a Playwright test.
    /// Appended because bitcode encodes enum variants by ordinal.
    PlaywrightTestBinding(PlaywrightTestBindingFact),
    /// A top-level statement or declaration emits runtime code beyond module
    /// imports and exports, which have their own extraction records.
    /// Appended because bitcode encodes enum variants by ordinal.
    TopLevelRuntimeStatement,
}

/// Deferred class provenance owned by the module declaring an object factory.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub enum FactoryPropertySource {
    /// A property path through a named type in the factory's module.
    TypedProperty {
        /// Named receiver type in the producer module.
        type_name: String,
        /// Remaining path through the receiver type.
        property_path: String,
    },
    /// A synchronous function call in the factory's module.
    FunctionReturn {
        /// Function binding in the producer module.
        callee_name: String,
    },
    /// A proven instance-returning static class method.
    StaticFactoryReturn {
        /// Class binding in the producer module.
        callee_object: String,
        /// Statically named instance-returning method.
        callee_method: String,
    },
    /// A class proven in the object factory's own module.
    LocalClass {
        /// Local class binding resolved relative to the factory module.
        class_local_name: String,
    },
    /// Return of the callback at this ordinal in the proven helper declaration.
    CallbackParameterReturn {
        /// Zero-based formal parameter ordinal.
        parameter_index: u32,
    },
}

/// Callback-origin member use, joined with the callee module's property source.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct CallbackFactoryPropertyAccessFact {
    /// Callee import binding in the caller module.
    pub callee_name: String,
    /// Static export selected from a namespace import, if present.
    pub callee_member: Option<String>,
    /// Requested path in the wrapper's returned value.
    pub property_path: String,
    /// Requested member on the callback result.
    pub member: String,
    /// A property write permits only the canonical Vue getter contract.
    pub vue_only: bool,
    /// Ordinary assigned value, ignored by a canonical Vue setter contract.
    pub assigned_class: Option<String>,
    /// Callback ordinal and class origin interpreted in the caller module.
    pub arguments: Vec<CallbackFactoryArgument>,
}

/// Proven callback result owned by a factory consumer's module.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct CallbackFactoryArgument {
    /// Zero-based actual argument ordinal.
    pub parameter_index: u32,
    /// Class binding resolved in the consumer module.
    pub class_local_name: String,
    /// This argument is an options object with a proven `get` callback.
    pub getter: bool,
    /// No mutable capture makes a lazy invocation select another class.
    pub lazy_safe: bool,
}

/// An exported object factory's deferred property receiver.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct FactoryReturnObjectPropertySourceFact {
    /// Public factory export name.
    pub factory_export_name: String,
    /// Path within the returned object, separate from any source property path.
    pub property_path: String,
    /// Names interpreted relative to this fact's owning module.
    pub source: FactoryPropertySource,
}

/// The load kind of the dynamic imports or patterns that start at `span_start`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ImportLoadKindOverrideFact {
    /// Byte offset of the call or `new` expression that records the edge.
    pub span_start: u32,
    /// The load kind of every edge that the expression records.
    pub kind: ImportLoadKind,
}

/// The Module Federation runtime function that a call names.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "camelCase")]
pub enum FederationRuntimeCall {
    /// `registerRemotes([{ name, entry }])`.
    RegisterRemotes,
    /// `loadRemote('remote/module')`.
    LoadRemote,
    /// `init({ remotes: [{ name, entry }] })`.
    /// Appended because bitcode encodes enum variants by ordinal.
    Init,
    /// `createInstance({ remotes: [{ name, entry }] })`.
    CreateInstance,
}

impl FederationRuntimeCall {
    /// The function name as the source writes it.
    #[must_use]
    pub const fn name(self) -> &'static str {
        match self {
            Self::RegisterRemotes => "registerRemotes",
            Self::LoadRemote => "loadRemote",
            Self::Init => "init",
            Self::CreateInstance => "createInstance",
        }
    }
}

/// One remote that a Module Federation runtime call names.
///
/// `remote` is the remote alias when the argument is a static literal, and
/// `None` when the call receives a value that static analysis cannot read.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct FederationRuntimeRemoteFact {
    /// The runtime function the call names.
    pub call: FederationRuntimeCall,
    /// The remote alias the call names, or `None` for a non-literal argument.
    pub remote: Option<String>,
}

/// Iterate Angular template member names from typed semantic facts.
fn angular_template_member_names_from_parts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &str> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::AngularTemplateMemberAccess(access) = fact {
            Some(access.member.as_str())
        } else {
            None
        }
    })
}

/// Iterate Angular template member names from a module's typed facts.
pub fn angular_template_member_names(module: &ModuleInfo) -> impl Iterator<Item = &str> {
    angular_template_member_names_from_parts(&module.semantic_facts)
}

/// Return true when the fact slice contains any Angular template member
/// reference.
#[must_use]
fn has_angular_template_members_from_parts(semantic_facts: &[SemanticFact]) -> bool {
    angular_template_member_names_from_parts(semantic_facts)
        .next()
        .is_some()
}

/// Return true when the module contains any Angular template member reference.
#[must_use]
pub fn has_angular_template_members(module: &ModuleInfo) -> bool {
    has_angular_template_members_from_parts(&module.semantic_facts)
}

/// Return true when a module spreads `this` in Angular template context.
#[must_use]
pub fn has_angular_this_spread(module: &ModuleInfo) -> bool {
    SemanticFactView::new(&module.semantic_facts, &module.member_accesses).has_angular_this_spread()
}

/// Return true when a module contains a dynamic custom-element render.
#[must_use]
pub fn has_dynamic_custom_element_render(module: &ModuleInfo) -> bool {
    module
        .semantic_facts
        .iter()
        .any(|fact| matches!(fact, SemanticFact::DynamicCustomElementRender(_)))
}

/// Typed-first view over semantic extraction facts.
///
/// Extraction populates `semantic_facts` directly. The `member_accesses` slice
/// remains available for consumers that need ordinary source member accesses,
/// but it is no longer decoded as a string protocol for semantic facts.
#[derive(Debug, Clone, Copy)]
pub struct SemanticFactView<'a> {
    semantic_facts: &'a [SemanticFact],
    member_accesses: &'a [MemberAccess],
}

impl<'a> SemanticFactView<'a> {
    /// Create a typed semantic fact view from current semantic facts plus
    /// ordinary source member accesses.
    #[must_use]
    pub const fn new(
        semantic_facts: &'a [SemanticFact],
        member_accesses: &'a [MemberAccess],
    ) -> Self {
        Self {
            semantic_facts,
            member_accesses,
        }
    }

    /// Iterate typed semantic facts.
    pub fn facts(self) -> impl Iterator<Item = &'a SemanticFact> + 'a {
        self.semantic_facts.iter()
    }

    /// Iterate Angular template member references.
    pub fn angular_template_member_names(self) -> impl Iterator<Item = &'a str> + 'a {
        angular_template_member_names_from_parts(self.semantic_facts)
    }

    /// Collect Angular component field array-type facts.
    pub fn angular_component_field_array_types(self) -> Vec<AngularComponentFieldArrayTypeFact> {
        angular_component_field_array_type_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Return true when any Angular template member reference exists.
    #[must_use]
    pub fn has_angular_template_members(self) -> bool {
        self.angular_template_member_names().next().is_some()
    }

    /// Return true when a module spreads `this` in Angular template context.
    #[must_use]
    pub fn has_angular_this_spread(self) -> bool {
        self.semantic_facts
            .iter()
            .any(|fact| matches!(fact, SemanticFact::AngularThisSpread(_)))
    }

    /// Iterate ordinary source member accesses.
    pub fn ordinary_member_accesses(self) -> impl Iterator<Item = &'a MemberAccess> + 'a {
        self.member_accesses.iter()
    }

    /// Collect class-scoped `this` member-access facts.
    pub fn class_this_member_accesses(self) -> Vec<ClassThisMemberAccessFact> {
        class_this_member_access_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect class-scoped `this` whole-object-use facts.
    pub fn class_this_whole_object_uses(self) -> Vec<ClassThisWholeObjectUseFact> {
        class_this_whole_object_use_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect instance-export binding facts.
    pub fn instance_export_bindings(self) -> Vec<InstanceExportBindingFact> {
        instance_export_binding_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Iterate exported object properties that contain class instances.
    pub fn exported_object_instance_properties(
        self,
    ) -> impl Iterator<Item = &'a ExportedObjectInstancePropertyFact> + 'a {
        exported_object_instance_property_facts(self.semantic_facts)
    }

    /// Iterate proven namespace-qualified class member accesses.
    pub fn qualified_class_member_accesses(
        self,
    ) -> impl Iterator<Item = &'a QualifiedClassMemberAccessFact> + 'a {
        qualified_class_member_access_facts(self.semantic_facts)
    }

    /// Collect static factory call member facts.
    pub fn factory_call_member_accesses(self) -> Vec<FactoryCallMemberAccessFact> {
        factory_call_member_access_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect free-function factory-return member facts.
    pub fn factory_fn_member_accesses(self) -> Vec<FactoryFnMemberAccessFact> {
        factory_fn_member_access_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect factory-return whole-object consumption facts.
    pub fn factory_fn_whole_objects(self) -> Vec<FactoryFnWholeObjectFact> {
        factory_fn_whole_object_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect object-literal factory-return property member facts.
    pub fn factory_return_object_property_accesses(
        self,
    ) -> Vec<FactoryReturnObjectPropertyAccessFact> {
        factory_return_object_property_access_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Iterate deferred object-factory property sources without copying their names.
    pub fn factory_return_object_property_sources(
        self,
    ) -> impl Iterator<Item = &'a FactoryReturnObjectPropertySourceFact> + 'a {
        self.semantic_facts.iter().filter_map(|fact| match fact {
            SemanticFact::FactoryReturnObjectPropertySource(source) => Some(source.as_ref()),
            _ => None,
        })
    }

    /// Property accesses with source-owned receiver admission.
    pub fn proven_factory_return_object_property_accesses(
        self,
    ) -> impl Iterator<Item = &'a FactoryReturnObjectPropertyAccessFact> + 'a {
        self.semantic_facts.iter().filter_map(|fact| match fact {
            SemanticFact::ProvenFactoryReturnObjectPropertyAccess(access) => Some(access),
            _ => None,
        })
    }

    /// Iterate caller-owned callback property projections.
    pub fn callback_factory_property_accesses(
        self,
    ) -> impl Iterator<Item = &'a CallbackFactoryPropertyAccessFact> + 'a {
        self.semantic_facts.iter().filter_map(|fact| match fact {
            SemanticFact::CallbackFactoryPropertyAccess(access) => Some(access.as_ref()),
            _ => None,
        })
    }

    /// Collect typed-property-hop member facts.
    pub fn typed_property_member_accesses(self) -> Vec<TypedPropertyMemberAccessFact> {
        typed_property_member_access_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect members whose presence is required by a named structural type.
    pub fn required_type_members(self) -> impl Iterator<Item = &'a RequiredTypeMemberFact> + 'a {
        required_type_member_facts(self.semantic_facts)
    }

    /// Collect type-alias receiver-surface edges.
    pub fn type_alias_surface_targets(self) -> Vec<TypeAliasSurfaceTargetFact> {
        type_alias_surface_target_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect string-valued enum member definitions.
    pub fn string_enum_member_values(self) -> Vec<StringEnumMemberValueFact> {
        string_enum_member_value_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect computed property accesses keyed by enum members.
    pub fn computed_enum_key_uses(self) -> Vec<ComputedEnumKeyUseFact> {
        computed_enum_key_use_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect static factory fluent-chain member facts.
    pub fn fluent_chain_member_accesses(self) -> Vec<FluentChainMemberAccessFact> {
        fluent_chain_member_access_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect constructor-rooted fluent-chain member facts.
    pub fn fluent_chain_new_member_accesses(self) -> Vec<FluentChainNewMemberAccessFact> {
        fluent_chain_new_member_access_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect Playwright fixture-use facts.
    pub fn playwright_fixture_uses(self) -> Vec<PlaywrightFixtureUseFact> {
        playwright_fixture_use_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect Playwright fixture-definition facts.
    pub fn playwright_fixture_definitions(self) -> Vec<PlaywrightFixtureDefinitionFact> {
        playwright_fixture_definition_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect Playwright fixture-alias facts.
    pub fn playwright_fixture_aliases(self) -> Vec<PlaywrightFixtureAliasFact> {
        playwright_fixture_alias_facts(self.semantic_facts)
            .cloned()
            .collect()
    }

    /// Collect conditional Playwright fixture-definition facts.
    pub fn playwright_conditional_fixture_definitions(
        self,
    ) -> Vec<PlaywrightConditionalFixtureDefinitionFact> {
        self.semantic_facts
            .iter()
            .filter_map(|fact| match fact {
                SemanticFact::PlaywrightConditionalFixtureDefinition(access) => {
                    Some(access.as_ref().clone())
                }
                _ => None,
            })
            .collect()
    }

    /// Collect the names of proven Playwright test bindings.
    pub fn playwright_test_bindings(self) -> Vec<PlaywrightTestBindingFact> {
        self.semantic_facts
            .iter()
            .filter_map(|fact| match fact {
                SemanticFact::PlaywrightTestBinding(binding) => Some(binding.clone()),
                _ => None,
            })
            .collect()
    }

    /// Collect Playwright fixture-type facts.
    pub fn playwright_fixture_types(self) -> Vec<PlaywrightFixtureTypeFact> {
        playwright_fixture_type_facts(self.semantic_facts)
            .cloned()
            .collect()
    }
}

/// Iterate ordinary whole-object uses.
pub fn ordinary_whole_object_uses(whole_object_uses: &[String]) -> impl Iterator<Item = &str> {
    whole_object_uses.iter().map(String::as_str)
}

/// Iterate typed instance-export binding facts.
fn instance_export_binding_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &InstanceExportBindingFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::InstanceExportBinding(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

fn exported_object_instance_property_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &ExportedObjectInstancePropertyFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::ExportedObjectInstanceProperty(property) = fact {
            Some(property)
        } else {
            None
        }
    })
}

fn qualified_class_member_access_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &QualifiedClassMemberAccessFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::QualifiedClassMemberAccess(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

fn class_this_member_access_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &ClassThisMemberAccessFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::ClassThisMemberAccess(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

fn class_this_whole_object_use_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &ClassThisWholeObjectUseFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::ClassThisWholeObjectUse(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

fn angular_component_field_array_type_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &AngularComponentFieldArrayTypeFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::AngularComponentFieldArrayType(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

/// Iterate typed factory-call member facts.
fn factory_call_member_access_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &FactoryCallMemberAccessFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::FactoryCallMemberAccess(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

/// Iterate typed free-function factory-return member facts.
fn factory_fn_member_access_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &FactoryFnMemberAccessFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::FactoryFnMemberAccess(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

fn factory_fn_whole_object_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &FactoryFnWholeObjectFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::FactoryFnWholeObject(fact) = fact {
            Some(fact)
        } else {
            None
        }
    })
}

/// Iterate object-literal factory-return property member facts.
fn factory_return_object_property_access_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &FactoryReturnObjectPropertyAccessFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::FactoryReturnObjectPropertyAccess(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

/// Iterate typed fluent-chain member facts.
fn fluent_chain_member_access_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &FluentChainMemberAccessFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::FluentChainMemberAccess(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

/// Iterate typed-property-hop member facts.
fn typed_property_member_access_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &TypedPropertyMemberAccessFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::TypedPropertyMemberAccess(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

fn required_type_member_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &RequiredTypeMemberFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::RequiredTypeMember(required) = fact {
            Some(required)
        } else {
            None
        }
    })
}

fn type_alias_surface_target_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &TypeAliasSurfaceTargetFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::TypeAliasSurfaceTarget(fact) = fact {
            Some(fact)
        } else {
            None
        }
    })
}

fn string_enum_member_value_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &StringEnumMemberValueFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::StringEnumMemberValue(fact) = fact {
            Some(fact)
        } else {
            None
        }
    })
}

fn computed_enum_key_use_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &ComputedEnumKeyUseFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::ComputedEnumKeyUse(fact) = fact {
            Some(fact)
        } else {
            None
        }
    })
}

/// Iterate typed constructor-rooted fluent-chain member facts.
fn fluent_chain_new_member_access_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &FluentChainNewMemberAccessFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::FluentChainNewMemberAccess(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

/// Iterate typed Playwright fixture-use facts.
fn playwright_fixture_use_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &PlaywrightFixtureUseFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::PlaywrightFixtureUse(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

/// Iterate typed Playwright fixture-definition facts.
fn playwright_fixture_definition_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &PlaywrightFixtureDefinitionFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::PlaywrightFixtureDefinition(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

/// Iterate typed Playwright fixture-alias facts.
fn playwright_fixture_alias_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &PlaywrightFixtureAliasFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::PlaywrightFixtureAlias(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

/// Iterate typed Playwright fixture-type facts.
fn playwright_fixture_type_facts(
    semantic_facts: &[SemanticFact],
) -> impl Iterator<Item = &PlaywrightFixtureTypeFact> {
    semantic_facts.iter().filter_map(|fact| {
        if let SemanticFact::PlaywrightFixtureType(access) = fact {
            Some(access)
        } else {
            None
        }
    })
}

/// A member name referenced from an Angular template surface.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct AngularTemplateMemberAccessFact {
    /// Referenced class member name.
    pub member: String,
}

/// A typed Angular component field that exposes array elements to templates.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct AngularComponentFieldArrayTypeFact {
    /// Component field name used as the template iterable.
    pub field: String,
    /// Array element class name.
    pub element_class: String,
}

/// Opaque Angular `{ ...this }` forwarding marker.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct AngularThisSpreadFact;

/// A member access on a static factory call result.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct FactoryCallMemberAccessFact {
    /// Local imported class or namespace object used as the factory callee.
    pub callee_object: String,
    /// Static factory method invoked on the callee object.
    pub callee_method: String,
    /// Member accessed on the returned instance-like object.
    pub member: String,
}

/// A member access on a value returned by an imported free-function factory.
///
/// `const x = importedFactory(); x.member` emits one fact per first-level read
/// on `x`. The analyze layer resolves `callee_name` through the consumer's
/// imports to the factory's origin module, reads that module's
/// `exported_factory_returns` to learn the returned class's local name, resolves
/// THAT through the factory module's own imports to the class export, and
/// credits `member` on the class. See issue #1441 (Part A).
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct FactoryFnMemberAccessFact {
    /// Local imported function used as the factory callee.
    pub callee_name: String,
    /// Member accessed on the returned instance-like object.
    pub member: String,
    /// The local holds the awaited call result (`const x = await factory()`).
    pub awaited: bool,
}

/// A factory-returned value consumed opaquely, so every member of the class it
/// returns must be treated as used.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct FactoryFnWholeObjectFact {
    /// Local imported function used as the factory callee.
    pub callee_name: String,
}

/// A member access reached through a property of a value returned by an imported
/// factory that returns an object literal.
///
/// `const ui = createUi(); ui.orders.member` emits one fact per member read on a
/// factory-result property. The analyze layer resolves `callee_name` through the
/// consumer's imports to the factory's origin module, reads that module's
/// `exported_factory_return_object_shapes` to find the property whose path equals
/// `property_path` and its class local name, resolves THAT through the factory
/// module's own imports to the class export, and credits `member` on the class
/// (gated on the export actually being a class with members). See issue #1858.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct FactoryReturnObjectPropertyAccessFact {
    /// Local imported function used as the factory callee.
    pub callee_name: String,
    /// Dotted property path between the factory-result local and the final member
    /// (e.g. `"orders"` for `ui.orders.member`, `"invoke.orders"` for `ui.invoke.orders.member`).
    pub property_path: String,
    /// Member accessed on the terminal property's instance.
    pub member: String,
}

/// A member access reached through a typed property hop that the extraction
/// layer could not resolve locally.
///
/// `constructor(private opts: Opts) { ... this.opts.c.optM() }` where `Opts`
/// is NOT declared in this file emits
/// `TypedPropertyMemberAccessFact { type_name: "Opts", property_path: "c", member: "optM" }`.
/// The analyze layer resolves `type_name` through the consumer's imports to the
/// declaring module, walks `property_path` through that module's
/// `type_member_types`, resolves the terminal type name through the declaring
/// module's own imports, and credits `member` on the resolved class (gated on
/// the export actually being a class with members). See issue #1785.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct TypedPropertyMemberAccessFact {
    /// Local (usually imported) named-type symbol the receiver is typed by.
    pub type_name: String,
    /// Remaining dotted property segments between the typed binding and the
    /// final member (e.g. `"c"` for `this.opts.c.optM()`).
    pub property_path: String,
    /// Member accessed on the terminal property's instance.
    pub member: String,
}

/// A class member directly required by a named structural type.
///
/// Optional properties and methods are excluded: removing an optional
/// implementation can preserve assignability, while removing a required one
/// from an explicit `implements` contract cannot.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct RequiredTypeMemberFact {
    /// Module-local interface or object-type alias name.
    pub type_name: String,
    /// Static required property or method name.
    pub member: String,
}

/// One direct contributor to a named type alias's receiver surface.
///
/// Nested property types are deliberately excluded: in
/// `{ nested: Nested }`, `Alias.member` does not access `Nested.member`.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct TypeAliasSurfaceTargetFact {
    /// Module-local alias declaration name.
    pub alias_name: String,
    /// Module-local or imported named type contributing the direct surface.
    pub target_name: String,
}

/// A statically known string value of a TypeScript enum member.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct StringEnumMemberValueFact {
    /// Module-local enum declaration name.
    pub enum_name: String,
    /// Static enum member name.
    pub member_name: String,
    /// Exact string initializer value.
    pub value: String,
}

/// A computed property access whose key is a static enum member.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ComputedEnumKeyUseFact {
    /// Local enum object used as the key source.
    pub key_object: String,
    /// Static member selected from the enum object.
    pub key_member: String,
}

/// A fluent chain rooted at a static factory call, one fact per chain. A step is
/// used when the root method is a factory and each earlier step returns `this`.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct FluentChainMemberAccessFact {
    /// Local imported class or namespace object used as the chain root.
    pub root_object: String,
    /// Static factory method that starts the fluent chain.
    pub root_method: String,
    /// The methods called after the root method, each once, in first-call order.
    pub steps: Vec<String>,
}

/// A fluent chain rooted at a `new` expression, one fact per chain. A step is
/// used when the first method and each earlier step return `this`.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct FluentChainNewMemberAccessFact {
    /// Local imported class constructed by the `new` expression.
    pub class_name: String,
    /// The method called on the new instance.
    pub first_method: String,
    /// The methods called after the first method, each once, in first-call order.
    pub steps: Vec<String>,
}

/// A member access on a Playwright fixture object inside a test callback.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct PlaywrightFixtureUseFact {
    /// Local test function or wrapper used as the callback callee.
    pub test_name: String,
    /// Fixture name or dotted fixture path referenced in the callback.
    pub fixture_name: String,
    /// Member accessed on the fixture target.
    pub member: String,
}

/// A Playwright fixture definition declared by a typed `test.extend<T>()`.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct PlaywrightFixtureDefinitionFact {
    /// Local test function or wrapper receiving the fixture definition.
    pub test_name: String,
    /// Fixture name or dotted fixture path declared by the fixture type.
    pub fixture_name: String,
    /// Local type symbol used as the fixture target.
    pub type_name: String,
}

/// A Playwright fixture definition from `<base>.extend<T>()` where `base` is
/// an imported name. The extractor cannot prove that `base` holds a Playwright
/// test, so analysis applies the definition only when `base` resolves to one.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct PlaywrightConditionalFixtureDefinitionFact {
    /// Local test function or wrapper receiving the fixture definition.
    pub test_name: String,
    /// Imported local name that `.extend<T>()` is called on.
    pub base_name: String,
    /// Fixture name or dotted fixture path declared by the fixture type.
    pub fixture_name: String,
    /// Local type symbol used as the fixture target.
    pub type_name: String,
}

/// A local name that holds a Playwright test: the result of an `.extend()` on
/// the `@playwright/test` `test` import or of a `mergeTests(...)` call.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct PlaywrightTestBindingFact {
    /// Local name of the Playwright test.
    pub test_name: String,
}

/// A Playwright fixture wrapper alias declared by `mergeTests` or `.extend`.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct PlaywrightFixtureAliasFact {
    /// Local test function or wrapper that inherits fixture definitions.
    pub test_name: String,
    /// Local test function or wrapper inherited by `test_name`.
    pub base_name: String,
}

/// A nested Playwright fixture binding declared by a fixture type alias.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct PlaywrightFixtureTypeFact {
    /// Local type alias containing the nested fixture binding.
    pub alias_name: String,
    /// Fixture name or dotted fixture path declared inside the type alias.
    pub fixture_name: String,
    /// Local type symbol used as the nested fixture target.
    pub type_name: String,
}

/// An exported value whose runtime instance targets a local class or interface.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct InstanceExportBindingFact {
    /// Exported binding name.
    pub export_name: String,
    /// Local class or interface symbol used as the instance target.
    pub target_name: String,
}

/// A property of an exported object whose value is an instance of a local class.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ExportedObjectInstancePropertyFact {
    /// Public export name of the containing object.
    pub export_name: String,
    /// Dotted path from the exported object to the instance property.
    pub property_path: String,
    /// Local class symbol instantiated at that property.
    pub class_local_name: String,
}

/// A proven class member read through a namespace-qualified constructor or local subclass.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct QualifiedClassMemberAccessFact {
    /// Local namespace-import binding.
    pub namespace_local: String,
    /// Class export selected from that namespace.
    pub class_export_name: String,
    /// Member accessed through the proven class or instance binding.
    pub member: String,
}

/// Opaque marker for a dynamic custom-element render site.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct DynamicCustomElementRenderFact;

/// The action performed by a Vitest module-mock operation.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum VitestModuleMockAction {
    /// Register a mock. `factory_replaces_original` is true only when the
    /// factory is structurally closed and cannot load the original module.
    ///
    /// Automock (`vi.mock` / `jest.mock` without a factory) is always
    /// `factory_replaces_original: false` by decision (issue #2082). For
    /// Vitest, the runner derives the mocked shape by importing the original
    /// module, so its top-level code executes at collection time, and
    /// file-level masking cannot express "module evaluated but exports
    /// stubbed". For Jest, a `__mocks__` sibling takes precedence and the
    /// original is genuinely not required, but the manual mock itself may
    /// load the original (`jest.requireActual`), and proving it never does
    /// would need a cross-file factory proof. Both runners therefore keep
    /// coverage credit for the automock form.
    Mock {
        /// Whether the factory provably replaces the original module.
        factory_replaces_original: bool,
    },
    /// Remove a registered mock and restore the original module.
    Unmock,
}

impl VitestModuleMockAction {
    /// Whether this operation registers a proven complete replacement.
    #[must_use]
    pub const fn replaces_original(self) -> bool {
        matches!(
            self,
            Self::Mock {
                factory_replaces_original: true
            }
        )
    }
}

/// Ordered Vitest module-mock operation with a static source target.
///
/// The declaring [`ModuleInfo::file_id`] owns the test-root provenance. The
/// resolver consumes `source` through its canonical specifier pipeline; this
/// fact deliberately carries no resolved path or duplicate diagnostic span.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct VitestModuleMockOperationFact {
    /// Static module specifier passed to `vi.mock` or `vi.unmock`.
    pub source: String,
    /// Source-order position of the call within the declaring module.
    pub call_start: u32,
    /// Typed mock or unmock action.
    pub action: VitestModuleMockAction,
}

/// A `this`-rooted member access with exact enclosing-class provenance.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ClassThisMemberAccessFact {
    /// Enclosing class local name, or `default` for an anonymous default class.
    pub class_local_name: String,
    /// Dotted receiver spelling beginning with `this.`.
    pub object: String,
    /// Terminal member being accessed.
    pub member: String,
}

/// A whole-object use of a `this`-rooted chain with enclosing-class provenance.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, bitcode::Encode, bitcode::Decode)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ClassThisWholeObjectUseFact {
    /// Enclosing class local name, or `default` for an anonymous default class.
    pub class_local_name: String,
    /// Dotted receiver spelling beginning with `this.`.
    pub object: String,
}

/// A statically flattenable callee path invoked in a module (e.g. `execSync`,
/// `child_process.exec`, `console.log`). One entry per unique `callee_path`
/// per module; the span anchors the first occurrence. Consumed by the
/// `boundaries.calls.forbidden` detector.
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode)]
pub struct CalleeUse {
    /// The dotted or bare callee path as written at the call site.
    pub callee_path: String,
    /// Start byte offset of the first call site using this path.
    pub span_start: u32,
}

/// A direct call whose root identifier resolves to a runtime ESM import.
///
/// Every occurrence is retained. Computed or optional callees and arbitrary
/// value aliases are excluded; origin resolution through re-exports is deferred
/// to analysis.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct ImportedCallSite {
    /// The local root import binding used by the callee.
    pub local_name: String,
    /// Dot-separated static member suffix, empty for a bare imported call.
    pub member_path: String,
    /// Static first string argument, or `None` for any other argument shape.
    pub first_argument: Option<String>,
    /// Start byte offset of this call site.
    pub span_start: u32,
}

/// A value reference to a runtime ESM import binding that is not an admitted
/// call site, or that initializes a top-level declarator.
///
/// The admission rules are the same as for [`ImportedCallSite`]: the binding
/// has one import declaration, it is not type-only, and the reference reads a
/// value. `fallow trace --dependency` reads these facts to count each use of
/// an imported name that it cannot resolve to a call, and to find project
/// wrappers such as `export const useX = useSelector.withTypes()`.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct ImportBindingReference {
    /// Index into `ModuleInfo.imports` of the root binding.
    pub import_index: u32,
    /// Static member suffix after the root, empty for a bare reference.
    pub member_path: Box<str>,
    /// How the code uses the reference.
    pub kind: ImportBindingReferenceKind,
    /// Start byte of the root identifier, or of the call for
    /// [`ImportBindingReferenceKind::InitializerCall`].
    pub span_start: u32,
    /// Name of the top-level declarator that this reference initializes.
    pub declared_name: Option<Box<str>>,
    /// The exported top-level declarator that the reference reads, when the
    /// reference names that declarator and not the import binding. The
    /// declarator is initialized by a reference to the import binding at
    /// `import_index`, so the reference is a use of the binding through a
    /// project wrapper in its own module. `None` for a direct reference.
    pub through: Option<Box<str>>,
}

/// How the code uses an [`ImportBindingReference`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub enum ImportBindingReferenceKind {
    /// An admitted call that is the whole initializer of a top-level
    /// declarator: `const x = useSelector.withTypes<T>()`.
    InitializerCall,
    /// The reference is the whole initializer of a declarator:
    /// `const x = useDispatch`.
    ValueAlias,
    /// The reference names a JSX opening element: `<Provider>`.
    JsxElement,
    /// Any other value use that is not an admitted call, for example an
    /// argument, an array element or an optional call.
    Other,
    /// A direct call of a wrapper declarator in its own module. Only a
    /// reference with `through` set has this kind.
    Call,
}

/// A `"use client"` / `"use server"` directive string written as an expression
/// statement in `program.body` (NOT the leading prologue), so the RSC bundler
/// silently ignores it. One entry per offending occurrence. Consumed by the
/// `misplaced-directive` detector.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct MisplacedDirectiveSite {
    /// `true` for `"use server"`, `false` for `"use client"`.
    pub is_server: bool,
    /// Start byte offset of the misplaced directive statement.
    pub span_start: u32,
}

/// Which side of a dependency-injection link a call site represents.
#[derive(Debug, Clone, Copy, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub enum DiRole {
    /// `provide(KEY, value)` / `app.provide(KEY, value)` / `setContext(KEY, value)`.
    Provide,
    /// `inject(KEY)` / `getContext(KEY)`.
    Inject,
}

/// Which framework's DI API a call site came from (drives the finding message).
#[derive(Debug, Clone, Copy, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub enum DiFramework {
    /// Vue `provide` / `inject` (from `vue` / `@vue/runtime-core`).
    Vue,
    /// Svelte `setContext` / `getContext` (from `svelte`).
    Svelte,
    /// Angular `inject(TOKEN)` / `@Inject(TOKEN)` (from `@angular/core`),
    /// matched against `{ provide: TOKEN, ... }` provider objects.
    Angular,
}

/// A Vue `provide`/`inject` or Svelte `setContext`/`getContext` call site keyed
/// by an identifier symbol. The `key_local` is resolved at analyze time through
/// the consuming module's import/export tables to a canonical defining-site
/// export key, so a provide and an inject of the same shared symbol unify even
/// across barrel re-exports. Consumed by the `unprovided-inject` detector.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct DiKeySite {
    /// The key identifier as written at the call site.
    pub key_local: String,
    /// Whether this is a provide or an inject.
    pub role: DiRole,
    /// Which framework's API this came from.
    pub framework: DiFramework,
    /// Start byte offset of the call expression (anchors the finding).
    pub span_start: u32,
}

/// A component prop declared by Vue `<script setup>` `defineProps` or Svelte 5
/// `$props()`. `used_in_script` / `used_in_template` are set during extraction;
/// the `unused-component-prop` detector flags a prop where neither is true. See
/// `harvest_define_props` and `harvest_svelte_props` in `sfc_props.rs`.
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode)]
pub struct ComponentProp {
    /// The declared prop name.
    pub name: String,
    /// The template/script-visible local binding name: the destructure alias for
    /// `const { name: alias } = defineProps()` or
    /// `let { name: alias } = $props()`, otherwise the prop name itself. A
    /// renamed prop is read through this local, so usage must be checked against
    /// it, not the declared name.
    pub local: String,
    /// Start byte offset of the prop declaration (anchors the finding).
    pub span_start: u32,
    /// Whether this prop is referenced in the component's `<script>` (a
    /// destructured local binding with a resolved reference, or a `props.<name>`
    /// member access). For React, this is set-in-body: a resolved reference to the
    /// destructured local anywhere in the component function body.
    pub used_in_script: bool,
    /// Whether this prop name is referenced in the component's `<template>`.
    /// Set by `apply_template_usage` when the template scanner credits the name.
    /// Always false for React (no template; React uses `used_in_script`).
    pub used_in_template: bool,
    /// The enclosing component name. Empty for Vue SFCs (one component per file,
    /// the file stem is the component, set by the detector). For React this is the
    /// component function/arrow name a prop was declared on, so the detector can
    /// emit the right `component_name` and apply the per-component abstain ladder
    /// (a file can declare several React components).
    pub component: String,
    /// React-only: `true` when the destructured prop local is referenced at least
    /// once OUTSIDE a child-JSX attribute value expression (a substantive
    /// consumption: a hook arg, a host-element child, a non-JSX-attr read). When
    /// `used_in_script` is true but this is false, the prop is referenced ONLY as
    /// the root of forwarded child attribute values, i.e. a pure pass-through.
    /// Always `false` for Vue (no forward-vs-consume distinction is computed).
    pub used_outside_forward: bool,
}

/// A Vue `<script setup>` `defineEmits` declared event, harvested from the type
/// tuple-call form (`defineEmits<{ (e: 'foo'): void }>()`), the type object form
/// (`defineEmits<{ foo: [x: string] }>()`), or the runtime array form
/// (`defineEmits(['foo'])`). `used` is set during extraction when the bound emit
/// name is called as `emit('<name>')`. The `unused-component-emit` detector flags
/// an event where `used` is false. See `harvest_define_emits` in `sfc_props.rs`.
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode, PartialEq, Eq)]
pub struct ComponentEmit {
    /// The declared emit event name.
    pub name: String,
    /// Start byte offset of the emit declaration (anchors the finding).
    pub span_start: u32,
    /// Whether this event is emitted via `emit('<name>')` somewhere in the
    /// component's `<script>`.
    pub used: bool,
}

/// A Svelte custom event dispatched via `dispatch('<name>')`, where `dispatch`
/// is the binding from a `const dispatch = createEventDispatcher()` call. Only
/// literal-first-arg dispatches are recorded; a `dispatch(<nonLiteral>)` sets
/// `ModuleInfo::has_dynamic_dispatch` instead. Consumed by the
/// `unused-svelte-event` detector, which flags an event dispatched here but
/// listened to nowhere project-wide (the cross-file dead-output direction). The
/// span is a byte offset (not an `oxc_span::Span`) so the type round-trips
/// through the bitcode cache directly, mirroring `ComponentEmit::span_start`.
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode, PartialEq, Eq)]
pub struct DispatchedEvent {
    /// The dispatched event name (the literal first argument).
    pub name: String,
    /// Start byte offset of the `dispatch(...)` call (anchors the finding).
    pub span_start: u32,
}

/// A declared Angular component/directive input, harvested from an `@Input()`
/// decorator or a signal `input()` / `input.required()` / `model()` initializer
/// on an Angular-decorated class. Consumed by the `unused-component-input`
/// detector, which flags an input read nowhere in its own component (neither the
/// template nor the class body). The span is stored as a byte offset (not an
/// `oxc_span::Span`) so the type is cheap to mirror onto the cache, matching
/// `ComponentEmit::span_start`. `ModuleInfo` is not serialized, so no serde
/// attrs are derived here. `bitcode` derives let the type be mirrored directly
/// onto `CachedModule` (the same pattern as `ComponentEmit`).
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode, PartialEq, Eq)]
pub struct AngularInputMember {
    /// The declared input name (the property key).
    pub name: String,
    /// Start byte offset of the property key (anchors the finding).
    pub span_start: u32,
}

/// A declared Angular component/directive output, harvested from an `@Output()`
/// decorator or a signal `output()` / `outputFromObservable()` initializer on an
/// Angular-decorated class. Consumed by the `unused-component-output` detector,
/// which flags an output emitted nowhere in its own component. A `model()` is an
/// input and a framework-driven output, so it is recorded ONLY as an input and
/// never appears here (the implicit `update:` emit is framework-managed). The
/// span is a byte offset for the same reason as `AngularInputMember`.
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode, PartialEq, Eq)]
pub struct AngularOutputMember {
    /// The declared output name (the property key).
    pub name: String,
    /// Start byte offset of the property key (anchors the finding).
    pub span_start: u32,
}

/// A declared Angular `@Component` and its `selector` value(s), harvested from a
/// `@Component({ selector: '...' })` decorator. Consumed by the Angular arm of
/// the `unrendered-component` detector, which flags a component whose every
/// element selector is used in NO template project-wide (and that is not
/// referenced by class name anywhere, e.g. routed / bootstrapped / dynamically
/// rendered). A multi-selector string (`'app-foo, [appBar]'`) is split into the
/// `selectors` list. The span is stored as a byte offset (not an
/// `oxc_span::Span`) so the type round-trips through the bitcode cache directly,
/// mirroring `AngularInputMember::span_start`. `@Directive` is intentionally NOT
/// harvested here (directives have no template render). `ModuleInfo` is not
/// serialized, so no serde attrs are derived.
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode, PartialEq, Eq)]
pub struct AngularComponentSelector {
    /// The declared selector strings for this component, split on `,`. A purely
    /// element-selector component has only `app-foo`-shaped entries; attribute
    /// (`[appFoo]`) and class (`.foo`) selectors are retained verbatim so the
    /// detector can abstain when ANY non-element selector is present.
    pub selectors: Vec<String>,
    /// Start byte offset of the component class declaration (anchors the
    /// finding).
    pub span_start: u32,
    /// The component class name (used to credit routed / bootstrapped / dynamic
    /// class-name references project-wide).
    pub class_name: String,
}

/// A Lit / web-component custom element registered in a module via
/// `@customElement('x-foo')` or `customElements.define('x-foo', C)`. Consumed by
/// the Lit arm of the `unrendered-component` detector. The span is stored as a
/// byte offset (not an `oxc_span::Span`) so the type round-trips through the
/// bitcode cache directly, mirroring `AngularComponentSelector::span_start`.
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode, PartialEq, Eq)]
pub struct RegisteredCustomElement {
    /// The registered custom-element tag name (`x-foo`).
    pub tag: String,
    /// The registering class's local name, used for the public-API / export
    /// abstain (an exported / published element is rendered by a downstream
    /// consumer the scan cannot see). Empty for an anonymous
    /// `export default @customElement('x-foo') class extends LitElement {}`.
    pub class_local_name: String,
    /// Start byte offset of the registering class declaration (anchors the
    /// finding at the element, NOT line 1, since a `.ts` file can register
    /// several custom elements).
    pub span_start: u32,
}

/// A key returned from a SvelteKit route `load()` function's terminal return
/// object literal. Harvested from `+page.{ts,server.ts,js,server.js}` files
/// exporting a `load` function. Consumed by the `unused-load-data-key` detector,
/// which flags a key read by no consumer. The span is stored as byte offsets
/// (not an `oxc_span::Span`) so the type round-trips through the bitcode cache
/// directly, mirroring `DiKeySite::span_start` / `ComponentEmit::span_start`.
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode, PartialEq, Eq)]
pub struct LoadReturnKey {
    /// The returned-object property key name.
    pub name: String,
    /// Start byte offset of the key (anchors the finding).
    pub span_start: u32,
    /// End byte offset of the key.
    pub span_end: u32,
}

/// The syntactic shape of an identified React component definition. Drives the
/// abstain ladder later phases apply: a `forwardRef` / `memo` wrapper whose
/// props come from an imported interface fallow cannot resolve must abstain
/// (ADR-001), not guess.
#[derive(Debug, Clone, Copy, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub enum ComponentFunctionKind {
    /// A `function Foo() { return <.../> }` declaration.
    FnDecl,
    /// A `const Foo = () => <.../>` arrow (or function-expression) binding.
    Arrow,
    /// A `const Foo = forwardRef((props, ref) => <.../>)` wrapper.
    ForwardRefWrapper,
    /// A `const Foo = memo((props) => <.../>)` wrapper.
    MemoWrapper,
}

/// An identified React component: a function/arrow whose body returns JSX.
/// Captured by `visit_jsx_element`'s enclosing-component tracking. The
/// `unused-component-prop` (React arm) and complexity-fold phases consume this;
/// the abstain flags keep zero-FP on the cases ADR-001 cannot resolve.
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode)]
pub struct ComponentFunction {
    /// The component name (the binding or declaration identifier).
    pub name: String,
    /// Start byte offset of the component definition (anchors findings).
    pub span_start: u32,
    /// The syntactic shape of the definition.
    pub kind: ComponentFunctionKind,
    /// Whether the component is exported from its module (a named export, a
    /// `export default`, or re-exported in the same module). Public-API
    /// components abstain in the prop phase.
    pub is_exported: bool,
    /// `true` when the component's props are not statically harvestable: a
    /// rest/spread in the signature (`{ ...rest }`), props passed wholesale to a
    /// hook/helper, or a `forwardRef` / `memo` wrapper whose props come from an
    /// imported interface generic fallow cannot resolve (ADR-001). The prop
    /// phase abstains on the whole component when set.
    pub has_unharvestable_props: bool,
    /// `true` when the component body calls `cloneElement` / `React.cloneElement`.
    /// `cloneElement` injects props by reflection, so the static forward-set is
    /// incomplete; the prop-drilling phase abstains on any chain through this
    /// component (ADR-001, zero-FP).
    pub uses_clone_element: bool,
    /// `true` when the component renders a `*.Provider` member-expression tag
    /// (`<FooContext.Provider>`). A context provider in the subtree means the
    /// drilling may be a deliberate non-context choice (or the prop is about to
    /// be provided); the prop-drilling phase downgrades/abstains.
    pub renders_provider: bool,
    /// `true` when the component passes a function as a child render value
    /// (render-props / children-as-function: `<Foo>{() => ...}</Foo>` or
    /// `<Foo render={() => ...}/>`). The forwarded shape is dynamic; the
    /// prop-drilling phase abstains on chains through this component.
    pub has_children_as_function: bool,
    /// `true` when the component body is pure structural indirection: a single
    /// statement returning exactly one capitalized/member-expression JSX element
    /// (no host wrapper, no extra children, optionally a fragment wrapping a
    /// single element) that forwards props via a bare spread of the component's
    /// own props binding / rest local (`<Child {...props}/>`), with NO named
    /// attributes alongside the spread and NO self-render. The cross-component
    /// `thin-wrapper` phase joins this with hook-density / cyclomatic checks and
    /// the resolved single render edge to flag a component that is a candidate
    /// for inlining. Computed from the component's own AST only, so it caches
    /// byte-identity-safe (ADR-001).
    pub is_pure_passthrough: bool,
}

/// The kind of a React hook call. `Custom` covers any `use*`-named call that is
/// not one of the built-in hooks.
#[derive(Debug, Clone, Copy, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub enum HookUseKind {
    /// `useState(...)`.
    UseState,
    /// `useEffect(...)`.
    UseEffect,
    /// `useMemo(...)`.
    UseMemo,
    /// `useCallback(...)`.
    UseCallback,
    /// Any other `use*`-named call (a custom hook).
    Custom,
}

/// A React hook call site inside a component. Consumed by the complexity-fold
/// phase (hook density) and surfaced as descriptive hotspot context.
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode)]
pub struct HookUse {
    /// The hook kind.
    pub kind: HookUseKind,
    /// The dependency-array arity, recorded ONLY when a literal array is present
    /// at the dependency-array position (`[a, b]` -> `Some(2)`, `[]` ->
    /// `Some(0)`). `None` when the call has no dependency array argument or the
    /// argument is not a literal array (ADR-001: do not guess).
    pub dep_array_arity: Option<u32>,
    /// Start byte offset of the hook call (anchors findings).
    pub span_start: u32,
    /// The enclosing component name (the top of the visitor's component stack
    /// when the hook call was recorded). Lets the descriptive per-component hook
    /// summary attribute hooks exactly even when a file declares several
    /// components. A hook recorded outside any component carries an empty string
    /// (the visitor only records hooks inside a component, so this is the
    /// rare top-level / unattributed case).
    pub component: String,
}

/// A render edge: one component rendering another (a capitalized or
/// member-expression JSX tag). Captured at extraction time with the child's
/// written name; resolution of `child_component_name` to a `FileId`/export is
/// deferred to graph build via the existing import map.
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode)]
pub struct RenderEdge {
    /// The name of the component that renders the child (the enclosing
    /// component). Empty when the JSX is not inside an identified component (a
    /// top-level render expression).
    pub parent_component: String,
    /// The rendered child component name as written (`Foo` or the full
    /// member-expression path `Foo.Bar`).
    pub child_component_name: String,
    /// The attribute (prop) names passed at the render site, in source order.
    pub attr_names: Vec<String>,
    /// `true` when the render site contains a JSX spread (`{...x}`), so the
    /// passed-prop set is not statically complete.
    pub has_spread: bool,
    /// The forwarded attributes at this render site: each pairs the child
    /// attribute NAME with the identifier ROOT of its value expression
    /// (`userName={user.name}` -> `{ attr: "userName", root: "user" }`;
    /// `value={x}` -> `{ attr: "value", root: "x" }`). ONLY plain identifier or
    /// member-root access values are recorded (`{x}`, `{x.y}`, `{x.y.z}`); a value
    /// that is a call, an arrow/function, a conditional, a JSX element, or any
    /// other complex expression is NOT recorded here (its root would not be a pure
    /// forward) and sets `has_complex_forward` instead. The prop-drilling chain
    /// walk uses this pairing to map "this component forwards prop P" to "the
    /// child receives it as attribute A".
    pub forward_attrs: Vec<ForwardAttr>,
    /// `true` when at least one attribute value at this render site is a complex
    /// expression (a call, an arrow/function render-prop, a conditional, a JSX
    /// element-as-prop, a template literal, etc.) whose identifier root was NOT
    /// recorded in `forward_attrs`. The prop-drilling phase abstains on a chain
    /// whose forwarded prop flows through such a value (ADR-001, zero-FP).
    pub has_complex_forward: bool,
}

/// One forwarded JSX attribute: the child attribute name plus the identifier
/// root of its value expression. See [`RenderEdge::forward_attrs`].
#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode)]
pub struct ForwardAttr {
    /// The child attribute (prop) name as written (`userName`).
    pub attr: String,
    /// The identifier root of the attribute value expression (`user` for
    /// `userName={user.name}`).
    pub root: String,
}

#[expect(
    clippy::trivially_copy_pass_by_ref,
    reason = "serde serialize_with requires &T"
)]
fn serialize_span<S: serde::Serializer>(span: &Span, serializer: S) -> Result<S::Ok, S::Error> {
    use serde::ser::SerializeMap;
    let mut map = serializer.serialize_map(Some(2))?;
    map.serialize_entry("start", &span.start)?;
    map.serialize_entry("end", &span.end)?;
    map.end()
}

/// Export identifier.
#[derive(Debug, Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum ExportName {
    /// A named export (e.g., `export const foo`).
    Named(String),
    /// The default export.
    Default,
}

impl ExportName {
    /// Compare against a string without allocating (avoids `to_string()`).
    #[must_use]
    pub fn matches_str(&self, s: &str) -> bool {
        match self {
            Self::Named(n) => n == s,
            Self::Default => s == "default",
        }
    }
}

impl std::fmt::Display for ExportName {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Named(n) => write!(f, "{n}"),
            Self::Default => write!(f, "default"),
        }
    }
}

/// An import declaration.
#[derive(Debug, Clone)]
pub struct ImportInfo {
    /// The import specifier (e.g., `./utils` or `react`).
    pub source: String,
    /// How the symbol is imported (named, default, namespace, or side-effect).
    pub imported_name: ImportedName,
    /// The local binding name in the importing module.
    pub local_name: String,
    /// Whether this is a type-only import (`import type`).
    pub is_type_only: bool,
    /// Whether this whole-module import forwards type meanings only.
    ///
    /// Set for `export type *` and `export type * as ns` inside a
    /// `declare module '...'` body (issue #2375). Those forms record the same
    /// bindingless whole-module shape the plain ambient star records
    /// (issue #2357), but the star they stand for erases every value meaning,
    /// so the graph credits the target's star surface in the type namespace
    /// alone. Every other import leaves this false: `is_type_only` already
    /// decides their namespace on its own.
    pub is_type_only_star: bool,
    /// Whether this import originated from a CSS-context.
    pub from_style: bool,
    /// Source span of the import declaration.
    pub span: Span,
    /// Span of the source string literal used by the LSP to highlight the specifier.
    pub source_span: Span,
}

/// How a symbol is imported.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum ImportedName {
    /// A named import (e.g., `import { foo }`).
    Named(String),
    /// A default import (e.g., `import React`).
    Default,
    /// A namespace import (e.g., `import * as utils`).
    Namespace,
    /// A side-effect import (e.g., `import './styles.css'`).
    SideEffect,
}

#[cfg(target_pointer_width = "64")]
const _: () = assert!(std::mem::size_of::<ExportInfo>() == 152);
#[cfg(target_pointer_width = "64")]
const _: () = assert!(std::mem::size_of::<ImportInfo>() == 96);
#[cfg(target_pointer_width = "64")]
const _: () = assert!(std::mem::size_of::<ExportName>() == 24);
#[cfg(target_pointer_width = "64")]
const _: () = assert!(std::mem::size_of::<ImportedName>() == 24);
#[cfg(target_pointer_width = "64")]
const _: () = assert!(std::mem::size_of::<MemberAccess>() == 48);
#[cfg(target_pointer_width = "64")]
const _: () = assert!(std::mem::size_of::<SemanticFact>() == 80);
#[cfg(target_pointer_width = "64")]
const _: () = assert!(std::mem::size_of::<SinkSite>() == 216);
#[cfg(target_pointer_width = "64")]
const _: () = assert!(std::mem::size_of::<ModuleInfo>() == 1472);
#[cfg(target_pointer_width = "64")]
const _: () = assert!(std::mem::size_of::<ImportBindingReference>() == 64);
#[cfg(target_pointer_width = "64")]
const _: () = assert!(std::mem::size_of::<TypeMemberTypeEntry>() == 72);

/// A re-export declaration.
#[derive(Debug, Clone)]
pub struct ReExportInfo {
    /// The module being re-exported from.
    pub source: String,
    /// The name imported from the source module (or `*` for star re-exports).
    pub imported_name: String,
    /// The name exported from this module.
    pub exported_name: String,
    /// Whether this is a type-only re-export.
    pub is_type_only: bool,
    /// Source span of the re-export declaration on this module.
    pub span: oxc_span::Span,
    /// Span of the whole re-export statement. A multi-binding statement
    /// yields one `ReExportInfo` per binding, each with a per-binding
    /// `span`; this field lets consumers reason about the enclosing
    /// statement (e.g. suppression coverage). Empty (`start == end`) for
    /// synthesized re-exports that have no single owning statement.
    pub statement_span: oxc_span::Span,
    /// Span of the source string literal (the specifier in quotes), used to
    /// anchor unresolved-import findings on the specifier. Empty
    /// (`start == end`) when no literal exists in the statement.
    pub source_span: oxc_span::Span,
}

/// A dynamic `import()` call.
#[derive(Debug, Clone)]
pub struct DynamicImportInfo {
    /// The import specifier.
    pub source: String,
    /// Source span of the `import()` expression.
    pub span: Span,
    /// Names destructured from the dynamic import result.
    /// Non-empty means `const { a, b } = await import(...)` -> Named imports.
    /// Empty means simple `import(...)` or `const x = await import(...)` -> Namespace.
    pub destructured_names: Vec<String>,
    /// The local variable name for `const x = await import(...)`.
    /// Used for namespace import narrowing via member access tracking.
    pub local_name: Option<String>,
    /// True when this dynamic import was synthesised by fallow rather than appearing in user source.
    pub is_speculative: bool,
    /// True when the value of an `import()` without a binding escapes, for
    /// example as a return value, a call argument, or an array element.
    /// The consumer can then read any export, so the edge credits the whole
    /// module namespace. False for a discarded `import()` statement, which
    /// only loads the module.
    pub value_escapes: bool,
}

/// A `require()` call.
#[derive(Debug, Clone)]
pub struct RequireCallInfo {
    /// The require specifier.
    pub source: String,
    /// Source span of the `require()` call.
    pub span: Span,
    /// Source span of the specifier string-literal argument (including its
    /// quotes), e.g. the `'./x'` in `require('./x')`. Used to anchor an
    /// `unresolved-import` diagnostic squiggly under the specifier rather than
    /// the `require` keyword. `Span::default()` when the argument is not a
    /// plain string literal.
    pub source_span: Span,
    /// Names destructured from the `require()` result.
    pub destructured_names: Vec<String>,
    /// The local variable name for `const x = require(...)`.
    pub local_name: Option<String>,
    /// `true` for `import type X = require('...')`, the one require spelling
    /// TypeScript erases entirely: the emitted JavaScript contains no
    /// `require` call, so the target is a type-space reference and never a
    /// runtime dependency. Always `false` for `const x = require(...)`, which
    /// has no type-only spelling. Read by dependency classification so a
    /// type-only devDependency is not reported as production usage.
    pub is_type_only: bool,
}

/// Result of parsing all files, including incremental cache statistics.
pub struct ParseResult {
    /// Extracted module information for all successfully parsed files.
    pub modules: Vec<ModuleInfo>,
    /// Files discovered with stable IDs but unreadable by the parser.
    pub read_failures: Vec<SourceReadFailure>,
    /// Files that parsed with diagnostics, so their extracted module may be
    /// incomplete. Reported, never used to withhold findings.
    pub parse_degradations: Vec<SourceParseDegradation>,
    /// Number of files whose parse results were loaded from cache (unchanged).
    pub cache_hits: usize,
    /// Number of files that required a full parse (new or changed).
    pub cache_misses: usize,
    /// Summed wall-clock time of the actual AST parses across all rayon workers.
    pub parse_cpu_ms: f64,
    /// Files whose bytes were read from disk: every parse, plus every cache
    /// hit that had to compare the content hash.
    pub files_read: u64,
    /// Bytes of source read from disk across all files.
    pub source_bytes_read: u64,
    /// Source bytes that the CSS comment mask read across all parsed files.
    pub css_masked_bytes: u64,
}

/// A discovered source that could not be read as UTF-8 text.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SourceReadFailure {
    /// Stable discovery identity retained even though no module was produced.
    pub file_id: FileId,
    /// Absolute discovered source path.
    pub path: PathBuf,
    /// Underlying filesystem or UTF-8 decoding error.
    pub error: String,
}

/// A discovered source that was read but did not parse cleanly.
///
/// The module it produced is still analyzed: dropping it would turn one broken
/// file into project-wide silence. The point of carrying the degradation is
/// that the imports the file failed to parse credited nothing, so its targets
/// can be reported as unused with full confidence unless a consumer is told the
/// parse was partial.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SourceParseDegradation {
    /// Stable discovery identity of the degraded source.
    pub file_id: FileId,
    /// Absolute discovered source path.
    pub path: PathBuf,
    /// Number of parser diagnostics reported for the file.
    pub error_count: u32,
    /// `true` when the parser abandoned the file instead of recovering.
    pub panicked: bool,
    /// The nesting cap when the file nests too deep to parse.
    pub nesting_limit: Option<u32>,
}

#[cfg(test)]
#[path = "extract_tests.rs"]
mod tests;

/// Framework owning a statically extracted component contract.
#[derive(Debug, Clone, Copy, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub enum ComponentFramework {
    /// React JSX.
    React,
    /// Preact JSX.
    Preact,
    /// Solid JSX.
    Solid,
    /// Qwik JSX.
    Qwik,
    /// Vue and Nuxt single-file components.
    Vue,
    /// Svelte components.
    Svelte,
    /// Astro components.
    Astro,
    /// Angular components and directives.
    Angular,
    /// Lit custom elements.
    Lit,
    /// Ember and Glimmer components.
    Ember,
}

/// Stable component binding identity, independent of transient parser symbols.
#[derive(Debug, Clone, PartialEq, Eq, Hash, bitcode::Encode, bitcode::Decode)]
pub enum ComponentReference {
    /// A same-module declaration, including resolved immutable local aliases.
    Local {
        /// Declaration binding name.
        name: String,
        /// Start byte of the declaration binding.
        span_start: u32,
    },
    /// An import binding. Analysis resolves its effective export via the graph.
    Import {
        /// Local name of the actual import binding, never a shadowing identifier.
        local: String,
        /// Start byte of the import binding declaration.
        span_start: u32,
    },
    /// A direct member of a proven namespace import.
    NamespaceMember {
        /// Local namespace import binding name.
        local: String,
        /// Namespace import binding byte anchor.
        span_start: u32,
        /// Effective value export requested by the member access.
        member: String,
    },
    /// A statically registered Angular selector or custom-element tag.
    Selector(String),
    /// Dynamic or unsupported component identity.
    Unknown,
}

/// A declared public input, kept distinct from legacy unused-prop facts.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct ComponentPropDeclaration {
    /// Component declaration name. Empty denotes the sole SFC default export.
    pub component: String,
    /// Stable declaration binding byte anchor.
    pub component_span: u32,
    /// Public input name.
    pub name: String,
    /// Local binding name used by destructured template reads.
    pub local: String,
    /// Additional public attribute names supplying the same input.
    pub aliases: Vec<String>,
    /// Declaration byte anchor in the original source.
    pub span_start: u32,
    /// Whether the declaration explicitly permits omission.
    pub optional: bool,
    /// Whether omission has a syntactically declared default value.
    pub has_default: bool,
    /// Whether the input is consumed within the component.
    pub is_used: bool,
    /// Producer framework.
    pub framework: ComponentFramework,
    /// Unsupported declarations, forwarding, or open consumers prohibit absence claims.
    pub incomplete: bool,
}

/// One inspected render invocation and its supplied input names.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct ComponentInvocation {
    /// Binding or selector used by the invocation.
    pub target: ComponentReference,
    /// Original source byte anchor of the opening tag or call.
    pub span_start: u32,
    /// Supplied names, independent of values and including proven spread keys.
    pub supplied: Vec<String>,
    /// Case-sensitive Lit JavaScript property bindings, distinct from HTML attributes.
    pub supplied_properties: Vec<String>,
    /// A spread or dynamic attribute may supply additional names.
    pub unknown_props: bool,
    /// Framework syntax of this caller.
    pub framework: ComponentFramework,
}

/// Persisted syntactic Effect evidence for one module.
///
/// The layer keys, their `dependencies` and `layer_root_keys` use one
/// format: a plain binding name (`FooLive`) or a class static member
/// (`FooService.layer`). Import aliases resolve to the imported name, and a
/// namespace member (`Ns.FooLive`) resolves to the member name.
#[derive(Debug, Clone, Default, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct EffectFacts {
    /// Module-scope classes that extend a tagged error constructor.
    pub tagged_errors: Vec<EffectTaggedError>,
    /// `catchTag("X")` arguments and `catchTags({ X })` keys.
    pub caught_tags: Vec<EffectCaughtTag>,
    /// Tags written as an object literal `_tag: "X"` property.
    pub literal_tags: Vec<String>,
    /// Layer definitions: module-scope consts and class static properties.
    pub layers: Vec<EffectLayer>,
    /// Keys that a value reference outside every layer definition reads.
    pub layer_root_keys: Vec<String>,
}

/// A module-scope class that extends a tagged error constructor.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct EffectTaggedError {
    /// Class binding name.
    pub name: String,
    /// The `_tag` string literal.
    pub tag: String,
    /// Byte offset of the class name.
    pub span_start: u32,
    /// The class is exported from its module.
    pub exported: bool,
    /// The module reads the class as a value outside its own declaration.
    pub local_value_reference: bool,
    /// The module reads the class in a type position outside its own declaration.
    pub local_type_reference: bool,
}

/// One tag that a `catchTag` or `catchTags` handler names.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct EffectCaughtTag {
    /// The handled tag.
    pub tag: String,
    /// Byte offset of the tag string or object key.
    pub span_start: u32,
}

/// A layer definition and the layer keys its initializer reads.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct EffectLayer {
    /// `FooLive` or `FooService.layer`.
    pub key: String,
    /// Byte offset of the binding name or static property key.
    pub span_start: u32,
    /// The const, or the class of a static property, is exported.
    pub exported: bool,
    /// Keys that value references inside the initializer read.
    pub dependencies: Vec<String>,
}

/// Persisted syntactic evidence for conservative component-input analysis.
#[derive(Debug, Clone, Default, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct ComponentContractFacts {
    /// Immutable root script aliases resolved to their semantic targets.
    pub aliases: Vec<ComponentAliasBinding>,
    /// Exact Angular templateUrl source owned by each component binding.
    pub external_templates: Vec<ComponentExternalTemplate>,
    /// Original component bodies that own embedded Glimmer templates.
    pub template_owners: Vec<ComponentTemplateOwner>,
    /// Effective local export bindings retained after graph payload release.
    pub exports: Vec<ComponentExportBinding>,
    /// Immutable local object shapes retained for template spread resolution.
    pub spread_bindings: Vec<ComponentSpreadBinding>,
    /// Known declaration contracts.
    pub declarations: Vec<ComponentPropDeclaration>,
    /// Inspected render sites, including module-level invocations.
    pub invocations: Vec<ComponentInvocation>,
    /// Component bindings used opaquely outside inspected renders.
    pub escapes: Vec<ComponentReference>,
    /// Frameworks with a dynamic consumer whose affected target is unknowable.
    pub incomplete_frameworks: Vec<ComponentFramework>,
}

/// An immutable, unescaped local object with statically known own keys.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct ComponentSpreadBinding {
    /// Root script binding name, resolved before template scopes are applied.
    pub local: String,
    /// Script binding declaration anchor.
    pub span_start: u32,
    /// Complete own property names.
    pub keys: Vec<String>,
}

/// An export name resolved to its syntactic component or import binding.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct ComponentExportBinding {
    /// Public export name, including `default`.
    pub export_name: String,
    /// Original export declaration byte anchor.
    pub export_span: u32,
    /// Proven local binding, canonicalizing immutable aliases.
    pub target: ComponentReference,
}

/// A semantic component declaration body containing an embedded template.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct ComponentTemplateOwner {
    /// Owning component binding anchor.
    pub component_span: u32,
    /// Original class body start.
    pub start: u32,
    /// Original class body end.
    pub end: u32,
}

/// A statically declared external template owned by one component.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct ComponentExternalTemplate {
    /// Owning component binding anchor.
    pub component_span: u32,
    /// Literal templateUrl source, resolved through the graph import edge.
    pub source: String,
}

/// An immutable root binding that aliases a component or import.
#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
pub struct ComponentAliasBinding {
    /// Root script binding spelling used by template expressions.
    pub local: String,
    /// Canonical semantic binding target, including its source anchor.
    pub target: ComponentReference,
}