Refactor: Extract CoordinateUtils and improve AST parser

Co-authored-by: taurekaw <taurekaw@gmail.com>

Author: cursoragent

IMPROVEMENTS_IMPLEMENTED.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]):
@@ -150,7 +156,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 +183,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)

harmonizer/ast_semantic_parser.py

@@ -21,8 +21,8 @@
 from typing import Dict, List, Optional, Set, Tuple
 
 from harmonizer.programming_constructs_vocabulary import (
-    PROGRAMMING_VERBS,
     COMPOUND_PATTERNS,
+    PROGRAMMING_VERBS,
 )
 
 

harmonizer/ast_semantic_parser_v2.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: