Merge pull request #69 from BruinGrowly/cursor/harmonize-and-improve-codebase-5508

Harmonize and improve codebase

Author: BruinGrowly

CI_VERIFICATION_REPORT.md

@@ -16,12 +16,18 @@ def check_harmony(
     print(f"Running LJPW Harmony Check on: {os.path.abspath(target_dir)}")
     print("=" * 60)
 
-    # Load config explicitly if provided, otherwise auto-load
-    # Note: LegacyCodeMapper loads config automatically from target_dir,
-    # but if we want to override with a specific file, we might need to adjust ConfigLoader.
-    # For now, we'll rely on auto-loading from target_dir.
-
+    # If analyzing a subdirectory, find project root for config
+    # Otherwise use target_dir
+    project_root = os.getcwd() if target_dir != "." else target_dir
+    
+    # Create mapper - it will load config from project_root
     mapper = LegacyCodeMapper(target_dir, quiet=not verbose)
+    
+    # If we're in project root, use config from there
+    if os.path.exists(os.path.join(project_root, "pyproject.toml")):
+        from harmonizer.config import ConfigLoader
+        mapper.config = ConfigLoader.load(project_root)
+    
     mapper.analyze_codebase(show_progress=True)
 
     failures = []

CODEBASE_IMPROVEMENT_REPORT.md

@@ -23,6 +23,12 @@ class AST_Semantic_Parser(ast.NodeVisitor):
     """
     A "Rosetta Stone" that translates Python AST nodes into
     DIVE-V2 conceptual keywords.
+
+    This parser walks through Python's Abstract Syntax Tree and categorizes
+    code constructs into semantic dimensions (Love, Justice, Power, Wisdom).
+
+    Note: Visitor methods don't "visit" in the semantic sense - they record
+    and categorize AST nodes into semantic concepts for later analysis.
     """
 
     def __init__(self, vocabulary: Set[str]):
@@ -109,9 +115,7 @@ def _map_word_to_concept(self, word: str) -> Optional[str]:
                 return concept
         return None
 
-    def get_intent_concepts(
-        self, function_name: str, docstring: Optional[str]
-    ) -> List[str]:
+    def get_intent_concepts(self, function_name: str, docstring: Optional[str]) -> List[str]:
         """
         Parses the function's name and docstring to find its "Stated Purpose" (Intent).
         """
@@ -131,9 +135,7 @@ def get_intent_concepts(
             return [word for word in name_words if word in self.known_vocabulary]
         return list(concepts)
 
-    def get_execution_map(
-        self, body: List[ast.AST]
-    ) -> Tuple[Dict[ast.AST, str], List[str]]:
+    def get_execution_map(self, body: List[ast.AST]) -> Tuple[Dict[ast.AST, str], List[str]]:
         """
         Parses the function's body to map each AST node to a semantic dimension
         and return the list of concepts found.
@@ -150,7 +152,13 @@ def _add_concept(self, node: ast.AST, concept: str):
         self._node_map[node] = concept
         self._concepts_found.add(concept)
 
-    def visit_Call(self, node: ast.Call):
+    def visit_Call(self, node: ast.Call) -> None:
+        """
+        Records function/method calls and categorizes them semantically.
+
+        Maps method names to semantic dimensions (e.g., 'execute' -> Power,
+        'validate' -> Justice, 'get' -> Wisdom).
+        """
         concept = None
         if isinstance(node.func, ast.Attribute):
             method_name = node.func.attr
@@ -171,36 +179,83 @@ def visit_Call(self, node: ast.Call):
             self._add_concept(node, concept)
         self.generic_visit(node)
 
-    def visit_If(self, node: ast.If):
+    def visit_If(self, node: ast.If) -> None:
+        """
+        Records If statements as Justice concepts (control flow/decision-making).
+
+        If statements enforce conditions and control execution flow, which
+        aligns with Justice (rules, structure, enforcement).
+        """
         self._add_concept(node, "justice")
         self.generic_visit(node)
 
-    def visit_Assert(self, node: ast.Assert):
+    def visit_Assert(self, node: ast.Assert) -> None:
+        """
+        Records Assert statements as Justice concepts (validation/enforcement).
+
+        Assertions enforce invariants and preconditions, directly representing
+        Justice principles of validation and rule enforcement.
+        """
         self._add_concept(node, "justice")
         self.generic_visit(node)
 
-    def visit_Try(self, node: ast.Try):
+    def visit_Try(self, node: ast.Try) -> None:
+        """
+        Records Try-Except blocks with dual semantics.
+
+        Try blocks represent Justice (structural error handling), while
+        exception handlers represent Love (mercy, graceful recovery).
+        """
         self._add_concept(node, "justice")
         if node.handlers:
             self._add_concept(node.handlers[0], "love")
         self.generic_visit(node)
 
-    def visit_Raise(self, node: ast.Raise):
+    def visit_Raise(self, node: ast.Raise) -> None:
+        """
+        Records Raise statements as Power concepts (forceful action).
+
+        Raising exceptions is an active, forceful interruption of normal
+        flow, representing Power (control, force, action).
+        """
         self._add_concept(node, "power")
         self.generic_visit(node)
 
-    def visit_For(self, node: ast.For):
+    def visit_For(self, node: ast.For) -> None:
+        """
+        Records For loops as Justice concepts (structured iteration).
+
+        For loops impose structure and order on iteration, representing
+        Justice (rules, patterns, systematic processing).
+        """
         self._add_concept(node, "justice")
         self.generic_visit(node)
 
-    def visit_While(self, node: ast.While):
+    def visit_While(self, node: ast.While) -> None:
+        """
+        Records While loops as Justice concepts (conditional iteration).
+
+        While loops enforce conditions for continued iteration, representing
+        Justice (rules, enforcement, conditional control).
+        """
         self._add_concept(node, "justice")
         self.generic_visit(node)
 
-    def visit_Return(self, node: ast.Return):
+    def visit_Return(self, node: ast.Return) -> None:
+        """
+        Records Return statements as Wisdom concepts (providing results).
+
+        Return statements deliver computed results or knowledge back to
+        callers, representing Wisdom (information, knowledge transfer).
+        """
         self._add_concept(node, "wisdom")
         self.generic_visit(node)
 
-    def generic_visit(self, node: ast.AST):
-        """This is the default visitor that just continues the walk."""
+    def generic_visit(self, node: ast.AST) -> None:
+        """
+        Default visitor that continues traversing the AST.
+
+        This method is called for AST node types that don't have
+        specific visitor methods defined.
+        """
         super().generic_visit(node)

IMPROVEMENTS_IMPLEMENTED.md

@@ -21,8 +21,8 @@
 from typing import Dict, List, Optional, Set, Tuple
 
 from harmonizer.programming_constructs_vocabulary import (
-    PROGRAMMING_VERBS,
     COMPOUND_PATTERNS,
+    PROGRAMMING_VERBS,
 )
 
 
@@ -73,9 +73,7 @@ def _split_name(self, name: str) -> List[str]:
         else:
             return self._split_camel_case(name)
 
-    def _map_word_to_concept(
-        self, word: str, context: str = "default"
-    ) -> Optional[str]:
+    def _map_word_to_concept(self, word: str, context: str = "default") -> Optional[str]:
         """
         Map a word to its semantic dimension.
 
@@ -121,9 +119,7 @@ def _check_compound_pattern(self, words: List[str]) -> Optional[str]:
                     return COMPOUND_PATTERNS[compound]
         return None
 
-    def get_intent_concepts(
-        self, function_name: str, docstring: Optional[str]
-    ) -> List[str]:
+    def get_intent_concepts(self, function_name: str, docstring: Optional[str]) -> List[str]:
         """
         Parse function name and docstring to extract semantic intent.
 
@@ -158,15 +154,11 @@ def get_intent_concepts(
 
         # Fallback to words in vocabulary
         if not concepts and name_words:
-            concepts.update(
-                [word for word in name_words if word in self.known_vocabulary]
-            )
+            concepts.update([word for word in name_words if word in self.known_vocabulary])
 
         return list(concepts)
 
-    def get_execution_map(
-        self, body: List[ast.AST]
-    ) -> Tuple[Dict[ast.AST, str], List[str]]:
+    def get_execution_map(self, body: List[ast.AST]) -> Tuple[Dict[ast.AST, str], List[str]]:
         """
         Parse function body to map AST nodes to semantic dimensions.
 

check_harmony.py

@@ -5,7 +5,7 @@
 
 import os
 from dataclasses import dataclass, field
-from typing import List, Dict, Any
+from typing import Any, Dict, List
 
 # Try to import tomli for TOML parsing
 try: