aicheck 0.1.0__py3-none-any.whl

aicheck/__init__.py

@@ -0,0 +1,3 @@
+"""aicheck — Catch AI-generated code issues before they catch you."""
+
+__version__ = "0.1.0"

aicheck/__main__.py

@@ -0,0 +1,4 @@
+from aicheck.cli import main
+
+if __name__ == "__main__":
+    main()

aicheck/analyzer.py

@@ -0,0 +1,91 @@
+import ast
+import importlib
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Protocol
+
+import requests
+
+from aicheck.detectors.api_usage import ApiUsageDetector
+from aicheck.detectors.dead_code import DeadCodeDetector
+from aicheck.detectors.hallucination import HallucinationDetector
+from aicheck.models import FileResult, Finding
+
+
+class DetectorProtocol(Protocol):
+    def check(self, tree: ast.AST, source: str) -> list[Finding]:
+        ...
+
+
+class Analyzer:
+    def __init__(self, timeout: int = 5):
+        self.timeout = timeout
+        self._detectors: list[DetectorProtocol] = [
+            HallucinationDetector(),
+            DeadCodeDetector(),
+            ApiUsageDetector(),
+        ]
+
+    def check_file(self, path: Path) -> FileResult:
+        with path.open(encoding="utf-8", errors="replace") as f:
+            source = f.read()
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return FileResult(path=path)
+        result = FileResult(path=path)
+        for detector in self._detectors:
+            result.findings.extend(detector.check(tree, source))
+        return result
+
+    def check_path(self, path: Path) -> list[FileResult]:
+        if path.is_file() and path.suffix == ".py":
+            return [self.check_file(path)]
+        results: list[FileResult] = []
+        files = list(path.rglob("*.py"))
+        with ThreadPoolExecutor(max_workers=8) as pool:
+            for r in pool.map(self.check_file, files):
+                results.append(r)
+        return results
+
+    @staticmethod
+    def known_modules() -> set[str]:
+        known = set(sys.builtin_module_names)
+        for m in list(sys.modules.keys()):
+            parts = m.split(".")
+            for i in range(len(parts)):
+                known.add(".".join(parts[: i + 1]))
+        known.update({
+            "os", "sys", "re", "json", "math", "datetime", "pathlib",
+            "collections", "functools", "itertools", "typing", "abc",
+            "dataclasses", "enum", "hashlib", "random", "statistics",
+            "uuid", "inspect", "textwrap", "string", "decimal", "fractions",
+            "io", "base64", "binascii", "pickle", "shelve", "sqlite3",
+            "csv", "configparser", "logging", "argparse", "subprocess",
+            "shutil", "tempfile", "glob", "fnmatch", "linecache",
+            "asyncio", "threading", "multiprocessing", "concurrent",
+            "http", "urllib", "socket", "ssl", "email", "xml", "html",
+            "unittest", "doctest", "pdb", "profile", "timeit",
+            "warnings", "contextlib", "atexit", "weakref", "copy",
+            "pprint", "reprlib", "enum", "numbers", "stat",
+            "calendar", "locale", "gettext", "platform",
+        })
+        return known
+
+
+def verify_import(name: str, timeout: int = 3) -> bool:
+    top = name.split(".")[0]
+    try:
+        importlib.import_module(top)
+        return True
+    except ImportError:
+        pass
+    try:
+        resp = requests.get(
+            f"https://pypi.org/pypi/{top}/json",
+            timeout=timeout,
+        )
+        return bool(resp.status_code == 200)
+    except requests.RequestException:
+        return False

aicheck/cli.py

