traceclip 0.1.0__tar.gz

traceclip-0.1.0/.github/workflows/detector_tests.yml

@@ -0,0 +1,34 @@
+name: Detector Tests
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    name: Run Detector Unit Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.10", "3.12"]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+
+    - name: Install package and dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+
+    - name: Run Detector Tests
+      run: |
+        python -m unittest tests/test_detector.py

traceclip-0.1.0/.github/workflows/performance_tests.yml

@@ -0,0 +1,34 @@
+name: Performance Tests
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    name: Run Performance Stress Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.10", "3.12"]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+
+    - name: Install package and dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+
+    - name: Run Performance Tests
+      run: |
+        python -m unittest tests/test_performance.py

traceclip-0.1.0/.github/workflows/test_cross-os.yml

@@ -0,0 +1,50 @@
+name: TraceClip CI/CD
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test:
+    name: Test on ${{ matrix.os }} with Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false # If Windows fails, let Ubuntu finish running so you can see all errors
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+    - name: Checkout Code
+      uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip' # Caches dependencies to speed up the workflow
+        
+    - name: Install Dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest pytest-cov
+        pip install -e .
+        
+    # CRITICAL: Headless Linux servers don't have a UI or clipboard by default.
+    # We install xclip and a virtual display (xvfb) so pyperclip doesn't instantly crash.
+    - name: Setup Headless Display for Linux Clipboard
+      if: runner.os == 'Linux'
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y xclip xvfb
+        
+    - name: Run Pytest (Linux)
+      if: runner.os == 'Linux'
+      # We use xvfb-run to simulate a screen for the clipboard
+      run: xvfb-run pytest --cov=traceclip -v
+      
+    - name: Run Pytest (Windows & macOS)
+      if: runner.os != 'Linux'
+      run: pytest --cov=traceclip -v

traceclip-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prakhar Bhardwaj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

traceclip-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: traceclip
+Version: 0.1.0
+Summary: A fast, local linting wrapper specifically designed for AI-generated code.
+Project-URL: Homepage, https://github.com/Prakhar3801b/Traceclip
+Project-URL: Repository, https://github.com/Prakhar3801b/Traceclip
+Project-URL: Bug Tracker, https://github.com/Prakhar3801b/Traceclip/issues
+Author-email: Prakhar Bhardwaj <bhardwajprakhar02@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,chatgpt,code-quality,copilot,linter,sanitizer,vibecheck
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.8
+Requires-Dist: rich>=12.0.0
+Description-Content-Type: text/markdown
+
+# Traceclip (vibecheck) 🧼
+
+**Traceclip** is a fast, local code sanitizer and linter designed specifically to prune and inspect AI-generated code. 
+
+Rather than enforcing pedantic style formats like traditional linters, `vibecheck` hunts down common AI developer artifacts and "hallucinations":
+- 🚫 **Unused Imports**: Bloat imported by AI but never referenced.
+- 🪦 **Dead Functions**: Functions generated by the AI that are defined but never called or referenced.
+- 🔑 **Placeholder Variables & Secrets**: Hardcoded templates like `API_KEY = "your_key_here"` or `URL = "https://example.com/api"`.
+- 🕳️ **Stub Implementations**: Empty functions with only `pass`, `...`, or `raise NotImplementedError`.
+
+It grades your script with a **Vibe Score** (out of 100). If your score drops too low, it fails!
+
+---
+
+## Installation
+
+Inside the project directory, run:
+```bash
+pip install -e .
+```
+
+## Usage
+
+Check a script:
+```bash
+vibecheck my_script.py
+```
+
+Check multiple files or directories:
+```bash
+vibecheck src/ tests/
+```
+
+Automatically sanitize and fix issues:
+```bash
+vibecheck my_script.py --fix
+```
+
+Enforce a minimum vibe score (ideal for CI/CD):
+```bash
+vibecheck my_script.py --min-score 80
+```

traceclip-0.1.0/README.md

@@ -0,0 +1,42 @@
+# Traceclip (vibecheck) 🧼
+
+**Traceclip** is a fast, local code sanitizer and linter designed specifically to prune and inspect AI-generated code. 
+
+Rather than enforcing pedantic style formats like traditional linters, `vibecheck` hunts down common AI developer artifacts and "hallucinations":
+- 🚫 **Unused Imports**: Bloat imported by AI but never referenced.
+- 🪦 **Dead Functions**: Functions generated by the AI that are defined but never called or referenced.
+- 🔑 **Placeholder Variables & Secrets**: Hardcoded templates like `API_KEY = "your_key_here"` or `URL = "https://example.com/api"`.
+- 🕳️ **Stub Implementations**: Empty functions with only `pass`, `...`, or `raise NotImplementedError`.
+
+It grades your script with a **Vibe Score** (out of 100). If your score drops too low, it fails!
+
+---
+
+## Installation
+
+Inside the project directory, run:
+```bash
+pip install -e .
+```
+
+## Usage
+
+Check a script:
+```bash
+vibecheck my_script.py
+```
+
+Check multiple files or directories:
+```bash
+vibecheck src/ tests/
+```
+
+Automatically sanitize and fix issues:
+```bash
+vibecheck my_script.py --fix
+```
+
+Enforce a minimum vibe score (ideal for CI/CD):
+```bash
+vibecheck my_script.py --min-score 80
+```

