Added comments, moved report to models directory

Signed-off-by: JonahSussman <[email protected]>

Author: JonahSussman

example/run_demo.py

@@ -19,7 +19,7 @@
 # Ensure that we have 'kai' in our import path
 sys.path.append("../../kai")
 from kai.kai_logging import formatter
-from kai.report import Report
+from kai.models.report import Report
 
 KAI_LOG = logging.getLogger(__name__)
 

kai/evaluation.py

@@ -10,8 +10,8 @@
 from kai.constants import PATH_BENCHMARKS
 from kai.models.file_solution import guess_language, parse_file_solution_content
 from kai.models.kai_config import KaiConfig, KaiConfigIncidentStoreSQLiteArgs
+from kai.models.report import Report
 from kai.models.report_types import ExtendedIncident
-from kai.report import Report
 from kai.service.incident_store.backend import SQLiteBackend
 from kai.service.incident_store.incident_store import Application, IncidentStore
 from kai.service.kai_application.util import get_prompt

kai/hub_importer.py

@@ -15,7 +15,7 @@
 from pydantic import BaseModel, Field
 
 from kai.models.kai_config import KaiConfig
-from kai.report import Report
+from kai.models.report import Report
 from kai.service.incident_store import Application, IncidentStore
 from kai.service.kai_application.kai_application import KaiApplication
 

kai/models/kai_config.py

@@ -135,6 +135,8 @@ class KaiConfigModels(BaseModel):
 # Main config
 
 
+# TODO: Evaluate the usage of pydantic-settings to simplify environment variable
+# and command line argument management.
 class KaiConfig(BaseModel):
     log_level: str = "info"
     file_log_level: str = "info"

kai/report.py renamed to kai/models/report.py

@@ -146,11 +146,13 @@ def _write_markdown_snippet(
 
         for count, (key, items) in enumerate(ruleset.violations.items()):
             f.write(f"### #{count} - {key}\n")
-            # Break out below for violation
-            # Then we can weave in an example perhaps?
-            # Or should there be a Markdown class that is responsible for blending
-            # . - Report
-            # . - Per Violation create a prompt/run/example
+            # Break out below for violation. Then we can weave in an example
+            # perhaps?
+            #
+            # Or should there be a Markdown class that is responsible for
+            # blending:
+            #   - Report
+            #   - Per Violation create a prompt/run/example
 
             f.write(f"* Category: {items.category}\n")
             if items.effort is not None:
@@ -189,7 +191,10 @@ def get_violation_snippet(self, ruleset_name: str, violation_name: str):
         buffer.write("* Source of rules:")
 
     def should_we_skip_incident(self, incident: Incident) -> bool:
-        # Filter out known issues
+        """
+        Filter out known issues
+        """
+
         file_path = remove_known_prefixes(urlparse(incident.uri).path)
 
         if file_path.startswith("target/"):

kai/models/report_types.py

@@ -3,11 +3,15 @@
 import os
 from enum import StrEnum
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Optional
 
 import yaml
 from pydantic import AliasChoices, BaseModel, Field, RootModel
 
+"""
+Report types ripped straight from analyzer-lsp.
+"""
+
 
 class Category(StrEnum):
     potential = "potential"
@@ -16,6 +20,10 @@ class Category(StrEnum):
 
 
 class Incident(BaseModel):
+    """
+    An Incident is a specific instance of a rule being violated.
+    """
+
     # NOTE: `str` is the best equivalent of Go's `json.RawMessage`
     uri: str
 
@@ -38,14 +46,14 @@ class Incident(BaseModel):
         serialization_alias="lineNumber",
     )
 
