packages feed

dhscanner-kbgen 2.5.0 → 2.6.0

raw patch · 3 files changed

+168/−100 lines, 3 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

+ Kbgen: FieldName :: String -> FieldName
+ Kbgen: FieldReadOf1stPartyImportedName :: FieldRead -> FieldName -> ImportedName -> ImportedFromFile -> FieldReadOf1stPartyImportedName
+ Kbgen: FieldReadOf1stPartyImportedNameCtor :: FieldReadOf1stPartyImportedName -> Fact
+ Kbgen: data FieldName
+ Kbgen: data FieldReadOf1stPartyImportedName
+ Kbgen: instance Data.Aeson.Types.FromJSON.FromJSON Kbgen.FieldName
+ Kbgen: instance Data.Aeson.Types.FromJSON.FromJSON Kbgen.FieldReadOf1stPartyImportedName
+ Kbgen: instance Data.Aeson.Types.ToJSON.ToJSON Kbgen.FieldName
+ Kbgen: instance Data.Aeson.Types.ToJSON.ToJSON Kbgen.FieldReadOf1stPartyImportedName
+ Kbgen: instance GHC.Internal.Classes.Eq Kbgen.FieldName
+ Kbgen: instance GHC.Internal.Classes.Eq Kbgen.FieldReadOf1stPartyImportedName
+ Kbgen: instance GHC.Internal.Classes.Ord Kbgen.FieldName
+ Kbgen: instance GHC.Internal.Classes.Ord Kbgen.FieldReadOf1stPartyImportedName
+ Kbgen: instance GHC.Internal.Generics.Generic Kbgen.FieldName
+ Kbgen: instance GHC.Internal.Generics.Generic Kbgen.FieldReadOf1stPartyImportedName
+ Kbgen: instance GHC.Internal.Show.Show Kbgen.FieldName
+ Kbgen: instance GHC.Internal.Show.Show Kbgen.FieldReadOf1stPartyImportedName

Files

dhscanner-kbgen.cabal view
@@ -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.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
+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.6.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
src/Kbgen.hs view
@@ -60,6 +60,7 @@     AssignValueToToplevelVarName(..),
     Call1stPartyFuncDefinedInFile(..),
     CallMethodOf1stPartyImportedName(..),
+    FieldReadOf1stPartyImportedName(..),
     ImportedName(..),
     ImportedFromFile(..),
     ParamName(..),
@@ -111,6 +112,7 @@     ParamIndex(..),
     FuncName(..),
     MethodName(..),
+    FieldName(..),
     ResolvedType(..),
     CallResolved(..),
     FieldReadResolved(..),
@@ -452,6 +454,55 @@     ImportedFromFile -- ^
     deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
 