traceclip-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "traceclip"
+version = "0.1.0"
+description = "A fast, local linting wrapper specifically designed for AI-generated code."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "Prakhar Bhardwaj", email = "bhardwajprakhar02@gmail.com" }
+]
+keywords = ["linter", "ai", "code-quality", "sanitizer", "vibecheck", "copilot", "chatgpt"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Quality Assurance",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "rich>=12.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Prakhar3801b/Traceclip"
+Repository = "https://github.com/Prakhar3801b/Traceclip"
+"Bug Tracker" = "https://github.com/Prakhar3801b/Traceclip/issues"
+
+[project.scripts]
+vibecheck = "traceclip.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/traceclip"]

traceclip-0.1.0/src/traceclip/__init__.py

@@ -0,0 +1,3 @@
+"""Traceclip: The AI-Generated Code Sanitizer."""
+
+__version__ = "0.1.0"

traceclip-0.1.0/src/traceclip/cli.py

@@ -0,0 +1,170 @@
+import os
+import sys
+import argparse
+from pathlib import Path
+from typing import List
+
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.text import Text
+
+from traceclip.detector import detect_issues
+from traceclip.fixer import fix_file
+
+console = Console()
+
+def find_py_files(paths: List[str]) -> List[Path]:
+    py_files = []
+    ignored_dirs = {".git", "venv", ".venv", "env", "__pycache__", ".pytest_cache", "build", "dist", ".egg-info"}
+
+    for path_str in paths:
+        path = Path(path_str)
+        if path.is_file():
+            if path.suffix == ".py":
+                py_files.append(path)
+        elif path.is_dir():
+            for root, dirs, files in os.walk(path):
+                # Prune ignored directories in-place to avoid traversing them
+                dirs[:] = [d for d in dirs if d not in ignored_dirs and not d.startswith(".")]
+                for file in files:
+                    if file.endswith(".py"):
+                        py_files.append(Path(root) / file)
+    return sorted(list(set(py_files)))
+
+def format_score(score: int) -> Text:
+    if score >= 90:
+        return Text(f"{score}/100 (IMMACULATE VIBES)", style="bold green")
+    elif score >= 70:
+        return Text(f"{score}/100 (PASSABLE VIBES)", style="bold yellow")
+    else:
+        return Text(f"{score}/100 (BAD VIBES)", style="bold red")
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Traceclip (vibecheck): The AI-Generated Code Sanitizer."
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        default=["."],
+        help="Files or directories to scan (default: current directory)."
+    )
+    parser.add_argument(
+        "--fix",
+        "-f",
+        action="store_true",
+        help="Automatically sanitize and fix issues in-place."
+    )
+    parser.add_argument(
+        "--min-score",
+        "-m",
+        type=int,
+        default=0,
+        help="Minimum allowed Vibe Score. Returns exit code 1 if any file scores lower."
+    )
+
+    args = parser.parse_args()
+    py_files = find_py_files(args.paths)
+
+    if not py_files:
+        console.print("[bold red]Error:[/] No Python files found to scan.", style="red")
+        sys.exit(1)
+
+    console.print(Panel(
+        "[bold cyan]Traceclip Vibecheck[/] - Linting wrapper for AI-generated code\n"
+        "[dim]Hunts down unused imports, dead functions, stub methods, and placeholder secrets.[/]",
+        border_style="cyan"
+    ))
+
+    all_passed = True
+    total_issues = 0
+    total_files = len(py_files)
+    scores = []
+
+    for file_path in py_files:
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                content = f.read()
+        except Exception as e:
+            console.print(f"[bold red]Error reading file {file_path}:[/] {e}")
+            continue
+
+        # Detect issues
+        issues = detect_issues(content, str(file_path))
+        
+        # Calculate Vibe Score
+        deductions = sum(issue.weight for issue in issues)
+        score = max(0, 100 - deductions)
+        scores.append(score)
+        total_issues += len(issues)
+
+        # Print report
+        relative_path = os.path.relpath(file_path, os.getcwd())
+        console.print(f"\n[bold underline]{relative_path}[/]")
+
+        if not issues:
+            console.print("  [bold green]✓[/] Vibe check passed! Code is clean and tidy. (Score: 100/100)")
+            continue
+
+        # Display issues in a table
+        table = Table(show_header=True, header_style="bold magenta", box=None, padding=(0, 2))
+        table.add_column("Line:Col", justify="right", style="dim")
+        table.add_column("Type", style="bold")
+        table.add_column("Message")
+        table.add_column("Context", style="italic dim")
+
+        for issue in issues:
+            sev_style = "bold red" if issue.severity == "error" else "yellow"
+            issue_type_formatted = f"[{sev_style}]{issue.issue_type.replace('_', ' ').title()}[/]"
+            table.add_row(
+                f"{issue.line}:{issue.col}",
+                issue_type_formatted,
+                issue.message,
+                issue.context
+            )
+        
+        console.print(table)
+        console.print(f"  [bold]Vibe Score:[/] ", end="")
+        console.print(format_score(score))
+
+        # Enforce min-score check
+        if score < args.min_score:
+            all_passed = False
+
+        # Run Auto-Fix if requested
+        if args.fix and len([i for i in issues if i.issue_type not in ("syntax_error", "wildcard_import")]) > 0:
+            console.print(f"  [cyan]Applying autofixes to {relative_path}...[/]")
+            fixed_content = fix_file(content, str(file_path))
+            try:
+                with open(file_path, "w", encoding="utf-8") as f:
+                    f.write(fixed_content)
+                console.print(f"  [bold green]✓[/] Sanitized and saved!")
+                # Recalculate score for summary print
+                fixed_issues = detect_issues(fixed_content, str(file_path))
+                fixed_deductions = sum(issue.weight for issue in fixed_issues)
+                fixed_score = max(0, 100 - fixed_deductions)
+                scores[-1] = fixed_score
+                console.print(f"  [bold]New Vibe Score:[/] ", end="")
+                console.print(format_score(fixed_score))
+            except Exception as e:
+                console.print(f"  [bold red]Failed to write fixes:[/] {e}")
+
+    # Summary Panel
+    avg_score = int(sum(scores) / len(scores)) if scores else 100
+    summary_style = "bold green" if avg_score >= 90 else "bold yellow" if avg_score >= 70 else "bold red"
+    
+    console.print("\n" + "="*50)
+    console.print(f"[bold cyan]Summary Report:[/]")
+    console.print(f"  Files scanned: {total_files}")
+    console.print(f"  Total issues found: {total_issues}")
+    console.print(f"  Average Vibe Score: ", end="")
+    console.print(format_score(avg_score))
+    console.print("="*50)
+
+    if not all_passed:
+        console.print("\n[bold red]✖ vibecheck failed:[/] One or more files scored below the minimum threshold of --min-score.", style="red")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