-    variables: Dict[str, Any] = Field(
+    variables: dict[str, Any] = Field(
         {}, validation_alias=AliasChoices("variables", "incident_variables")
     )
 
 
 class ExtendedIncident(Incident):
     """
-    A "flattened" incident, containing its ruleset and violation names.
+    An Incident with extra metadata.
     """
 
     ruleset_name: str
@@ -54,29 +62,37 @@ class ExtendedIncident(Incident):
     violation_description: Optional[str] = None
 
 
-# Link defines an external hyperlink
 class Link(BaseModel):
+    """
+    Link defines an external hyperlink.
+    """
+
     url: str
 
     # Title optional description
     title: str = ""
 
 
 class Violation(BaseModel):
+    """
+    A Violation is a specific rule being broken, i.e. a rule being "violated".
+    It may have many different incidents throughout the codebase.
+    """
+
     # Description text description about the violation
     description: str = ""
 
     # Category category of the violation
     category: Category = "potential"
 
     # Labels list of labels for the violation
-    labels: List[str] = []
+    labels: list[str] = []
 
     # Incidents list of instances of violation found
-    incidents: List[Incident] = []
+    incidents: list[Incident] = []
 
     # ExternalLinks hyperlinks to external sources of docs, fixes, etc.
-    links: List[Link] = []
+    links: list[Link] = []
 
     # Extras reserved for additional data
     # NOTE: `str` is the best equivalent of Go's `json.RawMessage`
@@ -87,34 +103,44 @@ class Violation(BaseModel):
 
 
 class RuleSet(BaseModel):
+    """
+    A RuleSet is a collection of rules that are evaluated together. It different
+    data on its rules: which rules were unmatched, which rules where skipped,
+    and which rules generated errors or violations.
+    """
+
     # Name is a name for the ruleset.
     name: Optional[str] = None
 
     # Description text description for the ruleset.
     description: str = ""
 
     # Tags list of generated tags from the rules in this ruleset.
-    tags: Optional[List[str]] = None
+    tags: Optional[list[str]] = None
 
     # Violations is a map containing violations generated for the matched rules
     # in this ruleset. Keys are rule IDs, values are their respective generated
     # violations.
-    violations: Dict[str, Violation] = {}
+    violations: dict[str, Violation] = {}
 
     # Errors is a map containing errors generated during evaluation of rules in
     # this ruleset. Keys are rule IDs, values are their respective generated
     # errors.
-    errors: Optional[Dict[str, str]] = None
+    errors: Optional[dict[str, str]] = None
 
     # Unmatched is a list of rule IDs of the rules that weren't matched.
-    unmatched: Optional[List[str]] = None
+    unmatched: Optional[list[str]] = None
 
     # Skipped is a list of rule IDs that were skipped
-    skipped: Optional[List[str]] = None
+    skipped: Optional[list[str]] = None
+
 
+class AnalysisReport(RootModel[list[RuleSet]]):
+    """
+    An analysis report is simply a list of rule sets.
+    """
 
-class AnalysisReport(RootModel[List[RuleSet]]):
-    root: List[RuleSet] = Field(..., title="AnalysisReport")
+    root: list[RuleSet] = Field(..., title="AnalysisReport")
 
 
 def generate_json_schema():

kai/result.py

@@ -9,7 +9,7 @@
 
 from kai.constants import PATH_TEMPLATES
 
-from .report import Report
+from .models.report import Report
 from .scm import GitDiff
 
 KAI_LOG = logging.getLogger(__name__)

kai/routes/load_analysis_report.py

@@ -4,7 +4,7 @@
 from aiohttp.web_request import Request
 from pydantic import BaseModel
 
-from kai.report import Report
+from kai.models.report import Report
 from kai.routes.util import to_route
 from kai.service.incident_store.incident_store import Application
 

kai/server.py

@@ -16,7 +16,6 @@
 
 log = logging.getLogger(__name__)
 
-# TODO: Make openapi spec for everything
 
 # TODO: Repo lives both on client and on server. Determine either A) Best way to
 # rectify differences or B) Only have the code on one and pass stuff between

kai/service/incident_store/incident_store.py

@@ -14,8 +14,8 @@
 from kai.constants import PATH_GIT_ROOT, PATH_KAI, PATH_LOCAL_REPO
 from kai.kai_logging import initLogging
 from kai.models.kai_config import KaiConfig
+from kai.models.report import Report
 from kai.models.util import filter_incident_vars
-from kai.report import Report
 from kai.service.incident_store.backend import IncidentStoreBackend
 from kai.service.incident_store.sql_types import (
     SQLAcceptedSolution,
@@ -157,6 +157,7 @@ def load_reports_from_directory(store: "IncidentStore", path: str):
         KAI_LOG.info(f"Loaded application - solved {app}\n")
 
 
+# NOTE: This application object is more like metadata than anything.
 @dataclass
 class Application:
     application_name: str
@@ -186,10 +187,9 @@ def load_report(self, app: Application, report: Report) -> tuple[int, int, int]:
         tuple containing (# of new incidents, # of unsolved incidents, # of
         solved incidents) in that order.
 
-        NOTE: This application object is more like metadata than anything.
-        """
 
-        # FIXME: Only does stuff within the same application. Maybe fixed?
+        TODO: Only does stuff within the same application. Maybe fixed?
+        """
 
         # NEW: Store whole report in table
         # - if we get the same report again, we should skip adding it. Have some identifier
@@ -200,14 +200,6 @@ def load_report(self, app: Application, report: Report) -> tuple[int, int, int]:
         # Iterate through all incidents in the report
         # - change so theres an identified like "commit application ruleset violation"
 
-        # create entries if not exists
-        # reference the old-new matrix
-        #           old
-        #         | NO     | YES
-        # --------|--------+-----------------------------
-        # new NO  | -      | update (SOLVED, embeddings)
-        #     YES | insert | update (line number, etc...)
-
         repo = Repo(unquote(urlparse(app.repo_uri_local).path))
         old_commit: str
         new_commit = app.current_commit
@@ -304,15 +296,24 @@ def load_report(self, app: Application, report: Report) -> tuple[int, int, int]:
 
             categorized_incidents = self.solution_detector(solution_detector_ctx)
 
-            for new_incident in categorized_incidents.new:
-                session.add(new_incident)
+            # create entries if not exists
+            #           old
+            #         | NO     | YES
+            # --------|--------+-----------------------------
+            # new NO  | -      | update (SOLVED, embeddings)
+            #     YES | insert | update (line number, etc...)
 
+            # Add new incidents
+
+            session.add_all(categorized_incidents.new)
             session.commit()
 
             KAI_LOG.debug(
                 f"Number of solved incidents: {len(categorized_incidents.solved)}"
             )
 
+            # Update solved incidents with their respective solutions
+
             for solved_incident in categorized_incidents.solved:
                 solution = self.solution_producer.produce_one(
                     solved_incident, repo, old_commit, new_commit