@@ -0,0 +1,53 @@
+import argparse
+import sys
+from pathlib import Path
+
+from aicheck.analyzer import Analyzer
+from aicheck.reporters.console import get_reporter
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="aicheck",
+        description="Catch AI-generated code issues before they catch you",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    check = sub.add_parser("check", help="Analyze Python files for AI code issues")
+    check.add_argument("path", type=str, nargs="?", default=".",
+                       help="File or directory to check")
+    check.add_argument("--format", choices=["console", "json"], default="console",
+                       help="Output format")
+
+    sub.add_parser("version", help="Show version")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "version" or not args.command:
+        from aicheck import __version__
+        print(f"aicheck v{__version__}")
+        return 0
+
+    if args.command == "check":
+        target = Path(args.path).resolve()
+        if not target.exists():
+            print(f"Error: path '{target}' does not exist", file=sys.stderr)
+            return 1
+        analyzer = Analyzer()
+        results = analyzer.check_path(target)
+        reporter = get_reporter(args.format)
+        output = reporter.report(results)
+        print(output)
+        all_passed = all(r.passed for r in results)
+        return 0 if all_passed else 1
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

aicheck/detectors/api_usage.py

@@ -0,0 +1,76 @@
+import ast
+import sys
+
+from aicheck.models import Finding, FindingKind, Severity
+
+
+class ApiUsageDetector:
+    FAKE_FUNCTIONS: dict[str, set[str]] = {
+        "os": {"path.join"},
+        "sys": {"argv"},
+        "re": {"search", "match", "findall", "sub", "split"},
+        "json": {"dumps", "loads", "dump", "load"},
+        "typing": {"List", "Dict", "Optional", "Tuple", "Union", "Any"},
+    }
+
+    REAL_STDLIB_FUNCTIONS: set[str] = set()
+
+    def __init__(self) -> None:
+        if not self.REAL_STDLIB_FUNCTIONS:
+            self._build_stdlib_index()
+
+    @staticmethod
+    def _build_stdlib_index() -> None:
+        known: set[str] = set()
+        for mod_name in sys.stdlib_module_names:
+            try:
+                mod = __import__(mod_name)
+                for attr in dir(mod):
+                    known.add(f"{mod_name}.{attr}")
+            except (ImportError, AttributeError):
+                pass
+        ApiUsageDetector.REAL_STDLIB_FUNCTIONS = known
+
+    def check(self, tree: ast.AST, source: str) -> list[Finding]:
+        findings: list[Finding] = []
+        self._check_wrong_stdlib_methods(tree, findings)
+        self._check_common_mistakes(tree, findings)
+        return findings
+
+    @staticmethod
+    def _check_wrong_stdlib_methods(tree: ast.AST, findings: list[Finding]) -> None:
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
+                if isinstance(node.func.value, ast.Name):
+                    mod = node.func.value.id
+                    func = f"{mod}.{node.func.attr}"
+                    if mod in ("os", "sys", "json", "re", "typing"):
+                        expected = ApiUsageDetector.FAKE_FUNCTIONS.get(mod, set())
+                        if node.func.attr not in expected:
+                            findings.append(Finding(
+                                kind=FindingKind.SUSPICIOUS_API,
+                                message=f"Suspicious API call: '{func}' — "
+                                        f"uncommon for module '{mod}'",
+                                line=node.lineno or 0,
+                                column=node.col_offset or 0,
+                                severity=Severity.MEDIUM,
+                                suggestion=f"Verify '{func}' is a valid {mod} function",
+                            ))
+
+    @staticmethod
+    def _check_common_mistakes(tree: ast.AST, findings: list[Finding]) -> None:
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
+                if isinstance(node.func.value, ast.Name):
+                    if node.func.value.id == "open" and node.func.attr == "read":
+                        findings.append(Finding(
+                            kind=FindingKind.SUSPICIOUS_API,
+                            message=(
+                                "Suspicious: 'open(...).read()' — "
+                                "use 'pathlib.Path.read_text()' instead"
+                            ),
+                            line=node.lineno or 0,
+                            column=node.col_offset or 0,
+                            severity=Severity.LOW,
+                            suggestion="Replace with Path.read_text()",
+                        ))

aicheck/detectors/dead_code.py

