supersonar 0.1.0__tar.gz

supersonar-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: supersonar
+Version: 0.1.0
+Summary: A SonarQube-like static analysis CLI for Python projects.
+Author: Supersonar Contributors
+License: MIT
+Keywords: static-analysis,lint,security,ci,sonarqube
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# supersonar
+
+`supersonar` is a lightweight, SonarQube-inspired static analysis CLI for Python projects.
+It is designed for local use and CI pipelines via `pip install`.
+
+## Quick start
+
+```bash
+pip install .
+supersonar scan . --format json
+```
+
+## CI usage
+
+```bash
+pip install supersonar
+supersonar scan . --format sarif --out reports/supersonar.sarif --fail-on high
+```
+
+## Config (`supersonar.toml`)
+
+```toml
+[scan]
+exclude = [".git", ".venv", "venv", "build", "dist", "__pycache__"]
+
+[quality_gate]
+fail_on = "high"
+max_issues = 0
+
+[report]
+format = "json"
+```
+
+## Rule coverage (MVP)
+
+- `SS001` - dangerous `eval` / `exec`
+- `SS002` - broad `except Exception` or bare `except`
+- `SS003` - hardcoded secret-like tokens
+- `SS004` - `TODO` / `FIXME` markers

supersonar-0.1.0/README.md

@@ -0,0 +1,39 @@
+# supersonar
+
+`supersonar` is a lightweight, SonarQube-inspired static analysis CLI for Python projects.
+It is designed for local use and CI pipelines via `pip install`.
+
+## Quick start
+
+```bash
+pip install .
+supersonar scan . --format json
+```
+
+## CI usage
+
+```bash
+pip install supersonar
+supersonar scan . --format sarif --out reports/supersonar.sarif --fail-on high
+```
+
+## Config (`supersonar.toml`)
+
+```toml
+[scan]
+exclude = [".git", ".venv", "venv", "build", "dist", "__pycache__"]
+
+[quality_gate]
+fail_on = "high"
+max_issues = 0
+
+[report]
+format = "json"
+```
+
+## Rule coverage (MVP)
+
+- `SS001` - dangerous `eval` / `exec`
+- `SS002` - broad `except Exception` or bare `except`
+- `SS003` - hardcoded secret-like tokens
+- `SS004` - `TODO` / `FIXME` markers

supersonar-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "supersonar"
+version = "0.1.0"
+description = "A SonarQube-like static analysis CLI for Python projects."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Supersonar Contributors" }]
+license = { text = "MIT" }
+keywords = ["static-analysis", "lint", "security", "ci", "sonarqube"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "License :: OSI Approved :: MIT License",
+  "Environment :: Console",
+]
+
+[project.scripts]
+supersonar = "supersonar.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["supersonar*"]
+

supersonar-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

supersonar-0.1.0/supersonar/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+__version__ = "0.1.0"
+

supersonar-0.1.0/supersonar/__main__.py

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

