Rename leaf into kind

Summary:
The term `leaf` is pretty ambiguous in our codebase. It is used in very various ways:
* To denote the source or sink kind (e.g, `UserControlled`). It is also called `leaf kind` sometimes.
* To denote a leaf name, i.e the callable that originated a source or sink, i.e the first frame or last frame of the trace.
* To denote a leaf taint, i.e the first frame or last frame of the trace.
* To denote a leaf in a binary tree.

To prevent confusion, I propose to rename the first use into `kind`. This is a lot more explicit in my opinion, and it is also the term we use in our user interface.

Reviewed By: dkgi

Differential Revision: D30758453

fbshipit-source-id: a99bf4c7883e19c35bd35e800d19b2e5e8b8ecd0

Author: arthaud

source/interprocedural_analyses/taint/backwardAnalysis.ml

@@ -228,8 +228,8 @@ module AnalysisInstance (FunctionContext : FUNCTION_CONTEXT) = struct
                     | Some argument -> get_argument_taint ~resolution ~argument)
                 | _ -> failwith "unexpected tito sink"
               in
-              let compute_tito_depth leaf depth =
-                match leaf with
+              let compute_tito_depth kind depth =
+                match kind with
                 | Sinks.LocalReturn -> max depth (1 + tito_depth)
                 | _ -> depth
               in
@@ -245,14 +245,14 @@ module AnalysisInstance (FunctionContext : FUNCTION_CONTEXT) = struct
                        ~f:breadcrumbs
                   |> BackwardTaint.transform
                        TraceLength.Self
-                       (Context (BackwardTaint.leaf, Map))
+                       (Context (BackwardTaint.kind, Map))
                        ~f:compute_tito_depth
                   |> BackwardState.Tree.create_leaf
                   |> BackwardState.Tree.prepend tito_path
                   |> BackwardState.Tree.join taint)
                 ~init:argument_taint
             in
-            BackwardTaint.partition BackwardTaint.leaf By ~f:Fn.id element
+            BackwardTaint.partition BackwardTaint.kind By ~f:Fn.id element
             |> Map.Poly.fold ~f:compute_parameter_tito ~init:argument_taint
           in
           let add_tito_feature_and_position leaf_taint =
@@ -306,7 +306,7 @@ module AnalysisInstance (FunctionContext : FUNCTION_CONTEXT) = struct
             | { tito = Some AllTito; _ } -> BackwardState.Tree.bottom
             | { tito = Some (SpecificTito { sanitized_tito_sinks; _ }); _ } ->
                 BackwardState.Tree.partition
-                  BackwardTaint.leaf
+                  BackwardTaint.kind
                   ByFilter
                   ~f:(fun sink ->
                     Option.some_if (not (Sinks.Set.mem sink sanitized_tito_sinks)) sink)
@@ -322,7 +322,7 @@ module AnalysisInstance (FunctionContext : FUNCTION_CONTEXT) = struct
             match AccessPath.of_expression ~resolution argument with
             | Some { AccessPath.root; path } ->
                 let features_to_add =
-                  BackwardState.Tree.filter_by_leaf ~leaf:Sinks.AddFeatureToArgument sink_taint
+                  BackwardState.Tree.filter_by_kind ~kind:Sinks.AddFeatureToArgument sink_taint
                   |> BackwardTaint.fold
                        BackwardTaint.simple_feature_self
                        ~f:Features.gather_breadcrumbs
@@ -1144,7 +1144,7 @@ module AnalysisInstance (FunctionContext : FUNCTION_CONTEXT) = struct
                 | { Sanitize.sinks = Some AllSinks; _ } -> BackwardState.Tree.empty
                 | { Sanitize.sinks = Some (SpecificSinks sanitized_sinks); _ } ->
                     BackwardState.Tree.partition
-                      BackwardTaint.leaf
+                      BackwardTaint.kind
                       ByFilter
                       ~f:(fun sink ->
                         Option.some_if (not (Sinks.Set.mem sink sanitized_sinks)) sink)
@@ -1425,13 +1425,13 @@ let extract_tito_and_sink_models define ~is_constructor ~resolution ~existing_ba
     let annotation = original.Node.value.Parameter.annotation in
     let partition =
       BackwardState.read ~root:(Root.Variable name) ~path:[] entry_taint
-      |> BackwardState.Tree.partition BackwardTaint.leaf By ~f:Fn.id
+      |> BackwardState.Tree.partition BackwardTaint.kind By ~f:Fn.id
     in
     let taint_in_taint_out =
       let features_to_attach =
         BackwardState.extract_features_to_attach
           ~root:parameter