+-- |
+--
+-- __Name__
+--
+-- This is how the fact will look inside the Prolog file
+--
+-- @
+-- kb_field_read_of_1st_party_imported_name( FieldRead, Field, Name, File ).
+-- @
+--
+-- __When should I use this fact__
+--
+-- A field read on a name imported from a 1st party file : the field read
+-- counterpart of 'CallMethodOf1stPartyImportedName'. @Name@ is the imported
+-- name, @File@ the file that defines it ( the same spelling as in 'ClassDef' ).
+--
+-- @
+-- // routes/web.php
+-- use App\\Http\\Controllers\\UserController;
+-- ...
+-- Route::post( \'/studio/theme\', [ UserController::class, \'editTheme\' ] );
+-- @
+--
+-- @
+-- kb_field_read_of_1st_party_imported_name( FieldRead, \'class\', \'UserController\', \'app/Http/Controllers/UserController.php\' ).
+-- @
+--
+-- Only one member deep : @Name.f@. A field read rooted at a 3rd party
+-- import is a 'FieldReadResolved' fact.
+--
+-- __Writing a predicate with this fact and others__
+--
+-- @
+-- php_class_of_class_constant( FieldRead, Class ) :-
+--     kb_field_read_of_1st_party_imported_name( FieldRead, \'class\', Name, File ),
+--     kb_class_def( Class, Name, File ).
+-- @
+--
+-- Other facts combined in this predicate:
+--
+--     * 'ClassDef'
+--
+data FieldReadOf1stPartyImportedName = FieldReadOf1stPartyImportedName
+    FieldRead -- ^
+    FieldName -- ^
+    ImportedName -- ^
+    ImportedFromFile -- ^
+    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
+
 data AssignValueToToplevelVarName = AssignValueToToplevelVarName
     AssignedValue -- ^
     Token.VarName -- ^
@@ -1428,6 +1479,7 @@ 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 FieldName = FieldName 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 )
 
@@ -1486,6 +1538,7 @@    | Call1stPartyFuncDefinedInDirCtor Call1stPartyFuncDefinedInDir
    | Call1stPartyFuncDefinedInFileCtor Call1stPartyFuncDefinedInFile
    | CallMethodOf1stPartyImportedNameCtor CallMethodOf1stPartyImportedName
+   | FieldReadOf1stPartyImportedNameCtor FieldReadOf1stPartyImportedName
    | CallMethodOfUntypedNamedParamCtor CallMethodOfUntypedNamedParam
    deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )
 
@@ -1534,6 +1587,7 @@ prologify (Call1stPartyFuncDefinedInDirCtor content) = prologify_Call1stPartyFuncDefinedInDir content
 prologify (Call1stPartyFuncDefinedInFileCtor content) = prologify_Call1stPartyFuncDefinedInFile content
 prologify (CallMethodOf1stPartyImportedNameCtor content) = prologify_CallMethodOf1stPartyImportedName content
+prologify (FieldReadOf1stPartyImportedNameCtor content) = prologify_FieldReadOf1stPartyImportedName content
 prologify (CallMethodOfUntypedNamedParamCtor content) = prologify_CallMethodOfUntypedNamedParam content
 
 prologify_ParamResolvedType' :: Location -> String -> String
@@ -1720,6 +1774,10 @@ 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_FieldReadOf1stPartyImportedName :: FieldReadOf1stPartyImportedName -> String
+prologify_FieldReadOf1stPartyImportedName (FieldReadOf1stPartyImportedName (FieldRead r) (FieldName field) (ImportedName name) (ImportedFromFile f)) =
+    printf "kb_field_read_of_1st_party_imported_name( %s, \'%s\', \'%s\', \'%s\' )." (locationify r) (quoted field) (quoted name) (quoted f)
 
 prologify_Call1stPartyFuncDefinedInDir :: Call1stPartyFuncDefinedInDir -> String
 prologify_Call1stPartyFuncDefinedInDir (Call1stPartyFuncDefinedInDir call func d) = prologify_Call1stPartyFuncDefinedInDir' call func d
test/SmokeTests.hs view
@@ -3,6 +3,8 @@ import Kbgen
     ( Call (..)
     , CallMethodOf1stPartyImportedName (..)
+    , FieldReadOf1stPartyImportedName (..)
+    , FieldName (..)
     , CallResolved (..)
     , ImportedFromFile (..)
     , ImportedName (..)
@@ -180,6 +182,13 @@         expected = "kb_call_method_of_1st_party_imported_name( " ++ locationify callLoc ++ ", 'normalize', 'PathUtil', 'util/PathUtil.java' )."
     in prologify (CallMethodOf1stPartyImportedNameCtor c) `shouldBe` expected
 
+testPrologifyFieldReadOf1stPartyImportedName :: IO ()
+testPrologifyFieldReadOf1stPartyImportedName =
+    let readLoc = sampleLoc 1
+        r = FieldReadOf1stPartyImportedName (FieldRead readLoc) (FieldName "class") (ImportedName "UserController") (ImportedFromFile "app/Http/Controllers/UserController.php")
+        expected = "kb_field_read_of_1st_party_imported_name( " ++ locationify readLoc ++ ", 'class', 'UserController', 'app/Http/Controllers/UserController.php' )."
+    in prologify (FieldReadOf1stPartyImportedNameCtor r) `shouldBe` expected
+
 -- a capitalized method name ( C# ) must not read as a Prolog variable
 testPrologifyCallResolvedMethodOfClassQuoted :: IO ()
 testPrologifyCallResolvedMethodOfClassQuoted =
@@ -212,6 +221,7 @@     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' testPrologifyFieldReadOf1stPartyImportedName "prologify_FieldReadOf1stPartyImportedName should render kb_field_read_of_1st_party_imported_name( <field read>, '<field>', '<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"