feat: Add prompt files for AST, CFG, Dataflow, TaintTracking, and Variables

Author: GeekMasher

.github/prompts/ast.prompt.md

@@ -0,0 +1,101 @@
+---
+mode: 'agent'
+---
+
+Given a AST class or set of classes, update and implement both the public and internal classes.
+
+**Guidelines:**
+
+- Always check the CodeQL TreeSitter.qll implementation first when checking the internal implementation to ensure consistency with the AST implementation.
+- Update the AST Node Type if necessary, following the guidelines in the "AST Nodes Types" section.
+- Always check and update the internal implementations of classes before updating the public classes.
+- Internal implementations should never return the TreeSitter class directly, always import and use `Impl` types.
+
+## Read TreeSitter Implementation
+
+Before implementing any AST classes or predicates, you should first read the CodeQL `TreeSitter.qll` implementation.
+This will help understand how the AST classes are implemented and how they relate to the TreeSitter implementation.
+The TreeSitter implementation is stored in the `TreeSitter.qll` file in the `ql/lib/codeql/bicep/ast/internal` directory.
+
+## AST Nodes Types
+
+If you are asked to update the AstNode type to include a new type, you should follow the guidelines below.
+
+- Read the `AstNodes.qll` file in the `ql/lib/codeql/bicep/ast/internal` directory to understand how the AstNode type is implemented.
+- SuperTypes are `TExpr`, `TStmts`, `TCallable`, `TLiterals`, `TConditionals`, etc.
+- Add the AST Node Type (e.g. `T${AstNode}`) to the SuperType
+- Update the `AstNodes.qll` file to include the new type.
+- Ensure that the new type is consistent with the existing types in the `AstNodes.qll` file
+
+**Example:**
+
+```codeql
+class TExpr = ${AstNode1} or ${AstNode2} or ${AstNode3} or ...;
+```
+
+## Internal Abstract Syntax Tree Implementation
+
+If you are asked to implementation any internal AstNode classes or predicates, you should follow the guidelines below.
+Internal classes and predicates should be stored in the `ql/lib/codeql/bicep/ast/internal/${AST_NODE}.qll` directory.
+
+The following rules should be followed when implementing AST classes and predicates:
+
+- Internal implementations should never return the TreeSitter class directly, always import and use `Impl` types
+- All internal classes should extend a SuperType class which can be found in `ast/internal/${SuperType}.qll` file.
+  - If the SuperType isn't known, check the `internal/AstNodes.qll`
+- Core logic should be in the internal class and reflected in the public facing class
+- Used named prediates the Tree Sitter class should be used in the internal implementation.
+  - If only `getChild(i)` is avalible, look at the Tree Sitter grammar and check which possition the field is in.
+- Include all of the correct imports for Impl classes
+- Convert TreeSitter classes to CodeQL classes by using the `toTreeSitter()` method.
+  - Example: `toTreeSitter(result) = ast.<TreeSitterPredicate>()`
+- Internal classes can call prediates from the `ast` by using the `toTreeSitter(result) = ast.<predicate>()` syntax.
+- Update internal implemention to directly use predicates from Tree Sitter module by using the ast in the class
+- include import statements for Impl classes, excluding the `Impl`
+  - For example: `private import ${CLASS}`
+
+**Example getting name field in the TreeSitter module:**
+
+```codeql
+class ${AstNode}Impl extends ${AstNodeSuperType} {
+  private Bicep::${TREESITTER_NODE} ast;
+  
+  ${ReturnType}Impl <predicate_name>() {
+    toTreeSitter(result) = ast.get<name>()
+ }
+}
+```
+
+## Public Abstract Syntax Tree Implementation
+
+The public user facing classes and predicates should be implemented in the `ql/lib/codeql/bicep/ast/${AST_NODE}.qll` directory.
+The public classes and predicates should follow the guidelines below:
+
+- Public classes should extend a base class such as:
+  - `Expr`: for expressions
+  - `Literals`: literals in the language
+  - `Stmts`: statements in the language
+  - `Calls`: for function / method calls
+  - `Callable`: for functions, methods, and lambdas definitions
+  - `Conditionals`: for if, switch, and other conditional statements
+- Public classes should use `instanceof ${AstNode}Impl` to check if the internal implementation is used.
+- Implement all abstract predicates from the base class
+- Predicates that are defined in the internal implementation should be used in the public implementation.
+  - Using the `${AstNode}Impl.super.${predicate}` syntax.
+  - Example: `Type getType() { result = TypeImpl.super.getType() }
+- Public classes should be in the base class 
+- Public classes should define a `getAPrimaryQlClass()` predicate that returns the primary CodeQL class name.
+- Public classes should define a `toString()` predicate that returns a string representation of the class.
+- All public classes and predicates should be documented with examples and descriptions.
+
+**Example:**
+
+```codeql
+class ${AstNode} extends Expr instanceof ${AstNode}Impl {
+
+  /** Returns the name of the AST node. */
+  ${ReturnType} <predicate_name>() {
+    result = ${AstNode}Impl.super.<predicate_name>();
+  }
+}
+```

.github/prompts/cfg.prompt.md

@@ -0,0 +1,138 @@
+---
+mode: 'agent'
+---
+
+Given a AST class or set of classes, create the various CFG related classes.
+This includes the following:
+- ControlFlowGraphImpl Tree class
+- CfgNodes classes for each AST Node
+
+**Guidelines:**
+
+- Classify the AST class into the appropriate Control Flow Graph (CFG) class.
+- Implement the `ControlFlowGraphImpl.qll` class if it does not exist.
+- Implement the `CfgNodes` classes for each AST Node, ensuring that they follow the naming conventions and structure outlined below.
+- All ControlFlowGraph Tree classes should be in the `ControlFlowGraphImpl.qll` file.
+- All CfgNodes classes should be in the `CfgNodes.qll` file.
+
+## Reading AST Implementaion
+
+All public AST classes are are in the `ql/lib/codeql/bicep/ast/*.qll` files.
+Read the classes implementation and documentation to understand the structure and relationships of the AST nodes.
+
+## Classification
+
+The AST classes should be classified into the following categories based on their structure and relationships:
+
+- **LeafTree**:
+  - AST nodes that do not have children, such as literals and identifiers.
+- **StandardPostOrderTree**:
+  - AST nodes that are traversed in a post-order manner
+- **PreOrderTree**:
+  - AST nodes that are traversed in a pre-order manner, meaning the node itself is visited before its children.
+- **PostOrderTree**:
+  - AST nodes that are traversed in a post-order manner,
+
+Once the classification is done, the appropriate Control Flow Graph (CFG) class should be created.
+
+## Control Flow Graph Implementaion
+
+If you are asked to implement any Control Flow Graph (CFG) classes or predicates, you should follow the guidelines below.
+The Control Flow Graph (CFG) is a representation of all paths that might be traversed through a program during its execution.
+The Control Flow Graph library is in `ql/lib/codeql/**/controlflow/internal/ControlFlowGraphImpl.qll`
+
+An AST node can only be represented as a single Control Flow Graph node class.
+All Control Flow Graph node classes should have a suffix of `Tree` to indicate that they are part of the Control Flow Graph library.
+Example classes include `ExprTree`, `StmtsTree`, and `ProgramTree`.
+
+Use the `first()` and `last()` predicates to indicate the first and last nodes in the control flow.
+
+### CFG LeafTree Nodes
+
+The LeafTree Nodes are a part of the Control Flow Graph library and represent an end nodes in the CFG.
+LeafTree Nodes are used to represent nodes in the CFG that do not have any children, meaning they are the end points of a path in the graph.
+
+All Literals AST types are represented as LeafTree Nodes.
+
+### CFG StandardPostOrderTree Nodes
+
+The StandardPostOrderTree Nodes are a part of the Control Flow Graph library and represent the nodes in the CFG that are traversed in a post-order manner.
+StandardPostOrderTree Nodes are used to represent nodes in the CFG that are traversed in a post-order manner, meaning that the children of a node are visited before the node itself.
+
+Expressions and statements in the CFG are represented as StandardPostOrderTree Nodes.
+
+If an expression or statement uses a predicate for accessing its children it should be used.
+If an expression or statement does not have a predicate for accessing its children, the `getChild(i)` method should be used to access the children.
+
+The following predicates should be implemented and overrided:
+- `override AstNode getChildNode(int i)`
+  - to get the child node at index `i`.
+  - result should be the child node at index `i`.
+  - If a node has multiple nodes, add the children in the order of execution in a Bicep program
+
+**StandardPostOrderTree Class Example:**
+
+```codeql
+class ${AstNode}Tree extends StandardPostOrderTree instanceof ${AstNode} {
+  override AstNode getChildNode(int i) {
+    i = 0 and result = super.getAChild()
+  }
+}
+```
+
+### CFG PreOrderTree Nodes
+
+The PreOrderTree Nodes are a part of the Control Flow Graph library and represent the nodes in the CFG that are traversed in a pre-order manner.
+PreOrderTree Nodes are used to represent nodes in the CFG that are traversed in a pre-order manner, meaning that the node itself is visited before its children.
+
+The following predicates should be implemented and overrided:
+
+- `final override predicate propagatesAbnormal(AstNode child)`
+  - to indicate if the node propagates abnormal control flow to its child.
+  - child should be matched with the child node of the AST node.
+- `override predicate succ(AstNode pred, AstNode succ, Completion c)`
+  - to indicate the successor of the node.
+  - `pred` should be the predecessor node.
+  - `succ` should be the successor node.
+  - `c` should be the completion of the successor node.
+- `override predicate last(AstNode node, Completion c)`
+  - to indicate if the node is the last node in the control flow.
+  - `node` should be the node to check.
+  - `c` should be the completion of the node.
+
+**PreOrderTree Class Example:**
+
+```codeql
+class ${AstNode}Tree extends PreOrderTree instanceof ${AstNode} {
+  final override predicate propagatesAbnormal(AstNode child) { child = super.getIdentifier() }
+
+  override predicate succ(AstNode pred, AstNode succ, Completion c) {
+    // Start with the identifier
+    pred = this and first(super.getIdentifier(), succ) and completionIsSimple(c)
+    or
+    last(super.getIdentifier(), pred, c) and first(super.getDefaultValue(), succ) and completionIsNormal(c)
+  }
+
+  override predicate last(AstNode node, Completion c) {
+    node = super.getDefaultValue() and completionIsNormal(c)
+  }
+}
+```
+
+Check and validate if a CFG Tree class is present in the `ControlFlowGraphImpl.qll` file.
+If on Tree class is not present, implement the class for the desired node.
+
+## CfgNodes Implementaion
+
+Check and validate if the `${AstNode}ChildMapping` or `${AstNode}CfgNode` classes are in the `CfgNodes.qll` file.
+Exprs and Stmts should be under there modules such as `ExprNodes` and `StmtsNodes`. 
+All CfgNodes classes either end with `CfgNode` or `ChildMapping`.
+
+For Expr based AST Nodes:
+- Create a `ChildMapping` abstract class inheriting both `ExprChildMapping` and `${AstNode}`
+  - Override the `relevantChild(AstNode n)` prediate
+- Create a class called `${AstNode}CfgNode` which extends the `ExprCfgNode`
+  - override `e` with the `${AstNode}ChildMapping`
+  - implement `final override ${AstNode} getExpr() { result = super.getExpr() }
+
+All Expr's with Left and Right Operations, implement final predicates returning `ExprCfgNode`