feat(cli iu): improvements to the cli UI, adding pre-commit hooks, updating documentation

Author: orenlab

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -62,4 +62,4 @@ body:
     id: notes
     attributes:
       label: Additional context
-      description: CFG structure, HTML screenshots, logs, etc.
+      description: CFG structure, HTML screenshots, logs, etc.

.github/ISSUE_TEMPLATE/cfg_semantics.yml

@@ -43,4 +43,4 @@ body:
     attributes:
       label: Desired CFG behavior
     validations:
-      required: true
+      required: true

.github/ISSUE_TEMPLATE/false_positive.yml

@@ -43,4 +43,4 @@ body:
     attributes:
       label: CFG-related?
       options:
-        - label: Control flow structure differs meaningfully
+        - label: Control flow structure differs meaningfully

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -43,4 +43,4 @@ body:
   - type: textarea
     id: alternatives
     attributes:
-      label: Alternatives considered
+      label: Alternatives considered

.github/actions/codeclone/README.md

@@ -8,4 +8,4 @@ Runs CodeClone to detect architectural code duplication in Python projects.
 - uses: orenlab/codeclone/.github/actions/codeclone@v1
   with:
     path: .
-    fail-on-new: true
+    fail-on-new: true

.github/actions/codeclone/action.yml

@@ -1,7 +1,7 @@
 name: CodeClone
 description: >
-  AST-based Python code clone detector focused on architectural duplication
-  and CI-friendly baseline enforcement.
+  Structural code quality analysis for Python with
+  CI-friendly baseline enforcement.
 
 author: OrenLab
 

.pre-commit-config.yaml

@@ -1,31 +1,55 @@
+default_install_hook_types: [ pre-commit, pre-push ]
+
 repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+      - id: check-toml
+      - id: check-yaml
+
   - repo: local
     hooks:
-      - id: ruff-check
-        name: Ruff (lint)
-        entry: ruff check .
+      - id: ruff-format
+        name: Ruff (format)
+        entry: ruff format .
         language: system
         pass_filenames: false
         types: [ python ]
+        stages: [ pre-commit ]
 
-      - id: ruff-format
-        name: Ruff (format)
-        entry: ruff format .
+      - id: ruff-check
+        name: Ruff (lint)
+        entry: ruff check .
         language: system
         pass_filenames: false
         types: [ python ]
+        stages: [ pre-commit ]
 
       - id: mypy
         name: Mypy
         entry: mypy .
         language: system
         pass_filenames: false
         types: [ python ]
+        stages: [ pre-commit ]
 
       - id: codeclone
         name: CodeClone
         entry: codeclone
         language: system
         pass_filenames: false
         args: [ ".", "--ci" ]
-        types: [ python ]
+        types: [ python ]
+        stages: [ pre-commit ]
+
+      - id: pytest
+        name: Pytest
+        entry: pytest -q
+        language: system
+        pass_filenames: false
+        types: [ python ]
+        stages: [ pre-push ]

AGENTS.md

@@ -28,12 +28,25 @@ It is optimized for **determinism**, **CI stability**, and **reproducible change
 5. **Golden tests are contract sentinels.**
     - Do not update golden snapshots to “fix” failing tests unless the contract change is intentional, versioned where
       required, documented, and explicitly approved.
+6. **Fingerprint-adjacent optimization policy**
+
+    - Performance work must not change AST normalization, fingerprint inputs, or clone identity semantics while
+      `FINGERPRINT_VERSION` remains unchanged.
+
+    - If a change in AST/core analysis can affect fingerprint bytes, clone identity, NEW vs KNOWN classification, or
+      baseline compatibility semantics, it is not a routine optimization. It must be treated as an explicit fingerprint
+      contract change and requires:
+        - `FINGERPRINT_VERSION` review or bump
+        - documentation updates
+        - migration/release notes
+        - explicit maintainer approval
+    - Performance alone is never a sufficient reason to change fingerprint semantics.
 
 ---
 
 ## 2) Quick orientation
 
-CodeClone is an AST/CFG-informed clone detector for Python. It supports:
+CodeClone provides structural code quality analysis for Python. It supports:
 
 - **function clones** (strongest signal)
 - **block clones** (sliding window of statements, may be noisy on boilerplate)