-          ~attach_to_leaf:Sinks.Attach
+          ~attach_to_kind:Sinks.Attach
           existing_backward.TaintResult.Backward.taint_in_taint_out
       in
       let candidate_tree =
@@ -1493,7 +1493,7 @@ let extract_tito_and_sink_models define ~is_constructor ~resolution ~existing_ba
       let features_to_attach =
         BackwardState.extract_features_to_attach
           ~root:parameter
-          ~attach_to_leaf:Sinks.Attach
+          ~attach_to_kind:Sinks.Attach
           existing_backward.TaintResult.Backward.sink_taint
       in
       if not (Features.SimpleSet.is_bottom features_to_attach) then

source/interprocedural_analyses/taint/domains.ml

@@ -8,16 +8,6 @@
 open Core
 open Ast
 
-module type SET_ARG = sig
-  include Abstract.SetDomain.ELEMENT
-
-  val equal : t -> t -> bool
-
-  val show : t -> string
-
-  val ignore_leaf_at_call : t -> bool
-end
-
 let location_to_json
     {
       Location.start = { line = start_line; column = start_column };
@@ -265,11 +255,11 @@ end
 module type TAINT_DOMAIN = sig
   include Abstract.Domain.S
 
-  type leaf [@@deriving eq]
+  type kind [@@deriving eq]
 
-  val leaf : leaf Abstract.Domain.part
+  val kind : kind Abstract.Domain.part
 
-  val ignore_leaf_at_call : leaf -> bool
+  val ignore_kind_at_call : kind -> bool
 
   val trace_info : TraceInfo.t Abstract.Domain.part
 
@@ -308,61 +298,71 @@ module type TAINT_DOMAIN = sig
   val to_external_json : filename_lookup:(Reference.t -> string option) -> t -> Yojson.Safe.json
 end
 
-module LeafTaint (Leaf : SET_ARG) = struct
+module type KIND_ARG = sig
+  include Abstract.SetDomain.ELEMENT
+
+  val equal : t -> t -> bool
+
+  val show : t -> string
+
+  val ignore_kind_at_call : t -> bool
+end
+
+module KindTaint (Kind : KIND_ARG) = struct
   module Key = struct
-    include Leaf
+    include Kind
 
     let absence_implicitly_maps_to_bottom = false
   end
 
   module Map = Abstract.MapDomain.Make (Key) (FlowDetails)
   include Map
 
-  let singleton leaf = Map.set Map.bottom ~key:leaf ~data:FlowDetails.initial
+  let singleton kind = Map.set Map.bottom ~key:kind ~data:FlowDetails.initial
 end
 
-module MakeTaint (Leaf : SET_ARG) : sig
-  include TAINT_DOMAIN with type leaf = Leaf.t
+module MakeTaint (Kind : KIND_ARG) : sig
+  include TAINT_DOMAIN with type kind = Kind.t
 
-  val leaves : t -> leaf list
+  val kinds : t -> kind list
 
-  val singleton : ?location:Location.WithModule.t -> leaf -> t
+  val singleton : ?location:Location.WithModule.t -> kind -> t
 
-  val of_list : ?location:Location.WithModule.t -> leaf list -> t
+  val of_list : ?location:Location.WithModule.t -> kind list -> t
 end = struct
   module Key = struct
     include TraceInfo
 
     let absence_implicitly_maps_to_bottom = true
   end
 
-  module LeafDomain = LeafTaint (Leaf)
-  module Map = Abstract.MapDomain.Make (Key) (LeafDomain)
+  module KindTaintDomain = KindTaint (Kind)
+  module Map = Abstract.MapDomain.Make (Key) (KindTaintDomain)
   include Map
 
-  type leaf = Leaf.t [@@deriving compare]
+  type kind = Kind.t [@@deriving compare]
 
-  let equal_leaf = Leaf.equal
+  let equal_kind = Kind.equal
 
-  let add ?location map leaf =
+  let add ?location map kind =
     let trace =
       match location with
       | None -> TraceInfo.Declaration { leaf_name_provided = false }
       | Some location -> TraceInfo.Origin location
     in
-    let leaf_taint = LeafDomain.singleton leaf in
+    let kind_taint = KindTaintDomain.singleton kind in
     Map.update map trace ~f:(function
-        | None -> leaf_taint
-        | Some existing -> LeafDomain.join leaf_taint existing)
+        | None -> kind_taint
+        | Some existing -> KindTaintDomain.join kind_taint existing)
 
 
-  let singleton ?location leaf = add ?location Map.bottom leaf
+  let singleton ?location kind = add ?location Map.bottom kind
 