supersonar-0.1.0/supersonar/cli.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from supersonar.config import Config, load_config
+from supersonar.models import Severity
+from supersonar.quality_gate import evaluate_gate
+from supersonar.reporters import to_json_report, to_sarif_report, write_report
+from supersonar.scanner import scan_path
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="supersonar", description="Static analysis scanner for Python.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scan = subparsers.add_parser("scan", help="Run static analysis scan.")
+    scan.add_argument("path", nargs="?", default=".", help="Path to scan.")
+    scan.add_argument("--config", help="Path to supersonar TOML config.")
+    scan.add_argument("--exclude", action="append", default=[], help="Extra exclude directory names.")
+    scan.add_argument("--format", choices=["json", "sarif"], help="Report output format.")
+    scan.add_argument("--out", help="Write report to file. Defaults to stdout.")
+    scan.add_argument("--fail-on", choices=["low", "medium", "high", "critical"], help="Fail on severity level.")
+    scan.add_argument("--max-issues", type=int, help="Fail if issue count exceeds this number.")
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command == "scan":
+        exit_code = run_scan(args)
+        raise SystemExit(exit_code)
+
+
+def run_scan(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    merged = merge_cli_with_config(args, config)
+
+    result = scan_path(args.path, excludes=merged.scan.exclude)
+    report_payload = render_report(result, merged.report.output_format)
+    write_report(report_payload, merged.report.out)
+
+    passed, reasons = evaluate_gate(
+        result,
+        fail_on=merged.quality_gate.fail_on,
+        max_issues=merged.quality_gate.max_issues,
+    )
+    if not passed:
+        for reason in reasons:
+            print(f"[gate] {reason}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def merge_cli_with_config(args: argparse.Namespace, config: Config) -> Config:
+    merged = config
+    if args.exclude:
+        merged.scan.exclude = list(dict.fromkeys([*merged.scan.exclude, *args.exclude]))
+    if args.format:
+        merged.report.output_format = args.format
+    if args.out:
+        merged.report.out = args.out
+    if args.fail_on:
+        merged.quality_gate.fail_on = args.fail_on
+    if args.max_issues is not None:
+        merged.quality_gate.max_issues = args.max_issues
+    return merged
+
+
+def render_report(result, output_format: str):
+    if output_format == "sarif":
+        return to_sarif_report(result)
+    if output_format == "json":
+        return to_json_report(result)
+    raise ValueError(f"Unsupported report format: {output_format}")
+
+
+if __name__ == "__main__":
+    main()
+

supersonar-0.1.0/supersonar/config.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+import tomllib
+
+from supersonar.models import Severity
+
+
+DEFAULT_EXCLUDES = [".git", ".venv", "venv", "build", "dist", "__pycache__"]
+
+
+@dataclass(slots=True)
+class ScanConfig:
+    exclude: list[str] = field(default_factory=lambda: DEFAULT_EXCLUDES.copy())
+
+
+@dataclass(slots=True)
+class QualityGateConfig:
+    fail_on: Severity | None = None
+    max_issues: int | None = None
+
+
+@dataclass(slots=True)
+class ReportConfig:
+    output_format: str = "json"
+    out: str | None = None
+
+
+@dataclass(slots=True)
+class Config:
+    scan: ScanConfig = field(default_factory=ScanConfig)
+    quality_gate: QualityGateConfig = field(default_factory=QualityGateConfig)
+    report: ReportConfig = field(default_factory=ReportConfig)
+
+
+def load_config(path: str | None) -> Config:
+    if path is None:
+        default = Path("supersonar.toml")
+        if not default.exists():
+            return Config()
+        path = str(default)
+
+    cfg_path = Path(path)
+    if not cfg_path.exists():
+        raise FileNotFoundError(f"Config file not found: {cfg_path}")
+
+    with cfg_path.open("rb") as fh:
+        payload = tomllib.load(fh)
+
+    scan = payload.get("scan", {})
+    quality_gate = payload.get("quality_gate", {})
+    report = payload.get("report", {})
+
+    config = Config()
+    config.scan.exclude = list(scan.get("exclude", config.scan.exclude))
+    config.quality_gate.fail_on = quality_gate.get("fail_on")
+    config.quality_gate.max_issues = quality_gate.get("max_issues")
+    config.report.output_format = report.get("format", config.report.output_format)
+    config.report.out = report.get("out")
+    return config
+

supersonar-0.1.0/supersonar/models.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Severity = Literal["low", "medium", "high", "critical"]
+
+
+@dataclass(slots=True)
+class Issue:
+    rule_id: str
+    title: str
+    severity: Severity
+    message: str
+    file_path: str
+    line: int
+    column: int
+
+
+@dataclass(slots=True)
+class ScanResult:
+    issues: list[Issue]
+    files_scanned: int
+

supersonar-0.1.0/supersonar/quality_gate.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from supersonar.models import ScanResult, Severity
+
+
+SEVERITY_ORDER: dict[Severity, int] = {
+    "low": 1,
+    "medium": 2,
+    "high": 3,
+    "critical": 4,
+}
+
+
+def evaluate_gate(
+    result: ScanResult,
+    fail_on: Severity | None = None,
+    max_issues: int | None = None,
+) -> tuple[bool, list[str]]:
+    failed_reasons: list[str] = []
+
+    if fail_on is not None:
+        threshold = SEVERITY_ORDER[fail_on]
+        if any(SEVERITY_ORDER[issue.severity] >= threshold for issue in result.issues):
+            failed_reasons.append(f"Detected issue severity >= '{fail_on}'")
+
+    if max_issues is not None and len(result.issues) > max_issues:
+        failed_reasons.append(f"Issue count {len(result.issues)} exceeds max_issues={max_issues}")
+
+    return (len(failed_reasons) == 0, failed_reasons)
+

supersonar-0.1.0/supersonar/reporters.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from collections import Counter
+import json
+from pathlib import Path
+from typing import Any
+
+from supersonar.models import Issue, ScanResult
+
+
+def _issue_to_dict(issue: Issue) -> dict[str, Any]:
+    return {
+        "rule_id": issue.rule_id,
+        "title": issue.title,
+        "severity": issue.severity,
+        "message": issue.message,
+        "file_path": issue.file_path,
+        "line": issue.line,
+        "column": issue.column,
+    }
+
+
+def to_json_report(result: ScanResult) -> dict[str, Any]:
+    counts = Counter(issue.severity for issue in result.issues)
+    return {
+        "files_scanned": result.files_scanned,
+        "issues_total": len(result.issues),
+        "severity_counts": dict(counts),
+        "issues": [_issue_to_dict(issue) for issue in result.issues],
+    }
+
+
+def to_sarif_report(result: ScanResult) -> dict[str, Any]:
+    sarif_results: list[dict[str, Any]] = []
+    for issue in result.issues:
+        sarif_results.append(
+            {
+                "ruleId": issue.rule_id,
+                "level": _severity_to_level(issue.severity),
+                "message": {"text": f"{issue.title}: {issue.message}"},
+                "locations": [
+                    {
+                        "physicalLocation": {
+                            "artifactLocation": {"uri": issue.file_path},
+                            "region": {"startLine": issue.line, "startColumn": issue.column},
+                        }
+                    }
+                ],
+            }
+        )
+
+    return {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {"driver": {"name": "supersonar", "informationUri": "https://example.com"}},
+                "results": sarif_results,
+            }
+        ],
+    }
+
+
+def write_report(payload: dict[str, Any], out: str | None) -> None:
+    rendered = json.dumps(payload, indent=2)
+    if out is None:
+        print(rendered)
+        return
+    output_path = Path(out)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(rendered, encoding="utf-8")
+
+
+def _severity_to_level(severity: str) -> str:
+    mapping = {
+        "low": "note",
+        "medium": "warning",
+        "high": "error",
+        "critical": "error",
+    }
+    return mapping.get(severity, "warning")
+