CHANGELOG.md

@@ -473,57 +473,57 @@ codeclone . --update-baseline
 
 ### Overview
 
-This release focuses on security hardening, robustness, and long-term maintainability.  
+This release focuses on security hardening, robustness, and long-term maintainability.
 No breaking API changes were introduced.
 
 The goal of this release is to provide users with a safe, deterministic, and CI-friendly
 tool suitable for security-sensitive and large-scale environments.
 
 ### Security & Robustness
 
-- **Path Traversal Protection**  
+- **Path Traversal Protection**
   Implemented strict path validation to prevent scanning outside the project root or
   accessing sensitive system directories, including macOS `/private` paths.
 
-- **Cache Integrity Protection**  
+- **Cache Integrity Protection**
   Added HMAC-SHA256 signing for cache files to prevent cache poisoning and detect tampering.
 
-- **Parser Safety Limits**  
+- **Parser Safety Limits**
   Introduced AST parsing time limits to mitigate risks from pathological or adversarial inputs.
 
-- **Resource Exhaustion Protection**  
+- **Resource Exhaustion Protection**
   Enforced a maximum file size limit (10MB) and a maximum file count per scan to prevent
   excessive memory or CPU usage.
 
-- **Structured Error Handling**  
+- **Structured Error Handling**
   Introduced a dedicated exception hierarchy (`ParseError`, `CacheError`, etc.) and replaced
   broad exception handling with graceful, user-friendly failure reporting.
 
 ### Performance Improvements
 
-- **Optimized AST Normalization**  
+- **Optimized AST Normalization**
   Replaced expensive `deepcopy` operations with in-place AST normalization, significantly
   reducing CPU and memory overhead.
 
-- **Improved Memory Efficiency**  
+- **Improved Memory Efficiency**
   Added an LRU cache for file reading and optimized string concatenation during fingerprint
   generation.
 
-- **HTML Report Memory Bounds**  
+- **HTML Report Memory Bounds**
   HTML reports now read only the required line ranges instead of entire files, reducing peak
   memory usage on large codebases.
 
 ### Architecture & Maintainability
 
-- **Strict Type Safety**  
+- **Strict Type Safety**
   Migrated all optional typing to Python 3.10+ `| None` syntax and achieved 100% `mypy` strict
   compliance.
 
-- **Modular CFG Design**  
+- **Modular CFG Design**
   Split CFG data structures and builder logic into separate modules (`cfg_model.py` and
   `cfg.py`) for improved clarity and extensibility.
 
-- **Template Extraction**  
+- **Template Extraction**
   Extracted HTML templates into a dedicated `templates.py` module.
 
 - Added a `py.typed` marker for downstream type checkers.
@@ -565,13 +565,13 @@ support for Python 3.10–3.14 across the test matrix.
 
 ### Fixed
 
-- **CFG Exception Handling**  
+- **CFG Exception Handling**
   Fixed incorrect control-flow linking for `try`/`except` blocks.
 
-- **Pattern Matching Support**  
+- **Pattern Matching Support**
   Added missing structural handling for `match`/`case` statements in the CFG.
 
-- **Block Detection Scaling**  
+- **Block Detection Scaling**
   Made `MIN_LINE_DISTANCE` dynamic based on block size to improve clone detection accuracy
   across differently sized functions.
 
@@ -581,7 +581,7 @@ support for Python 3.10–3.14 across the test matrix.
 
 ### BREAKING CHANGES
 
-- **CLI Arguments**  
+- **CLI Arguments**
   Renamed output flags for brevity and consistency:
     - `--json-out` → `--json`
     - `--text-out` → `--text`

CONTRIBUTING.md

@@ -2,8 +2,8 @@
 
 Thank you for your interest in contributing to **CodeClone**.
 
-CodeClone is an **AST + CFG-based code clone detector** focused on architectural duplication,
-not textual similarity.
+CodeClone provides **structural code quality analysis** for Python, including clone detection,
+quality metrics, and baseline-aware CI governance.
 
 Contributions are welcome — especially those that improve **signal quality**, **CFG semantics**,
 and **real-world CI usability**.