Python Code Harmonizer – Semantic analysis for clean maintainable code

Hacker News

Share card

Python Code Harmonizer – Semantic analysis for clean maintainable code

I've built a tool that performs semantic analysis on Python code to detect inconsistencies between function intent and actual implementation. What it does: The tool analyzes your Python functions and identifies cases where: - Function names/documentation promise one type of operation - The actual code implementation does something different - There's a semantic gap between stated purpose and execution How it works: 1. Parses Python AST to extract function names, docstrings, and implementation logic 2. Uses semantic analysis to map both intent and execution to conceptual spaces 3. Measures the distance between these spaces to flag significant mismatches 4. Generates a report showing which functions have the largest intent-execution gaps Example findings: - A function named `calculate_score()` that actually just fetches cached values - A `validate_input()` function that secretly sends analytics data - A `update_user_prefs()` function that uses destructive delete/recreate patterns What else it provides: Team collaboration benefits: - Objective metrics for code review discussions - Clear evidence when renaming functions or refactoring - Shared vocabulary for discussing code quality beyond "this feels wrong" Code quality trending: - Track semantic consistency across versions - Measure improvement after refactoring efforts - Identify areas where documentation needs updating Architectural insights: - Spot patterns where certain concepts are consistently misrepresented - Identify modules with high semantic confusion density - Find where your codebase's actual architecture diverges from intended design Integration ready: - Simple CLI output for CI/CD pipelines - Machine-readable results for custom reporting - Extensible framework for adding new semantic rules