supersonar-0.1.0/supersonar/rules/__init__.py

@@ -0,0 +1,4 @@
+from supersonar.rules.python import PythonRuleEngine
+
+__all__ = ["PythonRuleEngine"]
+

supersonar-0.1.0/supersonar/rules/python.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+import re
+
+from supersonar.models import Issue
+
+
+SECRET_PATTERN = re.compile(
+    r"(api[_-]?key|secret|token|password)\s*=\s*['\"][^'\"]{8,}['\"]",
+    re.IGNORECASE,
+)
+
+
+class PythonRuleEngine:
+    def run(self, file_path: Path) -> list[Issue]:
+        source = file_path.read_text(encoding="utf-8", errors="replace")
+        issues: list[Issue] = []
+        issues.extend(self._find_todo_fixme(source, file_path))
+        issues.extend(self._find_secrets(source, file_path))
+        issues.extend(self._analyze_ast(source, file_path))
+        return issues
+
+    def _find_todo_fixme(self, source: str, file_path: Path) -> list[Issue]:
+        issues: list[Issue] = []
+        for idx, line in enumerate(source.splitlines(), start=1):
+            if "TODO" in line or "FIXME" in line:
+                issues.append(
+                    Issue(
+                        rule_id="SS004",
+                        title="Work item marker in source",
+                        severity="low",
+                        message="Found TODO/FIXME marker. Track and resolve before release.",
+                        file_path=str(file_path),
+                        line=idx,
+                        column=max(line.find("TODO"), line.find("FIXME"), 0) + 1,
+                    )
+                )
+        return issues
+
+    def _find_secrets(self, source: str, file_path: Path) -> list[Issue]:
+        issues: list[Issue] = []
+        for idx, line in enumerate(source.splitlines(), start=1):
+            if SECRET_PATTERN.search(line):
+                issues.append(
+                    Issue(
+                        rule_id="SS003",
+                        title="Potential hardcoded secret",
+                        severity="high",
+                        message="Potential credential/token assignment found in source.",
+                        file_path=str(file_path),
+                        line=idx,
+                        column=1,
+                    )
+                )
+        return issues
+
+    def _analyze_ast(self, source: str, file_path: Path) -> list[Issue]:
+        issues: list[Issue] = []
+        try:
+            tree = ast.parse(source)
+        except SyntaxError as exc:
+            issues.append(
+                Issue(
+                    rule_id="SS000",
+                    title="Syntax error",
+                    severity="medium",
+                    message=f"Could not parse file: {exc.msg}",
+                    file_path=str(file_path),
+                    line=exc.lineno or 1,
+                    column=exc.offset or 1,
+                )
+            )
+            return issues
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+                if node.func.id in {"eval", "exec"}:
+                    issues.append(
+                        Issue(
+                            rule_id="SS001",
+                            title="Dangerous dynamic execution",
+                            severity="critical",
+                            message=f"Avoid {node.func.id}() because it executes dynamic code.",
+                            file_path=str(file_path),
+                            line=getattr(node, "lineno", 1),
+                            column=getattr(node, "col_offset", 0) + 1,
+                        )
+                    )
+            if isinstance(node, ast.ExceptHandler):
+                is_bare = node.type is None
+                is_exception = isinstance(node.type, ast.Name) and node.type.id == "Exception"
+                if is_bare or is_exception:
+                    issues.append(
+                        Issue(
+                            rule_id="SS002",
+                            title="Broad exception handling",
+                            severity="medium",
+                            message="Avoid bare except or except Exception; catch specific errors.",
+                            file_path=str(file_path),
+                            line=getattr(node, "lineno", 1),
+                            column=getattr(node, "col_offset", 0) + 1,
+                        )
+                    )
+        return issues
+