@@ -0,0 +1,65 @@
+import ast
+
+from aicheck.models import Finding, FindingKind, Severity
+
+
+class DeadCodeDetector:
+    def check(self, tree: ast.AST, source: str) -> list[Finding]:
+        findings: list[Finding] = []
+        self._check_unreachable(tree, findings)
+        self._check_unused_vars(tree, findings)
+        self._check_dead_after_return(tree, findings)
+        return findings
+
+    @staticmethod
+    def _check_unreachable(tree: ast.AST, findings: list[Finding]) -> None:
+        for node in ast.walk(tree):
+            if isinstance(node, ast.If):
+                if isinstance(node.test, ast.Constant) and node.test.value is False:
+                    findings.append(Finding(
+                        kind=FindingKind.UNREACHABLE_CODE,
+                        message="Unreachable branch: condition is always False",
+                        line=node.lineno or 0,
+                        column=node.col_offset or 0,
+                        severity=Severity.MEDIUM,
+                        suggestion="Remove dead branch or update condition",
+                    ))
+
+    @staticmethod
+    def _check_unused_vars(tree: ast.AST, findings: list[Finding]) -> None:
+        assigns: dict[str, ast.Name] = {}
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Assign):
+                for t in node.targets:
+                    if isinstance(t, ast.Name) and not t.id.startswith("_"):
+                        assigns[t.id] = t
+        for var, node in assigns.items():
+            count = sum(1 for n in ast.walk(tree)
+                        if isinstance(n, ast.Name) and n.id == var)
+            if count <= 1:
+                findings.append(Finding(
+                    kind=FindingKind.DEAD_CODE,
+                    message=f"Possibly unused variable: '{var}' (assigned but never read)",
+                    line=node.lineno or 0,
+                    column=node.col_offset or 0,
+                    severity=Severity.LOW,
+                    suggestion=f"Remove '{var}' or use it elsewhere",
+                ))
+
+    @staticmethod
+    def _check_dead_after_return(tree: ast.AST, findings: list[Finding]) -> None:
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                stmts = node.body
+                for i, stmt in enumerate(stmts[:-1]):
+                    if isinstance(stmt, (ast.Return, ast.Raise)):
+                        next_stmt = stmts[i + 1]
+                        findings.append(Finding(
+                            kind=FindingKind.DEAD_CODE,
+                            message=f"Dead code after {type(stmt).__name__.lower()} "
+                                    f"on line {next_stmt.lineno}",
+                            line=next_stmt.lineno or 0,
+                            column=next_stmt.col_offset or 0,
+                            severity=Severity.MEDIUM,
+                            suggestion="Remove unreachable statement or reorder logic",
+                        ))

aicheck/detectors/hallucination.py

@@ -0,0 +1,44 @@
+import ast
+
+from aicheck.models import Finding, FindingKind, Severity
+
+
+class HallucinationDetector:
+    FAKE_STDLIB_MODULES: set[str] = {
+        "utils", "helpers", "common", "tools", "misc",
+        "extras", "general", "core", "base", "utilities",
+        "datatools", "fileutils", "strutils", "validators",
+    }
+
+    def check(self, tree: ast.AST, source: str) -> list[Finding]:
+        findings: list[Finding] = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    top = alias.name.split(".")[0]
+                    if top in self.FAKE_STDLIB_MODULES:
+                        findings.append(Finding(
+                            kind=FindingKind.HALLUCINATED_IMPORT,
+                            message=f"Potentially hallucinated module: '{alias.name}' — "
+                                    f"'{top}' is a common LLM-invented name",
+                            line=node.lineno or 0,
+                            column=node.col_offset or 0,
+                            severity=Severity.HIGH,
+                            suggestion=(
+                                f"Verify '{alias.name}' exists; "
+                                "check PyPI or project dependencies"
+                            ),
+                        ))
+            elif isinstance(node, ast.ImportFrom):
+                if node.module:
+                    top = node.module.split(".")[0]
+                    if top in self.FAKE_STDLIB_MODULES and node.level is None:
+                        findings.append(Finding(
+                            kind=FindingKind.FAKE_STDLIB,
+                            message=f"Import from potentially fake module: '{node.module}'",
+                            line=node.lineno or 0,
+                            column=node.col_offset or 0,
+                            severity=Severity.HIGH,
+                            suggestion=f"Ensure '{node.module}' is a real package",
+                        ))
+        return findings

aicheck/models.py