traceclip-0.1.0/src/traceclip/detector.py

@@ -0,0 +1,358 @@
+import ast
+import re
+from dataclasses import dataclass
+from typing import List, Set, Dict, Any, Tuple
+
+# Severity weights for scoring
+WEIGHT_UNUSED_IMPORT = 5
+WEIGHT_WILDCARD_IMPORT = 5
+WEIGHT_DEAD_FUNCTION = 10
+WEIGHT_STUB_FUNCTION = 15
+WEIGHT_PLACEHOLDER_VAR = 20
+
+@dataclass
+class Issue:
+    file_path: str
+    line: int
+    col: int
+    issue_type: str
+    severity: str
+    message: str
+    weight: int
+    end_line: int = 0
+    context: str = ""
+
+class CodeAnalyzer(ast.NodeVisitor):
+    def __init__(self, file_path: str, source_code: str):
+        self.file_path = file_path
+        self.source_code = source_code
+        self.source_lines = source_code.splitlines()
+        self.issues: List[Issue] = []
+
+        # Tracks imports: bound_name -> (line, col, import_node, alias_node)
+        self.imports: Dict[str, Tuple[int, int, ast.AST, ast.alias]] = {}
+        # Tracks occurrences of names used in Load context
+        self.name_loads: Set[str] = set()
+        # Tracks occurrences of attribute access
+        self.attribute_loads: Set[str] = set()
+
+        # Tracks defined functions: name -> {node, line, end_line, is_method}
+        self.functions: Dict[str, Dict[str, Any]] = {}
+        # Tracks function names referenced (loads or attributes)
+        self.referenced_names: Set[str] = set()
+        # Reference line numbers for each name: name -> list of lines where it was referenced
+        self.name_reference_lines: Dict[str, List[int]] = {}
+        # Tracks exported names in __all__
+        self.exported_names: Set[str] = set()
+
+    def add_name_reference(self, name: str, line: int):
+        self.referenced_names.add(name)
+        if name not in self.name_reference_lines:
+            self.name_reference_lines[name] = []
+        self.name_reference_lines[name].append(line)
+
+    def visit_Import(self, node: ast.Import):
+        for alias in node.names:
+            # import foo.bar as baz -> bound name is baz
+            # import foo.bar -> bound name is foo
+            bound_name = alias.asname if alias.asname else alias.name.split('.')[0]
+            self.imports[bound_name] = (node.lineno, node.col_offset, node, alias)
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom):
+        for alias in node.names:
+            if alias.name == '*':
+                # Wildcard import detected
+                end_line = getattr(node, "end_lineno", node.lineno)
+                self.issues.append(Issue(
+                    file_path=self.file_path,
+                    line=node.lineno,
+                    col=node.col_offset,
+                    issue_type="wildcard_import",
+                    severity="warning",
+                    message=f"Wildcard import 'from {node.module} import *' pollutes namespace.",
+                    weight=WEIGHT_WILDCARD_IMPORT,
+                    end_line=end_line,
+                    context=self.get_line_context(node.lineno)
+                ))
+                continue
+            # from foo import bar as baz -> bound name is baz
+            # from foo import bar -> bound name is bar
+            bound_name = alias.asname if alias.asname else alias.name
+            self.imports[bound_name] = (node.lineno, node.col_offset, node, alias)
+        self.generic_visit(node)
+
+    def visit_Name(self, node: ast.Name):
+        if isinstance(node.ctx, ast.Load):
+            self.name_loads.add(node.id)
+            self.add_name_reference(node.id, node.lineno)
+        self.generic_visit(node)
+
+    def visit_Attribute(self, node: ast.Attribute):
+        # E.g. obj.method_name -> attribute access
+        self.attribute_loads.add(node.attr)
+        self.add_name_reference(node.attr, node.lineno)
+        self.generic_visit(node)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef):
+        self.process_function(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef):
+        self.process_function(node)
+
+    def process_function(self, node: Any):
+        # Skip dunder methods
+        if node.name.startswith("__") and node.name.endswith("__"):
+            self.generic_visit(node)
+            return
+
+        # Skip common entrypoints
+        if node.name == "main":
+            self.generic_visit(node)
+            return
+
+        # Record function details
+        end_line = getattr(node, "end_lineno", node.lineno)
+        self.functions[node.name] = {
+            "node": node,
+            "line": node.lineno,
+            "end_line": end_line,
+        }
+
+        # Check for stub implementations
+        self.check_stub_function(node)
+
+        self.generic_visit(node)
+
+    def check_stub_function(self, node: Any):
+        # A stub is a function with body containing only pass, Ellipsis, raise NotImplementedError
+        body = node.body
+        is_stub = False
+        reason = ""
+
+        if len(body) == 1:
+            stmt = body[0]
+            if isinstance(stmt, ast.Pass):
+                is_stub = True
+                reason = "contains only 'pass'"
+            elif isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Constant) and stmt.value.value is Ellipsis:
+                is_stub = True
+                reason = "contains only '...'"
+            elif isinstance(stmt, ast.Raise):
+                if isinstance(stmt.exc, ast.Name) and stmt.exc.id == "NotImplementedError":
+                    is_stub = True
+                    reason = "raises 'NotImplementedError'"
+                elif isinstance(stmt.exc, ast.Call) and isinstance(stmt.exc.func, ast.Name) and stmt.exc.func.id == "NotImplementedError":
+                    is_stub = True
+                    reason = "raises 'NotImplementedError'"
+            elif isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Constant) and isinstance(stmt.value.value, str):
+                # A function containing only a docstring
+                is_stub = True
+                reason = "contains only a docstring"
+
+        if is_stub:
+            self.issues.append(Issue(
+                file_path=self.file_path,
+                line=node.lineno,
+                col=node.col_offset,
+                issue_type="stub_function",
+                severity="warning",
+                message=f"Function '{node.name}' appears to be an empty stub ({reason}).",
+                weight=WEIGHT_STUB_FUNCTION,
+                end_line=getattr(node, "end_lineno", node.lineno),
+                context=self.get_line_context(node.lineno)
+            ))
+
+    def visit_Assign(self, node: ast.Assign):
+        self.check_placeholder_assignment(node)
+        self.check_all_export(node)
+        self.generic_visit(node)
+
+    def check_all_export(self, node: ast.Assign):
+        for t in node.targets:
+            if isinstance(t, ast.Name) and t.id == "__all__":
+                if isinstance(node.value, (ast.List, ast.Tuple, ast.Set)):
+                    for elt in node.value.elts:
+                        if isinstance(elt, ast.Constant) and isinstance(elt.value, str):
+                            self.exported_names.add(elt.value)
+                        elif isinstance(elt, ast.Str):
+                            self.exported_names.add(elt.s)
+
+    def visit_AnnAssign(self, node: ast.AnnAssign):
+        self.check_placeholder_assignment(node)
+        self.generic_visit(node)
+
+    def check_placeholder_assignment(self, node: Any):
+        # Extract string value if it's a constant
+        if not node.value or not isinstance(node.value, ast.Constant) or not isinstance(node.value.value, str):
+            return
+
+        val_str = node.value.value
+        targets = []
+        if isinstance(node, ast.Assign):
+            for t in node.targets:
+                if isinstance(t, ast.Name):
+                    targets.append(t.id)
+                elif isinstance(t, ast.Attribute):
+                    targets.append(t.attr)
+        elif isinstance(node, ast.AnnAssign):
+            if isinstance(node.target, ast.Name):
+                targets.append(node.target.id)
+            elif isinstance(node.target, ast.Attribute):
+                targets.append(node.target.attr)
+
+        placeholder_regexes = [
+            r"(?i)your_.*_here",
+            r"(?i)insert_.*",
+            r"(?i)enter_.*",
+            r"(?i)placeholder",
+            r"(?i)change[_-]?me",
+            r"(?i)todo",
+            r"(?i)<.*>",
+            r"(?i)\[.*\]",
+            r"(?i)your-.*",
+            r"^your_api_key$",
+            r"^your_token$",
+            r"^password123$",
+        ]
+
+        for target in targets:
+            is_placeholder = False
+            # Check value against regexes
+            for r in placeholder_regexes:
+                if re.search(r, val_str):
+                    is_placeholder = True
+                    break
+            
+            # Check key name + typical suspicious placeholder values
+            suspicious_keys = {"key", "token", "secret", "pass", "pwd", "credential", "url"}
+            any_suspicious_key = any(sk in target.lower() for sk in suspicious_keys)
+            
+            if any_suspicious_key:
+                # If key is key/token/secret and value is very typical dummy text
+                dummy_texts = {"your", "insert", "placeholder", "enter", "todo", "example", "here", "change", "secret"}
+                if any(dt in val_str.lower() for dt in dummy_texts) or len(val_str) < 5 or val_str.strip() == "":
+                    is_placeholder = True
+
+            if is_placeholder:
+                self.issues.append(Issue(
+                    file_path=self.file_path,
+                    line=node.lineno,
+                    col=node.col_offset,
+                    issue_type="placeholder_var",
+                    severity="error",
+                    message=f"Placeholder value '{val_str}' assigned to variable/attribute '{target}'.",
+                    weight=WEIGHT_PLACEHOLDER_VAR,
+                    end_line=getattr(node, "end_lineno", node.lineno),
+                    context=self.get_line_context(node.lineno)
+                ))
+
+    def get_line_context(self, lineno: int) -> str:
+        if 1 <= lineno <= len(self.source_lines):
+            return self.source_lines[lineno - 1].strip()
+        return ""
+
+    def analyze(self):
+        # Run visitor to collect all imports, functions, and references
+        self.visit(ast.parse(self.source_code))
+
+        # 1. Unused Imports check
+        # An import is unused if its bound name is never in name_loads (except inside imports themselves)
+        # Wait, if we import 'foo', but the only reference is the import statement itself.
+        # Since ast.alias / ast.Import nodes are visited, we should make sure that the name loads count references.
+        # Let's check which bound names have 0 references in the loads.
+        for bound_name, (line, col, node, alias) in self.imports.items():
+            if bound_name not in self.name_loads:
+                if bound_name not in self.exported_names:
+                    name_desc = alias.name
+                    if alias.asname:
+                        name_desc = f"{alias.name} as {alias.asname}"
+                    self.issues.append(Issue(
+                        file_path=self.file_path,
+                        line=line,
+                        col=col,
+                        issue_type="unused_import",
+                        severity="warning",
+                        message=f"Unused import '{name_desc}'.",
+                        weight=WEIGHT_UNUSED_IMPORT,
+                        end_line=getattr(node, "end_lineno", line),
+                        context=self.get_line_context(line)
+                    ))
+
+        # 2. Dead Functions check
+        for func_name, info in self.functions.items():
+            ref_lines = self.name_reference_lines.get(func_name, [])
+            
+            # An external reference is any reference outside the function's own body range
+            external_refs = [r_line for r_line in ref_lines if not (info["line"] <= r_line <= info["end_line"])]
+            
+            if len(external_refs) == 0:
+                self.issues.append(Issue(
+                    file_path=self.file_path,
+                    line=info["line"],
+                    col=info["node"].col_offset,
+                    issue_type="dead_function",
+                    severity="warning",
+                    message=f"Function '{func_name}' is defined but never called or referenced externally.",
+                    weight=WEIGHT_DEAD_FUNCTION,
+                    end_line=info["end_line"],
+                    context=self.get_line_context(info["line"])
+                ))
+
+
+def scan_comments_for_placeholders(source_code: str, file_path: str) -> List[Issue]:
+    issues = []
+    lines = source_code.splitlines()
+    ai_comment_patterns = [
+        (r"(?i)#\s*todo:\s*(implement|replace|fill)", "AI placeholder comment: TODO implementation detail"),
+        (r"(?i)#\s*generated\s*by\s*(copilot|ai|chatgpt)", "AI leftover comment: 'Generated by AI'"),
+        (r"(?i)#\s*insert\s*.*\s*here", "AI placeholder comment: insert indicator"),
+        (r"(?i)#\s*change\s*me", "AI placeholder comment: 'change me'"),
+    ]
+    for idx, line in enumerate(lines, 1):
+        # We only want to match actual comment lines or parts of lines that are comments
+        comment_match = re.search(r"#.*", line)
+        if comment_match:
+            comment_text = comment_match.group(0)
+            for pattern, message in ai_comment_patterns:
+                if re.search(pattern, comment_text):
+                    issues.append(Issue(
+                        file_path=file_path,
+                        line=idx,
+                        col=comment_match.start(),
+                        issue_type="placeholder_var", # Treat comment placeholders similarly to variable placeholders
+                        severity="warning",
+                        message=message,
+                        weight=5, # lighter weight for comments
+                        context=line.strip()
+                    ))
+    return issues
+
+
+def detect_issues(source_code: str, file_path: str) -> List[Issue]:
+    # AST analysis
+    try:
+        analyzer = CodeAnalyzer(file_path, source_code)
+        analyzer.analyze()
+        issues = analyzer.issues
+    except SyntaxError as e:
+        # If there's a syntax error, we report it as a critical failure
+        issues = [Issue(
+            file_path=file_path,
+            line=e.lineno or 1,
+            col=e.offset or 1,
+            issue_type="syntax_error",
+            severity="error",
+            message=f"Syntax Error: {e.msg}",
+            weight=50,
+            context=e.text.strip() if e.text else ""
+        )]
+        return issues
+
+    # Comments analysis
+    comment_issues = scan_comments_for_placeholders(source_code, file_path)
+    issues.extend(comment_issues)
+    
+    # Sort issues by line number
+    issues.sort(key=lambda x: x.line)
+    return issues