supersonar-0.1.0/supersonar/scanner.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from supersonar.models import Issue, ScanResult
+from supersonar.rules import PythonRuleEngine
+
+
+def _should_exclude(path: Path, excludes: list[str]) -> bool:
+    parts = set(path.parts)
+    return any(ex in parts for ex in excludes)
+
+
+def scan_path(root: str, excludes: list[str]) -> ScanResult:
+    root_path = Path(root).resolve()
+    rule_engine = PythonRuleEngine()
+    issues: list[Issue] = []
+    files_scanned = 0
+
+    for file_path in root_path.rglob("*.py"):
+        if _should_exclude(file_path, excludes):
+            continue
+        files_scanned += 1
+        issues.extend(rule_engine.run(file_path))
+
+    return ScanResult(issues=issues, files_scanned=files_scanned)
+

supersonar-0.1.0/supersonar.egg-info/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: supersonar
+Version: 0.1.0
+Summary: A SonarQube-like static analysis CLI for Python projects.
+Author: Supersonar Contributors
+License: MIT
+Keywords: static-analysis,lint,security,ci,sonarqube
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# supersonar
+
+`supersonar` is a lightweight, SonarQube-inspired static analysis CLI for Python projects.
+It is designed for local use and CI pipelines via `pip install`.
+
+## Quick start
+
+```bash
+pip install .
+supersonar scan . --format json
+```
+
+## CI usage
+
+```bash
+pip install supersonar
+supersonar scan . --format sarif --out reports/supersonar.sarif --fail-on high
+```
+
+## Config (`supersonar.toml`)
+
+```toml
+[scan]
+exclude = [".git", ".venv", "venv", "build", "dist", "__pycache__"]
+
+[quality_gate]
+fail_on = "high"
+max_issues = 0
+
+[report]
+format = "json"
+```
+
+## Rule coverage (MVP)
+
+- `SS001` - dangerous `eval` / `exec`
+- `SS002` - broad `except Exception` or bare `except`
+- `SS003` - hardcoded secret-like tokens
+- `SS004` - `TODO` / `FIXME` markers

