Skip to main content

fallow_types/
extract_calls.rs

1//! Persisted call-site facts: callee paths, imported calls, import binding
2//! references and process commands.
3
4/// A literal command that a process-spawning call runs.
5///
6/// The extractor records the call only when the callee resolves to a known
7/// process API (`node:child_process`, `execa`, `zx`, `Bun`) and the command is
8/// a string literal or the static head of a template.
9#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
10pub struct CommandInvocation {
11    /// The command text. For a program call this is the program name. For a
12    /// shell call this is the static shell text up to the first expression.
13    pub command: String,
14    /// True when a shell parses `command` (`exec`, `execSync`, `$` templates).
15    pub shell: bool,
16    /// Start byte offset of the command literal.
17    pub span_start: u32,
18}
19
20/// A flattenable callee path of a call or `new` form, with every site of that path and form.
21///
22/// The extractor groups the sites per `(callee_path, is_new)` in one script
23/// block, so the path string is stored once and each extra site costs 4 bytes.
24/// A module can still hold two entries with the same path and form when the
25/// sites are in different script blocks of a single-file component.
26#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode)]
27pub struct CalleeUse {
28    /// The dotted or bare callee path as written at the site (e.g. `cp.exec`).
29    pub callee_path: String,
30    /// Start byte offset of each site with this path and form, in source order.
31    /// Never empty.
32    pub span_starts: Vec<u32>,
33    /// True for a `new` expression. `banned-effect` and the trace read only false entries.
34    pub is_new: bool,
35}
36
37/// A direct call whose root identifier resolves to a runtime ESM import.
38///
39/// Every occurrence is retained. Computed or optional callees and arbitrary
40/// value aliases are excluded; origin resolution through re-exports is deferred
41/// to analysis.
42#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
43pub struct ImportedCallSite {
44    /// The local root import binding used by the callee.
45    pub local_name: String,
46    /// Dot-separated static member suffix, empty for a bare imported call.
47    pub member_path: String,
48    /// Static first string argument, or `None` for any other argument shape.
49    pub first_argument: Option<String>,
50    /// Start byte offset of this call site.
51    pub span_start: u32,
52}
53
54/// A value reference to a runtime ESM import binding that is not an admitted
55/// call site, or that initializes a top-level declarator.
56///
57/// The admission rules are the same as for [`ImportedCallSite`]: the binding
58/// has one import declaration, it is not type-only, and the reference reads a
59/// value. `fallow trace --dependency` reads these facts to count each use of
60/// an imported name that it cannot resolve to a call, and to find project
61/// wrappers such as `export const useX = useSelector.withTypes()`.
62#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
63pub struct ImportBindingReference {
64    /// Index into `ModuleInfo.imports` of the root binding.
65    pub import_index: u32,
66    /// Static member suffix after the root, empty for a bare reference.
67    pub member_path: Box<str>,
68    /// How the code uses the reference.
69    pub kind: ImportBindingReferenceKind,
70    /// Start byte of the root identifier, or of the call for
71    /// [`ImportBindingReferenceKind::InitializerCall`].
72    pub span_start: u32,
73    /// Name of the top-level declarator that this reference initializes.
74    pub declared_name: Option<Box<str>>,
75    /// The exported top-level declarator that the reference reads, when the
76    /// reference names that declarator and not the import binding. The
77    /// declarator is initialized by a reference to the import binding at
78    /// `import_index`, so the reference is a use of the binding through a
79    /// project wrapper in its own module. `None` for a direct reference.
80    pub through: Option<Box<str>>,
81}
82
83/// How the code uses an [`ImportBindingReference`].
84#[derive(Debug, Clone, Copy, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
85pub enum ImportBindingReferenceKind {
86    /// An admitted call that is the whole initializer of a top-level
87    /// declarator: `const x = useSelector.withTypes<T>()`.
88    InitializerCall,
89    /// The reference is the whole initializer of a declarator:
90    /// `const x = useDispatch`.
91    ValueAlias,
92    /// The reference names a JSX opening element: `<Provider>`.
93    JsxElement,
94    /// Any other value use that is not an admitted call, for example an
95    /// argument, an array element or an optional call.
96    Other,
97    /// A direct call of a wrapper declarator in its own module. Only a
98    /// reference with `through` set has this kind.
99    Call,
100}