traceclip-0.1.0/src/traceclip/fixer.py

@@ -0,0 +1,137 @@
+import ast
+import re
+from typing import List
+from traceclip.detector import CodeAnalyzer, Issue, scan_comments_for_placeholders
+
+def fix_file(source_code: str, file_path: str) -> str:
+    # 1. Detect issues using the same engine
+    try:
+        analyzer = CodeAnalyzer(file_path, source_code)
+        analyzer.analyze()
+        issues = analyzer.issues
+        # Exclude syntax errors and wildcard imports from being fixed automatically
+        issues = [i for i in issues if i.issue_type not in ("syntax_error", "wildcard_import")]
+    except Exception:
+        # If AST parsing fails, return source_code unmodified
+        return source_code
+
+    if not issues:
+        return source_code
+
+    # 2. Sort issues in descending order of line number to process bottom-up
+    # This prevents shifting lines of unprocessed issues above the current edit.
+    issues.sort(key=lambda x: (x.line, x.col), reverse=True)
+
+    lines = source_code.splitlines()
+    modified_lines = set()
+    needs_os_import = False
+
+    for issue in issues:
+        # Avoid double-modifying lines (e.g. if a function is both a stub and dead)
+        line_range = range(issue.line, issue.end_line + 1)
+        if any(l in modified_lines for l in line_range):
+            continue
+
+        # Mark range as modified
+        for l in line_range:
+            modified_lines.add(l)
+
+        if issue.issue_type == "unused_import":
+            # Find the import node in the analyzer
+            # Let's search the imports dict for the one matching this line
+            matching_import_info = None
+            bound_name_to_remove = None
+            for name, info in analyzer.imports.items():
+                import_line, import_col, node, alias = info
+                if import_line == issue.line:
+                    # Match by line number and column
+                    matching_import_info = info
+                    bound_name_to_remove = name
+                    break
+
+            if matching_import_info:
+                _, _, node, alias_node = matching_import_info
+                start_idx = node.lineno - 1
+                end_idx = getattr(node, "end_lineno", node.lineno) - 1
+
+                # Check if this import statement has multiple imported names
+                if len(node.names) > 1:
+                    # Reconstruct separate imports for all names that are NOT unused
+                    used_aliases = []
+                    for a in node.names:
+                        # Determine bound name for this alias
+                        b_name = a.asname if a.asname else (a.name if isinstance(node, ast.ImportFrom) else a.name.split('.')[0])
+                        # A name is used if it's not the one we are removing
+                        if b_name != bound_name_to_remove and b_name in analyzer.name_loads:
+                            used_aliases.append(a)
+
+                    # Comment out the old import statement
+                    for idx in range(start_idx, end_idx + 1):
+                        lines[idx] = f"# vibecheck-removed: {lines[idx]}"
+
+                    if used_aliases:
+                        # Build the new import line
+                        if isinstance(node, ast.Import):
+                            new_import_parts = [f"{a.name} as {a.asname}" if a.asname else a.name for a in used_aliases]
+                            new_import = "import " + ", ".join(new_import_parts)
+                        else:
+                            new_import_parts = [f"{a.name} as {a.asname}" if a.asname else a.name for a in used_aliases]
+                            new_import = f"from {node.module} import " + ", ".join(new_import_parts)
+                        
+                        # Append the new import statement right below the commented one
+                        lines[end_idx] = lines[end_idx] + "\n" + new_import
+                else:
+                    # Single name import: comment out the whole thing
+                    for idx in range(start_idx, end_idx + 1):
+                        lines[idx] = f"# vibecheck-removed: {lines[idx]}"
+
+        elif issue.issue_type in ("dead_function", "stub_function"):
+            start_idx = issue.line - 1
+            end_idx = issue.end_line - 1
+            prefix = "# vibecheck-removed: " if issue.issue_type == "dead_function" else "# vibecheck-stub-removed: "
+            for idx in range(start_idx, end_idx + 1):
+                lines[idx] = f"{prefix}{lines[idx]}"
+
+        elif issue.issue_type == "placeholder_var":
+            # For placeholder variables (API_KEY = "your_key"), replace with os.getenv
+            # Check if this is a comment placeholder or variable placeholder
+            # If it's a comment, we don't change the code (just keep it as is, or we can remove it. Let's just comment it out further or leave it)
+            if "comment:" in issue.message.lower():
+                # Comment placeholder, we can prefix the comment line with a warning or just leave it
+                continue
+
+            # Variable placeholder: e.g. API_KEY = "your_key"
+            start_idx = issue.line - 1
+            end_idx = issue.end_line - 1
+            
+            # Since AST is valid, we can parse this assignment line
+            # Let's extract the target and value
+            line_str = lines[start_idx]
+            if "=" in line_str:
+                parts = line_str.split("=", 1)
+                left_side = parts[0].rstrip()
+                # Find the target name
+                # Let's guess the target variable name: we can get it from the issue message or parse it
+                # E.g. "Placeholder value 'your_key' assigned to variable/attribute 'API_KEY'."
+                # We can extract the target name from the message or left_side
+                target_name = left_side.strip().split()[-1] # Simple guess
+                # Clean up characters like colon for typed annotations
+                if ":" in target_name:
+                    target_name = target_name.split(":")[0].strip()
+                
+                # Extract the original string literal value
+                # We know the issue.message contains "Placeholder value 'val' assigned to..."
+                # Let's extract 'val' from the message using regex
+                val_match = re.search(r"Placeholder value '(.*)' assigned to", issue.message)
+                val_str = val_match.group(1) if val_match else "your_key_here"
+
+                # Replace with os.getenv("TARGET_NAME", "default_val")
+                new_assignment = f"{left_side} = os.getenv({target_name!r}, {val_str!r})"
+                lines[start_idx] = f"# vibecheck-placeholder-fixed:\n# {line_str}\n{new_assignment}"
+                needs_os_import = True
+
+    # 3. Add import os if needed and not already imported and kept
+    if needs_os_import and ("os" not in analyzer.imports or "os" not in analyzer.name_loads):
+        lines.insert(0, "import os")
+
+    return "\n".join(lines) + "\n"

