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` site; one per `(callee_path, is_new)` per module.
21#[derive(Debug, Clone, bitcode::Encode, bitcode::Decode)]
22pub struct CalleeUse {
23 /// The dotted or bare callee path as written at the site (e.g. `cp.exec`).
24 pub callee_path: String,
25 /// Start byte offset of the first site with this path and form.
26 pub span_start: u32,
27 /// True for a `new` expression. `banned-effect` and the trace read only false entries.
28 pub is_new: bool,
29}
30
31/// A direct call whose root identifier resolves to a runtime ESM import.
32///
33/// Every occurrence is retained. Computed or optional callees and arbitrary
34/// value aliases are excluded; origin resolution through re-exports is deferred
35/// to analysis.
36#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
37pub struct ImportedCallSite {
38 /// The local root import binding used by the callee.
39 pub local_name: String,
40 /// Dot-separated static member suffix, empty for a bare imported call.
41 pub member_path: String,
42 /// Static first string argument, or `None` for any other argument shape.
43 pub first_argument: Option<String>,
44 /// Start byte offset of this call site.
45 pub span_start: u32,
46}
47
48/// A value reference to a runtime ESM import binding that is not an admitted
49/// call site, or that initializes a top-level declarator.
50///
51/// The admission rules are the same as for [`ImportedCallSite`]: the binding
52/// has one import declaration, it is not type-only, and the reference reads a
53/// value. `fallow trace --dependency` reads these facts to count each use of
54/// an imported name that it cannot resolve to a call, and to find project
55/// wrappers such as `export const useX = useSelector.withTypes()`.
56#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
57pub struct ImportBindingReference {
58 /// Index into `ModuleInfo.imports` of the root binding.
59 pub import_index: u32,
60 /// Static member suffix after the root, empty for a bare reference.
61 pub member_path: Box<str>,
62 /// How the code uses the reference.
63 pub kind: ImportBindingReferenceKind,
64 /// Start byte of the root identifier, or of the call for
65 /// [`ImportBindingReferenceKind::InitializerCall`].
66 pub span_start: u32,
67 /// Name of the top-level declarator that this reference initializes.
68 pub declared_name: Option<Box<str>>,
69 /// The exported top-level declarator that the reference reads, when the
70 /// reference names that declarator and not the import binding. The
71 /// declarator is initialized by a reference to the import binding at
72 /// `import_index`, so the reference is a use of the binding through a
73 /// project wrapper in its own module. `None` for a direct reference.
74 pub through: Option<Box<str>>,
75}
76
77/// How the code uses an [`ImportBindingReference`].
78#[derive(Debug, Clone, Copy, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
79pub enum ImportBindingReferenceKind {
80 /// An admitted call that is the whole initializer of a top-level
81 /// declarator: `const x = useSelector.withTypes<T>()`.
82 InitializerCall,
83 /// The reference is the whole initializer of a declarator:
84 /// `const x = useDispatch`.
85 ValueAlias,
86 /// The reference names a JSX opening element: `<Provider>`.
87 JsxElement,
88 /// Any other value use that is not an admitted call, for example an
89 /// argument, an array element or an optional call.
90 Other,
91 /// A direct call of a wrapper declarator in its own module. Only a
92 /// reference with `through` set has this kind.
93 Call,
94}