diff --git a/dhscanner-kbgen.cabal b/dhscanner-kbgen.cabal
--- a/dhscanner-kbgen.cabal
+++ b/dhscanner-kbgen.cabal
@@ -1,100 +1,100 @@
-cabal-version:      3.12
-name:               dhscanner-kbgen
-category:           parsing
-synopsis:           knowledge base predicates for static code analysis
-description:
-
-    * The [knowledge base](https://en.wikipedia.org/wiki/Knowledge_representation_and_reasoning) ( kb )
-      aims to be a data structure able to:
-
-        * represent /multiple/ facts about the source code repo
-        * from /various/ programming languages
-        * each fact can be translated to a [Prolog](https://en.wikipedia.org/wiki/Prolog) fact
-        * facts can be combined to create [predicates](https://en.wikipedia.org/wiki/Predicate_%28logic%29)
-        * predictaes can be combined to formulate /security queries/
-
-    * [Prolog](https://en.wikipedia.org/wiki/Prolog) facts describe relations between:
-
-        * code locations
-        * const strings
-        * const integers
-
-    * [Prolog](https://en.wikipedia.org/wiki/Prolog) facts can be /combined/:
-
-        * create /expressive/ queries from /simple/ facts
-        * [conjunction](https://en.wikipedia.org/wiki/Logical_conjunction)
-        * [disjunction](https://en.wikipedia.org/wiki/Logical_disjunction)
-        * [negation](https://en.wikipedia.org/wiki/Negation)
-
-    * [Prolog](https://en.wikipedia.org/wiki/Prolog) queries are /easy/ to write:
-
-        * you /don't/ have to be a Prolog expert
-        * copy-paste the basic facts to /any/ [LLM](https://en.wikipedia.org/wiki/Large_language_model)
-        * explain in plain English your query's purpose
-        * et voilà !
-
-version:            2.4.0
-license:            GPL-3.0-only
-license-file:       LICENSE
-author:             OrenGitHub
-maintainer:         Oren Ish Shalom
-copyright:          (c) 2025 Oren Ish Shalom
-homepage:           https://github.com/OrenGitHub/dhscanner
-stability:          experimental
-build-type:         Simple
-
-common ghc_options
-
-    ghc-options: -Wall -Werror=incomplete-patterns -O2
-
-library
-
-    import:
-        ghc_options
-
-    exposed-modules:
-        Kbgen
-
-    build-depends:
-        aeson >= 2.2 && < 2.4,
-        attoparsec >= 0.14 && < 0.15,
-        filepath >= 1.4 && < 1.6,
-        base >= 4.22 && < 4.23,
-        containers >= 0.8 && < 0.9,
-        text >= 2.0 && < 2.2,
-        dhscanner-ast >= 1.6.0,
-        dhscanner-bitcode >= 2.4.0
-
-    hs-source-dirs:
-        src
-
-    default-language:
-        GHC2024
-
-test-suite restoreloc
-
-    import:
-        ghc_options
-
-    type:
-        exitcode-stdio-1.0
-
-    hs-source-dirs:
-        test
-
-    main-is:
-        Test.hs
-
-    other-modules:
-        SmokeTests
-
-    build-depends:
-        base,
-        dhscanner-kbgen,
-        dhscanner-ast,
-        dhscanner-bitcode,
-        hspec,
-        QuickCheck
-
-    default-language:
-        GHC2024
+cabal-version:      3.12
+name:               dhscanner-kbgen
+category:           parsing
+synopsis:           knowledge base predicates for static code analysis
+description:
+
+    * The [knowledge base](https://en.wikipedia.org/wiki/Knowledge_representation_and_reasoning) ( kb )
+      aims to be a data structure able to:
+
+        * represent /multiple/ facts about the source code repo
+        * from /various/ programming languages
+        * each fact can be translated to a [Prolog](https://en.wikipedia.org/wiki/Prolog) fact
+        * facts can be combined to create [predicates](https://en.wikipedia.org/wiki/Predicate_%28logic%29)
+        * predictaes can be combined to formulate /security queries/
+
+    * [Prolog](https://en.wikipedia.org/wiki/Prolog) facts describe relations between:
+
+        * code locations
+        * const strings
+        * const integers
+
+    * [Prolog](https://en.wikipedia.org/wiki/Prolog) facts can be /combined/:
+
+        * create /expressive/ queries from /simple/ facts
+        * [conjunction](https://en.wikipedia.org/wiki/Logical_conjunction)
+        * [disjunction](https://en.wikipedia.org/wiki/Logical_disjunction)
+        * [negation](https://en.wikipedia.org/wiki/Negation)
+
+    * [Prolog](https://en.wikipedia.org/wiki/Prolog) queries are /easy/ to write:
+
+        * you /don't/ have to be a Prolog expert
+        * copy-paste the basic facts to /any/ [LLM](https://en.wikipedia.org/wiki/Large_language_model)
+        * explain in plain English your query's purpose
+        * et voilà !
+
+version:            2.5.0
+license:            GPL-3.0-only
+license-file:       LICENSE
+author:             OrenGitHub
+maintainer:         Oren Ish Shalom
+copyright:          (c) 2025 Oren Ish Shalom
+homepage:           https://github.com/OrenGitHub/dhscanner
+stability:          experimental
+build-type:         Simple
+
+common ghc_options
+
+    ghc-options: -Wall -Werror=incomplete-patterns -O2
+
+library
+
+    import:
+        ghc_options
+
+    exposed-modules:
+        Kbgen
+
+    build-depends:
+        aeson >= 2.2 && < 2.4,
+        attoparsec >= 0.14 && < 0.15,
+        filepath >= 1.4 && < 1.6,
+        base >= 4.22 && < 4.23,
+        containers >= 0.8 && < 0.9,
+        text >= 2.0 && < 2.2,
+        dhscanner-ast >= 1.6.0,
+        dhscanner-bitcode >= 2.4.0
+
+    hs-source-dirs:
+        src
+
+    default-language:
+        GHC2024
+
+test-suite restoreloc
+
+    import:
+        ghc_options
+
+    type:
+        exitcode-stdio-1.0
+
+    hs-source-dirs:
+        test
+
+    main-is:
+        Test.hs
+
+    other-modules:
+        SmokeTests
+
+    build-depends:
+        base,
+        dhscanner-kbgen,
+        dhscanner-ast,
+        dhscanner-bitcode,
+        hspec,
+        QuickCheck
+
+    default-language:
+        GHC2024
diff --git a/src/Kbgen.hs b/src/Kbgen.hs
--- a/src/Kbgen.hs
+++ b/src/Kbgen.hs
@@ -1,1793 +1,1912 @@
--- |
---
--- * The [knowledge base](https://en.wikipedia.org/wiki/Knowledge_representation_and_reasoning) ( kb )
---   aims to be a data structure able to:
---
---     * represent /multiple/ facts about the source code repo
---     * from /various/ programming languages
---     * each fact can be translated to a [Prolog](https://en.wikipedia.org/wiki/Prolog) fact
---     * facts can be combined to create [predicates](https://en.wikipedia.org/wiki/Predicate_%28logic%29)
---     * [predicates](https://en.wikipedia.org/wiki/Predicate_%28logic%29) can be combined to formulate /security queries/
---
--- * Facts describe relations between:
---
---     * code locations
---     * const strings
---     * const integers
---
--- * Code locations are capable of representing /all/ program entities
---
---     * classes
---     * methods
---     * lambdas
---     * annotations
---     * arguments
---     * parameters
---     * etc.
---
--- * Facts can be /combined/:
---
---     * [conjunction](https://en.wikipedia.org/wiki/Logical_conjunction)
---     * [disjunction](https://en.wikipedia.org/wiki/Logical_disjunction)
---     * [negation](https://en.wikipedia.org/wiki/Negation)
---
--- * [Prolog](https://en.wikipedia.org/wiki/Prolog) queries are /easy/ to write:
---
---     * you /don't/ have to be a Prolog expert
---     * copy-paste the basic facts to /any/ [LLM](https://en.wikipedia.org/wiki/Large_language_model)
---     * explain in plain English your query's purpose
---     * et voilà !
---
--- * Its main purpose is to serve as the:
---
---     * penultimate step for /static code analysis/ 
---     * part of the [dhscanner](https://github.com/OrenGitHub/dhscanner.vps) framework
---
---         * [SAST](https://en.wikipedia.org/wiki/Static_application_security_testing) for security scans 🔒
---         * [PII](https://en.wikipedia.org/wiki/Personal_data) leaks detection 🪪
---
-
-{-# LANGUAGE DeriveGeneric #-}
-{-# LANGUAGE DeriveAnyClass #-}
-{-# LANGUAGE OverloadedStrings #-}
-
-module Kbgen (
-    KeywordArgForCall(..),
-    ParamResolvedType(..),
-    ClassDef(..),
-    FuncDef(..),
-    Call1stPartyFuncDefinedInDir(..),
-    AssignValueToToplevelVarName(..),
-    Call1stPartyFuncDefinedInFile(..),
-    ParamName(..),
-    CallMethodOfClass(..),
-    ConstString(..),
-    ConstInteger(..),
-    MethodOfClass(..),
-    MethodHasName(..),
-    ClassHas1stPartySuper(..),
-    ClassHas3rdPartySuper(..),
-    CallMethodOfUntypedNamedParam(..),
-    ArgiForCall(..),
-    DataflowEdge(..),
-    ConstBoolTrue(..),
-    ConstNull(..),
-    GatedReturn(..),
-    TopLevelIfThenElseGadget(..),
-    CallGuardedByCondInThenPart(..),
-    CallGuardedByCondInElsePart(..),
-    ThenPart(..),
-    ElsePart(..),
-    Comparison(..),
-    CallableReturnsValue(..),
-    CallableReturnsWithoutValue(..),
-    Cond(..),
-    Lhs(..),
-    Rhs(..),
-    ComparisonOp(..),
-    ReturnedValue(..),
-    ClassAnnotation(..),
-    CallableAnnotation(..),
-    ParamAnnotation(..),
-    Annotation(..),
-    CallableSourceBodyLength(..),
-    ParamiOfCallable(..),
-    prologify,
-    To(..),
-    Arg(..),
-    From(..),
-    Func(..),
-    Call(..),
-    Class(..),
-    Param(..),
-    Method(..),
-    Callable(..),
-    Keyword(..),
-    Resolved(..),
-    ArgIndex(..),
-    ParamIndex(..),
-    FuncName(..),
-    MethodName(..),
-    ResolvedType(..),
-    CallResolved(..),
-    FieldReadResolved(..),
-    FieldRead(..),
-    CalledFrom(..),
-    AssignedValue(..),
-    ResolvedSuper(..),
-    FuncDefinedInDir(..),
-    FuncDefinedInFile(..),
-    ClassDefinedInFile(..),
-    SuperDefinedInFile(..),
-    SuperQualifiedName(..),
-    ConstStr(..),
-    ConstInt(..),
-    Fact(..),
-    locationify,
-    restoreloc
-)
-
-where
-
--- general imports
-import Data.Aeson
-import Text.Printf
-import GHC.Generics (Generic)
-import System.FilePath (takeDirectory)
-import Data.Attoparsec.Text (Parser, char, decimal, parseOnly, string, takeText)
-import Data.Text (Text)
-import qualified Data.Text as T
-
--- general qualified imports
-import qualified Data.List as List
-
--- project imports
-import Location
-import qualified Token
-import qualified Fqn
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_keyword_arg_for_call( Keyword, Arg, Call ).
--- @
---
--- __When should I use this fact__ ( motivation: [CVE-2024-52803](https://nvd.nist.gov/vuln/detail/CVE-2024-52803) )
---
--- Code snippet ( Python ):
---
--- @
--- Popen(f'llamafactory-cli train {save_cmd(args)}', env=env, shell=True)
--- @
---
--- See complete source example: [here](https://github.com/hiyouga/LLaMA-Factory/commit/b3aa80d54a67da45e9e237e349486fb9c162b2ac)
---
--- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-52803](https://nvd.nist.gov/vuln/detail/CVE-2024-52803) )
---
--- @
--- subprocess_Popen_called_with_shell_eq_True( Call ) :-
---     kb_keyword_arg_for_call( \'shell\', TrueValue, Call ),
---     kb_call_resolved( Call, \'subprocess.Popen\' ),
---     kb_const_bool_true( TrueValue ).
--- @
---
--- Other facts combined in this example predicate:
---
---     * 'CallResolved'
---     * 'ConstBoolTrue'
---
-data KeywordArgForCall = KeywordArgForCall
-    Keyword -- ^
-    Arg -- ^
-    Call -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_param_has_resolved_type( Param, ResolvedType ).
--- @
---
--- __When should I use this fact__ ( motivation: [CVE-2024-49380](https://nvd.nist.gov/vuln/detail/CVE-2024-49380) )
---
--- Code snippet ( Golang ):
---
--- @
--- func postLocal(w http.ResponseWriter, r *http.Request) { ... }
--- @
---
--- See complete source example: [here](https://github.com/plentico/plenti/blob/01825e0dcd3505fac57adc2edf29f772d585c008/cmd/serve.go#L205)
---
--- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-49380](https://nvd.nist.gov/vuln/detail/CVE-2024-49380) )
---
--- @
--- looks_like_user_input( RequestParam ) :-
---     kb_param_has_resolved_type( RequestParam, \'net/http.Request\' ),
---     kb_param_has_resolved_type( ResponseParam, \'net/http.ResponseWriter\' ),
---     kb_param_i_of_callable( ResponseParam, 0, Handler ),
---     kb_param_i_of_callable( RequestParam, 1, Handler ).
--- @
---
--- Other facts combined in this predicate:
---
---     * 'ParamiOfCallable'
---
-data ParamResolvedType = ParamResolvedType
-    Param -- ^
-    ResolvedType -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_class_def( Class, Name, DefinedInFile ).
--- @
---
--- __When should I use this fact__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
---
--- @
--- # authentication.py
--- class LoginHandler(BaseHandler): ...
---
--- # index.py
--- from tornado.web import RequestHandler
--- class BaseHandler(RequestHandler): ...
--- @
---
--- See complete source example [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/authentication.py#L10),
--- [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L35)
--- and [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L15)
---
--- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
---
--- @
--- skip_level_subclass_of( Subclass, \'tornado.web.RequestHandler\' ) :-
---     kb_class_def( Subclass, _, _ ),
---     kb_class_has_1st_party_super( Subclass, ClassName, ClassDefinedInFile ),
---     kb_class_def( Class, ClassName, ClassDefinedInFile )
---     kb_class_has_3rd_party_super( Class, _, \'tornado.web.RequestHandler\' ).
--- @
---
--- Other facts combined in this predicate:
---
---     * 'ClassHas1stPartySuper'
---     * 'ClassHas3rdPartySuper'
---
-data ClassDef = ClassDef
-    Class -- ^
-    Token.ClassName -- ^
-    ClassDefinedInFile -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_func_def( Func, Name, DefinedInFile, DefinedInDir ).
--- @
---
--- __When should I use this fact__ ( motivation: [CVE-2024-29028](https://nvd.nist.gov/vuln/detail/CVE-2024-29028) )
---
--- @
--- # http_getter.go
--- g.GET("/get/httpmeta", func(c echo.Context) error {
---     urlStr := c.QueryParam("url")
---     ...
---     getter.GetHTMLMeta(urlStr)
---
--- # html_meta.go
--- func GetHTMLMeta(urlStr string) (*HTMLMeta, error) {
---     ...
---     http.Get(urlStr)
--- @
---
--- See complete source example [here](https://github.com/usememos/memos/blob/v0.14.0/api/v1/http_getter.go#L23),
--- and [here](https://github.com/usememos/memos/blob/v0.14.0/plugin/http-getter/html_meta.go#L24)
---
--- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-29028](https://nvd.nist.gov/vuln/detail/CVE-2024-29028) )
---
--- @
--- suspected_ssrf_sink( Func ) :-
---     kb_resolved_call( Call, \'net/http.Get\' ),
---     kb_arg_i_for_call( Arg, 0, Call ),
---     utils_dataflow_path( Param, Arg ),
---     kb_param_has_resolved_type( Param, \'string\' ),
---     kb_param_i_of_callable( Param, _, Func ),
---     kb_func_def( Func, Name, _, FuncDefinedInDir ),
---     kb_call_1st_party_func_defined_in_dir( _, Name, FuncDefinedInDir ).
--- @
---
--- Other facts combined in this predicate:
---
---     * 'CallResolved'
---     * 'ArgiForCall'
---     * 'ParamResolvedType'
---     * 'ParamiOfCallable'
---     * 'Call1stPartyFuncDefinedInDir'
---
-data FuncDef = FuncDef
-    Func -- ^
-    Token.FuncName -- ^
-    FuncDefinedInFile -- ^
-    FuncDefinedInDir -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_call_1st_party_func_defined_in_dir( Call, Name, DefinedInDir ).
--- @
---
--- __When should I use this fact__ ( motivation: [CVE-2024-29028](https://nvd.nist.gov/vuln/detail/CVE-2024-29028) )
---
--- @
--- # http_getter.go
--- g.GET("/get/httpmeta", func(c echo.Context) error {
---     urlStr := c.QueryParam("url")
---     ...
---     getter.GetHTMLMeta(urlStr)
---
--- # html_meta.go
--- func GetHTMLMeta(urlStr string) (*HTMLMeta, error) {
---     ...
---     http.Get(urlStr)
--- @
---
--- See complete source example [here](https://github.com/usememos/memos/blob/v0.14.0/api/v1/http_getter.go#L23),
--- and [here](https://github.com/usememos/memos/blob/v0.14.0/plugin/http-getter/html_meta.go#L24)
---
--- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-29028](https://nvd.nist.gov/vuln/detail/CVE-2024-29028) )
---
--- @
--- suspected_ssrf_sink( Func ) :-
---     kb_resolved_call( Call, \'net/http.Get\' ),
---     kb_arg_i_for_call( Arg, 0, Call ),
---     utils_dataflow_path( Param, Arg ),
---     kb_param_has_resolved_type( Param, \'string\' ),
---     kb_param_i_of_callable( Param, _, Func ),
---     kb_func_def( Func, Name, _, FuncDefinedInDir ),
---     kb_call_1st_party_func_from_dir( _, Name, FuncDefinedInDir ).
--- @
---
--- Other facts combined in this predicate:
---
---     * 'CallResolved'
---     * 'ArgiForCall'
---     * 'ParamResolvedType'
---     * 'ParamiOfCallable'
---
-data Call1stPartyFuncDefinedInDir = Call1stPartyFuncDefinedInDir
-    Call -- ^
-    FuncName -- ^
-    FuncDefinedInDir -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
-data Call1stPartyFuncDefinedInFile = Call1stPartyFuncDefinedInFile
-    Call -- ^
-    FuncName -- ^
-    FuncDefinedInFile -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
-data AssignValueToToplevelVarName = AssignValueToToplevelVarName
-    AssignedValue -- ^
-    Token.VarName -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Description:__
---
--- Input parameter of some callable ( method, function, lambda ) has the specified name
---
--- __Prolog signature:__
---
--- @
--- kb_param_has_name( Param, Name ).
--- @
---
--- __Code Example ( Javascript ):__
---
--- Motivated by [GHSL-2023-203](https://github.com/advplyr/audiobookshelf/security/advisories/GHSA-mgj7-rfx8-vhpr#event-116560)
--- ( [source code](https://github.com/advplyr/audiobookshelf/blob/d7b2476473ef1934eedec41425837cddf2d4b13e/server/controllers/AuthorController.js#L66)
--- and see also [here](https://github.com/advplyr/audiobookshelf/blob/d7b2476473ef1934eedec41425837cddf2d4b13e/server/controllers/AuthorController.js#L74)
--- and [here](https://github.com/advplyr/audiobookshelf/blob/d7b2476473ef1934eedec41425837cddf2d4b13e/server/routers/ApiRouter.js#L201) )
---
--- @
--- // ApiRouter.js
--- const express = require(\'express\')
---
--- class ApiRouter {
---   constructor(Server) { this.router = express() }
---   init() { this.router.patch(\'\/authors\/:id', ... , AuthorController.update.bind(this)) }
---
--- // AuthorController.js
--- class AuthorController { async update(req, res) { ... } }
--- @
---
--- __Writing new predicates:__
---
--- Facts combined in this predicate:
---
---     * 'ParamName'
---     * 'ParamiOfCallable'
---
--- @
--- http_request_param_of_method( Param, Method ) :-
---     kb_param_name( Param, \'req\' ),
---     kb_param_name( SecondParam, \'res\' ),
---     kb_param_i_of_callable( Param, 0, Method ),
---     kb_param_i_of_callable( SecondParam, 1, Method ).
--- @
---
--- Facts combined in this predicate:
---
---     * 'ArgiForCall'
---     * 'ClassName'
---     * 'MethodName'
---
--- @
--- request_handler( Method ) :-
---     kb_resolved_call( Call, \'express.patch\' ),
---     kb_arg_i_for_call( RequestHandler, 2, Call ),
---     kb_resolved_part_i_call( RequestHandler, 0, ClassName ),
---     kb_resolved_part_i_call( RequestHandler, 1, MethodName ),
---     kb_method_of_class( Method, Class ),
---     kb_method_name( Method, MethodName ),
---     kb_class_name( Class, ClassName ).
--- @
---
---
-data ParamName = ParamName
-    Param -- ^
-    Token.ParamName -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_class_has_1st_party_super( Class, SuperName, SuperDefinedInFile ).
--- @
---
--- __When should I use this fact__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
---
--- @
--- # authentication.py
--- class LoginHandler(BaseHandler): ...
---
--- # index.py
--- from tornado.web import RequestHandler
--- class BaseHandler(RequestHandler): ...
--- @
---
--- See complete source example [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/authentication.py#L10),
--- [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L35)
--- and [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L15)
---
--- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
---
--- @
--- skip_level_subclass_of( Subclass, \'tornado.web.RequestHandler\' ) :-
---     kb_class_def( Subclass, _, _ ),
---     kb_class_has_1st_party_super( Subclass, ClassName, ClassDefinedInFile ),
---     kb_class_def( Class, ClassName, ClassDefinedInFile )
---     kb_class_has_3rd_party_super( Class, _, \'tornado.web.RequestHandler\' ).
--- @
---
--- Other facts combined in this predicate:
---
---     * 'ClassDef'
---     * 'ClassHas3rdPartySuper'
---
-data ClassHas1stPartySuper = ClassHas1stPartySuper
-    Class -- ^
-    Token.SuperName -- ^
-    SuperDefinedInFile -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_class_has_3rd_party_super( Class, SuperName, SuperQualifiedName ).
--- @
---
--- __When should I use this fact__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
---
--- @
--- # authentication.py
--- class LoginHandler(BaseHandler): ...
---
--- # index.py
--- from tornado.web import RequestHandler
--- class BaseHandler(RequestHandler): ...
--- @
---
--- See complete source example [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/authentication.py#L10),
--- [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L35)
--- and [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L15)
---
--- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
---
--- @
--- skip_level_subclass_of( Subclass, \'tornado.web.RequestHandler\' ) :-
---     kb_class_def( Subclass, _, _ ),
---     kb_class_has_1st_party_super( Subclass, ClassName, ClassDefinedInFile ),
---     kb_class_def( Class, ClassName, ClassDefinedInFile )
---     kb_class_has_3rd_party_super( Class, _, \'tornado.web.RequestHandler\' ).
--- @
---
--- Other facts combined in this predicate:
---
---     * 'ClassDef'
---     * 'ClassHas1stPartySuper'
---
-data ClassHas3rdPartySuper = ClassHas3rdPartySuper
-    Class -- ^
-    Token.SuperName -- ^
-    SuperQualifiedName -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_call_method_of_class( Call, Method, Class ).
--- @
---
--- __When should I use this fact__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
---
--- @
--- # index.py
--- from tornado.web import RequestHandler
--- class BaseHandler(RequestHandler): ...
---
--- # authentication.py
--- class LoginHandler(BaseHandler):
---     def post(self, ...):
---         n = self.get_query_argument("next", ...)
---         self.redirect(n or ...)
--- @
---
--- See complete source example [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/authentication.py#L10),
--- [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L35)
--- and [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L15)
---
--- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
---
--- @
--- user_controlled_query_argument( Call ) :-
---     kb_call_method_of_class( Call, \'get_query_argument\', Class ),
---     kb_class_has_3rd_party_super( Class, \'tornado.web.RequestHandler\'),
---     kb_arg_i_for_call( QueryParamName, 0, Call),
---     kb_const_string( QueryParamName, _ ).
--- @
---
--- Other facts combined in this predicate:
---
---     * 'ClassHas3rdPartySuper'
---     * 'ArgiForCall'
---     * 'ConstString'
---
-data CallMethodOfClass = CallMethodOfClass
-    Call -- ^
-    MethodName -- ^
-    Class -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_call_method_of_untyped_named_param( Param, ParamName, MethodName ).
--- @
---
--- __When should I use this fact__ ( motivation: [CVE-2024-47769](https://nvd.nist.gov/vuln/detail/CVE-2024-47769) )
---
--- @
--- // corePublicRouter.js
--- const express = require('express');
--- const router = express.Router();
---
--- router.route('...').get(function (req, res) {
---     const { ..., file } = req.params;
---     const fileName = file;
---     return res.sendFile(fileName, ...);
--- }
--- @
---
--- See complete source example [here](https://github.com/idurar/idurar-erp-crm/blob/d7b2215a17bb2b52acfdab8f1646685d13df9a00/backend/src/routes/coreRoutes/corePublicRouter.js#L8-L24),
---
--- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-47769](https://nvd.nist.gov/vuln/detail/CVE-2024-47769) )
---
--- @
--- arbitrary_file_read( Call ) :-
---     kb_call_resolved( Call, \'express.Router.route.get\'),
---     kb_call_method_of_untyped_named_param( Param, \'res\', \'sendFile\' ),
---     kb_arg_i_for_call( Lambda, 0, Call ),
---     kb_param_i_of_callable( Param, 1, Lambda ).
--- @
---
--- Other facts combined in this predicate:
---
---     * 'CallResolved'
---     * 'ArgiForCall'
---     * 'ParamiOfCallable'
---
-data CallMethodOfUntypedNamedParam = CallMethodOfUntypedNamedParam
-    Call -- ^
-    MethodName -- ^
-    Token.ParamName -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
--- capture inheritance from third party classes
-data ClassAnnotation = ClassAnnotation
-    Class -- ^
-    Annotation -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
-data CallableAnnotation = CallableAnnotation
-    Callable -- ^
-    Annotation -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- @
--- kb_param_has_annotation( Param, Annotation ).
--- @
---
--- __When should I use this fact__
---
--- In Spring, user input reaches a handler through annotated params :
---
--- @
--- \@GetMapping( "/items" )
--- public List\<Item\> items( \@RequestParam( name = "q" ) String q ) { ... }
--- @
---
--- __Writing a predicate with this fact and others__
---
--- @
--- spring_request_param( Param ) :-
---     kb_param_has_annotation( Param, Annotation ),
---     kb_call_resolved( Annotation, 'org.springframework.web.bind.annotation.RequestParam' ).
--- @
---
--- Like every annotation, it is lowered as a call at its own location,
--- so its fqn and args come from 'CallResolved' and 'KeywordArgForCall'.
-data ParamAnnotation = ParamAnnotation
-    Param -- ^
-    Annotation -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_callable_source_body_length( Callable, N ).
--- @
---
--- Number of source-level @[ Ast.Stmt ]@ statements in the callable's body,
--- as observed at codegen time (before any lowering to bitcode). Independent
--- of how many bitcode instructions the body lowered to.
---
--- Intended for query predicates that need a source-fidelity signal ( e.g.
--- \"this wrapper's source body is a single statement\" for HOC-unwrap ),
--- rather than trying to reconstruct that shape from flat SSA bitcode after
--- the fact.
---
--- Emitted for 'Method', 'Lambda' and 'Function' callables. Not emitted for
--- 'Script' \-- see 'Callable.numOriginalSourceInstructions'.
-data CallableSourceBodyLength = CallableSourceBodyLength
-    Callable -- ^
-    Word -- ^ number of source-level statements in the body
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
--- capture usage of inherited third party methods
-data MethodOfClass = MethodOfClass
-    Method -- ^
-    Class -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_method_has_name( Method, Name ).
--- @
---
--- __When should I use this fact__
---
--- @
--- \@RestController
--- public class OidcRestController {
---     \@RequestMapping( method = RequestMethod.GET )
---     public void oidc( ... ) { ... }
--- }
--- @
---
--- __Writing a predicate with this fact and others__
---
--- @
--- method_of_class_by_names( Method, MethodName, ClassName ) :-
---     kb_method_has_name( Method, MethodName ),
---     kb_method_of_class( Method, Class ),
---     kb_class_def( Class, ClassName, _ ).
--- @
---
--- Other facts combined in this example predicate:
---
---     * 'MethodOfClass'
---     * 'ClassDef'
---
-data MethodHasName = MethodHasName
-    Method -- ^
-    Token.MethodName -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_arg_i_for_call( Arg, Index, Call ).
--- @
---
--- __When should I use this fact__ ( motivation: [CVE-2024-47769](https://nvd.nist.gov/vuln/detail/CVE-2024-47769) )
---
--- @
--- // corePublicRouter.js
--- const express = require('express');
--- const router = express.Router();
---
--- router.route('...').get(function (req, res) {
---     const { ..., file } = req.params;
---     const fileName = file;
---     return res.sendFile(fileName, ...);
--- }
--- @
---
--- See complete source example [here](https://github.com/idurar/idurar-erp-crm/blob/d7b2215a17bb2b52acfdab8f1646685d13df9a00/backend/src/routes/coreRoutes/corePublicRouter.js#L8-L24),
---
--- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-47769](https://nvd.nist.gov/vuln/detail/CVE-2024-47769) )
---
--- @
--- arbitrary_file_read( Call ) :-
---     kb_call_resolved( Call, \'express.Router.route.get\'),
---     kb_call_method_of_untyped_named_param( Param, \'res\', \'sendFile\' ),
---     kb_arg_i_for_call( Lambda, 0, Call ),
---     kb_param_i_of_callable( Param, 1, Lambda ).
--- @
---
--- Other facts combined in this predicate:
---
---     * 'CallResolved'
---     * 'CallMethodOfUntypedNamedParam'
---     * 'ParamiOfCallable'
---
--- ==== __Tip 💡__
---
--- When the exact index is irrelevant, use:
---
--- @
--- kb_arg_i_for_call( Arg, _, Call ).
--- @
---
-data ArgiForCall = ArgiForCall
-    Arg -- ^
-    ArgIndex -- ^
-    Call -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_param_i_of_callable( Param, Index, Callable ).
--- @
---
--- __When should I use this fact__ ( motivation: [CVE-2024-29028](https://nvd.nist.gov/vuln/detail/CVE-2024-29028) )
---
--- @
--- # http_getter.go
--- g.GET("/get/httpmeta", func(c echo.Context) error {
---     urlStr := c.QueryParam("url")
---     ...
---     getter.GetHTMLMeta(urlStr)
---
--- # html_meta.go
--- func GetHTMLMeta(urlStr string) (*HTMLMeta, error) {
---     ...
---     http.Get(urlStr)
--- @
---
--- See complete source example [here](https://github.com/usememos/memos/blob/v0.14.0/api/v1/http_getter.go#L23),
--- and [here](https://github.com/usememos/memos/blob/v0.14.0/plugin/http-getter/html_meta.go#L24)
---
--- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-29028](https://nvd.nist.gov/vuln/detail/CVE-2024-29028) )
---
--- @
--- suspected_ssrf_sink( Func ) :-
---     kb_resolved_call( Call, \'net/http.Get\' ),
---     kb_arg_i_for_call( Arg, 0, Call ),
---     utils_dataflow_path( Param, Arg ),
---     kb_param_has_resolved_type( Param, \'string\' ),
---     kb_param_i_of_callable( Param, _, Func ),
---     kb_func_def( Func, Name, _, FuncDefinedInDir ),
---     kb_call_1st_party_func_defined_in_dir( _, Name, FuncDefinedInDir ).
--- @
---
--- Other facts combined in this predicate:
---
---     * 'CallResolved'
---     * 'ArgiForCall'
---     * 'ParamResolvedType'
---     * 'FuncDef'
---     * 'Call1stPartyFuncDefinedInDir'
---
--- ==== __Tip 💡__
---
--- When the _exact index_ is _irrelevant_, use:
---
--- @
--- kb_param_i_of_callable( Param, _, Callable ).
--- @
---
-data ParamiOfCallable = ParamiOfCallable
-    Param -- ^
-    ParamIndex -- ^ 0-based
-    Callable -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
-data CallResolved = CallResolved
-    Call -- ^
-    Resolved -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_field_read_resolved( FieldRead, Fqn ).
--- @
---
--- __When should I use this fact__
---
--- Reading a field of an imported name ( an enum constant, a static
--- field ) carries the resolved fqn of what was read :
---
--- @
--- import org.springframework.web.bind.annotation.RequestMethod;
---
--- \@RequestMapping( method = RequestMethod.GET )
--- public void oidc( ... ) { ... }
--- @
---
--- __Writing a predicate with this fact and others__
---
--- @
--- spring_request_mapping_get( Mapping ) :-
---     kb_keyword_arg_for_call( 'method', FieldRead, Mapping ),
---     kb_field_read_resolved( FieldRead, 'org.springframework.web.bind.annotation.RequestMethod.GET' ).
--- @
---
--- Other facts combined in this example predicate:
---
---     * 'KeywordArgForCall'
---
--- The @FieldRead@ slot is the location of the field read expression,
--- which is also where it shows up as an argument ( 'ArgiForCall',
--- 'KeywordArgForCall' ) or as a dataflow node ( 'DataflowEdge' ).
---
-data FieldReadResolved = FieldReadResolved
-    FieldRead -- ^
-    Resolved -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_called_from( Call, Callable ).
--- @
---
--- __When should I use this fact__
---
--- Web-app request handlers routinely /extract fields/ from the incoming
--- request \- headers, cookies, query parameters, body \- and the /name/
--- of the field is often the security-relevant piece ( e.g. the constant
--- string \'x-api-key\' says "this callable does API-key authentication" ).
--- To reason about /which/ callable extracts /which/ field, you need to
--- know that a particular call site lives inside the body of a particular
--- callable.
---
--- No pre-existing fact tied a 'Call' back to its enclosing 'Callable' \-
--- 'ParamiOfCallable' does the analogous thing for /parameters/ only.
--- Because 'CalledFrom' exposes the 'Call' /location/ ( not just its FQN ),
--- it composes with 'ArgiForCall' and 'ConstString' to also surface the
--- /arguments/ passed at that specific call site.
---
--- Code snippet ( Typescript, Next.js \- formbricks at v3.16.0 ):
---
--- @
--- export const authenticateRequest = async (request: Request) => {
---     const apiKey = request.headers.get(\"x-api-key\");
---     if (!apiKey) return null;
---     const apiKeyData = await getApiKeyWithPermissions(apiKey);
---     ...
--- };
--- @
---
--- See complete source example [here](https://github.com/formbricks/formbricks/blob/v3.16.0/apps/web/app/api/v1/auth.ts#L7-L36)
---
--- __Writing a predicate with this fact and others__
---
--- Compose 'CalledFrom' with 'ArgiForCall' and 'ConstString' to enumerate
--- the constant-string header names each callable extracts from the
--- incoming request:
---
--- @
--- extracts_request_header_named( Callable, HeaderName ) :-
---     kb_called_from( Call, Callable ),
---     kb_call_resolved( Call, \'Request.headers.get\' ),
---     kb_arg_i_for_call( HeaderConst, 0, Call ),
---     kb_const_string( HeaderConst, HeaderName ).
--- @
---
--- Applied to @authenticateRequest@ above, this yields
--- @extracts_request_header_named( authenticateRequest, \'x-api-key\' )@ \-
--- one of the six structural indicators for recognizing Shape-A
--- ( identity-carrier ) request authenticators.
---
--- Other facts combined in this predicate:
---
---     * 'CallResolved'
---     * 'ArgiForCall'
---     * 'ConstString'
---
-data CalledFrom = CalledFrom
-    Call -- ^
-    Callable -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
-
--- |
---
--- Usage:
---
--- @
--- kb_const_str( Param, Index, Callable ).
--- @
---
--- ==== __Tip 💡__
---
--- sometimes the exact index is irrelevant, see 'Arg_for_Call'
---
-data ConstString = ConstString
-    ConstStr -- ^
-    Token.ConstStr -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_const_int( Loc, Value ).
--- @
---
--- __When should I use this fact__
---
--- Any time a query needs to discriminate on the /value/ of a constant
--- integer literal appearing in source code, typically as an argument
--- to a function that carries semantic information in that integer.
--- The canonical example is the HTTP status code passed to a response
--- constructor:
---
--- @
--- return Response.json({ error: \"unauthorized\" }, { status: 401 });
--- @
---
--- Recognizing this shape ( a bad status code returned early from a
--- callable ) is used to identify authenticating functions.
---
--- __Writing a predicate with this fact and others__
---
--- @
--- utils_ts_response_json_with_status( Function, Code ) :-
---     kb_call_resolved( OuterCall, \'nodejs.Response.json\' ),
---     kb_arg_i_for_call( DictifyCall, 1, OuterCall ),
---     kb_arg_i_for_call( KvCall, _, DictifyCall ),
---     kb_arg_i_for_call( KeyLoc, 0, KvCall ),
---     kb_const_string( KeyLoc, \'status\' ),
---     kb_arg_i_for_call( ValueLoc, 1, KvCall ),
---     kb_const_int( ValueLoc, Code ),
---     kb_called_from( OuterCall, Function ).
--- @
---
--- Other facts combined in this example predicate:
---
---     * 'CallResolved'
---     * 'ArgiForCall'
---     * 'ConstString'
---     * 'CalledFrom'
---
-data ConstInteger = ConstInteger
-    ConstInt -- ^
-    Token.ConstInt -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_const_null( Loc ).
--- @
---
--- __When should I use this fact__
---
--- Returning early from a function with a null value has many uses cases related to security.
--- ( Python @None@ and Ruby @nil@ use this predicate as well )
---
--- __Writing a predicate with this fact and others__
---
--- @
--- kb_gated_return_null( Cond ) :-
---     kb_gated_return( Cond, ReturnedValue ),
---     kb_const_null( ReturnedValue ).
--- @
---
--- Other facts combined in this example predicate:
---
---     * 'GatedReturn'
---
-data ConstNull = ConstNull Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_gated_return( Cond, ReturnedValue ).
--- @
---
--- __When should I use this fact__
---
--- Authenticating functions reject invalid credentials with an early return
--- from a guarded @if@. This fact pinpoints that rejection gate.
---
--- __Writing a predicate with this fact and others__
---
--- @
--- utils_early_return_null_on_missing_request_header_value( Callable, KeyName ) :-
---     kb_called_from( Call, Callable ),
---     kb_call_resolved( Call, \'nodejs.Request.headers.get\' ),
---     kb_arg_i_for_call( KeyArg, 0, Call ),
---     kb_const_string( KeyArg, KeyName ),
---     utils_intra_dataflow_path( Call, Var, _ ),
---     kb_gated_return_null( Cond ),
---     utils_intra_dataflow_path( Var, Cond, _ ).
---
--- kb_gated_return_null( Cond ) :- kb_gated_return( Cond, RV ), kb_const_null( RV ).
--- @
---
--- Other facts combined in this example predicate:
---
---     * 'ConstNull'
---     * 'CallResolved'
---     * 'ArgiForCall'
---     * 'ConstString'
---     * 'CalledFrom'
---
-data GatedReturn = GatedReturn
-    Cond -- ^
-    ReturnedValue -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_top_level_if_then_else_gadget( Callable, Cond, ThenPart, ElsePart ).
--- @
---
--- __When should I use this fact__
---
--- Every @if@ statement with a non-empty else, sitting directly in the
--- callable\'s body ( not nested inside another @if@ ), fires this fact.
--- The bitcode keeps no locations for the then \/ else parts, so both
--- wrap the location of the condition, and render as
--- @then_part_startloc_...@ \/ @else_part_startloc_...@.
---
--- @
--- if (isValidRedirectUrl(redirectUrl)) {
---     response.sendRedirect(redirectUrl);
--- } else {
---     response.sendError(HttpServletResponse.SC_BAD_REQUEST);
--- }
--- @
---
--- __Writing a predicate with this fact and others__
---
--- @
--- sanitized_by_error_in_else_part( Callable, Call, Cond ) :-
---     kb_top_level_if_then_else_gadget( Callable, Cond, ThenPart, ElsePart ),
---     kb_call_guarded_by_cond_in_then_part( Call, Cond, ThenPart ),
---     kb_call_guarded_by_cond_in_else_part( ErrorCall, Cond, ElsePart ),
---     kb_call_resolved( ErrorCall, \'jakarta.servlet.http.HttpServletResponse.sendError\' ).
--- @
---
--- Other facts combined in this example predicate:
---
---     * 'CallGuardedByCondInThenPart'
---     * 'CallGuardedByCondInElsePart'
---     * 'CallResolved'
---
-data TopLevelIfThenElseGadget = TopLevelIfThenElseGadget
-    Callable -- ^
-    Cond -- ^
-    ThenPart -- ^
-    ElsePart -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_call_guarded_by_cond_in_then_part( Call, Cond, ThenPart ).
--- @
---
--- __When should I use this fact__
---
--- Every call in the then part of a 'TopLevelIfThenElseGadget' fires
--- this fact, including calls in @if@ statements nested inside it.
---
-data CallGuardedByCondInThenPart = CallGuardedByCondInThenPart
-    Call -- ^
-    Cond -- ^
-    ThenPart -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_call_guarded_by_cond_in_else_part( Call, Cond, ElsePart ).
--- @
---
--- __When should I use this fact__
---
--- Every call in the else part of a 'TopLevelIfThenElseGadget' fires
--- this fact, including calls in @if@ statements nested inside it.
---
-data CallGuardedByCondInElsePart = CallGuardedByCondInElsePart
-    Call -- ^
-    Cond -- ^
-    ElsePart -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_comparison( Cond, Lhs, Rhs, Op ).
--- @
---
--- __When should I use this fact__
---
--- Binary comparison instructions ( currently @==@ \/ @===@ mapped to
--- the Prolog atom @eq@, and @!=@ \/ @!==@ mapped to @neq@ ) fire this
--- fact. The @Cond@ slot is the location of the comparison\'s output
--- variable, which makes composing with 'GatedReturn' straightforward:
--- when the boolean condition of an @if@ that early-returns is itself a
--- comparison, both facts share the same location in the @Cond@ slot.
---
--- __Writing a predicate with this fact and others__
---
--- @
--- gated_return_on_comparison( Lhs, Rhs, Op, ReturnedValue ) :-
---     kb_gated_return( Cond, ReturnedValue ),
---     kb_comparison( Cond, Lhs, Rhs, Op ).
--- @
---
--- Other facts combined in this example predicate:
---
---     * 'GatedReturn'
---
-data Comparison = Comparison
-    Cond -- ^
-    Lhs -- ^
-    Rhs -- ^
-    ComparisonOp -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_callable_returns_value( Callable, ReturnedValue ).
--- @
---
--- __When should I use this fact__
---
--- Every explicit `return exp;` inside a callable's body fires this fact
--- once, keyed by the enclosing callable and the returned expression's
--- location. Downstream predicates like `kb_const_null` or
--- `kb_call_resolved` add semantic meaning to the value slot.
---
-data CallableReturnsValue = CallableReturnsValue
-    Callable -- ^
-    ReturnedValue -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_callable_returns_without_value( Callable, ReturnStmtLocation ).
--- @
---
--- __When should I use this fact__
---
--- User-written bare `return;` (no value expression) fires this fact once,
--- keyed by the enclosing callable and the location of the return
--- statement itself. Distinct fact from 'CallableReturnsValue' because
--- there is no value-expression location to anchor on; the return
--- statement location is used instead.
---
-data CallableReturnsWithoutValue = CallableReturnsWithoutValue
-    Callable -- ^
-    Location -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Name__
---
--- This is how the fact will look inside the Prolog file
---
--- @
--- kb_dataflow_edge( From, To ).
--- @
---
-data DataflowEdge = DataflowEdge
-    From -- ^
-    To -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
-data Arg = Arg Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data Call = Call Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data FieldRead = FieldRead Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data Param = Param Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data Class = Class Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
-data To = To Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data From = From Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data Func = Func Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data Method = Method Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data Callable = Callable Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data ConstStr = ConstStr Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data ConstInt = ConstInt Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data Annotation = Annotation Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data AssignedValue = AssignedValue Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data ConstBoolTrue = ConstBoolTrue Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data Cond = Cond Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data Lhs = Lhs Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data Rhs = Rhs Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data ComparisonOp = ComparisonOp String deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data ReturnedValue = ReturnedValue Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data ThenPart = ThenPart Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data ElsePart = ElsePart Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
-data Keyword = Keyword String deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data Resolved = Resolved Fqn.Fqn deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data ArgIndex = ArgIndex Word deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data ParamIndex = ParamIndex Word deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data FuncName = FuncName String deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data MethodName = MethodName String deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data ConstStrValue = ConstStrValue String deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data SuperQualifiedName = SuperQualifiedName Fqn.Fqn deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
-data FuncDefinedInDir = FuncDefinedInDir FilePath deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data FuncDefinedInFile = FuncDefinedInFile FilePath deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data ClassDefinedInFile = ClassDefinedInFile FilePath deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-data SuperDefinedInFile = SuperDefinedInFile FilePath deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
-data ResolvedType = ResolvedType
-    Fqn.Fqn -- ^
-    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
-data ResolvedSuper = ResolvedSuper Fqn.Fqn deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
--- * each fact is derived from a /single/ bitcode 'Bitcode.Instruction'
---
--- * often, a single bitcode instruction will yield /more/ than one fact
---
-data Fact
-   = FuncDefCtor FuncDef 
-   | ClassDefCtor ClassDef
-   | ParamNameCtor ParamName
-   | ArgiForCallCtor ArgiForCall
-   | ConstStringCtor ConstString
-   | ConstIntegerCtor ConstInteger
-   | DataflowEdgeCtor DataflowEdge
-   | CallResolvedCtor CallResolved
-   | FieldReadResolvedCtor FieldReadResolved
-   | CalledFromCtor CalledFrom
-   | ConstBoolTrueCtor ConstBoolTrue
-   | ConstNullCtor ConstNull
-   | GatedReturnCtor GatedReturn
-   | TopLevelIfThenElseGadgetCtor TopLevelIfThenElseGadget
-   | CallGuardedByCondInThenPartCtor CallGuardedByCondInThenPart
-   | CallGuardedByCondInElsePartCtor CallGuardedByCondInElsePart
-   | ComparisonCtor Comparison
-   | CallableReturnsValueCtor CallableReturnsValue
-   | CallableReturnsWithoutValueCtor CallableReturnsWithoutValue
-   | MethodOfClassCtor MethodOfClass
-   | MethodHasNameCtor MethodHasName
-   | ClassAnnotationCtor ClassAnnotation
-   | ParamiOfCallableCtor ParamiOfCallable
-   | KeywordArgForCallCtor KeywordArgForCall
-   | ParamResolvedTypeCtor ParamResolvedType
-   | CallMethodOfClassCtor CallMethodOfClass
-   | CallableAnnotationCtor CallableAnnotation
-   | ParamAnnotationCtor ParamAnnotation
-   | ClassHas1stPartySuperCtor ClassHas1stPartySuper
-   | ClassHas3rdPartySuperCtor ClassHas3rdPartySuper
-   | CallableSourceBodyLengthCtor CallableSourceBodyLength
-   | AssignValueToToplevelVarNameCtor AssignValueToToplevelVarName
-   | Call1stPartyFuncDefinedInDirCtor Call1stPartyFuncDefinedInDir
-   | Call1stPartyFuncDefinedInFileCtor Call1stPartyFuncDefinedInFile
-   | CallMethodOfUntypedNamedParamCtor CallMethodOfUntypedNamedParam
-   deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
-
--- |
--- Translate a code fact into a prolog fact
---
--- 'ParamName'
---
--- @
--- kb_param_has_name( Param, Name ).
--- @
---
-prologify :: Fact -> String
-prologify (FuncDefCtor content) = prologify_FuncDef content
-prologify (ClassDefCtor content) = prologify_ClassDef content
-prologify (ParamNameCtor content) = prologify_ParamName content
-prologify (ArgiForCallCtor content) = prologifyArgiForCall content
-prologify (ConstStringCtor content) = prologify_ConstString content
-prologify (ConstIntegerCtor content) = prologify_ConstInteger content
-prologify (DataflowEdgeCtor content) = prologify_DataflowEdge content
-prologify (CallResolvedCtor content) = prologify_CallResolved content
-prologify (FieldReadResolvedCtor content) = prologify_FieldReadResolved content
-prologify (CalledFromCtor content) = prologify_CalledFrom content
-prologify (ConstBoolTrueCtor content) = prologify_ConstBoolTrue content
-prologify (ConstNullCtor content) = prologify_ConstNull content
-prologify (GatedReturnCtor content) = prologify_GatedReturn content
-prologify (TopLevelIfThenElseGadgetCtor content) = prologify_TopLevelIfThenElseGadget content
-prologify (CallGuardedByCondInThenPartCtor content) = prologify_CallGuardedByCondInThenPart content
-prologify (CallGuardedByCondInElsePartCtor content) = prologify_CallGuardedByCondInElsePart content
-prologify (ComparisonCtor content) = prologify_Comparison content
-prologify (CallableReturnsValueCtor content) = prologify_CallableReturnsValue content
-prologify (CallableReturnsWithoutValueCtor content) = prologify_CallableReturnsWithoutValue content
-prologify (MethodOfClassCtor content) = prologify_MethodOfClass content
-prologify (MethodHasNameCtor content) = prologify_MethodHasName content
-prologify (ClassAnnotationCtor content) = prologify_ClassAnnotation content
-prologify (ParamiOfCallableCtor content) = prologify_ParamiOfCallable content
-prologify (ParamResolvedTypeCtor content) = prologify_ParamResolvedType content
-prologify (CallMethodOfClassCtor content) = prologify_CallMethodOfClass content
-prologify (KeywordArgForCallCtor content) = prologify_KeywordArgForCall content
-prologify (CallableAnnotationCtor content) = prologify_CallableAnnotation content
-prologify (ParamAnnotationCtor content) = prologify_ParamAnnotation content
-prologify (CallableSourceBodyLengthCtor content) = prologify_CallableSourceBodyLength content
-prologify (ClassHas1stPartySuperCtor content) = prologify_ClassHas1stPartySuper content
-prologify (ClassHas3rdPartySuperCtor content) = prologify_ClassHas3rdPartySuper content
-prologify (AssignValueToToplevelVarNameCtor content) = prologify_AssignValueToToplevelVarName content
-prologify (Call1stPartyFuncDefinedInDirCtor content) = prologify_Call1stPartyFuncDefinedInDir content
-prologify (Call1stPartyFuncDefinedInFileCtor content) = prologify_Call1stPartyFuncDefinedInFile content
-prologify (CallMethodOfUntypedNamedParamCtor content) = prologify_CallMethodOfUntypedNamedParam content
-
-prologify_ParamResolvedType' :: Location -> String -> String
-prologify_ParamResolvedType' l fqn = printf "kb_param_has_resolved_type( %s, \'%s\' )." (locationify l) fqn
-
-prologify_ParamResolvedType :: ParamResolvedType -> String
-prologify_ParamResolvedType (ParamResolvedType (Param loc) (ResolvedType fqn)) = prologify_ParamResolvedType' loc (prologifyFqn fqn)
-
-prologify_CallMethodOfClass' :: Location -> String -> Location -> String
-prologify_CallMethodOfClass' call method klass = printf "kb_call_method_of_class( %s, \'%s\', %s )." (locationify call) method (locationify klass)
-
-prologify_CallMethodOfClass :: CallMethodOfClass -> String
-prologify_CallMethodOfClass (CallMethodOfClass (Call loc) (MethodName m) (Class c)) = prologify_CallMethodOfClass' loc m c
-
-prologify_ParamName' :: Location -> String -> String
-prologify_ParamName' l name = printf "kb_param_has_name( %s, \'%s\' )." (locationify l) name
-
-prologify_ParamName :: ParamName -> String
-prologify_ParamName (ParamName (Param loc) (Token.ParamName (Token.Named name _))) = prologify_ParamName' loc name
-
-prologify_ClassDef' :: Location -> String -> FilePath -> String
-prologify_ClassDef' l name f = printf "kb_class_def( %s, \'%s\', \'%s\' )." (locationify l) name f
-
-prologify_ClassDef :: ClassDef -> String
-prologify_ClassDef (ClassDef (Class loc) (Token.ClassName (Token.Named name _)) (ClassDefinedInFile f)) = prologify_ClassDef' loc name f
-
-prologify_FuncDef' :: Location -> String -> FilePath -> FilePath -> String
-prologify_FuncDef' l name f d = printf "kb_func_def( %s, \'%s\', \'%s\', \'%s\' )." (locationify l) name f d
-
-prologify_FuncDef :: FuncDef -> String
-prologify_FuncDef (FuncDef (Func loc) (Token.FuncName (Token.Named name _)) (FuncDefinedInFile f) (FuncDefinedInDir d)) = prologify_FuncDef' loc name f d
-
--- | contents of a single-quoted prolog atom : backslashes and quotes
--- are escaped, so source strings like @\\[@ or @it's@ load verbatim
-quoted :: String -> String
-quoted = concatMap quoted'
-
-quoted' :: Char -> String
-quoted' '\\' = "\\\\"
-quoted' '\'' = "\\'"
-quoted' c = [c]
-
-prologify_ConstString' :: Location -> String -> String
-prologify_ConstString' l value = printf "kb_const_string( %s, \'%s\' )." (locationify l) (quoted value)
-
-prologify_ConstString :: ConstString -> String
-prologify_ConstString (ConstString (ConstStr loc) (Token.ConstStr value _)) = prologify_ConstString' loc value
-
-prologify_ConstInteger' :: Location -> Int -> String
-prologify_ConstInteger' l value = printf "kb_const_int( %s, %d )." (locationify l) value
-
-prologify_ConstInteger :: ConstInteger -> String
-prologify_ConstInteger (ConstInteger (ConstInt loc) (Token.ConstInt value _)) = prologify_ConstInteger' loc value
-
-prologify_CallResolved'' :: Location -> String -> Token.ClassName -> String
-prologify_CallResolved'' call m c = printf "kb_call_method_of_class( %s, %s, %s )." (locationify call) m (locationify (Token.getClassNameLocation c))
-
-prologify_CallResolved' :: Location -> Fqn.Fqn -> String
-prologify_CallResolved' call (Fqn.CallMethodOfClass _ m c) = prologify_CallResolved'' call m c 
-prologify_CallResolved' call fqn = printf "kb_call_resolved( %s, \'%s\' )." (locationify call) (prologifyFqn fqn)
-
-prologify_DataflowEdge :: DataflowEdge -> String
-prologify_DataflowEdge (DataflowEdge (From u) (To v)) = prologify_DataflowEdge' u v
-
-prologify_DataflowEdge' :: Location -> Location -> String
-prologify_DataflowEdge' u v = printf "kb_dataflow_edge( %s, %s )." (locationify u) (locationify v)
-
-prologify_CallResolved :: CallResolved -> String
-prologify_CallResolved (CallResolved (Call call) (Resolved fqn)) = prologify_CallResolved' call fqn
-
-prologify_FieldReadResolved' :: Location -> Fqn.Fqn -> String
-prologify_FieldReadResolved' r fqn = printf "kb_field_read_resolved( %s, '%s' )." (locationify r) (quoted (prologifyFqn fqn))
-
-prologify_FieldReadResolved :: FieldReadResolved -> String
-prologify_FieldReadResolved (FieldReadResolved (FieldRead r) (Resolved fqn)) = prologify_FieldReadResolved' r fqn
-
-prologify_ConstBoolTrue' :: Location -> String
-prologify_ConstBoolTrue' trueValue = printf "kb_class_name( %s, \'%s\' )." (locationify trueValue)
-
-prologify_ConstBoolTrue :: ConstBoolTrue -> String
-prologify_ConstBoolTrue (ConstBoolTrue trueValue) = prologify_ConstBoolTrue' trueValue
-
-prologify_ConstNull' :: Location -> String
-prologify_ConstNull' l = printf "kb_const_null( %s )." (locationify l)
-
-prologify_ConstNull :: ConstNull -> String
-prologify_ConstNull (ConstNull loc) = prologify_ConstNull' loc
-
-prologify_GatedReturn' :: Location -> Location -> String
-prologify_GatedReturn' c v = printf "kb_gated_return( %s, %s )." (locationify c) (locationify v)
-
-prologify_GatedReturn :: GatedReturn -> String
-prologify_GatedReturn (GatedReturn (Cond c) (ReturnedValue v)) = prologify_GatedReturn' c v
-
-thenPartify :: Location -> String
-thenPartify l = "then_part_" ++ locationify l
-
-elsePartify :: Location -> String
-elsePartify l = "else_part_" ++ locationify l
-
-prologify_TopLevelIfThenElseGadget' :: Location -> Location -> Location -> Location -> String
-prologify_TopLevelIfThenElseGadget' callable c t e = printf "kb_top_level_if_then_else_gadget( %s, %s, %s, %s )." (locationify callable) (locationify c) (thenPartify t) (elsePartify e)
-
-prologify_TopLevelIfThenElseGadget :: TopLevelIfThenElseGadget -> String
-prologify_TopLevelIfThenElseGadget (TopLevelIfThenElseGadget (Callable callable) (Cond c) (ThenPart t) (ElsePart e)) = prologify_TopLevelIfThenElseGadget' callable c t e
-
-prologify_CallGuardedByCondInThenPart' :: Location -> Location -> Location -> String
-prologify_CallGuardedByCondInThenPart' call c t = printf "kb_call_guarded_by_cond_in_then_part( %s, %s, %s )." (locationify call) (locationify c) (thenPartify t)
-
-prologify_CallGuardedByCondInThenPart :: CallGuardedByCondInThenPart -> String
-prologify_CallGuardedByCondInThenPart (CallGuardedByCondInThenPart (Call call) (Cond c) (ThenPart t)) = prologify_CallGuardedByCondInThenPart' call c t
-
-prologify_CallGuardedByCondInElsePart' :: Location -> Location -> Location -> String
-prologify_CallGuardedByCondInElsePart' call c e = printf "kb_call_guarded_by_cond_in_else_part( %s, %s, %s )." (locationify call) (locationify c) (elsePartify e)
-
-prologify_CallGuardedByCondInElsePart :: CallGuardedByCondInElsePart -> String
-prologify_CallGuardedByCondInElsePart (CallGuardedByCondInElsePart (Call call) (Cond c) (ElsePart e)) = prologify_CallGuardedByCondInElsePart' call c e
-
-prologify_Comparison' :: Location -> Location -> Location -> String -> String
-prologify_Comparison' c l r op = printf "kb_comparison( %s, %s, %s, %s )." (locationify c) (locationify l) (locationify r) op
-
-prologify_Comparison :: Comparison -> String
-prologify_Comparison (Comparison (Cond c) (Lhs l) (Rhs r) (ComparisonOp op)) = prologify_Comparison' c l r op
-
-prologify_CallableReturnsValue' :: Location -> Location -> String
-prologify_CallableReturnsValue' c v = printf "kb_callable_returns_value( %s, %s )." (locationify c) (locationify v)
-
-prologify_CallableReturnsValue :: CallableReturnsValue -> String
-prologify_CallableReturnsValue (CallableReturnsValue (Callable c) (ReturnedValue v)) = prologify_CallableReturnsValue' c v
-
-prologify_CallableReturnsWithoutValue' :: Location -> Location -> String
-prologify_CallableReturnsWithoutValue' c s = printf "kb_callable_returns_without_value( %s, %s )." (locationify c) (locationify s)
-
-prologify_CallableReturnsWithoutValue :: CallableReturnsWithoutValue -> String
-prologify_CallableReturnsWithoutValue (CallableReturnsWithoutValue (Callable c) s) = prologify_CallableReturnsWithoutValue' c s
-
-prologify_MethodOfClass' :: Location -> Location -> String
-prologify_MethodOfClass' m c = printf "kb_method_of_class( %s, %s )." (locationify m) (locationify c)
-
-prologify_MethodOfClass :: MethodOfClass -> String
-prologify_MethodOfClass (MethodOfClass (Method m) (Class c)) = prologify_MethodOfClass' m c
-
-prologify_MethodHasName' :: Location -> String -> String
-prologify_MethodHasName' m name = printf "kb_method_has_name( %s, \'%s\' )." (locationify m) name
-
-prologify_MethodHasName :: MethodHasName -> String
-prologify_MethodHasName (MethodHasName (Method m) (Token.MethodName (Token.Named name _))) = prologify_MethodHasName' m name
-
-prologify_ClassHas1stPartySuper' :: Location -> String -> FilePath -> String
-prologify_ClassHas1stPartySuper' c s f = printf "kb_class_has_1st_party_super( %s, \'%s\', \'%s\' )." (locationify c) s f
- 
-prologify_ClassHas1stPartySuper :: ClassHas1stPartySuper -> String
-prologify_ClassHas1stPartySuper (ClassHas1stPartySuper (Class c) (Token.SuperName (Token.Named s _)) (SuperDefinedInFile f)) = prologify_ClassHas1stPartySuper' c s f
-
-prologify_ClassHas3rdPartySuper' :: Location -> String -> Fqn.Fqn -> String
-prologify_ClassHas3rdPartySuper' c s f = printf "kb_class_has_3rd_party_super( %s, \'%s\', \'%s\' )." (locationify c) s (prologifyFqn f)
- 
-prologify_ClassHas3rdPartySuper :: ClassHas3rdPartySuper -> String
-prologify_ClassHas3rdPartySuper (ClassHas3rdPartySuper (Class c) (Token.SuperName (Token.Named s _)) (SuperQualifiedName f)) = prologify_ClassHas3rdPartySuper' c s f
-
-prologify_AssignValueToToplevelVarName :: AssignValueToToplevelVarName -> String
-prologify_AssignValueToToplevelVarName (AssignValueToToplevelVarName value varname) = prologify_AssignValueToToplevelVarName' value varname
-
-prologify_AssignValueToToplevelVarName' :: AssignedValue -> Token.VarName -> String
-prologify_AssignValueToToplevelVarName' (AssignedValue value) (Token.VarName (Token.Named varname l)) = prologify_AssignValueToToplevelVarName'' value varname (Location.filename l)
-
-prologify_AssignValueToToplevelVarName'' :: Location -> String -> FilePath -> String
-prologify_AssignValueToToplevelVarName'' value varname f = printf "kb_assign_value_to_toplevel_varname( %s, \'%s\', \'%s\', \'%s\')." (locationify value) varname f (takeDirectory f)
-
-prologify_Call1stPartyFuncDefinedInFile :: Call1stPartyFuncDefinedInFile -> String
-prologify_Call1stPartyFuncDefinedInFile (Call1stPartyFuncDefinedInFile call func f) = prologify_Call1stPartyFuncDefinedInFile' call func f
-
-prologify_Call1stPartyFuncDefinedInFile' :: Call -> FuncName -> FuncDefinedInFile -> String
-prologify_Call1stPartyFuncDefinedInFile' (Call call) (FuncName func) (FuncDefinedInFile f) = prologify_Call1stPartyFuncDefinedInFile'' call func f
-
-prologify_Call1stPartyFuncDefinedInFile'' :: Location -> String -> FilePath -> String
-prologify_Call1stPartyFuncDefinedInFile'' call func f = printf "kb_call_1st_party_func_defined_in_file( %s, \'%s\', \'%s\' )." (locationify call) func f
-
-prologify_Call1stPartyFuncDefinedInDir :: Call1stPartyFuncDefinedInDir -> String
-prologify_Call1stPartyFuncDefinedInDir (Call1stPartyFuncDefinedInDir call func d) = prologify_Call1stPartyFuncDefinedInDir' call func d
-
-prologify_Call1stPartyFuncDefinedInDir' :: Call -> FuncName -> FuncDefinedInDir -> String
-prologify_Call1stPartyFuncDefinedInDir' (Call call) (FuncName f) (FuncDefinedInDir d) = prologify_Call1stPartyFuncDefinedInDir'' call f d
-
-prologify_Call1stPartyFuncDefinedInDir'' :: Location -> String -> FilePath -> String
-prologify_Call1stPartyFuncDefinedInDir'' call f d = printf "kb_call_1st_party_func_defined_in_dir( %s, \'%s\', \'%s\' )." (locationify call) f d
-
-prologify_CallMethodOfUntypedNamedParam :: CallMethodOfUntypedNamedParam -> String
-prologify_CallMethodOfUntypedNamedParam (CallMethodOfUntypedNamedParam call method p) = prologify_CallMethodOfUntypedNamedParam' call method p
-
-prologify_CallMethodOfUntypedNamedParam' :: Call -> MethodName -> Token.ParamName -> String
-prologify_CallMethodOfUntypedNamedParam' (Call call) (MethodName m) (Token.ParamName (Token.Named _ p)) = prologify_CallMethodOfUntypedNamedParam'' call m p
-
-prologify_CallMethodOfUntypedNamedParam'' :: Location -> String -> Location -> String
-prologify_CallMethodOfUntypedNamedParam'' call m p = printf "kb_call_method_of_untyped_named_param( %s, \'%s\', %s )." (locationify call) m (locationify p)
-
-prologifyArgiForCall' :: Location -> Word -> Location -> String
-prologifyArgiForCall' a i c = printf "kb_arg_i_for_call( %s, %u, %s )." (locationify a) i (locationify c)
-
-prologifyArgiForCall :: ArgiForCall -> String
-prologifyArgiForCall (ArgiForCall (Arg a) (ArgIndex i) (Call c)) = prologifyArgiForCall' a i c
-
-prologify_ClassAnnotation' :: Location -> Location -> String
-prologify_ClassAnnotation' c a = printf "kb_class_has_annotation( %s, %s )." (locationify c) (locationify a)
-
-prologify_ClassAnnotation :: ClassAnnotation -> String
-prologify_ClassAnnotation (ClassAnnotation (Class c) (Annotation a)) = prologify_ClassAnnotation' c a
-
-prologify_KeywordArgForCall' ::  String -> Location -> Location -> String
-prologify_KeywordArgForCall' kw a c = printf "kb_keyword_arg_for_call( \'%s\', %s, %s )." (quoted kw) (locationify a) (locationify c)
-
-prologify_KeywordArgForCall :: KeywordArgForCall -> String
-prologify_KeywordArgForCall (KeywordArgForCall (Keyword kw) (Arg a) (Call c)) = prologify_KeywordArgForCall' kw a c
-
-prologify_CallableAnnotation' :: Location -> Location -> String
-prologify_CallableAnnotation' c a = printf "kb_callable_has_annotation( %s, %s )." (locationify c) (locationify a)
-
-prologify_CallableAnnotation :: CallableAnnotation -> String
-prologify_CallableAnnotation (CallableAnnotation (Callable c) (Annotation a)) = prologify_CallableAnnotation' c a
-
-prologify_ParamAnnotation' :: Location -> Location -> String
-prologify_ParamAnnotation' p a = printf "kb_param_has_annotation( %s, %s )." (locationify p) (locationify a)
-
-prologify_ParamAnnotation :: ParamAnnotation -> String
-prologify_ParamAnnotation (ParamAnnotation (Param p) (Annotation a)) = prologify_ParamAnnotation' p a
-
-prologify_CallableSourceBodyLength' :: Location -> Word -> String
-prologify_CallableSourceBodyLength' c n = printf "kb_callable_source_body_length( %s, %u )." (locationify c) n
-
-prologify_CallableSourceBodyLength :: CallableSourceBodyLength -> String
-prologify_CallableSourceBodyLength (CallableSourceBodyLength (Callable c) n) = prologify_CallableSourceBodyLength' c n
-
-prologify_ParamiOfCallable' :: Location -> Word -> Location -> String
-prologify_ParamiOfCallable' p i c = printf "kb_param_i_of_callable( %s, %u, %s )." (locationify p) i (locationify c)
-
-prologify_ParamiOfCallable :: ParamiOfCallable -> String
-prologify_ParamiOfCallable (ParamiOfCallable (Param p) (ParamIndex i) (Callable c)) = prologify_ParamiOfCallable' p i c
-
-prologify_CalledFrom' :: Location -> Location -> String
-prologify_CalledFrom' call callable = printf "kb_called_from( %s, %s )." (locationify call) (locationify callable)
-
-prologify_CalledFrom :: CalledFrom -> String
-prologify_CalledFrom (CalledFrom (Call call) (Callable callable)) = prologify_CalledFrom' call callable
-
-normalizeChar :: Char -> String
-normalizeChar '/' = "_slash_"
-normalizeChar '.' = "_dot_"
-normalizeChar '-' = "_dash_"
-normalizeChar '['  = "_lbrack_"
-normalizeChar ']'  = "_rbrack_"
-normalizeChar '('  = "_lparen_"
-normalizeChar ')'  = "_rparen_"
-normalizeChar c = [c]
-
-normalize :: FilePath -> FilePath
-normalize path = concatMap normalizeChar path
-
-prologifyFqn :: Fqn.Fqn -> String
-prologifyFqn (Fqn.ThirdPartyImport fqn) = prologifyThirdPartyImport fqn
-prologifyFqn (Fqn.FieldedAccess fqn fieldName) = prologifyFieldedAccess fqn fieldName
-prologifyFqn fqn = show fqn
-
-prologifyThirdPartyImport :: Fqn.ThirdPartyImportContent -> String
-prologifyThirdPartyImport (Fqn.ThirdPartyImportContent p [] Nothing _) = p
-prologifyThirdPartyImport (Fqn.ThirdPartyImportContent p [] (Just name) _) = p ++ "." ++ name
-prologifyThirdPartyImport (Fqn.ThirdPartyImportContent p rest Nothing _) = p ++ "." ++ List.intercalate "." rest
-prologifyThirdPartyImport (Fqn.ThirdPartyImportContent p rest (Just name) _) = p ++ "." ++ List.intercalate "." rest ++ "." ++ name
-
-prologifyFieldedAccess :: Fqn.Fqn -> Token.FieldName -> String
-prologifyFieldedAccess fqn (Token.FieldName (Token.Named fieldName _)) = (prologifyFqn fqn) ++ "." ++ fieldName
-
-locationify :: Location -> String
-locationify l = let
-    x = Location.lineStart l
-    y = Location.colStart l
-    z = Location.lineEnd l
-    w = Location.colEnd l
-    f = normalize (Location.filename l)
-    in printf "startloc_%u_%u_endloc_%u_%u_%s" x y z w f
-
-restoreloc :: String -> Maybe Location
-restoreloc s = case parseOnly locationParser (T.pack s) of { Right l -> Just l; _ -> Nothing; }
-
-locationParser :: Parser Location
-locationParser = do {
-
-    _ <- string "startloc_"; x <- decimal; _ <- char '_'; y <- decimal;
-    _ <- string "_endloc_" ; z <- decimal; _ <- char '_'; w <- decimal;
-    _ <- char '_'; fname <- takeText;
-
-    pure Location {
-        filename  = restoreFilename (T.unpack fname),
-        lineStart = x,
-        colStart = y,
-        lineEnd = z,
-        colEnd = w
-    }
-}
-
-data Rule = Rule { from :: Text, to :: Text }
-
-rules :: [ Rule ]
-rules =
-    [ Rule { from = "_slash_",  to = "/" }
-    , Rule { from = "_dot_",    to = "." }
-    , Rule { from = "_dash_",   to = "-" }
-    , Rule { from = "_lbrack_", to = "[" }
-    , Rule { from = "_rbrack_", to = "]" }
-    , Rule { from = "_lparen_", to = "(" }
-    , Rule { from = "_rparen_", to = ")" }
-    ]
-
-applyRule :: Rule -> Text -> Text
-applyRule Rule { from = f, to = t } = T.replace f t
-
-applyRuleStep :: Text -> Rule -> Text
-applyRuleStep acc r = applyRule r acc
-
-restore :: Text -> Text
-restore txt = List.foldl' applyRuleStep txt rules
-
-textToStringAdapter :: (Text -> Text) -> String -> String
-textToStringAdapter f = T.unpack . f . T.pack
-
-restoreFilename :: String -> String
+-- |
+--
+-- * The [knowledge base](https://en.wikipedia.org/wiki/Knowledge_representation_and_reasoning) ( kb )
+--   aims to be a data structure able to:
+--
+--     * represent /multiple/ facts about the source code repo
+--     * from /various/ programming languages
+--     * each fact can be translated to a [Prolog](https://en.wikipedia.org/wiki/Prolog) fact
+--     * facts can be combined to create [predicates](https://en.wikipedia.org/wiki/Predicate_%28logic%29)
+--     * [predicates](https://en.wikipedia.org/wiki/Predicate_%28logic%29) can be combined to formulate /security queries/
+--
+-- * Facts describe relations between:
+--
+--     * code locations
+--     * const strings
+--     * const integers
+--
+-- * Code locations are capable of representing /all/ program entities
+--
+--     * classes
+--     * methods
+--     * lambdas
+--     * annotations
+--     * arguments
+--     * parameters
+--     * etc.
+--
+-- * Facts can be /combined/:
+--
+--     * [conjunction](https://en.wikipedia.org/wiki/Logical_conjunction)
+--     * [disjunction](https://en.wikipedia.org/wiki/Logical_disjunction)
+--     * [negation](https://en.wikipedia.org/wiki/Negation)
+--
+-- * [Prolog](https://en.wikipedia.org/wiki/Prolog) queries are /easy/ to write:
+--
+--     * you /don't/ have to be a Prolog expert
+--     * copy-paste the basic facts to /any/ [LLM](https://en.wikipedia.org/wiki/Large_language_model)
+--     * explain in plain English your query's purpose
+--     * et voilà !
+--
+-- * Its main purpose is to serve as the:
+--
+--     * penultimate step for /static code analysis/ 
+--     * part of the [dhscanner](https://github.com/OrenGitHub/dhscanner.vps) framework
+--
+--         * [SAST](https://en.wikipedia.org/wiki/Static_application_security_testing) for security scans 🔒
+--         * [PII](https://en.wikipedia.org/wiki/Personal_data) leaks detection 🪪
+--
+
+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE DeriveAnyClass #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+module Kbgen (
+    KeywordArgForCall(..),
+    ParamResolvedType(..),
+    ClassDef(..),
+    FuncDef(..),
+    Call1stPartyFuncDefinedInDir(..),
+    AssignValueToToplevelVarName(..),
+    Call1stPartyFuncDefinedInFile(..),
+    CallMethodOf1stPartyImportedName(..),
+    ImportedName(..),
+    ImportedFromFile(..),
+    ParamName(..),
+    CallMethodOfClass(..),
+    ConstString(..),
+    ConstInteger(..),
+    MethodOfClass(..),
+    MethodHasName(..),
+    ClassHas1stPartySuper(..),
+    ClassHas3rdPartySuper(..),
+    CallMethodOfUntypedNamedParam(..),
+    ArgiForCall(..),
+    DataflowEdge(..),
+    ConstBoolTrue(..),
+    ConstNull(..),
+    GatedReturn(..),
+    TopLevelIfThenElseGadget(..),
+    CallGuardedByCondInThenPart(..),
+    CallGuardedByCondInElsePart(..),
+    ThenPart(..),
+    ElsePart(..),
+    Comparison(..),
+    CallableReturnsValue(..),
+    CallableReturnsWithoutValue(..),
+    Cond(..),
+    Lhs(..),
+    Rhs(..),
+    ComparisonOp(..),
+    ReturnedValue(..),
+    ClassAnnotation(..),
+    CallableAnnotation(..),
+    ParamAnnotation(..),
+    Annotation(..),
+    CallableSourceBodyLength(..),
+    ParamiOfCallable(..),
+    prologify,
+    To(..),
+    Arg(..),
+    From(..),
+    Func(..),
+    Call(..),
+    Class(..),
+    Param(..),
+    Method(..),
+    Callable(..),
+    Keyword(..),
+    Resolved(..),
+    ArgIndex(..),
+    ParamIndex(..),
+    FuncName(..),
+    MethodName(..),
+    ResolvedType(..),
+    CallResolved(..),
+    FieldReadResolved(..),
+    FieldRead(..),
+    CalledFrom(..),
+    AssignedValue(..),
+    ResolvedSuper(..),
+    FuncDefinedInDir(..),
+    FuncDefinedInFile(..),
+    ClassDefinedInFile(..),
+    SuperDefinedInFile(..),
+    SuperQualifiedName(..),
+    ConstStr(..),
+    ConstInt(..),
+    Fact(..),
+    locationify,
+    restoreloc,
+    prologifyFqn
+)
+
+where
+
+-- general imports
+import Data.Aeson
+import Text.Printf
+import GHC.Generics (Generic)
+import System.FilePath (takeDirectory)
+import Data.Attoparsec.Text (Parser, char, decimal, parseOnly, string, takeText)
+import Data.Text (Text)
+import qualified Data.Text as T
+
+-- general qualified imports
+import qualified Data.List as List
+
+-- project imports
+import Location
+import qualified Token
+import qualified Fqn
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_keyword_arg_for_call( Keyword, Arg, Call ).
+-- @
+--
+-- __When should I use this fact__ ( motivation: [CVE-2024-52803](https://nvd.nist.gov/vuln/detail/CVE-2024-52803) )
+--
+-- Code snippet ( Python ):
+--
+-- @
+-- Popen(f'llamafactory-cli train {save_cmd(args)}', env=env, shell=True)
+-- @
+--
+-- See complete source example: [here](https://github.com/hiyouga/LLaMA-Factory/commit/b3aa80d54a67da45e9e237e349486fb9c162b2ac)
+--
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-52803](https://nvd.nist.gov/vuln/detail/CVE-2024-52803) )
+--
+-- @
+-- subprocess_Popen_called_with_shell_eq_True( Call ) :-
+--     kb_keyword_arg_for_call( \'shell\', TrueValue, Call ),
+--     kb_call_resolved( Call, \'subprocess.Popen\' ),
+--     kb_const_bool_true( TrueValue ).
+-- @
+--
+-- Other facts combined in this example predicate:
+--
+--     * 'CallResolved'
+--     * 'ConstBoolTrue'
+--
+data KeywordArgForCall = KeywordArgForCall
+    Keyword -- ^
+    Arg -- ^
+    Call -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_param_has_resolved_type( Param, ResolvedType ).
+-- @
+--
+-- __When should I use this fact__ ( motivation: [CVE-2024-49380](https://nvd.nist.gov/vuln/detail/CVE-2024-49380) )
+--
+-- Code snippet ( Golang ):
+--
+-- @
+-- func postLocal(w http.ResponseWriter, r *http.Request) { ... }
+-- @
+--
+-- See complete source example: [here](https://github.com/plentico/plenti/blob/01825e0dcd3505fac57adc2edf29f772d585c008/cmd/serve.go#L205)
+--
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-49380](https://nvd.nist.gov/vuln/detail/CVE-2024-49380) )
+--
+-- @
+-- looks_like_user_input( RequestParam ) :-
+--     kb_param_has_resolved_type( RequestParam, \'net/http.Request\' ),
+--     kb_param_has_resolved_type( ResponseParam, \'net/http.ResponseWriter\' ),
+--     kb_param_i_of_callable( ResponseParam, 0, Handler ),
+--     kb_param_i_of_callable( RequestParam, 1, Handler ).
+-- @
+--
+-- Other facts combined in this predicate:
+--
+--     * 'ParamiOfCallable'
+--
+data ParamResolvedType = ParamResolvedType
+    Param -- ^
+    ResolvedType -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_class_def( Class, Name, DefinedInFile ).
+-- @
+--
+-- __When should I use this fact__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
+--
+-- @
+-- # authentication.py
+-- class LoginHandler(BaseHandler): ...
+--
+-- # index.py
+-- from tornado.web import RequestHandler
+-- class BaseHandler(RequestHandler): ...
+-- @
+--
+-- See complete source example [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/authentication.py#L10),
+-- [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L35)
+-- and [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L15)
+--
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
+--
+-- @
+-- skip_level_subclass_of( Subclass, \'tornado.web.RequestHandler\' ) :-
+--     kb_class_def( Subclass, _, _ ),
+--     kb_class_has_1st_party_super( Subclass, ClassName, ClassDefinedInFile ),
+--     kb_class_def( Class, ClassName, ClassDefinedInFile )
+--     kb_class_has_3rd_party_super( Class, _, \'tornado.web.RequestHandler\' ).
+-- @
+--
+-- Other facts combined in this predicate:
+--
+--     * 'ClassHas1stPartySuper'
+--     * 'ClassHas3rdPartySuper'
+--
+data ClassDef = ClassDef
+    Class -- ^
+    Token.ClassName -- ^
+    ClassDefinedInFile -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_func_def( Func, Name, DefinedInFile, DefinedInDir ).
+-- @
+--
+-- __When should I use this fact__ ( motivation: [CVE-2024-29028](https://nvd.nist.gov/vuln/detail/CVE-2024-29028) )
+--
+-- @
+-- # http_getter.go
+-- g.GET("/get/httpmeta", func(c echo.Context) error {
+--     urlStr := c.QueryParam("url")
+--     ...
+--     getter.GetHTMLMeta(urlStr)
+--
+-- # html_meta.go
+-- func GetHTMLMeta(urlStr string) (*HTMLMeta, error) {
+--     ...
+--     http.Get(urlStr)
+-- @
+--
+-- See complete source example [here](https://github.com/usememos/memos/blob/v0.14.0/api/v1/http_getter.go#L23),
+-- and [here](https://github.com/usememos/memos/blob/v0.14.0/plugin/http-getter/html_meta.go#L24)
+--
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-29028](https://nvd.nist.gov/vuln/detail/CVE-2024-29028) )
+--
+-- @
+-- suspected_ssrf_sink( Func ) :-
+--     kb_resolved_call( Call, \'net/http.Get\' ),
+--     kb_arg_i_for_call( Arg, 0, Call ),
+--     utils_dataflow_path( Param, Arg ),
+--     kb_param_has_resolved_type( Param, \'string\' ),
+--     kb_param_i_of_callable( Param, _, Func ),
+--     kb_func_def( Func, Name, _, FuncDefinedInDir ),
+--     kb_call_1st_party_func_defined_in_dir( _, Name, FuncDefinedInDir ).
+-- @
+--
+-- Other facts combined in this predicate:
+--
+--     * 'CallResolved'
+--     * 'ArgiForCall'
+--     * 'ParamResolvedType'
+--     * 'ParamiOfCallable'
+--     * 'Call1stPartyFuncDefinedInDir'
+--
+data FuncDef = FuncDef
+    Func -- ^
+    Token.FuncName -- ^
+    FuncDefinedInFile -- ^
+    FuncDefinedInDir -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_call_1st_party_func_defined_in_dir( Call, Name, DefinedInDir ).
+-- @
+--
+-- __When should I use this fact__ ( motivation: [CVE-2024-29028](https://nvd.nist.gov/vuln/detail/CVE-2024-29028) )
+--
+-- @
+-- # http_getter.go
+-- g.GET("/get/httpmeta", func(c echo.Context) error {
+--     urlStr := c.QueryParam("url")
+--     ...
+--     getter.GetHTMLMeta(urlStr)
+--
+-- # html_meta.go
+-- func GetHTMLMeta(urlStr string) (*HTMLMeta, error) {
+--     ...
+--     http.Get(urlStr)
+-- @
+--
+-- See complete source example [here](https://github.com/usememos/memos/blob/v0.14.0/api/v1/http_getter.go#L23),
+-- and [here](https://github.com/usememos/memos/blob/v0.14.0/plugin/http-getter/html_meta.go#L24)
+--
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-29028](https://nvd.nist.gov/vuln/detail/CVE-2024-29028) )
+--
+-- @
+-- suspected_ssrf_sink( Func ) :-
+--     kb_resolved_call( Call, \'net/http.Get\' ),
+--     kb_arg_i_for_call( Arg, 0, Call ),
+--     utils_dataflow_path( Param, Arg ),
+--     kb_param_has_resolved_type( Param, \'string\' ),
+--     kb_param_i_of_callable( Param, _, Func ),
+--     kb_func_def( Func, Name, _, FuncDefinedInDir ),
+--     kb_call_1st_party_func_from_dir( _, Name, FuncDefinedInDir ).
+-- @
+--
+-- Other facts combined in this predicate:
+--
+--     * 'CallResolved'
+--     * 'ArgiForCall'
+--     * 'ParamResolvedType'
+--     * 'ParamiOfCallable'
+--
+data Call1stPartyFuncDefinedInDir = Call1stPartyFuncDefinedInDir
+    Call -- ^
+    FuncName -- ^
+    FuncDefinedInDir -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+data Call1stPartyFuncDefinedInFile = Call1stPartyFuncDefinedInFile
+    Call -- ^
+    FuncName -- ^
+    FuncDefinedInFile -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_call_method_of_1st_party_imported_name( Call, Method, Name, File ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- A method called on a name imported from a 1st party file : a class,
+-- an object, a module level value. @Name@ is the imported name, @File@
+-- the file that defines it ( the same spelling as in 'ClassDef' and
+-- 'FuncDef' ).
+--
+-- @
+-- // util/PathUtil.java
+-- package org.example.util;
+-- public class PathUtil {
+--     public static File normalize( String path ) { ... }
+-- }
+--
+-- // web/Upload.java
+-- import org.example.util.PathUtil;
+-- ...
+-- PathUtil.normalize( base + "/" + name )
+-- @
+--
+-- @
+-- kb_call_method_of_1st_party_imported_name( Call, \'normalize\', \'PathUtil\', \'util/PathUtil.java\' ).
+-- @
+--
+-- Only one member deep : @Name.m( .. )@. A longer chain
+-- ( @Name.a.m( .. )@ ) and a call of the imported name itself are
+-- 'CallResolved' facts only.
+--
+-- __Writing a predicate with this fact and others__
+--
+-- @
+-- callgraph_1st_party_import_callee( Call, Callee ) :-
+--     kb_call_method_of_1st_party_imported_name( Call, Method, Name, File ),
+--     kb_class_def( Class, Name, File ),
+--     kb_method_of_class( Callee, Class ),
+--     kb_method_has_name( Callee, Method ).
+-- @
+--
+-- Other facts combined in this predicate:
+--
+--     * 'ClassDef'
+--     * 'MethodOfClass'
+--     * 'MethodHasName'
+--
+data CallMethodOf1stPartyImportedName = CallMethodOf1stPartyImportedName
+    Call -- ^
+    MethodName -- ^
+    ImportedName -- ^
+    ImportedFromFile -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+data AssignValueToToplevelVarName = AssignValueToToplevelVarName
+    AssignedValue -- ^
+    Token.VarName -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Description:__
+--
+-- Input parameter of some callable ( method, function, lambda ) has the specified name
+--
+-- __Prolog signature:__
+--
+-- @
+-- kb_param_has_name( Param, Name ).
+-- @
+--
+-- __Code Example ( Javascript ):__
+--
+-- Motivated by [GHSL-2023-203](https://github.com/advplyr/audiobookshelf/security/advisories/GHSA-mgj7-rfx8-vhpr#event-116560)
+-- ( [source code](https://github.com/advplyr/audiobookshelf/blob/d7b2476473ef1934eedec41425837cddf2d4b13e/server/controllers/AuthorController.js#L66)
+-- and see also [here](https://github.com/advplyr/audiobookshelf/blob/d7b2476473ef1934eedec41425837cddf2d4b13e/server/controllers/AuthorController.js#L74)
+-- and [here](https://github.com/advplyr/audiobookshelf/blob/d7b2476473ef1934eedec41425837cddf2d4b13e/server/routers/ApiRouter.js#L201) )
+--
+-- @
+-- // ApiRouter.js
+-- const express = require(\'express\')
+--
+-- class ApiRouter {
+--   constructor(Server) { this.router = express() }
+--   init() { this.router.patch(\'\/authors\/:id', ... , AuthorController.update.bind(this)) }
+--
+-- // AuthorController.js
+-- class AuthorController { async update(req, res) { ... } }
+-- @
+--
+-- __Writing new predicates:__
+--
+-- Facts combined in this predicate:
+--
+--     * 'ParamName'
+--     * 'ParamiOfCallable'
+--
+-- @
+-- http_request_param_of_method( Param, Method ) :-
+--     kb_param_name( Param, \'req\' ),
+--     kb_param_name( SecondParam, \'res\' ),
+--     kb_param_i_of_callable( Param, 0, Method ),
+--     kb_param_i_of_callable( SecondParam, 1, Method ).
+-- @
+--
+-- Facts combined in this predicate:
+--
+--     * 'ArgiForCall'
+--     * 'ClassName'
+--     * 'MethodName'
+--
+-- @
+-- request_handler( Method ) :-
+--     kb_resolved_call( Call, \'express.patch\' ),
+--     kb_arg_i_for_call( RequestHandler, 2, Call ),
+--     kb_resolved_part_i_call( RequestHandler, 0, ClassName ),
+--     kb_resolved_part_i_call( RequestHandler, 1, MethodName ),
+--     kb_method_of_class( Method, Class ),
+--     kb_method_name( Method, MethodName ),
+--     kb_class_name( Class, ClassName ).
+-- @
+--
+--
+data ParamName = ParamName
+    Param -- ^
+    Token.ParamName -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_class_has_1st_party_super( Class, SuperName, SuperDefinedInFile ).
+-- @
+--
+-- __When should I use this fact__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
+--
+-- @
+-- # authentication.py
+-- class LoginHandler(BaseHandler): ...
+--
+-- # index.py
+-- from tornado.web import RequestHandler
+-- class BaseHandler(RequestHandler): ...
+-- @
+--
+-- See complete source example [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/authentication.py#L10),
+-- [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L35)
+-- and [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L15)
+--
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
+--
+-- @
+-- skip_level_subclass_of( Subclass, \'tornado.web.RequestHandler\' ) :-
+--     kb_class_def( Subclass, _, _ ),
+--     kb_class_has_1st_party_super( Subclass, ClassName, ClassDefinedInFile ),
+--     kb_class_def( Class, ClassName, ClassDefinedInFile )
+--     kb_class_has_3rd_party_super( Class, _, \'tornado.web.RequestHandler\' ).
+-- @
+--
+-- Other facts combined in this predicate:
+--
+--     * 'ClassDef'
+--     * 'ClassHas3rdPartySuper'
+--
+data ClassHas1stPartySuper = ClassHas1stPartySuper
+    Class -- ^
+    Token.SuperName -- ^
+    SuperDefinedInFile -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_class_has_3rd_party_super( Class, SuperName, SuperQualifiedName ).
+-- @
+--
+-- __When should I use this fact__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
+--
+-- @
+-- # authentication.py
+-- class LoginHandler(BaseHandler): ...
+--
+-- # index.py
+-- from tornado.web import RequestHandler
+-- class BaseHandler(RequestHandler): ...
+-- @
+--
+-- See complete source example [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/authentication.py#L10),
+-- [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L35)
+-- and [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L15)
+--
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
+--
+-- @
+-- skip_level_subclass_of( Subclass, \'tornado.web.RequestHandler\' ) :-
+--     kb_class_def( Subclass, _, _ ),
+--     kb_class_has_1st_party_super( Subclass, ClassName, ClassDefinedInFile ),
+--     kb_class_def( Class, ClassName, ClassDefinedInFile )
+--     kb_class_has_3rd_party_super( Class, _, \'tornado.web.RequestHandler\' ).
+-- @
+--
+-- Other facts combined in this predicate:
+--
+--     * 'ClassDef'
+--     * 'ClassHas1stPartySuper'
+--
+data ClassHas3rdPartySuper = ClassHas3rdPartySuper
+    Class -- ^
+    Token.SuperName -- ^
+    SuperQualifiedName -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_call_method_of_class( Call, Method, Class ).
+-- @
+--
+-- __When should I use this fact__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
+--
+-- @
+-- # index.py
+-- from tornado.web import RequestHandler
+-- class BaseHandler(RequestHandler): ...
+--
+-- # authentication.py
+-- class LoginHandler(BaseHandler):
+--     def post(self, ...):
+--         n = self.get_query_argument("next", ...)
+--         self.redirect(n or ...)
+-- @
+--
+-- See complete source example [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/authentication.py#L10),
+-- [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L35)
+-- and [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L15)
+--
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
+--
+-- @
+-- user_controlled_query_argument( Call ) :-
+--     kb_call_method_of_class( Call, \'get_query_argument\', Class ),
+--     kb_class_has_3rd_party_super( Class, \'tornado.web.RequestHandler\'),
+--     kb_arg_i_for_call( QueryParamName, 0, Call),
+--     kb_const_string( QueryParamName, _ ).
+-- @
+--
+-- Other facts combined in this predicate:
+--
+--     * 'ClassHas3rdPartySuper'
+--     * 'ArgiForCall'
+--     * 'ConstString'
+--
+data CallMethodOfClass = CallMethodOfClass
+    Call -- ^
+    MethodName -- ^
+    Class -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_call_method_of_untyped_named_param( Param, ParamName, MethodName ).
+-- @
+--
+-- __When should I use this fact__ ( motivation: [CVE-2024-47769](https://nvd.nist.gov/vuln/detail/CVE-2024-47769) )
+--
+-- @
+-- // corePublicRouter.js
+-- const express = require('express');
+-- const router = express.Router();
+--
+-- router.route('...').get(function (req, res) {
+--     const { ..., file } = req.params;
+--     const fileName = file;
+--     return res.sendFile(fileName, ...);
+-- }
+-- @
+--
+-- See complete source example [here](https://github.com/idurar/idurar-erp-crm/blob/d7b2215a17bb2b52acfdab8f1646685d13df9a00/backend/src/routes/coreRoutes/corePublicRouter.js#L8-L24),
+--
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-47769](https://nvd.nist.gov/vuln/detail/CVE-2024-47769) )
+--
+-- @
+-- arbitrary_file_read( Call ) :-
+--     kb_call_resolved( Call, \'express.Router.route.get\'),
+--     kb_call_method_of_untyped_named_param( Param, \'res\', \'sendFile\' ),
+--     kb_arg_i_for_call( Lambda, 0, Call ),
+--     kb_param_i_of_callable( Param, 1, Lambda ).
+-- @
+--
+-- Other facts combined in this predicate:
+--
+--     * 'CallResolved'
+--     * 'ArgiForCall'
+--     * 'ParamiOfCallable'
+--
+data CallMethodOfUntypedNamedParam = CallMethodOfUntypedNamedParam
+    Call -- ^
+    MethodName -- ^
+    Token.ParamName -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+-- capture inheritance from third party classes
+data ClassAnnotation = ClassAnnotation
+    Class -- ^
+    Annotation -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+data CallableAnnotation = CallableAnnotation
+    Callable -- ^
+    Annotation -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- @
+-- kb_param_has_annotation( Param, Annotation ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- In Spring, user input reaches a handler through annotated params :
+--
+-- @
+-- \@GetMapping( "/items" )
+-- public List\<Item\> items( \@RequestParam( name = "q" ) String q ) { ... }
+-- @
+--
+-- __Writing a predicate with this fact and others__
+--
+-- @
+-- spring_request_param( Param ) :-
+--     kb_param_has_annotation( Param, Annotation ),
+--     kb_call_resolved( Annotation, 'org.springframework.web.bind.annotation.RequestParam' ).
+-- @
+--
+-- Like every annotation, it is lowered as a call at its own location,
+-- so its fqn and args come from 'CallResolved' and 'KeywordArgForCall'.
+data ParamAnnotation = ParamAnnotation
+    Param -- ^
+    Annotation -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_callable_source_body_length( Callable, N ).
+-- @
+--
+-- Number of source-level @[ Ast.Stmt ]@ statements in the callable's body,
+-- as observed at codegen time (before any lowering to bitcode). Independent
+-- of how many bitcode instructions the body lowered to.
+--
+-- Intended for query predicates that need a source-fidelity signal ( e.g.
+-- \"this wrapper's source body is a single statement\" for HOC-unwrap ),
+-- rather than trying to reconstruct that shape from flat SSA bitcode after
+-- the fact.
+--
+-- Emitted for 'Method', 'Lambda' and 'Function' callables. Not emitted for
+-- 'Script' \-- see 'Callable.numOriginalSourceInstructions'.
+data CallableSourceBodyLength = CallableSourceBodyLength
+    Callable -- ^
+    Word -- ^ number of source-level statements in the body
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+-- capture usage of inherited third party methods
+data MethodOfClass = MethodOfClass
+    Method -- ^
+    Class -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_method_has_name( Method, Name ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- @
+-- \@RestController
+-- public class OidcRestController {
+--     \@RequestMapping( method = RequestMethod.GET )
+--     public void oidc( ... ) { ... }
+-- }
+-- @
+--
+-- __Writing a predicate with this fact and others__
+--
+-- @
+-- method_of_class_by_names( Method, MethodName, ClassName ) :-
+--     kb_method_has_name( Method, MethodName ),
+--     kb_method_of_class( Method, Class ),
+--     kb_class_def( Class, ClassName, _ ).
+-- @
+--
+-- Other facts combined in this example predicate:
+--
+--     * 'MethodOfClass'
+--     * 'ClassDef'
+--
+data MethodHasName = MethodHasName
+    Method -- ^
+    Token.MethodName -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_arg_i_for_call( Arg, Index, Call ).
+-- @
+--
+-- __When should I use this fact__ ( motivation: [CVE-2024-47769](https://nvd.nist.gov/vuln/detail/CVE-2024-47769) )
+--
+-- @
+-- // corePublicRouter.js
+-- const express = require('express');
+-- const router = express.Router();
+--
+-- router.route('...').get(function (req, res) {
+--     const { ..., file } = req.params;
+--     const fileName = file;
+--     return res.sendFile(fileName, ...);
+-- }
+-- @
+--
+-- See complete source example [here](https://github.com/idurar/idurar-erp-crm/blob/d7b2215a17bb2b52acfdab8f1646685d13df9a00/backend/src/routes/coreRoutes/corePublicRouter.js#L8-L24),
+--
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-47769](https://nvd.nist.gov/vuln/detail/CVE-2024-47769) )
+--
+-- @
+-- arbitrary_file_read( Call ) :-
+--     kb_call_resolved( Call, \'express.Router.route.get\'),
+--     kb_call_method_of_untyped_named_param( Param, \'res\', \'sendFile\' ),
+--     kb_arg_i_for_call( Lambda, 0, Call ),
+--     kb_param_i_of_callable( Param, 1, Lambda ).
+-- @
+--
+-- Other facts combined in this predicate:
+--
+--     * 'CallResolved'
+--     * 'CallMethodOfUntypedNamedParam'
+--     * 'ParamiOfCallable'
+--
+-- ==== __Tip 💡__
+--
+-- When the exact index is irrelevant, use:
+--
+-- @
+-- kb_arg_i_for_call( Arg, _, Call ).
+-- @
+--
+data ArgiForCall = ArgiForCall
+    Arg -- ^
+    ArgIndex -- ^
+    Call -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_param_i_of_callable( Param, Index, Callable ).
+-- @
+--
+-- __When should I use this fact__ ( motivation: [CVE-2024-29028](https://nvd.nist.gov/vuln/detail/CVE-2024-29028) )
+--
+-- @
+-- # http_getter.go
+-- g.GET("/get/httpmeta", func(c echo.Context) error {
+--     urlStr := c.QueryParam("url")
+--     ...
+--     getter.GetHTMLMeta(urlStr)
+--
+-- # html_meta.go
+-- func GetHTMLMeta(urlStr string) (*HTMLMeta, error) {
+--     ...
+--     http.Get(urlStr)
+-- @
+--
+-- See complete source example [here](https://github.com/usememos/memos/blob/v0.14.0/api/v1/http_getter.go#L23),
+-- and [here](https://github.com/usememos/memos/blob/v0.14.0/plugin/http-getter/html_meta.go#L24)
+--
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-29028](https://nvd.nist.gov/vuln/detail/CVE-2024-29028) )
+--
+-- @
+-- suspected_ssrf_sink( Func ) :-
+--     kb_resolved_call( Call, \'net/http.Get\' ),
+--     kb_arg_i_for_call( Arg, 0, Call ),
+--     utils_dataflow_path( Param, Arg ),
+--     kb_param_has_resolved_type( Param, \'string\' ),
+--     kb_param_i_of_callable( Param, _, Func ),
+--     kb_func_def( Func, Name, _, FuncDefinedInDir ),
+--     kb_call_1st_party_func_defined_in_dir( _, Name, FuncDefinedInDir ).
+-- @
+--
+-- Other facts combined in this predicate:
+--
+--     * 'CallResolved'
+--     * 'ArgiForCall'
+--     * 'ParamResolvedType'
+--     * 'FuncDef'
+--     * 'Call1stPartyFuncDefinedInDir'
+--
+-- ==== __Tip 💡__
+--
+-- When the _exact index_ is _irrelevant_, use:
+--
+-- @
+-- kb_param_i_of_callable( Param, _, Callable ).
+-- @
+--
+data ParamiOfCallable = ParamiOfCallable
+    Param -- ^
+    ParamIndex -- ^ 0-based
+    Callable -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+data CallResolved = CallResolved
+    Call -- ^
+    Resolved -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_field_read_resolved( FieldRead, Fqn ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- Reading a field of an imported name ( an enum constant, a static
+-- field ) carries the resolved fqn of what was read :
+--
+-- @
+-- import org.springframework.web.bind.annotation.RequestMethod;
+--
+-- \@RequestMapping( method = RequestMethod.GET )
+-- public void oidc( ... ) { ... }
+-- @
+--
+-- __Writing a predicate with this fact and others__
+--
+-- @
+-- spring_request_mapping_get( Mapping ) :-
+--     kb_keyword_arg_for_call( 'method', FieldRead, Mapping ),
+--     kb_field_read_resolved( FieldRead, 'org.springframework.web.bind.annotation.RequestMethod.GET' ).
+-- @
+--
+-- Other facts combined in this example predicate:
+--
+--     * 'KeywordArgForCall'
+--
+-- The @FieldRead@ slot is the location of the field read expression,
+-- which is also where it shows up as an argument ( 'ArgiForCall',
+-- 'KeywordArgForCall' ) or as a dataflow node ( 'DataflowEdge' ).
+--
+data FieldReadResolved = FieldReadResolved
+    FieldRead -- ^
+    Resolved -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_called_from( Call, Callable ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- Web-app request handlers routinely /extract fields/ from the incoming
+-- request \- headers, cookies, query parameters, body \- and the /name/
+-- of the field is often the security-relevant piece ( e.g. the constant
+-- string \'x-api-key\' says "this callable does API-key authentication" ).
+-- To reason about /which/ callable extracts /which/ field, you need to
+-- know that a particular call site lives inside the body of a particular
+-- callable.
+--
+-- No pre-existing fact tied a 'Call' back to its enclosing 'Callable' \-
+-- 'ParamiOfCallable' does the analogous thing for /parameters/ only.
+-- Because 'CalledFrom' exposes the 'Call' /location/ ( not just its FQN ),
+-- it composes with 'ArgiForCall' and 'ConstString' to also surface the
+-- /arguments/ passed at that specific call site.
+--
+-- Code snippet ( Typescript, Next.js \- formbricks at v3.16.0 ):
+--
+-- @
+-- export const authenticateRequest = async (request: Request) => {
+--     const apiKey = request.headers.get(\"x-api-key\");
+--     if (!apiKey) return null;
+--     const apiKeyData = await getApiKeyWithPermissions(apiKey);
+--     ...
+-- };
+-- @
+--
+-- See complete source example [here](https://github.com/formbricks/formbricks/blob/v3.16.0/apps/web/app/api/v1/auth.ts#L7-L36)
+--
+-- __Writing a predicate with this fact and others__
+--
+-- Compose 'CalledFrom' with 'ArgiForCall' and 'ConstString' to enumerate
+-- the constant-string header names each callable extracts from the
+-- incoming request:
+--
+-- @
+-- extracts_request_header_named( Callable, HeaderName ) :-
+--     kb_called_from( Call, Callable ),
+--     kb_call_resolved( Call, \'Request.headers.get\' ),
+--     kb_arg_i_for_call( HeaderConst, 0, Call ),
+--     kb_const_string( HeaderConst, HeaderName ).
+-- @
+--
+-- Applied to @authenticateRequest@ above, this yields
+-- @extracts_request_header_named( authenticateRequest, \'x-api-key\' )@ \-
+-- one of the six structural indicators for recognizing Shape-A
+-- ( identity-carrier ) request authenticators.
+--
+-- Other facts combined in this predicate:
+--
+--     * 'CallResolved'
+--     * 'ArgiForCall'
+--     * 'ConstString'
+--
+data CalledFrom = CalledFrom
+    Call -- ^
+    Callable -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+
+-- |
+--
+-- Usage:
+--
+-- @
+-- kb_const_str( Param, Index, Callable ).
+-- @
+--
+-- ==== __Tip 💡__
+--
+-- sometimes the exact index is irrelevant, see 'Arg_for_Call'
+--
+data ConstString = ConstString
+    ConstStr -- ^
+    Token.ConstStr -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_const_int( Loc, Value ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- Any time a query needs to discriminate on the /value/ of a constant
+-- integer literal appearing in source code, typically as an argument
+-- to a function that carries semantic information in that integer.
+-- The canonical example is the HTTP status code passed to a response
+-- constructor:
+--
+-- @
+-- return Response.json({ error: \"unauthorized\" }, { status: 401 });
+-- @
+--
+-- Recognizing this shape ( a bad status code returned early from a
+-- callable ) is used to identify authenticating functions.
+--
+-- __Writing a predicate with this fact and others__
+--
+-- @
+-- utils_ts_response_json_with_status( Function, Code ) :-
+--     kb_call_resolved( OuterCall, \'nodejs.Response.json\' ),
+--     kb_arg_i_for_call( DictifyCall, 1, OuterCall ),
+--     kb_arg_i_for_call( KvCall, _, DictifyCall ),
+--     kb_arg_i_for_call( KeyLoc, 0, KvCall ),
+--     kb_const_string( KeyLoc, \'status\' ),
+--     kb_arg_i_for_call( ValueLoc, 1, KvCall ),
+--     kb_const_int( ValueLoc, Code ),
+--     kb_called_from( OuterCall, Function ).
+-- @
+--
+-- Other facts combined in this example predicate:
+--
+--     * 'CallResolved'
+--     * 'ArgiForCall'
+--     * 'ConstString'
+--     * 'CalledFrom'
+--
+data ConstInteger = ConstInteger
+    ConstInt -- ^
+    Token.ConstInt -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_const_null( Loc ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- Returning early from a function with a null value has many uses cases related to security.
+-- ( Python @None@ and Ruby @nil@ use this predicate as well )
+--
+-- __Writing a predicate with this fact and others__
+--
+-- @
+-- kb_gated_return_null( Cond ) :-
+--     kb_gated_return( Cond, ReturnedValue ),
+--     kb_const_null( ReturnedValue ).
+-- @
+--
+-- Other facts combined in this example predicate:
+--
+--     * 'GatedReturn'
+--
+data ConstNull = ConstNull Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_gated_return( Cond, ReturnedValue ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- Authenticating functions reject invalid credentials with an early return
+-- from a guarded @if@. This fact pinpoints that rejection gate.
+--
+-- __Writing a predicate with this fact and others__
+--
+-- @
+-- utils_early_return_null_on_missing_request_header_value( Callable, KeyName ) :-
+--     kb_called_from( Call, Callable ),
+--     kb_call_resolved( Call, \'nodejs.Request.headers.get\' ),
+--     kb_arg_i_for_call( KeyArg, 0, Call ),
+--     kb_const_string( KeyArg, KeyName ),
+--     utils_intra_dataflow_path( Call, Var, _ ),
+--     kb_gated_return_null( Cond ),
+--     utils_intra_dataflow_path( Var, Cond, _ ).
+--
+-- kb_gated_return_null( Cond ) :- kb_gated_return( Cond, RV ), kb_const_null( RV ).
+-- @
+--
+-- Other facts combined in this example predicate:
+--
+--     * 'ConstNull'
+--     * 'CallResolved'
+--     * 'ArgiForCall'
+--     * 'ConstString'
+--     * 'CalledFrom'
+--
+data GatedReturn = GatedReturn
+    Cond -- ^
+    ReturnedValue -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_top_level_if_then_else_gadget( Callable, Cond, ThenPart, ElsePart ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- Every @if@ statement with a non-empty else, sitting directly in the
+-- callable\'s body ( not nested inside another @if@ ), fires this fact.
+-- The bitcode keeps no locations for the then \/ else parts, so both
+-- wrap the location of the condition, and render as
+-- @then_part_startloc_...@ \/ @else_part_startloc_...@.
+--
+-- @
+-- if (isValidRedirectUrl(redirectUrl)) {
+--     response.sendRedirect(redirectUrl);
+-- } else {
+--     response.sendError(HttpServletResponse.SC_BAD_REQUEST);
+-- }
+-- @
+--
+-- __Writing a predicate with this fact and others__
+--
+-- @
+-- sanitized_by_error_in_else_part( Callable, Call, Cond ) :-
+--     kb_top_level_if_then_else_gadget( Callable, Cond, ThenPart, ElsePart ),
+--     kb_call_guarded_by_cond_in_then_part( Call, Cond, ThenPart ),
+--     kb_call_guarded_by_cond_in_else_part( ErrorCall, Cond, ElsePart ),
+--     kb_call_resolved( ErrorCall, \'jakarta.servlet.http.HttpServletResponse.sendError\' ).
+-- @
+--
+-- Other facts combined in this example predicate:
+--
+--     * 'CallGuardedByCondInThenPart'
+--     * 'CallGuardedByCondInElsePart'
+--     * 'CallResolved'
+--
+data TopLevelIfThenElseGadget = TopLevelIfThenElseGadget
+    Callable -- ^
+    Cond -- ^
+    ThenPart -- ^
+    ElsePart -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_call_guarded_by_cond_in_then_part( Call, Cond, ThenPart ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- Every call in the then part of a 'TopLevelIfThenElseGadget' fires
+-- this fact, including calls in @if@ statements nested inside it.
+--
+data CallGuardedByCondInThenPart = CallGuardedByCondInThenPart
+    Call -- ^
+    Cond -- ^
+    ThenPart -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_call_guarded_by_cond_in_else_part( Call, Cond, ElsePart ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- Every call in the else part of a 'TopLevelIfThenElseGadget' fires
+-- this fact, including calls in @if@ statements nested inside it.
+--
+data CallGuardedByCondInElsePart = CallGuardedByCondInElsePart
+    Call -- ^
+    Cond -- ^
+    ElsePart -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_comparison( Cond, Lhs, Rhs, Op ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- Binary comparison instructions ( currently @==@ \/ @===@ mapped to
+-- the Prolog atom @eq@, and @!=@ \/ @!==@ mapped to @neq@ ) fire this
+-- fact. The @Cond@ slot is the location of the comparison\'s output
+-- variable, which makes composing with 'GatedReturn' straightforward:
+-- when the boolean condition of an @if@ that early-returns is itself a
+-- comparison, both facts share the same location in the @Cond@ slot.
+--
+-- __Writing a predicate with this fact and others__
+--
+-- @
+-- gated_return_on_comparison( Lhs, Rhs, Op, ReturnedValue ) :-
+--     kb_gated_return( Cond, ReturnedValue ),
+--     kb_comparison( Cond, Lhs, Rhs, Op ).
+-- @
+--
+-- Other facts combined in this example predicate:
+--
+--     * 'GatedReturn'
+--
+data Comparison = Comparison
+    Cond -- ^
+    Lhs -- ^
+    Rhs -- ^
+    ComparisonOp -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_callable_returns_value( Callable, ReturnedValue ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- Every explicit `return exp;` inside a callable's body fires this fact
+-- once, keyed by the enclosing callable and the returned expression's
+-- location. Downstream predicates like `kb_const_null` or
+-- `kb_call_resolved` add semantic meaning to the value slot.
+--
+data CallableReturnsValue = CallableReturnsValue
+    Callable -- ^
+    ReturnedValue -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_callable_returns_without_value( Callable, ReturnStmtLocation ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- User-written bare `return;` (no value expression) fires this fact once,
+-- keyed by the enclosing callable and the location of the return
+-- statement itself. Distinct fact from 'CallableReturnsValue' because
+-- there is no value-expression location to anchor on; the return
+-- statement location is used instead.
+--
+data CallableReturnsWithoutValue = CallableReturnsWithoutValue
+    Callable -- ^
+    Location -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_dataflow_edge( From, To ).
+-- @
+--
+data DataflowEdge = DataflowEdge
+    From -- ^
+    To -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+data Arg = Arg Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data Call = Call Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data FieldRead = FieldRead Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data Param = Param Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data Class = Class Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+data To = To Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data From = From Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data Func = Func Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data Method = Method Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data Callable = Callable Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data ConstStr = ConstStr Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data ConstInt = ConstInt Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data Annotation = Annotation Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data AssignedValue = AssignedValue Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data ConstBoolTrue = ConstBoolTrue Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data Cond = Cond Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data Lhs = Lhs Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data Rhs = Rhs Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data ComparisonOp = ComparisonOp String deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data ReturnedValue = ReturnedValue Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data ThenPart = ThenPart Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data ElsePart = ElsePart Location deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+data Keyword = Keyword String deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data Resolved = Resolved Fqn.Fqn deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data ArgIndex = ArgIndex Word deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data ParamIndex = ParamIndex Word deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data FuncName = FuncName String deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data MethodName = MethodName String deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data ConstStrValue = ConstStrValue String deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data SuperQualifiedName = SuperQualifiedName Fqn.Fqn deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+data FuncDefinedInDir = FuncDefinedInDir FilePath deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data FuncDefinedInFile = FuncDefinedInFile FilePath deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data ImportedName = ImportedName String deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data ImportedFromFile = ImportedFromFile FilePath deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data ClassDefinedInFile = ClassDefinedInFile FilePath deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+data SuperDefinedInFile = SuperDefinedInFile FilePath deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+data ResolvedType = ResolvedType
+    Fqn.Fqn -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+data ResolvedSuper = ResolvedSuper Fqn.Fqn deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+-- * each fact is derived from a /single/ bitcode 'Bitcode.Instruction'
+--
+-- * often, a single bitcode instruction will yield /more/ than one fact
+--
+data Fact
+   = FuncDefCtor FuncDef 
+   | ClassDefCtor ClassDef
+   | ParamNameCtor ParamName
+   | ArgiForCallCtor ArgiForCall
+   | ConstStringCtor ConstString
+   | ConstIntegerCtor ConstInteger
+   | DataflowEdgeCtor DataflowEdge
+   | CallResolvedCtor CallResolved
+   | FieldReadResolvedCtor FieldReadResolved
+   | CalledFromCtor CalledFrom
+   | ConstBoolTrueCtor ConstBoolTrue
+   | ConstNullCtor ConstNull
+   | GatedReturnCtor GatedReturn
+   | TopLevelIfThenElseGadgetCtor TopLevelIfThenElseGadget
+   | CallGuardedByCondInThenPartCtor CallGuardedByCondInThenPart
+   | CallGuardedByCondInElsePartCtor CallGuardedByCondInElsePart
+   | ComparisonCtor Comparison
+   | CallableReturnsValueCtor CallableReturnsValue
+   | CallableReturnsWithoutValueCtor CallableReturnsWithoutValue
+   | MethodOfClassCtor MethodOfClass
+   | MethodHasNameCtor MethodHasName
+   | ClassAnnotationCtor ClassAnnotation
+   | ParamiOfCallableCtor ParamiOfCallable
+   | KeywordArgForCallCtor KeywordArgForCall
+   | ParamResolvedTypeCtor ParamResolvedType
+   | CallMethodOfClassCtor CallMethodOfClass
+   | CallableAnnotationCtor CallableAnnotation
+   | ParamAnnotationCtor ParamAnnotation
+   | ClassHas1stPartySuperCtor ClassHas1stPartySuper
+   | ClassHas3rdPartySuperCtor ClassHas3rdPartySuper
+   | CallableSourceBodyLengthCtor CallableSourceBodyLength
+   | AssignValueToToplevelVarNameCtor AssignValueToToplevelVarName
+   | Call1stPartyFuncDefinedInDirCtor Call1stPartyFuncDefinedInDir
+   | Call1stPartyFuncDefinedInFileCtor Call1stPartyFuncDefinedInFile
+   | CallMethodOf1stPartyImportedNameCtor CallMethodOf1stPartyImportedName
+   | CallMethodOfUntypedNamedParamCtor CallMethodOfUntypedNamedParam
+   deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
+-- |
+-- Translate a code fact into a prolog fact
+--
+-- 'ParamName'
+--
+-- @
+-- kb_param_has_name( Param, Name ).
+-- @
+--
+prologify :: Fact -> String
+prologify (FuncDefCtor content) = prologify_FuncDef content
+prologify (ClassDefCtor content) = prologify_ClassDef content
+prologify (ParamNameCtor content) = prologify_ParamName content
+prologify (ArgiForCallCtor content) = prologifyArgiForCall content
+prologify (ConstStringCtor content) = prologify_ConstString content
+prologify (ConstIntegerCtor content) = prologify_ConstInteger content
+prologify (DataflowEdgeCtor content) = prologify_DataflowEdge content
+prologify (CallResolvedCtor content) = prologify_CallResolved content
+prologify (FieldReadResolvedCtor content) = prologify_FieldReadResolved content
+prologify (CalledFromCtor content) = prologify_CalledFrom content
+prologify (ConstBoolTrueCtor content) = prologify_ConstBoolTrue content
+prologify (ConstNullCtor content) = prologify_ConstNull content
+prologify (GatedReturnCtor content) = prologify_GatedReturn content
+prologify (TopLevelIfThenElseGadgetCtor content) = prologify_TopLevelIfThenElseGadget content
+prologify (CallGuardedByCondInThenPartCtor content) = prologify_CallGuardedByCondInThenPart content
+prologify (CallGuardedByCondInElsePartCtor content) = prologify_CallGuardedByCondInElsePart content
+prologify (ComparisonCtor content) = prologify_Comparison content
+prologify (CallableReturnsValueCtor content) = prologify_CallableReturnsValue content
+prologify (CallableReturnsWithoutValueCtor content) = prologify_CallableReturnsWithoutValue content
+prologify (MethodOfClassCtor content) = prologify_MethodOfClass content
+prologify (MethodHasNameCtor content) = prologify_MethodHasName content
+prologify (ClassAnnotationCtor content) = prologify_ClassAnnotation content
+prologify (ParamiOfCallableCtor content) = prologify_ParamiOfCallable content
+prologify (ParamResolvedTypeCtor content) = prologify_ParamResolvedType content
+prologify (CallMethodOfClassCtor content) = prologify_CallMethodOfClass content
+prologify (KeywordArgForCallCtor content) = prologify_KeywordArgForCall content
+prologify (CallableAnnotationCtor content) = prologify_CallableAnnotation content
+prologify (ParamAnnotationCtor content) = prologify_ParamAnnotation content
+prologify (CallableSourceBodyLengthCtor content) = prologify_CallableSourceBodyLength content
+prologify (ClassHas1stPartySuperCtor content) = prologify_ClassHas1stPartySuper content
+prologify (ClassHas3rdPartySuperCtor content) = prologify_ClassHas3rdPartySuper content
+prologify (AssignValueToToplevelVarNameCtor content) = prologify_AssignValueToToplevelVarName content
+prologify (Call1stPartyFuncDefinedInDirCtor content) = prologify_Call1stPartyFuncDefinedInDir content
+prologify (Call1stPartyFuncDefinedInFileCtor content) = prologify_Call1stPartyFuncDefinedInFile content
+prologify (CallMethodOf1stPartyImportedNameCtor content) = prologify_CallMethodOf1stPartyImportedName content
+prologify (CallMethodOfUntypedNamedParamCtor content) = prologify_CallMethodOfUntypedNamedParam content
+
+prologify_ParamResolvedType' :: Location -> String -> String
+prologify_ParamResolvedType' l fqn = printf "kb_param_has_resolved_type( %s, \'%s\' )." (locationify l) fqn
+
+prologify_ParamResolvedType :: ParamResolvedType -> String
+prologify_ParamResolvedType (ParamResolvedType (Param loc) (ResolvedType fqn)) = prologify_ParamResolvedType' loc (prologifyFqn fqn)
+
+prologify_CallMethodOfClass' :: Location -> String -> Location -> String
+prologify_CallMethodOfClass' call method klass = printf "kb_call_method_of_class( %s, \'%s\', %s )." (locationify call) method (locationify klass)
+
+prologify_CallMethodOfClass :: CallMethodOfClass -> String
+prologify_CallMethodOfClass (CallMethodOfClass (Call loc) (MethodName m) (Class c)) = prologify_CallMethodOfClass' loc m c
+
+prologify_ParamName' :: Location -> String -> String
+prologify_ParamName' l name = printf "kb_param_has_name( %s, \'%s\' )." (locationify l) name
+
+prologify_ParamName :: ParamName -> String
+prologify_ParamName (ParamName (Param loc) (Token.ParamName (Token.Named name _))) = prologify_ParamName' loc name
+
+prologify_ClassDef' :: Location -> String -> FilePath -> String
+prologify_ClassDef' l name f = printf "kb_class_def( %s, \'%s\', \'%s\' )." (locationify l) name f
+
+prologify_ClassDef :: ClassDef -> String
+prologify_ClassDef (ClassDef (Class loc) (Token.ClassName (Token.Named name _)) (ClassDefinedInFile f)) = prologify_ClassDef' loc name f
+
+prologify_FuncDef' :: Location -> String -> FilePath -> FilePath -> String
+prologify_FuncDef' l name f d = printf "kb_func_def( %s, \'%s\', \'%s\', \'%s\' )." (locationify l) name f d
+
+prologify_FuncDef :: FuncDef -> String
+prologify_FuncDef (FuncDef (Func loc) (Token.FuncName (Token.Named name _)) (FuncDefinedInFile f) (FuncDefinedInDir d)) = prologify_FuncDef' loc name f d
+
+-- | contents of a single-quoted prolog atom : backslashes and quotes
+-- are escaped, so source strings like @\\[@ or @it's@ load verbatim.
+-- Line breaks are escaped too ( @\\n@ / @\\r@ ), so every fact stays
+-- on one line of the kb while the atom still reads back as the
+-- original multi-line string ( dhscanner.runner#236 ).
+quoted :: String -> String
+quoted = concatMap quoted'
+
+quoted' :: Char -> String
+quoted' '\\' = "\\\\"
+quoted' '\'' = "\\'"
+quoted' '\n' = "\\n"
+quoted' '\r' = "\\r"
+quoted' c = [c]
+
+prologify_ConstString' :: Location -> String -> String
+prologify_ConstString' l value = printf "kb_const_string( %s, \'%s\' )." (locationify l) (quoted value)
+
+prologify_ConstString :: ConstString -> String
+prologify_ConstString (ConstString (ConstStr loc) (Token.ConstStr value _)) = prologify_ConstString' loc value
+
+prologify_ConstInteger' :: Location -> Int -> String
+prologify_ConstInteger' l value = printf "kb_const_int( %s, %d )." (locationify l) value
+
+prologify_ConstInteger :: ConstInteger -> String
+prologify_ConstInteger (ConstInteger (ConstInt loc) (Token.ConstInt value _)) = prologify_ConstInteger' loc value
+
+prologify_CallResolved'' :: Location -> String -> Token.ClassName -> String
+prologify_CallResolved'' call m c = printf "kb_call_method_of_class( %s, \'%s\', %s )." (locationify call) (quoted m) (locationify (Token.getClassNameLocation c))
+
+prologify_CallResolved' :: Location -> Fqn.Fqn -> String
+prologify_CallResolved' call (Fqn.CallMethodOfClass _ m c) = prologify_CallResolved'' call m c 
+prologify_CallResolved' call fqn = printf "kb_call_resolved( %s, \'%s\' )." (locationify call) (quoted (prologifyFqn fqn))
+
+prologify_DataflowEdge :: DataflowEdge -> String
+prologify_DataflowEdge (DataflowEdge (From u) (To v)) = prologify_DataflowEdge' u v
+
+prologify_DataflowEdge' :: Location -> Location -> String
+prologify_DataflowEdge' u v = printf "kb_dataflow_edge( %s, %s )." (locationify u) (locationify v)
+
+prologify_CallResolved :: CallResolved -> String
+prologify_CallResolved (CallResolved (Call call) (Resolved fqn)) = prologify_CallResolved' call fqn
+
+prologify_FieldReadResolved' :: Location -> Fqn.Fqn -> String
+prologify_FieldReadResolved' r fqn = printf "kb_field_read_resolved( %s, '%s' )." (locationify r) (quoted (prologifyFqn fqn))
+
+prologify_FieldReadResolved :: FieldReadResolved -> String
+prologify_FieldReadResolved (FieldReadResolved (FieldRead r) (Resolved fqn)) = prologify_FieldReadResolved' r fqn
+
+prologify_ConstBoolTrue' :: Location -> String
+prologify_ConstBoolTrue' trueValue = printf "kb_class_name( %s, \'%s\' )." (locationify trueValue)
+
+prologify_ConstBoolTrue :: ConstBoolTrue -> String
+prologify_ConstBoolTrue (ConstBoolTrue trueValue) = prologify_ConstBoolTrue' trueValue
+
+prologify_ConstNull' :: Location -> String
+prologify_ConstNull' l = printf "kb_const_null( %s )." (locationify l)
+
+prologify_ConstNull :: ConstNull -> String
+prologify_ConstNull (ConstNull loc) = prologify_ConstNull' loc
+
+prologify_GatedReturn' :: Location -> Location -> String
+prologify_GatedReturn' c v = printf "kb_gated_return( %s, %s )." (locationify c) (locationify v)
+
+prologify_GatedReturn :: GatedReturn -> String
+prologify_GatedReturn (GatedReturn (Cond c) (ReturnedValue v)) = prologify_GatedReturn' c v
+
+thenPartify :: Location -> String
+thenPartify l = "then_part_" ++ locationify l
+
+elsePartify :: Location -> String
+elsePartify l = "else_part_" ++ locationify l
+
+prologify_TopLevelIfThenElseGadget' :: Location -> Location -> Location -> Location -> String
+prologify_TopLevelIfThenElseGadget' callable c t e = printf "kb_top_level_if_then_else_gadget( %s, %s, %s, %s )." (locationify callable) (locationify c) (thenPartify t) (elsePartify e)
+
+prologify_TopLevelIfThenElseGadget :: TopLevelIfThenElseGadget -> String
+prologify_TopLevelIfThenElseGadget (TopLevelIfThenElseGadget (Callable callable) (Cond c) (ThenPart t) (ElsePart e)) = prologify_TopLevelIfThenElseGadget' callable c t e
+
+prologify_CallGuardedByCondInThenPart' :: Location -> Location -> Location -> String
+prologify_CallGuardedByCondInThenPart' call c t = printf "kb_call_guarded_by_cond_in_then_part( %s, %s, %s )." (locationify call) (locationify c) (thenPartify t)
+
+prologify_CallGuardedByCondInThenPart :: CallGuardedByCondInThenPart -> String
+prologify_CallGuardedByCondInThenPart (CallGuardedByCondInThenPart (Call call) (Cond c) (ThenPart t)) = prologify_CallGuardedByCondInThenPart' call c t
+
+prologify_CallGuardedByCondInElsePart' :: Location -> Location -> Location -> String
+prologify_CallGuardedByCondInElsePart' call c e = printf "kb_call_guarded_by_cond_in_else_part( %s, %s, %s )." (locationify call) (locationify c) (elsePartify e)
+
+prologify_CallGuardedByCondInElsePart :: CallGuardedByCondInElsePart -> String
+prologify_CallGuardedByCondInElsePart (CallGuardedByCondInElsePart (Call call) (Cond c) (ElsePart e)) = prologify_CallGuardedByCondInElsePart' call c e
+
+prologify_Comparison' :: Location -> Location -> Location -> String -> String
+prologify_Comparison' c l r op = printf "kb_comparison( %s, %s, %s, %s )." (locationify c) (locationify l) (locationify r) op
+
+prologify_Comparison :: Comparison -> String
+prologify_Comparison (Comparison (Cond c) (Lhs l) (Rhs r) (ComparisonOp op)) = prologify_Comparison' c l r op
+
+prologify_CallableReturnsValue' :: Location -> Location -> String
+prologify_CallableReturnsValue' c v = printf "kb_callable_returns_value( %s, %s )." (locationify c) (locationify v)
+
+prologify_CallableReturnsValue :: CallableReturnsValue -> String
+prologify_CallableReturnsValue (CallableReturnsValue (Callable c) (ReturnedValue v)) = prologify_CallableReturnsValue' c v
+
+prologify_CallableReturnsWithoutValue' :: Location -> Location -> String
+prologify_CallableReturnsWithoutValue' c s = printf "kb_callable_returns_without_value( %s, %s )." (locationify c) (locationify s)
+
+prologify_CallableReturnsWithoutValue :: CallableReturnsWithoutValue -> String
+prologify_CallableReturnsWithoutValue (CallableReturnsWithoutValue (Callable c) s) = prologify_CallableReturnsWithoutValue' c s
+
+prologify_MethodOfClass' :: Location -> Location -> String
+prologify_MethodOfClass' m c = printf "kb_method_of_class( %s, %s )." (locationify m) (locationify c)
+
+prologify_MethodOfClass :: MethodOfClass -> String
+prologify_MethodOfClass (MethodOfClass (Method m) (Class c)) = prologify_MethodOfClass' m c
+
+prologify_MethodHasName' :: Location -> String -> String
+prologify_MethodHasName' m name = printf "kb_method_has_name( %s, \'%s\' )." (locationify m) name
+
+prologify_MethodHasName :: MethodHasName -> String
+prologify_MethodHasName (MethodHasName (Method m) (Token.MethodName (Token.Named name _))) = prologify_MethodHasName' m name
+
+prologify_ClassHas1stPartySuper' :: Location -> String -> FilePath -> String
+prologify_ClassHas1stPartySuper' c s f = printf "kb_class_has_1st_party_super( %s, \'%s\', \'%s\' )." (locationify c) s f
+ 
+prologify_ClassHas1stPartySuper :: ClassHas1stPartySuper -> String
+prologify_ClassHas1stPartySuper (ClassHas1stPartySuper (Class c) (Token.SuperName (Token.Named s _)) (SuperDefinedInFile f)) = prologify_ClassHas1stPartySuper' c s f
+
+prologify_ClassHas3rdPartySuper' :: Location -> String -> Fqn.Fqn -> String
+prologify_ClassHas3rdPartySuper' c s f = printf "kb_class_has_3rd_party_super( %s, \'%s\', \'%s\' )." (locationify c) s (prologifyFqn f)
+ 
+prologify_ClassHas3rdPartySuper :: ClassHas3rdPartySuper -> String
+prologify_ClassHas3rdPartySuper (ClassHas3rdPartySuper (Class c) (Token.SuperName (Token.Named s _)) (SuperQualifiedName f)) = prologify_ClassHas3rdPartySuper' c s f
+
+prologify_AssignValueToToplevelVarName :: AssignValueToToplevelVarName -> String
+prologify_AssignValueToToplevelVarName (AssignValueToToplevelVarName value varname) = prologify_AssignValueToToplevelVarName' value varname
+
+prologify_AssignValueToToplevelVarName' :: AssignedValue -> Token.VarName -> String
+prologify_AssignValueToToplevelVarName' (AssignedValue value) (Token.VarName (Token.Named varname l)) = prologify_AssignValueToToplevelVarName'' value varname (Location.filename l)
+
+prologify_AssignValueToToplevelVarName'' :: Location -> String -> FilePath -> String
+prologify_AssignValueToToplevelVarName'' value varname f = printf "kb_assign_value_to_toplevel_varname( %s, \'%s\', \'%s\', \'%s\')." (locationify value) varname f (takeDirectory f)
+
+prologify_Call1stPartyFuncDefinedInFile :: Call1stPartyFuncDefinedInFile -> String
+prologify_Call1stPartyFuncDefinedInFile (Call1stPartyFuncDefinedInFile call func f) = prologify_Call1stPartyFuncDefinedInFile' call func f
+
+prologify_Call1stPartyFuncDefinedInFile' :: Call -> FuncName -> FuncDefinedInFile -> String
+prologify_Call1stPartyFuncDefinedInFile' (Call call) (FuncName func) (FuncDefinedInFile f) = prologify_Call1stPartyFuncDefinedInFile'' call func f
+
+prologify_Call1stPartyFuncDefinedInFile'' :: Location -> String -> FilePath -> String
+prologify_Call1stPartyFuncDefinedInFile'' call func f = printf "kb_call_1st_party_func_defined_in_file( %s, \'%s\', \'%s\' )." (locationify call) func f
+
+prologify_CallMethodOf1stPartyImportedName :: CallMethodOf1stPartyImportedName -> String
+prologify_CallMethodOf1stPartyImportedName (CallMethodOf1stPartyImportedName (Call call) (MethodName m) (ImportedName name) (ImportedFromFile f)) =
+    printf "kb_call_method_of_1st_party_imported_name( %s, \'%s\', \'%s\', \'%s\' )." (locationify call) (quoted m) (quoted name) (quoted f)
+
+prologify_Call1stPartyFuncDefinedInDir :: Call1stPartyFuncDefinedInDir -> String
+prologify_Call1stPartyFuncDefinedInDir (Call1stPartyFuncDefinedInDir call func d) = prologify_Call1stPartyFuncDefinedInDir' call func d
+
+prologify_Call1stPartyFuncDefinedInDir' :: Call -> FuncName -> FuncDefinedInDir -> String
+prologify_Call1stPartyFuncDefinedInDir' (Call call) (FuncName f) (FuncDefinedInDir d) = prologify_Call1stPartyFuncDefinedInDir'' call f d
+
+prologify_Call1stPartyFuncDefinedInDir'' :: Location -> String -> FilePath -> String
+prologify_Call1stPartyFuncDefinedInDir'' call f d = printf "kb_call_1st_party_func_defined_in_dir( %s, \'%s\', \'%s\' )." (locationify call) f d
+
+prologify_CallMethodOfUntypedNamedParam :: CallMethodOfUntypedNamedParam -> String
+prologify_CallMethodOfUntypedNamedParam (CallMethodOfUntypedNamedParam call method p) = prologify_CallMethodOfUntypedNamedParam' call method p
+
+prologify_CallMethodOfUntypedNamedParam' :: Call -> MethodName -> Token.ParamName -> String
+prologify_CallMethodOfUntypedNamedParam' (Call call) (MethodName m) (Token.ParamName (Token.Named _ p)) = prologify_CallMethodOfUntypedNamedParam'' call m p
+
+prologify_CallMethodOfUntypedNamedParam'' :: Location -> String -> Location -> String
+prologify_CallMethodOfUntypedNamedParam'' call m p = printf "kb_call_method_of_untyped_named_param( %s, \'%s\', %s )." (locationify call) m (locationify p)
+
+prologifyArgiForCall' :: Location -> Word -> Location -> String
+prologifyArgiForCall' a i c = printf "kb_arg_i_for_call( %s, %u, %s )." (locationify a) i (locationify c)
+
+prologifyArgiForCall :: ArgiForCall -> String
+prologifyArgiForCall (ArgiForCall (Arg a) (ArgIndex i) (Call c)) = prologifyArgiForCall' a i c
+
+prologify_ClassAnnotation' :: Location -> Location -> String
+prologify_ClassAnnotation' c a = printf "kb_class_has_annotation( %s, %s )." (locationify c) (locationify a)
+
+prologify_ClassAnnotation :: ClassAnnotation -> String
+prologify_ClassAnnotation (ClassAnnotation (Class c) (Annotation a)) = prologify_ClassAnnotation' c a
+
+prologify_KeywordArgForCall' ::  String -> Location -> Location -> String
+prologify_KeywordArgForCall' kw a c = printf "kb_keyword_arg_for_call( \'%s\', %s, %s )." (quoted kw) (locationify a) (locationify c)
+
+prologify_KeywordArgForCall :: KeywordArgForCall -> String
+prologify_KeywordArgForCall (KeywordArgForCall (Keyword kw) (Arg a) (Call c)) = prologify_KeywordArgForCall' kw a c
+
+prologify_CallableAnnotation' :: Location -> Location -> String
+prologify_CallableAnnotation' c a = printf "kb_callable_has_annotation( %s, %s )." (locationify c) (locationify a)
+
+prologify_CallableAnnotation :: CallableAnnotation -> String
+prologify_CallableAnnotation (CallableAnnotation (Callable c) (Annotation a)) = prologify_CallableAnnotation' c a
+
+prologify_ParamAnnotation' :: Location -> Location -> String
+prologify_ParamAnnotation' p a = printf "kb_param_has_annotation( %s, %s )." (locationify p) (locationify a)
+
+prologify_ParamAnnotation :: ParamAnnotation -> String
+prologify_ParamAnnotation (ParamAnnotation (Param p) (Annotation a)) = prologify_ParamAnnotation' p a
+
+prologify_CallableSourceBodyLength' :: Location -> Word -> String
+prologify_CallableSourceBodyLength' c n = printf "kb_callable_source_body_length( %s, %u )." (locationify c) n
+
+prologify_CallableSourceBodyLength :: CallableSourceBodyLength -> String
+prologify_CallableSourceBodyLength (CallableSourceBodyLength (Callable c) n) = prologify_CallableSourceBodyLength' c n
+
+prologify_ParamiOfCallable' :: Location -> Word -> Location -> String
+prologify_ParamiOfCallable' p i c = printf "kb_param_i_of_callable( %s, %u, %s )." (locationify p) i (locationify c)
+
+prologify_ParamiOfCallable :: ParamiOfCallable -> String
+prologify_ParamiOfCallable (ParamiOfCallable (Param p) (ParamIndex i) (Callable c)) = prologify_ParamiOfCallable' p i c
+
+prologify_CalledFrom' :: Location -> Location -> String
+prologify_CalledFrom' call callable = printf "kb_called_from( %s, %s )." (locationify call) (locationify callable)
+
+prologify_CalledFrom :: CalledFrom -> String
+prologify_CalledFrom (CalledFrom (Call call) (Callable callable)) = prologify_CalledFrom' call callable
+
+normalizeChar :: Char -> String
+normalizeChar '/' = "_slash_"
+normalizeChar '.' = "_dot_"
+normalizeChar '-' = "_dash_"
+normalizeChar '['  = "_lbrack_"
+normalizeChar ']'  = "_rbrack_"
+normalizeChar '('  = "_lparen_"
+normalizeChar ')'  = "_rparen_"
+normalizeChar c = [c]
+
+normalize :: FilePath -> FilePath
+normalize path = concatMap normalizeChar path
+
+-- | The atom spelling of a resolved fqn ( 'CallResolved', 'FieldReadResolved',
+-- 'ParamResolvedType', 'ClassHas3rdPartySuper' ). A 3rd party fqn is its
+-- dotted name ( @javax.imageio.ImageIO.read@ ), a native type its plain
+-- name ( @string@ ), a receiver that could not be typed is @Unknown@.
+-- 1st party roots are tagged, @\<tag\>[ .. ]@ ( the same convention as
+-- @\<dhscanner-instrumentation\>[ .. ]@ ), so they never spell a 3rd
+-- party fqn :
+--
+-- @
+-- \<1st-party\>[File].Name.m          a name imported from a 1st party file
+-- \<1st-party-dir\>[Dir].Alias.m      a 1st party package ( dir ) import
+-- \<1st-party-class\>[Class].m        a 1st party class ( or a call of its method )
+-- \<this\>[Class].m , \<self\>[Class].m
+-- \<param\>[Param].m                  a method of an untyped param
+-- @
+--
+-- The spelling is for reading a kb and for exact matches only : a
+-- predicate that needs the parts joins on the structured facts
+-- ( 'CallMethodOf1stPartyImportedName', 'CallMethodOfClass', 'ClassDef', .. ).
+prologifyFqn :: Fqn.Fqn -> String
+prologifyFqn (Fqn.ThirdPartyImport fqn) = prologifyThirdPartyImport fqn
+prologifyFqn (Fqn.FieldedAccess fqn fieldName) = prologifyFieldedAccess fqn fieldName
+prologifyFqn Fqn.NativeTypeInt = "int"
+prologifyFqn Fqn.NativeTypeString = "string"
+prologifyFqn Fqn.NativeTypeBool = "bool"
+prologifyFqn Fqn.NativeTypeNull = "null"
+prologifyFqn (Fqn.NativeTypeConstInt _) = "int"
+prologifyFqn (Fqn.NativeTypeConstStr _) = "string"
+prologifyFqn (Fqn.NativeTypeConstBool _) = "bool"
+prologifyFqn (Fqn.ClassName (Fqn.ClassNameContent c)) = tagged "1st-party-class" (className c)
+prologifyFqn (Fqn.ClassInstance (Fqn.ClassInstanceContent Fqn.Self c)) = tagged "self" (className c)
+prologifyFqn (Fqn.ClassInstance (Fqn.ClassInstanceContent Fqn.This c)) = tagged "this" (className c)
+prologifyFqn (Fqn.CallMethodOfClass _ m c) = tagged "1st-party-class" (className c) ++ "." ++ m
+prologifyFqn (Fqn.CallMethodOfUntypedNamedParam _ m (Token.ParamName (Token.Named p _))) = tagged "param" p ++ "." ++ m
+prologifyFqn (Fqn.CallFuncFromImportedDir _ f d) = tagged "1st-party-dir" d ++ "." ++ f
+prologifyFqn (Fqn.CallFuncFromImportedFile _ f file) = tagged "1st-party" file ++ "." ++ f
+prologifyFqn (Fqn.FirstPartyImport (Fqn.FirstPartyImportContent file name)) = tagged "1st-party" file ++ maybe "" ("." ++) name
+prologifyFqn (Fqn.FirstPartyDirImport (Fqn.FirstPartyDirImportContent d alias)) = tagged "1st-party-dir" d ++ maybe "" ("." ++) alias
+prologifyFqn Fqn.Unknown = "Unknown"
+
+tagged :: String -> String -> String
+tagged tag value = "<" ++ tag ++ ">[" ++ value ++ "]"
+
+className :: Token.ClassName -> String
+className (Token.ClassName (Token.Named name _)) = name
+
+prologifyThirdPartyImport :: Fqn.ThirdPartyImportContent -> String
+prologifyThirdPartyImport (Fqn.ThirdPartyImportContent p [] Nothing _) = p
+prologifyThirdPartyImport (Fqn.ThirdPartyImportContent p [] (Just name) _) = p ++ "." ++ name
+prologifyThirdPartyImport (Fqn.ThirdPartyImportContent p rest Nothing _) = p ++ "." ++ List.intercalate "." rest
+prologifyThirdPartyImport (Fqn.ThirdPartyImportContent p rest (Just name) _) = p ++ "." ++ List.intercalate "." rest ++ "." ++ name
+
+prologifyFieldedAccess :: Fqn.Fqn -> Token.FieldName -> String
+prologifyFieldedAccess fqn (Token.FieldName (Token.Named fieldName _)) = (prologifyFqn fqn) ++ "." ++ fieldName
+
+locationify :: Location -> String
+locationify l = let
+    x = Location.lineStart l
+    y = Location.colStart l
+    z = Location.lineEnd l
+    w = Location.colEnd l
+    f = normalize (Location.filename l)
+    in printf "startloc_%u_%u_endloc_%u_%u_%s" x y z w f
+
+restoreloc :: String -> Maybe Location
+restoreloc s = case parseOnly locationParser (T.pack s) of { Right l -> Just l; _ -> Nothing; }
+
+locationParser :: Parser Location
+locationParser = do {
+
+    _ <- string "startloc_"; x <- decimal; _ <- char '_'; y <- decimal;
+    _ <- string "_endloc_" ; z <- decimal; _ <- char '_'; w <- decimal;
+    _ <- char '_'; fname <- takeText;
+
+    pure Location {
+        filename  = restoreFilename (T.unpack fname),
+        lineStart = x,
+        colStart = y,
+        lineEnd = z,
+        colEnd = w
+    }
+}
+
+data Rule = Rule { from :: Text, to :: Text }
+
+rules :: [ Rule ]
+rules =
+    [ Rule { from = "_slash_",  to = "/" }
+    , Rule { from = "_dot_",    to = "." }
+    , Rule { from = "_dash_",   to = "-" }
+    , Rule { from = "_lbrack_", to = "[" }
+    , Rule { from = "_rbrack_", to = "]" }
+    , Rule { from = "_lparen_", to = "(" }
+    , Rule { from = "_rparen_", to = ")" }
+    ]
+
+applyRule :: Rule -> Text -> Text
+applyRule Rule { from = f, to = t } = T.replace f t
+
+applyRuleStep :: Text -> Rule -> Text
+applyRuleStep acc r = applyRule r acc
+
+restore :: Text -> Text
+restore txt = List.foldl' applyRuleStep txt rules
+
+textToStringAdapter :: (Text -> Text) -> String -> String
+textToStringAdapter f = T.unpack . f . T.pack
+
+restoreFilename :: String -> String
 restoreFilename = textToStringAdapter restore
diff --git a/test/SmokeTests.hs b/test/SmokeTests.hs
--- a/test/SmokeTests.hs
+++ b/test/SmokeTests.hs
@@ -1,144 +1,231 @@
-module SmokeTests (runSmokeTests) where
-
-import Kbgen
-    ( Call (..)
-    , CallGuardedByCondInElsePart (..)
-    , CallGuardedByCondInThenPart (..)
-    , Callable (..)
-    , Cond (..)
-    , ConstNull (..)
-    , ElsePart (..)
-    , Fact (..)
-    , FieldRead (..)
-    , FieldReadResolved (..)
-    , GatedReturn (..)
-    , Method (..)
-    , MethodHasName (..)
-    , Resolved (..)
-    , ReturnedValue (..)
-    , ThenPart (..)
-    , TopLevelIfThenElseGadget (..)
-    , locationify
-    , prologify
-    , restoreloc
-    )
-import qualified Fqn
-import Location (Location (..))
-import qualified Token
-import Test.Hspec (Spec, hspec, it, shouldBe)
-
-it' :: IO () -> String -> Spec
-it' testBody label = it label testBody
-
-completelyInvalidLocationString :: String
-completelyInvalidLocationString = "Blahhh"
-
-testCompletelyInvalidLocationString :: IO ()
-testCompletelyInvalidLocationString = restoreloc completelyInvalidLocationString `shouldBe` Nothing
-
-locationStringWithoutProperPrefix :: String
-locationStringWithoutProperPrefix = "____startloc_1_2_endloc_3_4_foo_dot_c"
-
-testLocationStringWithoutProperPrefix :: IO ()
-testLocationStringWithoutProperPrefix = restoreloc locationStringWithoutProperPrefix `shouldBe` Nothing
-
-locationStringWithoutProperFormatExample1 :: String
-locationStringWithoutProperFormatExample1 = "startloc_1_2_end_3_4_foo_dot_c"
-
-testLocationStringWithoutProperFormatExample1 :: IO ()
-testLocationStringWithoutProperFormatExample1 = restoreloc locationStringWithoutProperFormatExample1 `shouldBe` Nothing
-
-locationStringWithoutProperFormatExample2 :: String
-locationStringWithoutProperFormatExample2 = "startloc_1_2_endloc____3_4_foo_dot_c"
-
-testLocationStringWithoutProperFormatExample2 :: IO ()
-testLocationStringWithoutProperFormatExample2 = restoreloc locationStringWithoutProperFormatExample2 `shouldBe` Nothing
-
-locationStringWithoutProperFormatExample3 :: String
-locationStringWithoutProperFormatExample3 = "startloc_1_2_endloc_3______4_foo_dot_c"
-
-testLocationStringWithoutProperFormatExample3 :: IO ()
-testLocationStringWithoutProperFormatExample3 = restoreloc locationStringWithoutProperFormatExample3 `shouldBe` Nothing
-
-sampleLoc :: Word -> Location
-sampleLoc n =
-    Location
-        { lineStart = n
-        , colStart = n
-        , lineEnd = n
-        , colEnd = n
-        , filename = "foo.c"
-        }
-
-testPrologifyConstNull :: IO ()
-testPrologifyConstNull =
-    let loc = sampleLoc 1
-        expected = "kb_const_null( " ++ locationify loc ++ " )."
-    in prologify (ConstNullCtor (ConstNull loc)) `shouldBe` expected
-
-testPrologifyGatedReturn :: IO ()
-testPrologifyGatedReturn =
-    let condLoc = sampleLoc 1
-        retLoc = sampleLoc 2
-        gr = GatedReturn (Cond condLoc) (ReturnedValue retLoc)
-        expected = "kb_gated_return( " ++ locationify condLoc ++ ", " ++ locationify retLoc ++ " )."
-    in prologify (GatedReturnCtor gr) `shouldBe` expected
-
-testPrologifyMethodHasName :: IO ()
-testPrologifyMethodHasName =
-    let methodLoc = sampleLoc 1
-        name = Token.MethodName (Token.Named "oidc" (sampleLoc 2))
-        mn = MethodHasName (Method methodLoc) name
-        expected = "kb_method_has_name( " ++ locationify methodLoc ++ ", 'oidc' )."
-    in prologify (MethodHasNameCtor mn) `shouldBe` expected
-
-testPrologifyFieldReadResolved :: IO ()
-testPrologifyFieldReadResolved =
-    let readLoc = sampleLoc 1
-        requestMethod = Fqn.ThirdPartyImport (Fqn.ThirdPartyImportContent "org" ["springframework", "web", "bind", "annotation"] (Just "RequestMethod") Nothing)
-        get = Token.FieldName (Token.Named "GET" (sampleLoc 2))
-        r = FieldReadResolved (FieldRead readLoc) (Resolved (Fqn.FieldedAccess requestMethod get))
-        expected = "kb_field_read_resolved( " ++ locationify readLoc ++ ", 'org.springframework.web.bind.annotation.RequestMethod.GET' )."
-    in prologify (FieldReadResolvedCtor r) `shouldBe` expected
-
-testPrologifyTopLevelIfThenElseGadget :: IO ()
-testPrologifyTopLevelIfThenElseGadget =
-    let callableLoc = sampleLoc 1
-        condLoc = sampleLoc 2
-        g = TopLevelIfThenElseGadget (Callable callableLoc) (Cond condLoc) (ThenPart condLoc) (ElsePart condLoc)
-        expected = "kb_top_level_if_then_else_gadget( " ++ locationify callableLoc ++ ", " ++ locationify condLoc ++ ", then_part_" ++ locationify condLoc ++ ", else_part_" ++ locationify condLoc ++ " )."
-    in prologify (TopLevelIfThenElseGadgetCtor g) `shouldBe` expected
-
-testPrologifyCallGuardedByCondInThenPart :: IO ()
-testPrologifyCallGuardedByCondInThenPart =
-    let callLoc = sampleLoc 1
-        condLoc = sampleLoc 2
-        c = CallGuardedByCondInThenPart (Call callLoc) (Cond condLoc) (ThenPart condLoc)
-        expected = "kb_call_guarded_by_cond_in_then_part( " ++ locationify callLoc ++ ", " ++ locationify condLoc ++ ", then_part_" ++ locationify condLoc ++ " )."
-    in prologify (CallGuardedByCondInThenPartCtor c) `shouldBe` expected
-
-testPrologifyCallGuardedByCondInElsePart :: IO ()
-testPrologifyCallGuardedByCondInElsePart =
-    let callLoc = sampleLoc 1
-        condLoc = sampleLoc 2
-        c = CallGuardedByCondInElsePart (Call callLoc) (Cond condLoc) (ElsePart condLoc)
-        expected = "kb_call_guarded_by_cond_in_else_part( " ++ locationify callLoc ++ ", " ++ locationify condLoc ++ ", else_part_" ++ locationify condLoc ++ " )."
-    in prologify (CallGuardedByCondInElsePartCtor c) `shouldBe` expected
-
-tests :: Spec
-tests = do
-    it' testCompletelyInvalidLocationString "completelyInvalidLocationString should return Nothing"
-    it' testLocationStringWithoutProperPrefix "locationStringWithoutProperPrefix should return Nothing"
-    it' testLocationStringWithoutProperFormatExample1 "locationStringWithoutProperFormatExample1 should return Nothing"
-    it' testLocationStringWithoutProperFormatExample2 "locationStringWithoutProperFormatExample2 should return Nothing"
-    it' testLocationStringWithoutProperFormatExample3 "locationStringWithoutProperFormatExample3 should return Nothing"
-    it' testPrologifyConstNull "prologify_ConstNull should render kb_const_null( <loc> )."
-    it' testPrologifyGatedReturn "prologify_GatedReturn should render kb_gated_return( <cond>, <ret> )."
-    it' testPrologifyMethodHasName "prologify_MethodHasName should render kb_method_has_name( <method>, '<name>' )."
-    it' testPrologifyFieldReadResolved "prologify_FieldReadResolved should render kb_field_read_resolved( <field read>, '<fqn>' )."
-    it' testPrologifyTopLevelIfThenElseGadget "prologify_TopLevelIfThenElseGadget should render kb_top_level_if_then_else_gadget( <callable>, <cond>, then_part_<cond>, else_part_<cond> )."
-    it' testPrologifyCallGuardedByCondInThenPart "prologify_CallGuardedByCondInThenPart should render kb_call_guarded_by_cond_in_then_part( <call>, <cond>, then_part_<cond> )."
-    it' testPrologifyCallGuardedByCondInElsePart "prologify_CallGuardedByCondInElsePart should render kb_call_guarded_by_cond_in_else_part( <call>, <cond>, else_part_<cond> )."
-
-runSmokeTests :: IO ()
-runSmokeTests = hspec tests
+module SmokeTests (runSmokeTests) where
+
+import Kbgen
+    ( Call (..)
+    , CallMethodOf1stPartyImportedName (..)
+    , CallResolved (..)
+    , ImportedFromFile (..)
+    , ImportedName (..)
+    , MethodName (..)
+    , prologifyFqn
+    , CallGuardedByCondInElsePart (..)
+    , CallGuardedByCondInThenPart (..)
+    , Callable (..)
+    , Cond (..)
+    , ConstNull (..)
+    , ConstStr (..)
+    , ConstString (..)
+    , ElsePart (..)
+    , Fact (..)
+    , FieldRead (..)
+    , FieldReadResolved (..)
+    , GatedReturn (..)
+    , Method (..)
+    , MethodHasName (..)
+    , Resolved (..)
+    , ReturnedValue (..)
+    , ThenPart (..)
+    , TopLevelIfThenElseGadget (..)
+    , locationify
+    , prologify
+    , restoreloc
+    )
+import qualified Fqn
+import Location (Location (..))
+import qualified Token
+import Test.Hspec (Spec, hspec, it, shouldBe)
+
+it' :: IO () -> String -> Spec
+it' testBody label = it label testBody
+
+completelyInvalidLocationString :: String
+completelyInvalidLocationString = "Blahhh"
+
+testCompletelyInvalidLocationString :: IO ()
+testCompletelyInvalidLocationString = restoreloc completelyInvalidLocationString `shouldBe` Nothing
+
+locationStringWithoutProperPrefix :: String
+locationStringWithoutProperPrefix = "____startloc_1_2_endloc_3_4_foo_dot_c"
+
+testLocationStringWithoutProperPrefix :: IO ()
+testLocationStringWithoutProperPrefix = restoreloc locationStringWithoutProperPrefix `shouldBe` Nothing
+
+locationStringWithoutProperFormatExample1 :: String
+locationStringWithoutProperFormatExample1 = "startloc_1_2_end_3_4_foo_dot_c"
+
+testLocationStringWithoutProperFormatExample1 :: IO ()
+testLocationStringWithoutProperFormatExample1 = restoreloc locationStringWithoutProperFormatExample1 `shouldBe` Nothing
+
+locationStringWithoutProperFormatExample2 :: String
+locationStringWithoutProperFormatExample2 = "startloc_1_2_endloc____3_4_foo_dot_c"
+
+testLocationStringWithoutProperFormatExample2 :: IO ()
+testLocationStringWithoutProperFormatExample2 = restoreloc locationStringWithoutProperFormatExample2 `shouldBe` Nothing
+
+locationStringWithoutProperFormatExample3 :: String
+locationStringWithoutProperFormatExample3 = "startloc_1_2_endloc_3______4_foo_dot_c"
+
+testLocationStringWithoutProperFormatExample3 :: IO ()
+testLocationStringWithoutProperFormatExample3 = restoreloc locationStringWithoutProperFormatExample3 `shouldBe` Nothing
+
+sampleLoc :: Word -> Location
+sampleLoc n =
+    Location
+        { lineStart = n
+        , colStart = n
+        , lineEnd = n
+        , colEnd = n
+        , filename = "foo.c"
+        }
+
+testPrologifyConstNull :: IO ()
+testPrologifyConstNull =
+    let loc = sampleLoc 1
+        expected = "kb_const_null( " ++ locationify loc ++ " )."
+    in prologify (ConstNullCtor (ConstNull loc)) `shouldBe` expected
+
+testPrologifyGatedReturn :: IO ()
+testPrologifyGatedReturn =
+    let condLoc = sampleLoc 1
+        retLoc = sampleLoc 2
+        gr = GatedReturn (Cond condLoc) (ReturnedValue retLoc)
+        expected = "kb_gated_return( " ++ locationify condLoc ++ ", " ++ locationify retLoc ++ " )."
+    in prologify (GatedReturnCtor gr) `shouldBe` expected
+
+testPrologifyMethodHasName :: IO ()
+testPrologifyMethodHasName =
+    let methodLoc = sampleLoc 1
+        name = Token.MethodName (Token.Named "oidc" (sampleLoc 2))
+        mn = MethodHasName (Method methodLoc) name
+        expected = "kb_method_has_name( " ++ locationify methodLoc ++ ", 'oidc' )."
+    in prologify (MethodHasNameCtor mn) `shouldBe` expected
+
+testPrologifyFieldReadResolved :: IO ()
+testPrologifyFieldReadResolved =
+    let readLoc = sampleLoc 1
+        requestMethod = Fqn.ThirdPartyImport (Fqn.ThirdPartyImportContent "org" ["springframework", "web", "bind", "annotation"] (Just "RequestMethod") Nothing)
+        get = Token.FieldName (Token.Named "GET" (sampleLoc 2))
+        r = FieldReadResolved (FieldRead readLoc) (Resolved (Fqn.FieldedAccess requestMethod get))
+        expected = "kb_field_read_resolved( " ++ locationify readLoc ++ ", 'org.springframework.web.bind.annotation.RequestMethod.GET' )."
+    in prologify (FieldReadResolvedCtor r) `shouldBe` expected
+
+testPrologifyTopLevelIfThenElseGadget :: IO ()
+testPrologifyTopLevelIfThenElseGadget =
+    let callableLoc = sampleLoc 1
+        condLoc = sampleLoc 2
+        g = TopLevelIfThenElseGadget (Callable callableLoc) (Cond condLoc) (ThenPart condLoc) (ElsePart condLoc)
+        expected = "kb_top_level_if_then_else_gadget( " ++ locationify callableLoc ++ ", " ++ locationify condLoc ++ ", then_part_" ++ locationify condLoc ++ ", else_part_" ++ locationify condLoc ++ " )."
+    in prologify (TopLevelIfThenElseGadgetCtor g) `shouldBe` expected
+
+testPrologifyCallGuardedByCondInThenPart :: IO ()
+testPrologifyCallGuardedByCondInThenPart =
+    let callLoc = sampleLoc 1
+        condLoc = sampleLoc 2
+        c = CallGuardedByCondInThenPart (Call callLoc) (Cond condLoc) (ThenPart condLoc)
+        expected = "kb_call_guarded_by_cond_in_then_part( " ++ locationify callLoc ++ ", " ++ locationify condLoc ++ ", then_part_" ++ locationify condLoc ++ " )."
+    in prologify (CallGuardedByCondInThenPartCtor c) `shouldBe` expected
+
+testPrologifyCallGuardedByCondInElsePart :: IO ()
+testPrologifyCallGuardedByCondInElsePart =
+    let callLoc = sampleLoc 1
+        condLoc = sampleLoc 2
+        c = CallGuardedByCondInElsePart (Call callLoc) (Cond condLoc) (ElsePart condLoc)
+        expected = "kb_call_guarded_by_cond_in_else_part( " ++ locationify callLoc ++ ", " ++ locationify condLoc ++ ", else_part_" ++ locationify condLoc ++ " )."
+    in prologify (CallGuardedByCondInElsePartCtor c) `shouldBe` expected
+
+pathUtil :: Fqn.Fqn
+pathUtil = Fqn.FirstPartyImport (Fqn.FirstPartyImportContent "util/PathUtil.java" (Just "PathUtil"))
+
+member :: String -> Token.FieldName
+member name = Token.FieldName (Token.Named name (sampleLoc 2))
+
+-- no Haskell `show` leaks into a kb atom
+testPrologifyCallResolved1stPartyImport :: IO ()
+testPrologifyCallResolved1stPartyImport =
+    let callLoc = sampleLoc 1
+        c = CallResolved (Call callLoc) (Resolved (Fqn.FieldedAccess pathUtil (member "normalize")))
+        expected = "kb_call_resolved( " ++ locationify callLoc ++ ", '<1st-party>[util/PathUtil.java].PathUtil.normalize' )."
+    in prologify (CallResolvedCtor c) `shouldBe` expected
+
+testPrologifyFqnShapes :: IO ()
+testPrologifyFqnShapes =
+    let klass = Token.ClassName (Token.Named "Foo" (sampleLoc 3))
+        param = Token.ParamName (Token.Named "res" (sampleLoc 4))
+    in map prologifyFqn
+        [ Fqn.NativeTypeString
+        , Fqn.NativeTypeConstInt 7
+        , Fqn.ClassName (Fqn.ClassNameContent klass)
+        , Fqn.FieldedAccess (Fqn.ClassInstance (Fqn.ClassInstanceContent Fqn.This klass)) (member "m")
+        , Fqn.FieldedAccess (Fqn.CallMethodOfClass (sampleLoc 5) "build" klass) (member "run")
+        , Fqn.CallMethodOfUntypedNamedParam (sampleLoc 5) "sendFile" param
+        , Fqn.FieldedAccess (Fqn.CallFuncFromImportedFile (sampleLoc 5) "helper" "lib/a.ts") (member "x")
+        , Fqn.FirstPartyDirImport (Fqn.FirstPartyDirImportContent "pkg/util" Nothing)
+        , Fqn.FieldedAccess Fqn.Unknown (member "to_i")
+        ] `shouldBe`
+        [ "string"
+        , "int"
+        , "<1st-party-class>[Foo]"
+        , "<this>[Foo].m"
+        , "<1st-party-class>[Foo].build.run"
+        , "<param>[res].sendFile"
+        , "<1st-party>[lib/a.ts].helper.x"
+        , "<1st-party-dir>[pkg/util]"
+        , "Unknown.to_i"
+        ]
+
+testPrologifyCallMethodOf1stPartyImportedName :: IO ()
+testPrologifyCallMethodOf1stPartyImportedName =
+    let callLoc = sampleLoc 1
+        c = CallMethodOf1stPartyImportedName (Call callLoc) (MethodName "normalize") (ImportedName "PathUtil") (ImportedFromFile "util/PathUtil.java")
+        expected = "kb_call_method_of_1st_party_imported_name( " ++ locationify callLoc ++ ", 'normalize', 'PathUtil', 'util/PathUtil.java' )."
+    in prologify (CallMethodOf1stPartyImportedNameCtor c) `shouldBe` expected
+
+-- a capitalized method name ( C# ) must not read as a Prolog variable
+testPrologifyCallResolvedMethodOfClassQuoted :: IO ()
+testPrologifyCallResolvedMethodOfClassQuoted =
+    let callLoc = sampleLoc 1
+        klass = Token.ClassName (Token.Named "BackupController" (sampleLoc 3))
+        c = CallResolved (Call callLoc) (Resolved (Fqn.CallMethodOfClass (sampleLoc 5) "GetBackup" klass))
+        expected = "kb_call_method_of_class( " ++ locationify callLoc ++ ", 'GetBackup', " ++ locationify (sampleLoc 3) ++ " )."
+    in prologify (CallResolvedCtor c) `shouldBe` expected
+
+testPrologifyCallResolvedEscapesQuote :: IO ()
+testPrologifyCallResolvedEscapesQuote =
+    let callLoc = sampleLoc 1
+        odd' = Fqn.FirstPartyImport (Fqn.FirstPartyImportContent "it's/a.rb" (Just "DB"))
+        c = CallResolved (Call callLoc) (Resolved (Fqn.FieldedAccess odd' (member "exec")))
+        expected = "kb_call_resolved( " ++ locationify callLoc ++ ", '<1st-party>[it\\'s/a.rb].DB.exec' )."
+    in prologify (CallResolvedCtor c) `shouldBe` expected
+
+-- a multi-line string constant must stay one kb line ( dhscanner.runner#236 )
+testPrologifyConstStringEscapesLineBreaks :: IO ()
+testPrologifyConstStringEscapesLineBreaks =
+    let loc = sampleLoc 1
+        value = "# first\nsecond\r\nit's \\ third"
+        c = ConstString (ConstStr loc) (Token.ConstStr value (sampleLoc 1))
+        expected = "kb_const_string( " ++ locationify loc ++ ", '# first\\nsecond\\r\\nit\\'s \\\\ third' )."
+    in prologify (ConstStringCtor c) `shouldBe` expected
+
+tests :: Spec
+tests = do
+    it' testPrologifyConstStringEscapesLineBreaks "kb_const_string escapes line breaks, so one fact = one line"
+    it' testPrologifyCallResolved1stPartyImport "kb_call_resolved of a 1st party import member is tagged, not Haskell show"
+    it' testPrologifyFqnShapes "prologifyFqn spells every fqn shape without Haskell show"
+    it' testPrologifyCallMethodOf1stPartyImportedName "prologify_CallMethodOf1stPartyImportedName should render kb_call_method_of_1st_party_imported_name( <call>, '<method>', '<name>', '<file>' )."
+    it' testPrologifyCallResolvedMethodOfClassQuoted "kb_call_method_of_class quotes the method name"
+    it' testPrologifyCallResolvedEscapesQuote "kb_call_resolved escapes a quote in the fqn"
+    it' testCompletelyInvalidLocationString "completelyInvalidLocationString should return Nothing"
+    it' testLocationStringWithoutProperPrefix "locationStringWithoutProperPrefix should return Nothing"
+    it' testLocationStringWithoutProperFormatExample1 "locationStringWithoutProperFormatExample1 should return Nothing"
+    it' testLocationStringWithoutProperFormatExample2 "locationStringWithoutProperFormatExample2 should return Nothing"
+    it' testLocationStringWithoutProperFormatExample3 "locationStringWithoutProperFormatExample3 should return Nothing"
+    it' testPrologifyConstNull "prologify_ConstNull should render kb_const_null( <loc> )."
+    it' testPrologifyGatedReturn "prologify_GatedReturn should render kb_gated_return( <cond>, <ret> )."
+    it' testPrologifyMethodHasName "prologify_MethodHasName should render kb_method_has_name( <method>, '<name>' )."
+    it' testPrologifyFieldReadResolved "prologify_FieldReadResolved should render kb_field_read_resolved( <field read>, '<fqn>' )."
+    it' testPrologifyTopLevelIfThenElseGadget "prologify_TopLevelIfThenElseGadget should render kb_top_level_if_then_else_gadget( <callable>, <cond>, then_part_<cond>, else_part_<cond> )."
+    it' testPrologifyCallGuardedByCondInThenPart "prologify_CallGuardedByCondInThenPart should render kb_call_guarded_by_cond_in_then_part( <call>, <cond>, then_part_<cond> )."
+    it' testPrologifyCallGuardedByCondInElsePart "prologify_CallGuardedByCondInElsePart should render kb_call_guarded_by_cond_in_else_part( <call>, <cond>, else_part_<cond> )."
+
+runSmokeTests :: IO ()
+runSmokeTests = hspec tests