traceclip-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+# Traceclip test package

traceclip-0.1.0/tests/test_detector.py

@@ -0,0 +1,129 @@
+import unittest
+from traceclip.detector import detect_issues
+from traceclip.fixer import fix_file
+
+class TestTraceclip(unittest.TestCase):
+    def test_unused_imports(self):
+        code = """import os
+import sys
+from collections import defaultdict, Counter
+import math as m
+
+d = defaultdict(int)
+"""
+        issues = detect_issues(code, "test.py")
+        types = [i.issue_type for i in issues]
+        messages = [i.message for i in issues]
+        
+        self.assertIn("unused_import", types)
+        # os, sys, Counter, m are unused
+        unused_names = [m for m in messages if "Unused import" in m]
+        self.assertEqual(len(unused_names), 4)
+        self.assertTrue(any("os" in m for m in unused_names))
+        self.assertTrue(any("sys" in m for m in unused_names))
+        self.assertTrue(any("Counter" in m for m in unused_names))
+        self.assertTrue(any("math as m" in m for m in unused_names))
+
+    def test_wildcard_import(self):
+        code = "from math import *"
+        issues = detect_issues(code, "test.py")
+        types = [i.issue_type for i in issues]
+        self.assertIn("wildcard_import", types)
+
+    def test_dead_functions(self):
+        code = """def dead_func(x):
+    return x * 2
+
+def recursive_dead_func(n):
+    if n <= 1:
+        return 1
+    return n * recursive_dead_func(n-1)
+
+def active_func():
+    return 42
+
+print(active_func())
+"""
+        issues = detect_issues(code, "test.py")
+        dead_funcs = [i.message for i in issues if i.issue_type == "dead_function"]
+        self.assertEqual(len(dead_funcs), 2)
+        self.assertTrue(any("dead_func" in m for m in dead_funcs))
+        self.assertTrue(any("recursive_dead_func" in m for m in dead_funcs))
+        self.assertFalse(any("active_func" in m for m in dead_funcs))
+
+    def test_placeholder_variables(self):
+        code = """API_KEY = "your_api_key_here"
+PASSWORD = "insert_password_here"
+token = "enter_token_here"
+my_val = "normal value"
+"""
+        issues = detect_issues(code, "test.py")
+        placeholders = [i.message for i in issues if i.issue_type == "placeholder_var"]
+        self.assertEqual(len(placeholders), 3)
+        self.assertTrue(any("API_KEY" in m for m in placeholders))
+        self.assertTrue(any("PASSWORD" in m for m in placeholders))
+        self.assertTrue(any("token" in m for m in placeholders))
+        self.assertFalse(any("my_val" in m for m in placeholders))
+
+    def test_stub_functions(self):
+        code = """def stub1():
+    pass
+
+def stub2():
+    ...
+
+def stub3():
+    raise NotImplementedError
+
+def active():
+    print("hello")
+"""
+        issues = detect_issues(code, "test.py")
+        stubs = [i.message for i in issues if i.issue_type == "stub_function"]
+        self.assertEqual(len(stubs), 3)
+        self.assertTrue(any("stub1" in m for m in stubs))
+        self.assertTrue(any("stub2" in m for m in stubs))
+        self.assertTrue(any("stub3" in m for m in stubs))
+        self.assertFalse(any("active" in m for m in stubs))
+
+    def test_comment_scanning(self):
+        code = """# generated by copilot
+# TODO: implement this
+# normal comment
+"""
+        issues = detect_issues(code, "test.py")
+        comments = [i.message for i in issues if i.issue_type == "placeholder_var" and "comment:" in i.message.lower()]
+        self.assertEqual(len(comments), 2)
+
+    def test_fix_unused_imports(self):
+        code = """import sys
+from collections import defaultdict, Counter
+
+d = defaultdict(int)
+"""
+        fixed = fix_file(code, "test.py")
+        self.assertIn("# vibecheck-removed: import sys", fixed)
+        self.assertIn("# vibecheck-removed: from collections import defaultdict, Counter", fixed)
+        self.assertIn("from collections import defaultdict", fixed)
+        self.assertNotIn("Counter", fixed.splitlines()[-1]) # Counter is removed in the recreated import
+
+    def test_fix_dead_functions(self):
+        code = """def dead_func():
+    return 1
+
+print("hello")
+"""
+        fixed = fix_file(code, "test.py")
+        self.assertIn("# vibecheck-removed: def dead_func():", fixed)
+        self.assertIn("# vibecheck-removed:     return 1", fixed)
+
+    def test_fix_placeholder_variables(self):
+        code = """API_KEY = "your_api_key_here"
+"""
+        # API_KEY is a placeholder, should be replaced by os.getenv, and import os added
+        fixed = fix_file(code, "test.py")
+        self.assertIn("import os", fixed)
+        self.assertIn("API_KEY = os.getenv('API_KEY', 'your_api_key_here')", fixed)
+
+if __name__ == "__main__":
+    unittest.main()