supersonar-0.1.0/supersonar.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+pyproject.toml
+supersonar/__init__.py
+supersonar/__main__.py
+supersonar/cli.py
+supersonar/config.py
+supersonar/models.py
+supersonar/quality_gate.py
+supersonar/reporters.py
+supersonar/scanner.py
+supersonar.egg-info/PKG-INFO
+supersonar.egg-info/SOURCES.txt
+supersonar.egg-info/dependency_links.txt
+supersonar.egg-info/entry_points.txt
+supersonar.egg-info/top_level.txt
+supersonar/rules/__init__.py
+supersonar/rules/python.py
+tests/test_quality_gate.py
+tests/test_scanner.py

supersonar-0.1.0/supersonar.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

supersonar-0.1.0/supersonar.egg-info/entry_points.txt

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

supersonar-0.1.0/supersonar.egg-info/top_level.txt

@@ -0,0 +1 @@
+supersonar

supersonar-0.1.0/tests/test_quality_gate.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import unittest
+
+from supersonar.models import Issue, ScanResult
+from supersonar.quality_gate import evaluate_gate
+
+
+class QualityGateTests(unittest.TestCase):
+    def test_fails_on_severity_threshold(self) -> None:
+        result = ScanResult(
+            issues=[
+                Issue(
+                    rule_id="SS001",
+                    title="t",
+                    severity="critical",
+                    message="m",
+                    file_path="x.py",
+                    line=1,
+                    column=1,
+                )
+            ],
+            files_scanned=1,
+        )
+        passed, reasons = evaluate_gate(result, fail_on="high")
+        self.assertFalse(passed)
+        self.assertTrue(reasons)
+
+    def test_passes_under_max_issues(self) -> None:
+        result = ScanResult(issues=[], files_scanned=1)
+        passed, reasons = evaluate_gate(result, max_issues=0)
+        self.assertTrue(passed)
+        self.assertEqual(reasons, [])
+
+
+if __name__ == "__main__":
+    unittest.main()
+

supersonar-0.1.0/tests/test_scanner.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from pathlib import Path
+import tempfile
+import unittest
+
+from supersonar.scanner import scan_path
+
+
+class ScannerTests(unittest.TestCase):
+    def test_detects_eval_issue(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            sample = root / "sample.py"
+            sample.write_text("value = eval('2+2')\n", encoding="utf-8")
+
+            result = scan_path(str(root), excludes=[])
+            rule_ids = {issue.rule_id for issue in result.issues}
+
+            self.assertIn("SS001", rule_ids)
+            self.assertEqual(result.files_scanned, 1)
+
+    def test_excludes_directory(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            src = root / "src"
+            src.mkdir()
+            ignored = root / "venv"
+            ignored.mkdir()
+            (src / "ok.py").write_text("print('ok')\n", encoding="utf-8")
+            (ignored / "bad.py").write_text("eval('x')\n", encoding="utf-8")
+
+            result = scan_path(str(root), excludes=["venv"])
+            rule_ids = {issue.rule_id for issue in result.issues}
+
+            self.assertNotIn("SS001", rule_ids)
+            self.assertEqual(result.files_scanned, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()
+