-  let of_list ?location leaves = List.fold leaves ~init:Map.bottom ~f:(add ?location)
+  let of_list ?location kinds = List.fold kinds ~init:Map.bottom ~f:(add ?location)
 
-  let leaf = LeafDomain.Key
+  let kind = KindTaintDomain.Key
 
-  let ignore_leaf_at_call = Leaf.ignore_leaf_at_call
+  let ignore_kind_at_call = Kind.ignore_kind_at_call
 
   let trace_info = Map.Key
 
@@ -380,14 +380,14 @@ end = struct
 
   let first_indices = Features.FirstIndexSet.Self
 
-  let leaves map =
-    Map.fold leaf ~init:[] ~f:List.cons map |> List.dedup_and_sort ~compare:Leaf.compare
+  let kinds map =
+    Map.fold kind ~init:[] ~f:List.cons map |> List.dedup_and_sort ~compare:Kind.compare
 
 
   let create_json ~trace_info_to_json taint =
-    let leaf_to_json trace_info (leaf, features) =
+    let leaf_to_json trace_info (kind, features) =
       let trace_length = FlowDetails.fold TraceLength.Self features ~f:min ~init:55555 in
-      let leaf_kind_json = `String (Leaf.show leaf) in
+      let kind_json = `String (Kind.show kind) in
       let breadcrumbs, leaf_json =
         let gather_json { Abstract.OverUnderSetDomain.element; in_under } breadcrumbs =
           match element with
@@ -402,7 +402,7 @@ end = struct
         in
         let gather_return_access_path path leaves =
           let path_name = Abstract.TreeDomain.Label.show_path path in
-          `Assoc ["kind", leaf_kind_json; "name", `String path_name; "depth", `Int trace_length]
+          `Assoc ["kind", kind_json; "name", `String path_name; "depth", `Int trace_length]
           :: leaves
         in
         let breadcrumbs =
@@ -411,7 +411,7 @@ end = struct
         let leaves =
           FlowDetails.get FlowDetails.Slots.LeafName features
           |> Features.LeafNameSet.elements
-          |> List.map ~f:(Features.LeafName.to_json ~leaf_kind_json)
+          |> List.map ~f:(Features.LeafName.to_json ~kind_json)
         in
         let first_index_breadcrumbs =
           FlowDetails.get FlowDetails.Slots.FirstIndex features
@@ -439,7 +439,7 @@ end = struct
       let trace_json = trace_info_to_json ~trace_length trace_info in
       let leaf_json =
         if List.is_empty leaf_json then
-          [`Assoc ["kind", leaf_kind_json]]
+          [`Assoc ["kind", kind_json]]
         else
           leaf_json
       in