traceclip-0.1.0/tests/test_fixtures/dirty_sample.py

@@ -0,0 +1,38 @@
+# Generated by ChatGPT
+
+import sys
+import os
+from collections import defaultdict, Counter
+from math import *
+
+API_KEY = "your_api_key_here"
+PORT = 8080
+
+def dead_utility_func(x):
+    # This is a dead function defined by AI but never called
+    return x * 2
+
+def active_func(data):
+    # This is used and references defaultdict
+    d = defaultdict(int)
+    for item in data:
+        d[item] += 1
+    return d
+
+def recursive_dead_func(n):
+    if n <= 1:
+        return 1
+    # Only references itself (recursive)
+    return n * recursive_dead_func(n - 1)
+
+def empty_stub_func():
+    # TODO: implement this later
+    pass
+
+def raise_stub_func():
+    raise NotImplementedError
+
+if __name__ == "__main__":
+    test_data = [1, 2, 2, 3]
+    result = active_func(test_data)
+    print(f"Result: {result}")

traceclip-0.1.0/tests/test_performance.py

@@ -0,0 +1,84 @@
+import unittest
+import time
+from traceclip.detector import detect_issues
+from traceclip.fixer import fix_file
+
+class TestPerformance(unittest.TestCase):
+    def test_large_file_performance(self):
+        lines = []
+        
+        # 1. Add 100 unused imports
+        for i in range(100):
+            lines.append(f"import unused_module_{i}")
+            
+        # Add used imports
+        lines.append("import os")
+        lines.append("from collections import defaultdict")
+        
+        # 2. Add 200 placeholder variables (100 API keys, 100 DB URLs)
+        for i in range(100):
+            lines.append(f"API_KEY_{i} = 'your_api_key_here_{i}'")
+            lines.append(f"DB_URL_{i} = 'insert_db_url_here'")
+            
+        # 3. Add 100 stub functions (which will also be dead)
+        for i in range(100):
+            lines.append(f"def stub_function_{i}():")
+            lines.append("    pass")
+            
+        # 4. Add 250 active functions (chained calls)
+        for i in range(250):
+            lines.append(f"def active_function_{i}(x):")
+            if i == 0:
+                lines.append("    return x + 1")
+            else:
+                lines.append(f"    return active_function_{i-1}(x) + 1")
+                
+        # 5. Add 250 dead functions
+        for i in range(250):
+            lines.append(f"def dead_function_{i}(x):")
+            lines.append("    return x * 2")
+            
+        # 6. Entrypoint using active functions
+        lines.append("if __name__ == '__main__':")
+        lines.append("    d = defaultdict(int)")
+        lines.append("    print(active_function_249(10))")
+        
+        large_code = "\n".join(lines)
+        line_count = len(lines)
+        
+        # Measure detection speed
+        start_detect = time.perf_counter()
+        issues = detect_issues(large_code, "large_file.py")
+        detect_duration = time.perf_counter() - start_detect
+        
+        # Measure fixing speed
+        start_fix = time.perf_counter()
+        fixed_code = fix_file(large_code, "large_file.py")
+        fix_duration = time.perf_counter() - start_fix
+        
+        # Print stats
+        print(f"\n[Stress Test] Generated codebase: {line_count} lines.")
+        print(f"  - Detected {len(issues)} issues in {detect_duration:.4f} seconds.")
+        print(f"  - Fixed codebase in {fix_duration:.4f} seconds.")
+        
+        # Performance assertions (sub-second threshold)
+        self.assertLess(detect_duration, 1.0, f"Detection took too long: {detect_duration:.4f}s")
+        self.assertLess(fix_duration, 1.5, f"Fixing took too long: {fix_duration:.4f}s")
+        
+        # Correctness checks: we expect:
+        # - 100 unused imports
+        # - 200 placeholder variables
+        # - 100 stub functions
+        # - 250 dead functions
+        # - 100 stub functions (which are also dead functions)
+        # Total issues should be at least 750
+        self.assertGreaterEqual(len(issues), 750)
+        
+        # Syntax check: verify the fixed codebase compiles successfully as valid Python
+        try:
+            compile(fixed_code, "large_file.py", "exec")
+        except SyntaxError as e:
+            self.fail(f"Autofixer produced syntactically invalid Python code: {e}")
+
+if __name__ == "__main__":
+    unittest.main()