@@ -0,0 +1,51 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class Severity(Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class FindingKind(Enum):
+    HALLUCINATED_IMPORT = "hallucinated_import"
+    DEAD_CODE = "dead_code"
+    SUSPICIOUS_API = "suspicious_api"
+    UNREACHABLE_CODE = "unreachable_code"
+    FAKE_STDLIB = "fake_stdlib"
+
+
+@dataclass
+class Finding:
+    kind: FindingKind
+    message: str
+    line: int
+    column: int
+    severity: Severity
+    suggestion: str = ""
+
+
+@dataclass
+class FileResult:
+    path: Path
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def score(self) -> float:
+        if not self.findings:
+            return 100.0
+        penalties = {
+            Severity.LOW: 2,
+            Severity.MEDIUM: 5,
+            Severity.HIGH: 15,
+            Severity.CRITICAL: 30,
+        }
+        total_penalty = sum(penalties[f.severity] for f in self.findings)
+        return max(0.0, 100.0 - total_penalty)
+
+    @property
+    def passed(self) -> bool:
+        return self.score >= 70.0

aicheck/reporters/console.py

@@ -0,0 +1,65 @@
+import json
+
+from aicheck.models import FileResult
+
+
+class ConsoleReporter:
+    def report(self, results: list[FileResult]) -> str:
+        lines: list[str] = []
+        passed = 0
+        failed = 0
+        for r in results:
+            status = "PASS" if r.passed else "FAIL"
+            if r.passed:
+                passed += 1
+            else:
+                failed += 1
+            lines.append(f"[{status}] {r.path}  (score: {r.score:.1f})")
+            for f in r.findings:
+                lines.append(
+                    f"  {f.severity.value:>8}  L{f.line}:{f.column}  "
+                    f"[{f.kind.value}] {f.message}"
+                )
+                if f.suggestion:
+                    lines.append(f"           \u21b3 {f.suggestion}")
+        if not results:
+            lines.append("No Python files found.")
+        lines.append("")
+        total = len(results)
+        lines.append(f"Files: {total}  Passed: {passed}  Failed: {failed}")
+        if total:
+            avg = sum(r.score for r in results) / total
+            lines.append(f"Average confidence score: {avg:.1f}/100")
+        return "\n".join(lines)
+
+
+class JsonReporter:
+    def report(self, results: list[FileResult]) -> str:
+        data = []
+        for r in results:
+            data.append({
+                "path": str(r.path),
+                "score": r.score,
+                "passed": r.passed,
+                "findings": [
+                    {
+                        "kind": f.kind.value,
+                        "severity": f.severity.value,
+                        "line": f.line,
+                        "column": f.column,
+                        "message": f.message,
+                        "suggestion": f.suggestion,
+                    }
+                    for f in r.findings
+                ],
+            })
+        return json.dumps({"files": data}, indent=2)
+
+
+def get_reporter(format: str) -> ConsoleReporter | JsonReporter:
+    reporters: dict[str, type[ConsoleReporter] | type[JsonReporter]] = {
+        "console": ConsoleReporter,
+        "json": JsonReporter,
+    }
+    cls = reporters.get(format, ConsoleReporter)
+    return cls()

aicheck-0.1.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: aicheck
+Version: 0.1.0
+Summary: Catch AI-generated code issues before they catch you
+Author-email: Mahesh Makvana <maheshmakvana@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/maheshmakvana/ai-check
+Project-URL: Repository, https://github.com/maheshmakvana/ai-check
+Project-URL: BugTracker, https://github.com/maheshmakvana/ai-check/issues
+Keywords: ai verification,code review,hallucination detection,llm code,ai code quality,code analysis,static analysis,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: ruff>=0.3.0; extra == "test"
+Requires-Dist: mypy>=1.8.0; extra == "test"
+Dynamic: license-file
+
+# aicheck
+
+**Catch AI-generated code issues before they catch you.**
+
+`aicheck` is a static analysis toolkit that detects common failure patterns in AI-generated Python code:
+
+- **Hallucinated imports** — modules LLMs frequently invent (e.g. `utils`, `helpers`, `misc`)
+- **Dead code** — unused variables, unreachable branches, code after `return`/`raise`
+- **Suspicious API usage** — wrong method names for stdlib modules, `open().read()` patterns
+- **Confidence scoring** — each file gets a 0–100 score based on findings severity
+
+## Installation
+
+```bash
+pip install aicheck
+```
+
+## Quick Start
+
+```bash
+# Check a single file
+aicheck check my_file.py
+
+# Check an entire project
+aicheck check src/
+
+# JSON output for CI integration
+aicheck check src/ --format json
+```
+
+## Sample Output
+
+```
+[FAIL] src/suspicious.py  (score: 62.0)
+    high  L1:0  [hallucinated_import] Potentially hallucinated module: 'utils'
+           ↳ Verify 'utils' exists; check PyPI or project dependencies
+  medium  L14:4  [unreachable_code] Unreachable branch: condition is always False
+     low  L11:4  [dead_code] Possibly unused variable: 'unused_var'
+
+Files: 1  Passed: 0  Failed: 1
+Average confidence score: 62.0/100
+```
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `aicheck check <path>` | Analyze a file or directory |
+| `aicheck check <path> --format json` | Output as JSON |
+| `aicheck version` | Show version |
+
+## Score Interpretation
+
+| Score | Meaning |
+|---|---|
+| 100–90 | Clean |
+| 89–70 | Minor issues |
+| 69–50 | Moderate issues — review recommended |
+| <50 | Critical — do not commit without review |
+
+## Development
+
+```bash
+git clone https://github.com/maheshmakvana/ai-check.git
+cd ai-check
+python -m venv venv && source venv/bin/activate
+pip install -e ".[test]"
+pytest tests/ -v
+ruff check src/
+mypy src/
+```
+
+## License
+
+MIT

aicheck-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+aicheck/__init__.py,sha256=Nou2fyj0YdJwS0Ac7uylkqMsewiW2PBU6-U_DJ7zwYk,95
+aicheck/__main__.py,sha256=qO9J--ZracllvI82Yvm5VbPwJ6HMOvQwr16xMr0Qr2w,68
+aicheck/analyzer.py,sha256=3b_FLWM_slOlgs14m03O7l92i1GS4GELIgU5fJEnZw0,3239
+aicheck/cli.py,sha256=qCSW1Z0bMzo3f4D9p1WrFhSkrR5ZH8LOXTwNMhNBlzA,1624
+aicheck/models.py,sha256=EF49aSmTvdwHT1PKXAaUV3ghtRXWv04lWtoO8UgA2yQ,1117
+aicheck/detectors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aicheck/detectors/api_usage.py,sha256=cIDRpHcoMwpRtguLDPSzSL-15QhLyB9XNcM5KAbIJeg,3302
+aicheck/detectors/dead_code.py,sha256=4CumefKRCrLmXYWi7RvLslBc_NfiCKyVSE29grg9v-4,2992
+aicheck/detectors/hallucination.py,sha256=I5E047KdgsR6jMcBRFQgqMkFojiD6lk_yGcycKTh3aI,2039
+aicheck/reporters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aicheck/reporters/console.py,sha256=cGJe6PxLudbjmMjPelj-_hHLHPdTTtpW7eKqVhz-zFU,2153
+aicheck-0.1.0.dist-info/licenses/LICENSE,sha256=0zsWw8F2DlZR_O7d0Q5nbKLHMtR6TLFmmPg2ydwiQhw,1070
+aicheck-0.1.0.dist-info/METADATA,sha256=tE5Sd2UFAyoABvuk9X1yy_heBUWPHaDXIEpREN8izKk,3302
+aicheck-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+aicheck-0.1.0.dist-info/entry_points.txt,sha256=LtifEuMHrM2bGF9CI2cr-3p3neHfBYN7DIpK-MdvuaQ,45
+aicheck-0.1.0.dist-info/top_level.txt,sha256=YudTcArgQTnZ2GWpH5h5UAvkbcyXBMNVhuWXDmqI8F4,8
+aicheck-0.1.0.dist-info/RECORD,,

aicheck-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aicheck-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+aicheck = aicheck.cli:main

aicheck-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mahesh Makvana
+
+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.

aicheck-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aicheck