@@ -457,8 +457,8 @@ end = struct
       in
       `Assoc (trace_json :: association)
     in
-    let trace_to_json (traceinfo, leaftaint) =
-      LeafDomain.Map.to_alist leaftaint |> List.map ~f:(leaf_to_json traceinfo)
+    let trace_to_json (trace_info, kind_taint) =
+      KindTaintDomain.Map.to_alist kind_taint |> List.map ~f:(leaf_to_json trace_info)
     in
     (* expand now do dedup possibly abstract targets that resolve to the same concrete ones *)
     let taint = Map.transform Key Abstract.Domain.Map ~f:TraceInfo.expand_call_site taint in
@@ -494,29 +494,29 @@ end = struct
       let length = FlowDetails.get FlowDetails.Slots.TraceLength flow_details in
       TraceLength.is_bottom length || TraceLength.less_or_equal ~left:maximum_length ~right:length
     in
-    transform LeafDomain.KeyValue Filter ~f:filter_flow
+    transform KindTaintDomain.KeyValue Filter ~f:filter_flow
 
 
   let apply_call location ~callees ~port ~path ~element:taint =
-    let apply (trace_info, leaf_taint) =
+    let apply (trace_info, kind_taint) =
       let open TraceInfo in
-      let leaf_taint =
-        LeafDomain.transform
+      let kind_taint =
+        KindTaintDomain.transform
           Features.TitoPositionSet.Self
           Abstract.Domain.Map
           ~f:(fun _ -> Features.TitoPositionSet.bottom)
-          leaf_taint
+          kind_taint
       in
       match trace_info with
       | Origin _
       | CallSite _ ->
           let increase_length n = if n < max_int then n + 1 else n in
           let trace_info = CallSite { location; callees; port; path } in
-          let leaf_taint =
-            leaf_taint
-            |> LeafDomain.transform TraceLength.Self Abstract.Domain.Map ~f:increase_length
+          let kind_taint =
+            kind_taint
+            |> KindTaintDomain.transform TraceLength.Self Abstract.Domain.Map ~f:increase_length
           in
-          trace_info, leaf_taint
+          trace_info, kind_taint
       | Declaration { leaf_name_provided } ->
           let trace_info = Origin location in
           let new_leaf_names =
@@ -529,14 +529,14 @@ end = struct
               in
               List.map ~f:make_leaf_name callees |> Features.LeafNameSet.of_list
           in
-          let leaf_taint =
-            LeafDomain.transform
+          let kind_taint =
+            KindTaintDomain.transform
               Features.LeafNameSet.Self
               Abstract.Domain.Add
               ~f:new_leaf_names
-              leaf_taint
+              kind_taint
           in
-          trace_info, leaf_taint
+          trace_info, kind_taint
     in
     Map.transform Map.KeyValue Abstract.Domain.Map ~f:apply taint
 end
@@ -559,9 +559,9 @@ module MakeTaintTree (Taint : TAINT_DOMAIN) () = struct
     let transform_path (path, tip) =
       let tip =
         Taint.partition
-          Taint.leaf
+          Taint.kind
           ByFilter
-          ~f:(fun leaf -> if Taint.ignore_leaf_at_call leaf then None else Some false)
+          ~f:(fun kind -> if Taint.ignore_kind_at_call kind then None else Some false)
           tip
         |> (fun map -> Map.Poly.find map false)
         |> function
@@ -618,10 +618,10 @@ module MakeTaintTree (Taint : TAINT_DOMAIN) () = struct
     transform Taint.Self Map ~f:(Taint.prune_maximum_length maximum_length)
 
 
-  let filter_by_leaf ~leaf taint_tree =
+  let filter_by_kind ~kind taint_tree =
     collapse ~transform:Fn.id taint_tree
-    |> Taint.partition Taint.leaf ByFilter ~f:(fun candidate ->
-           if Taint.equal_leaf leaf candidate then Some true else None)
+    |> Taint.partition Taint.kind ByFilter ~f:(fun candidate ->
+           if Taint.equal_kind kind candidate then Some true else None)
     |> (fun map -> Map.Poly.find map true)
     |> Option.value ~default:Taint.bottom
 
@@ -705,10 +705,10 @@ module MakeTaintEnvironment (Taint : TAINT_DOMAIN) () = struct
 
   let roots environment = fold Key ~f:List.cons ~init:[] environment
 
-  let extract_features_to_attach ~root ~attach_to_leaf taint =
+  let extract_features_to_attach ~root ~attach_to_kind taint =
     let gather_features to_add features = Features.SimpleSet.add_set features ~to_add in
     read ~root ~path:[] taint
-    |> Tree.transform Taint.leaf Filter ~f:(Taint.equal_leaf attach_to_leaf)
+    |> Tree.transform Taint.kind Filter ~f:(Taint.equal_kind attach_to_kind)
     |> Tree.collapse ~transform:Fn.id
     |> Taint.fold Taint.simple_feature_self ~f:gather_features ~init:Features.SimpleSet.bottom
 end
@@ -725,7 +725,7 @@ let local_return_taint =
   BackwardTaint.create
     [
       Part (BackwardTaint.trace_info, TraceInfo.Declaration { leaf_name_provided = false });
-      Part (BackwardTaint.leaf, Sinks.LocalReturn);
+      Part (BackwardTaint.kind, Sinks.LocalReturn);
       Part (TraceLength.Self, 0);
       Part (Features.ReturnAccessPathSet.Element, []);
       Part (Features.SimpleSet.Self, Features.SimpleSet.empty);

source/interprocedural_analyses/taint/features.ml

@@ -67,13 +67,13 @@ module LeafName = struct
 
   let show = Format.asprintf "%a" pp
 
-  let to_json ~leaf_kind_json { leaf; port } =
+  let to_json ~kind_json { leaf; port } =
     let port_assoc =
       match port with
       | Some port -> ["port", `String port]
       | None -> []
     in
-    `Assoc (port_assoc @ ["kind", leaf_kind_json; "name", `String leaf])
+    `Assoc (port_assoc @ ["kind", kind_json; "name", `String leaf])
 end
 
 module LeafNameSet = Abstract.SetDomain.Make (LeafName)