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 +100/−100
- src/Kbgen.hs +58/−0
- test/SmokeTests.hs +10/−0
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"