parallax-scan 0.3.0__tar.gz

parallax_scan-0.3.0/LICENSE

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

parallax_scan-0.3.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: parallax-scan
+Version: 0.3.0
+Summary: Find functions that work on the same resource through different code paths — the architectural-duplication detector that token-similarity tools miss.
+Author-email: Ziyad Alotaibi <ziyad.alotaibe@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ziyad00/parallax
+Project-URL: Issues, https://github.com/ziyad00/parallax/issues
+Keywords: duplication,static-analysis,ast,refactor,code-quality
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# parallax
+
+[![PyPI version](https://img.shields.io/pypi/v/parallax-scan.svg)](https://pypi.org/project/parallax-scan/)
+[![CI](https://github.com/ziyad00/parallax/actions/workflows/ci.yml/badge.svg)](https://github.com/ziyad00/parallax/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Find code that does the same logical job through different paths.
+
+Token-similarity tools (jscpd, PMD CPD, `pylint duplicate-code`) detect copy-paste. parallax detects something different: two pieces of code that touch the same set of resources, regardless of how the code is written. Different filters, different return shapes, even different languages.
+
+## Model
+
+A **unit** of code (function, method, file, module, microservice, ...) touches a set of **resources** (database tables, HTTP endpoints, Redis keys, env vars, file paths, ...). Units sharing the same resource set are clustered as duplication candidates.
+
+Both unit detection and resource detection are pluggable per **extractor**.
+
+## Built-in extractors
+
+| Name | Unit | Resource |
+|---|---|---|
+| `sqlalchemy` | Python function/method | SQLAlchemy ORM model classes |
+| `django` | Python function/method | Django ORM model classes |
+| `http-urls` | any text file | HTTP URL paths |
+| `env-vars` | any text file | Environment variable names |
+| `redis-keys` | any text file | Redis key namespaces |
+
+## Installation
+
+```bash
+pip install parallax-scan
+```
+
+## Usage
+
+```bash
+parallax scan path/to/repo
+parallax scan path/to/repo --extractor sqlalchemy
+parallax scan path/to/repo -e sqlalchemy -e http-urls
+parallax scan path/to/repo --min-resources 3 --top 20
+parallax scan path/to/repo --cross-file-only
+parallax scan path/to/repo --format html -o report.html
+parallax scan path/to/repo --format sarif -o parallax.sarif
+```
+
+## Configuration
+
+Drop `.parallax.toml` at your repo root:
+
+```toml
+[scan]
+min_resources = 3
+min_cluster_size = 2
+
+[ci]
+max_cluster_size = 5
+
+[[ignore]]
+resources = ["User", "Place"]
+reason = "Generic"
+```
+
+In CI:
+
+```bash
+parallax scan . --ci
+parallax scan . --format sarif -o parallax.sarif
+```
+
+`--ci` exits non-zero only when a cluster meets `ci.max_cluster_size`. Without it, any cluster is non-zero.
+
+## Comparison
+
+| Tool | Catches | Doesn't catch |
+|---|---|---|
+| jscpd, PMD CPD, pylint duplicate-code | Token-similar copy-paste | Code with different surface shape |
+| Sourcegraph | Manual code search | Automatic detection |
+| `pydeps`, `dependency-cruiser` | Module-level imports | Same-resource overlap |
+| semgrep | Hand-written patterns | Discovery |
+| parallax | Same-resource overlap regardless of shape | Single-instance bad patterns |
+
+## Status
+
+Alpha. API and CLI are unstable until 1.0.
+
+## Writing an extractor
+
+```python
+from pathlib import Path
+from typing import Iterable
+
+from parallax import Unit
+from parallax.extractors.base import Extractor
+
+
+class TerraformAwsExtractor(Extractor):
+    name = "terraform-aws"
+
+    def extract(self, root: Path) -> Iterable[Unit]:
+        for tf in root.rglob("*.tf"):
+            ...
+```
+
+Register in `parallax.extractors.BUILTIN_EXTRACTORS`.
+
+## License
+
+MIT

parallax_scan-0.3.0/README.md

@@ -0,0 +1,107 @@
+# parallax
+
+[![PyPI version](https://img.shields.io/pypi/v/parallax-scan.svg)](https://pypi.org/project/parallax-scan/)
+[![CI](https://github.com/ziyad00/parallax/actions/workflows/ci.yml/badge.svg)](https://github.com/ziyad00/parallax/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Find code that does the same logical job through different paths.
+
+Token-similarity tools (jscpd, PMD CPD, `pylint duplicate-code`) detect copy-paste. parallax detects something different: two pieces of code that touch the same set of resources, regardless of how the code is written. Different filters, different return shapes, even different languages.
+
+## Model
+
+A **unit** of code (function, method, file, module, microservice, ...) touches a set of **resources** (database tables, HTTP endpoints, Redis keys, env vars, file paths, ...). Units sharing the same resource set are clustered as duplication candidates.
+
+Both unit detection and resource detection are pluggable per **extractor**.
+
+## Built-in extractors
+
+| Name | Unit | Resource |
+|---|---|---|
+| `sqlalchemy` | Python function/method | SQLAlchemy ORM model classes |
+| `django` | Python function/method | Django ORM model classes |
+| `http-urls` | any text file | HTTP URL paths |
+| `env-vars` | any text file | Environment variable names |
+| `redis-keys` | any text file | Redis key namespaces |
+
+## Installation
+
+```bash
+pip install parallax-scan
+```
+
+## Usage
+
+```bash
+parallax scan path/to/repo
+parallax scan path/to/repo --extractor sqlalchemy
+parallax scan path/to/repo -e sqlalchemy -e http-urls
+parallax scan path/to/repo --min-resources 3 --top 20
+parallax scan path/to/repo --cross-file-only
+parallax scan path/to/repo --format html -o report.html
+parallax scan path/to/repo --format sarif -o parallax.sarif
+```
+
+## Configuration
+
+Drop `.parallax.toml` at your repo root:
+
+```toml
+[scan]
+min_resources = 3
+min_cluster_size = 2
+
+[ci]
+max_cluster_size = 5
+
+[[ignore]]
+resources = ["User", "Place"]
+reason = "Generic"
+```
+
+In CI:
+
+```bash
+parallax scan . --ci
+parallax scan . --format sarif -o parallax.sarif
+```
+
+`--ci` exits non-zero only when a cluster meets `ci.max_cluster_size`. Without it, any cluster is non-zero.
+
+## Comparison
+
+| Tool | Catches | Doesn't catch |
+|---|---|---|
+| jscpd, PMD CPD, pylint duplicate-code | Token-similar copy-paste | Code with different surface shape |
+| Sourcegraph | Manual code search | Automatic detection |
+| `pydeps`, `dependency-cruiser` | Module-level imports | Same-resource overlap |
+| semgrep | Hand-written patterns | Discovery |
+| parallax | Same-resource overlap regardless of shape | Single-instance bad patterns |
+
+## Status
+
+Alpha. API and CLI are unstable until 1.0.
+
+## Writing an extractor
+
+```python
+from pathlib import Path
+from typing import Iterable
+
+from parallax import Unit
+from parallax.extractors.base import Extractor
+
+
+class TerraformAwsExtractor(Extractor):
+    name = "terraform-aws"
+
+    def extract(self, root: Path) -> Iterable[Unit]:
+        for tf in root.rglob("*.tf"):
+            ...
+```
+
+Register in `parallax.extractors.BUILTIN_EXTRACTORS`.
+
+## License
+
+MIT

parallax_scan-0.3.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "parallax-scan"
+version = "0.3.0"
+description = "Find functions that work on the same resource through different code paths — the architectural-duplication detector that token-similarity tools miss."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Ziyad Alotaibi", email = "ziyad.alotaibe@gmail.com" }
+]
+keywords = ["duplication", "static-analysis", "ast", "refactor", "code-quality"]
+dependencies = [
+  "tomli; python_version < '3.11'",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Quality Assurance",
+  "Intended Audience :: Developers",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7",
+  "pytest-cov>=4",
+  "ruff>=0.5",
+]
+
+[project.scripts]
+parallax = "parallax.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/ziyad00/parallax"
+Issues = "https://github.com/ziyad00/parallax/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

parallax_scan-0.3.0/setup.cfg

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

parallax_scan-0.3.0/src/parallax/__init__.py

@@ -0,0 +1,20 @@
+"""parallax: find code that does the same logical job through different paths."""
+
+from .core import (
+    Cluster,
+    FoldedGroup,
+    Unit,
+    fold_units_by_class,
+    group_by_resource_set,
+)
+from .extractors.base import Extractor
+
+__all__ = [
+    "Cluster",
+    "Extractor",
+    "FoldedGroup",
+    "Unit",
+    "fold_units_by_class",
+    "group_by_resource_set",
+]
+__version__ = "0.3.0"

parallax_scan-0.3.0/src/parallax/cli.py

@@ -0,0 +1,270 @@
+"""parallax CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .config import Config, load_config
+from .core import Cluster, Unit, group_by_resource_set
+from .extractors import BUILTIN_EXTRACTORS
+from .reporters import render_html, render_json, render_sarif, render_text
+from .verify import verify_cluster
+
+
+REPORTERS = {"text", "json", "html", "sarif"}
+
+
+def _build_argparser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="parallax",
+        description="Find code that does the same logical job through different paths.",
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+
+    scan = sub.add_parser("scan", help="Scan a tree for clusters of overlapping units.")
+    scan.add_argument("path", type=Path, help="Root directory to scan.")
+    scan.add_argument(
+        "--extractor",
+        "-e",
+        action="append",
+        choices=sorted(BUILTIN_EXTRACTORS),
+        help="Which extractor to run. Repeat to combine. Default: all.",
+    )
+    scan.add_argument(
+        "--config",
+        "-c",
+        type=Path,
+        help=(
+            "Path to a config file (TOML). If omitted, parallax looks for "
+            ".parallax.toml in the working directory."
+        ),
+    )
+    scan.add_argument(
+        "--min-resources",
+        type=int,
+        help="Override config.scan.min_resources.",
+    )
+    scan.add_argument(
+        "--min-cluster-size",
+        type=int,
+        help="Override config.scan.min_cluster_size.",
+    )
+    scan.add_argument(
+        "--format",
+        "-f",
+        choices=sorted(REPORTERS),
+        default="text",
+        help="Output format. Default 'text'.",
+    )
+    scan.add_argument(
+        "--output",
+        "-o",
+        type=Path,
+        help="Write output to FILE instead of stdout.",
+    )
+    scan.add_argument(
+        "--json",
+        action="store_true",
+        help="Shortcut for --format json.",
+    )
+    scan.add_argument(
+        "--cross-file-only",
+        action="store_true",
+        help="Drop clusters whose units all live in one file.",
+    )
+    scan.add_argument(
+        "--top",
+        type=int,
+        default=None,
+        help="Limit the report to the N highest-scoring clusters.",
+    )
+    scan.add_argument(
+        "--fold-threshold",
+        type=int,
+        default=5,
+        help="Collapse N+ methods of the same class into one row in text output. Set 0 to disable.",
+    )
+    scan.add_argument(
+        "--ci",
+        action="store_true",
+        help="Exit non-zero only when a cluster meets ci.max_cluster_size from config.",
+    )
+
+    sub.add_parser("list-extractors", help="Print the extractors built into parallax.")
+
+    verify = sub.add_parser(
+        "verify",
+        help="Read a cluster (JSON on stdin or --file) and run deeper analysis.",
+    )
+    verify.add_argument(
+        "--root",
+        type=Path,
+        default=Path("."),
+        help="Source root used to resolve unit locations. Default: cwd.",
+    )
+    verify.add_argument(
+        "--file",
+        type=Path,
+        help="Read the cluster JSON from FILE instead of stdin.",
+    )
+
+    return p
+
+
+def _apply_overrides(args: argparse.Namespace, cfg: Config) -> Config:
+    """CLI flags trump config-file values when given."""
+    if args.min_resources is not None:
+        cfg.min_resources = args.min_resources
+    if args.min_cluster_size is not None:
+        cfg.min_cluster_size = args.min_cluster_size
+    return cfg
+
+
+def _filter_ignored(
+    clusters: list[Cluster], cfg: Config
+) -> tuple[list[Cluster], list[Cluster]]:
+    """Split clusters into (kept, ignored)."""
+    kept: list[Cluster] = []
+    ignored: list[Cluster] = []
+    for c in clusters:
+        if cfg.matches_ignore(c.resources) is not None:
+            ignored.append(c)
+        else:
+            kept.append(c)
+    return kept, ignored
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    if not args.path.exists():
+        print(f"error: {args.path} does not exist", file=sys.stderr)
+        return 2
+
+    cfg = load_config(args.config)
+    cfg = _apply_overrides(args, cfg)
+
+    extractor_names: list[str] = args.extractor or sorted(BUILTIN_EXTRACTORS)
+    units: list[Unit] = []
+    for name in extractor_names:
+        cls = BUILTIN_EXTRACTORS[name]
+        units.extend(cls().extract(args.path))
+
+    clusters = group_by_resource_set(
+        units,
+        min_resources=cfg.min_resources,
+        min_cluster_size=cfg.min_cluster_size,
+        cross_file_only=args.cross_file_only,
+    )
+    kept, ignored = _filter_ignored(clusters, cfg)
+    if args.top is not None and args.top >= 0:
+        kept = kept[: args.top]
+
+    fmt = "json" if args.json else args.format
+    if fmt == "text":
+        output = render_text(
+            kept,
+            scanned_units=len(units),
+            extractors=extractor_names,
+            min_resources=cfg.min_resources,
+            min_cluster_size=cfg.min_cluster_size,
+            fold_threshold=max(0, args.fold_threshold),
+        )
+        if ignored:
+            output += f"\n({len(ignored)} cluster(s) suppressed by ignore rules)\n"
+    elif fmt == "json":
+        output = render_json(kept, scanned_units=len(units))
+    elif fmt == "html":
+        output = render_html(
+            kept,
+            scanned_units=len(units),
+            extractors=extractor_names,
+            min_resources=cfg.min_resources,
+            min_cluster_size=cfg.min_cluster_size,
+        )
+    elif fmt == "sarif":
+        output = render_sarif(kept, scanned_units=len(units), extractors=extractor_names)
+    else:  # pragma: no cover
+        raise ValueError(f"unknown format: {fmt}")
+
+    if args.output:
+        args.output.write_text(output, encoding="utf-8")
+    else:
+        sys.stdout.write(output)
+        if not output.endswith("\n"):
+            sys.stdout.write("\n")
+
+    return _exit_code(kept, cfg, args.ci)
+
+
+def _exit_code(kept: list[Cluster], cfg: Config, ci_mode: bool) -> int:
+    if ci_mode:
+        if cfg.max_cluster_size is None:
+            return 0
+        if any(c.size >= cfg.max_cluster_size for c in kept):
+            return 1
+        return 0
+    return 0 if not kept else 1
+
+
+def cmd_verify(args: argparse.Namespace) -> int:
+    raw = args.file.read_text(encoding="utf-8") if args.file else sys.stdin.read()
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(f"error: invalid JSON: {e}", file=sys.stderr)
+        return 2
+
+    cluster: dict | None
+    if isinstance(payload, dict) and "units" in payload:
+        cluster = payload
+    elif isinstance(payload, dict) and "clusters" in payload and payload["clusters"]:
+        cluster = payload["clusters"][0]
+    else:
+        print(
+            "error: expected a cluster dict (with 'units') or a scan payload "
+            "(with 'clusters')",
+            file=sys.stderr,
+        )
+        return 2
+
+    results = verify_cluster(cluster, root=args.root)
+    if not results:
+        print("No applicable verifiers for this cluster.")
+        return 0
+
+    for r in results:
+        print(
+            f"verifier={r.verifier} "
+            f"recommendation={r.recommendation.value} "
+            f"mean_similarity={r.mean_similarity:.2f}"
+        )
+        for p in r.pairs:
+            print(f"  {p.score:.2f}  {p.a_location}  ~  {p.b_location}")
+    return 0
+
+
+def cmd_list_extractors(_: argparse.Namespace) -> int:
+    for name, cls in sorted(BUILTIN_EXTRACTORS.items()):
+        doc_first_line = (cls.__doc__ or "").strip().splitlines()[:1]
+        summary = doc_first_line[0] if doc_first_line else ""
+        print(f"{name:<14} {summary}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_argparser()
+    args = parser.parse_args(argv)
+    if args.command == "scan":
+        return cmd_scan(args)
+    if args.command == "list-extractors":
+        return cmd_list_extractors(args)
+    if args.command == "verify":
+        return cmd_verify(args)
+    parser.error("unknown command")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())