codeecho 1.1.0__tar.gz → 1.2.0__tar.gz

codeecho-1.2.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 1.2.0 - 2026-09-18
+
+### Added
+
+- `config.ini` (seeded into `CODEECHO_CONFIG_DIR`) with an `[override]` section that lets you rename
+  the `.ignore` file via the `ignore-file` key. Falls back to the bundled `.ignore` when the
+  configured file is missing.
+- `--target-list` flag: treat `PATH` as a single file listing scan targets, one per line (blank
+  lines and `#`-prefixed comments are skipped), instead of passing `PATH` arguments directly.
+- `--basis` flag: file listing basis target paths, one per line — same format as
+  `--target-list`. Absolute file/directory entries are merged into the scan automatically
+  and matched exactly; relative entries (e.g. a bare filename) are matched by filename/suffix
+  against any file discovered in the scan. The report is filtered to only clone groups
+  touching at least one basis file, and groups duplicated purely among basis files are
+  flagged (`basis_internal` in JSON, a "Basis-to-Basis" badge in HTML, `is_basis` per member).
+
+## 1.1.0 - 2026-08-15
+
+### Added
+
+- Gosu (`.gs`, `.gsx`) is now parsed with a dedicated [tree-sitter-gosu](https://github.com/rcw3bb/tree-sitter-gosu)
+  grammar instead of the Java fallback, enabling accurate fragment extraction using Gosu-native node types
+  (`compilation_unit`, `function_declaration`, `constructor_declaration`, `class_declaration`).
+
+## 1.0.1 - 2026-07-10
+
+### Fixed
+
+- Type-3 clone detection no longer flags fragments as clones when one is nested inside the other
+  within the same file (e.g. a `function` inside its enclosing `class`).
+- Type-3 clone groups now drop outer/container fragments (e.g. a whole-`file` fragment) when a
+  more specific nested fragment from the same file is already a member of that group, preventing
+  false positives caused by union-find transitivity.
+
+## 1.0.0 - 2026-07-10
+
+### Added
+
+- Initial release of codeecho.

{codeecho-1.1.0 → codeecho-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeecho
-Version: 1.1.0
+Version: 1.2.0
 Summary: A developer tool that scans your codebase to detect and highlight ECHOES of duplicated or near-duplicated code so you can refactor toward cleaner, more maintainable designs.
 License: MIT License
          
@@ -44,12 +44,11 @@ Requires-Dist: tree-sitter-python (>=0.25.0,<0.26.0)
 Requires-Dist: tree-sitter-typescript (>=0.23.2,<0.24.0)
 Description-Content-Type: text/markdown
 
-# codeecho 1.1.0
+# codeecho 1.2.0
 
-> A developer tool that scans your codebase to detect and highlight **echoes** of duplicated or near-duplicated code, so you can refactor toward cleaner, more maintainable designs.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/rcw3bb/codeecho/blob/main/LICENSE) [![Version](https://img.shields.io/badge/Version-1.2.0-green.svg)](https://github.com/rcw3bb/codeecho/blob/main/CHANGELOG.md) [![Python](https://img.shields.io/badge/Python-3.14%2B-blue)](https://www.python.org/) [![PyPI](https://img.shields.io/badge/PyPI-codeecho-orange)](https://pypi.org/project/codeecho/)
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-1.1.0-blue.svg)](CHANGELOG.md)
+> A developer tool that scans your codebase to detect and highlight **echoes** of duplicated or near-duplicated code, so you can refactor toward cleaner, more maintainable designs.
 
 ## Prerequisites
 
@@ -104,6 +103,8 @@ python -m codeecho <path> [options]
 | `--format <fmt>` | `both` | Output format: `json`, `html`, or `both`. |
 | `--min-tokens <n>` | `10` | Minimum token count for a code fragment to be included. |
 | `--exclude <pattern>` | _(none)_ | Glob pattern(s) to exclude from scanning (repeatable). |
+| `--target-list` | `false` | Treat `PATH` as a single existing file listing target paths (files and/or directories), one per line, instead of individual `PATH` arguments. Blank lines and lines starting with `#` are skipped. |
+| `--basis <file>` | _(none)_ | File listing basis target paths, one per line — same format as `--target-list`. Absolute file/directory entries are merged into the scan automatically and matched exactly; relative entries (e.g. a bare filename like `Foo.gs`) are matched by filename/suffix against any file discovered in the scan. The report is filtered to only clone groups touching at least one basis file, and groups duplicated purely among basis files are flagged (`basis_internal` in JSON, a "Basis-to-Basis" badge in HTML). |
 | `--version` | | Print the version and exit. |
 | `-h, --help` | | Show help and exit. |
 
@@ -139,16 +140,39 @@ Exclude test and vendor directories:
 python -m codeecho . --exclude "*/tests/*" --exclude "*/vendor/*"
 ```
 
+Scan targets listed in a file, one path per line:
+
+```powershell
+python -m codeecho targets.txt --target-list
+```
+
+Find where code from a reference/basis set of files is duplicated elsewhere in the codebase:
+
+```powershell
+python -m codeecho src --basis basis.txt
+```
+
 ## Configuration
 
 | Environment variable | Description |
 |----------------------|-------------|
-| `CODEECHO_CONFIG_DIR` | Directory where `logging.ini` and `.ignore` are seeded on first run. When unset, the bundled copies inside the package are used directly. |
+| `CODEECHO_CONFIG_DIR` | Directory where `logging.ini`, `.ignore`, and `config.ini` are seeded on first run. When unset, the bundled copies inside the package are used directly. |
 
 ### `.ignore` file
 
 On first run, a `.ignore` file is seeded into `CODEECHO_CONFIG_DIR` (or the package directory when unset). It follows gitignore syntax and is applied during file scanning to exclude paths in addition to any `--exclude` patterns passed on the command line. Edit this file to permanently suppress paths you never want scanned.
 
+### Overriding the ignore filename
+
+`config.ini` (also seeded into `CODEECHO_CONFIG_DIR` on first run) contains an `[override]` section with an `ignore-file` key, which names the file used in place of `.ignore`, resolved relative to `CODEECHO_CONFIG_DIR`:
+
+```ini
+[override]
+ignore-file = .ignore
+```
+
+Point `ignore-file` at a different filename to use an alternate ignore file (also placed inside `CODEECHO_CONFIG_DIR`). If the configured file is missing, codeecho logs a warning and falls back to the bundled `.ignore`.
+
 ## Development
 
 ### Prerequisites
@@ -197,11 +221,11 @@ poetry run pylint codeecho
 poetry run pytest --cov=codeecho tests --cov-report html
 ```
 
-## [Changelog](CHANGELOG.md)
+## [Changelog](https://github.com/rcw3bb/codeecho/blob/main/CHANGELOG.md)
 
 ## License
 
-This project is licensed under the [MIT License](LICENSE).
+This project is licensed under the [MIT License](https://github.com/rcw3bb/codeecho/blob/main/LICENSE).
 
 ## Author
 

{codeecho-1.1.0 → codeecho-1.2.0}/README.md

@@ -1,9 +1,8 @@
-# codeecho 1.1.0
+# codeecho 1.2.0
 
-> A developer tool that scans your codebase to detect and highlight **echoes** of duplicated or near-duplicated code, so you can refactor toward cleaner, more maintainable designs.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/rcw3bb/codeecho/blob/main/LICENSE) [![Version](https://img.shields.io/badge/Version-1.2.0-green.svg)](https://github.com/rcw3bb/codeecho/blob/main/CHANGELOG.md) [![Python](https://img.shields.io/badge/Python-3.14%2B-blue)](https://www.python.org/) [![PyPI](https://img.shields.io/badge/PyPI-codeecho-orange)](https://pypi.org/project/codeecho/)
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-1.1.0-blue.svg)](CHANGELOG.md)
+> A developer tool that scans your codebase to detect and highlight **echoes** of duplicated or near-duplicated code, so you can refactor toward cleaner, more maintainable designs.
 
 ## Prerequisites
 
@@ -58,6 +57,8 @@ python -m codeecho <path> [options]
 | `--format <fmt>` | `both` | Output format: `json`, `html`, or `both`. |
 | `--min-tokens <n>` | `10` | Minimum token count for a code fragment to be included. |
 | `--exclude <pattern>` | _(none)_ | Glob pattern(s) to exclude from scanning (repeatable). |
+| `--target-list` | `false` | Treat `PATH` as a single existing file listing target paths (files and/or directories), one per line, instead of individual `PATH` arguments. Blank lines and lines starting with `#` are skipped. |
+| `--basis <file>` | _(none)_ | File listing basis target paths, one per line — same format as `--target-list`. Absolute file/directory entries are merged into the scan automatically and matched exactly; relative entries (e.g. a bare filename like `Foo.gs`) are matched by filename/suffix against any file discovered in the scan. The report is filtered to only clone groups touching at least one basis file, and groups duplicated purely among basis files are flagged (`basis_internal` in JSON, a "Basis-to-Basis" badge in HTML). |
 | `--version` | | Print the version and exit. |
 | `-h, --help` | | Show help and exit. |
 
@@ -93,16 +94,39 @@ Exclude test and vendor directories:
 python -m codeecho . --exclude "*/tests/*" --exclude "*/vendor/*"
 ```
 
+Scan targets listed in a file, one path per line:
+
+```powershell
+python -m codeecho targets.txt --target-list
+```
+
+Find where code from a reference/basis set of files is duplicated elsewhere in the codebase:
+
+```powershell
+python -m codeecho src --basis basis.txt
+```
+
 ## Configuration
 
 | Environment variable | Description |
 |----------------------|-------------|
-| `CODEECHO_CONFIG_DIR` | Directory where `logging.ini` and `.ignore` are seeded on first run. When unset, the bundled copies inside the package are used directly. |
+| `CODEECHO_CONFIG_DIR` | Directory where `logging.ini`, `.ignore`, and `config.ini` are seeded on first run. When unset, the bundled copies inside the package are used directly. |
 
 ### `.ignore` file
 
 On first run, a `.ignore` file is seeded into `CODEECHO_CONFIG_DIR` (or the package directory when unset). It follows gitignore syntax and is applied during file scanning to exclude paths in addition to any `--exclude` patterns passed on the command line. Edit this file to permanently suppress paths you never want scanned.
 
+### Overriding the ignore filename
+
+`config.ini` (also seeded into `CODEECHO_CONFIG_DIR` on first run) contains an `[override]` section with an `ignore-file` key, which names the file used in place of `.ignore`, resolved relative to `CODEECHO_CONFIG_DIR`:
+
+```ini
+[override]
+ignore-file = .ignore
+```
+
+Point `ignore-file` at a different filename to use an alternate ignore file (also placed inside `CODEECHO_CONFIG_DIR`). If the configured file is missing, codeecho logs a warning and falls back to the bundled `.ignore`.
+
 ## Development
 
 ### Prerequisites
@@ -151,11 +175,11 @@ poetry run pylint codeecho
 poetry run pytest --cov=codeecho tests --cov-report html
 ```
 
-## [Changelog](CHANGELOG.md)
+## [Changelog](https://github.com/rcw3bb/codeecho/blob/main/CHANGELOG.md)
 
 ## License
 
-This project is licensed under the [MIT License](LICENSE).
+This project is licensed under the [MIT License](https://github.com/rcw3bb/codeecho/blob/main/LICENSE).
 
 ## Author
 

{codeecho-1.1.0 → codeecho-1.2.0}/codeecho/__init__.py

@@ -2,21 +2,25 @@
 codeecho - A developer tool that scans your codebase to detect and highlight ECHOES
 of duplicated or near-duplicated code so you can refactor toward cleaner, more
 maintainable designs.
+
+:author: Ron Webb
+:since: 1.0.0
 """
 
 from env_dir_bootstrap import EnvDirBootstrap
 from logenrich import setup_logger
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 
 _bootstrapper = EnvDirBootstrap(
     env_var="CODEECHO_CONFIG_DIR",
-    resources=["logging.ini", ".ignore"],
+    resources=["logging.ini", ".ignore", "config.ini"],
     package="codeecho",
 )
 
 _bootstrapper.setup()
 
 CONF_DIR = str(_bootstrapper.get_dir())
+DEFAULT_IGNORE_PATH = _bootstrapper.resolve(".ignore")
 
 setup_logger("codeecho", conf_dir=CONF_DIR)

{codeecho-1.1.0 → codeecho-1.2.0}/codeecho/__main__.py

@@ -4,9 +4,13 @@ CLI entry point for codeecho.
 Invoked via::
 
     poetry run python -m codeecho [OPTIONS] PATH
+
+:author: Ron Webb
+:since: 1.0.0
 """
 
 import json
+import logging
 import os
 import uuid
 from pathlib import Path
@@ -24,20 +28,27 @@ from rich.progress import (
 )
 from rich.table import Table
 
-from codeecho import __version__, CONF_DIR
-from codeecho import extractor, fingerprint, parser as ts_parser, scanner
-from codeecho.db import SessionDB, get_db_path
-from codeecho.detector import detect
-from codeecho.models import ScanResult
-from codeecho.reporter import html_reporter, json_reporter
+from . import __version__, CONF_DIR, DEFAULT_IGNORE_PATH
+from . import basis as basis_module
+from . import extractor, fingerprint, parser as ts_parser, scanner
+from .config import Config
+from .db import SessionDB, get_db_path
+from .detector import detect
+from .models import ScanResult
+from .reporter import html_reporter, json_reporter
 
 _console = Console()
+_config = Config()
+_logger = logging.getLogger("codeecho.__main__")
 
 _FORMAT_CHOICES = click.Choice(["json", "html", "both"])
 
 
 def _parse_types(types_str: str) -> set[int]:
-    """Parse ``--types`` value into a set of integers."""
+    """Parse ``--types`` value into a set of integers.
+
+    :since: 1.0.0
+    """
     if types_str.strip().lower() == "all":
         return {1, 2, 3}
     result: set[int] = set()
@@ -52,6 +63,120 @@ def _parse_types(types_str: str) -> set[int]:
     return result
 
 
+def _read_target_list(list_file: Path) -> list[Path]:
+    """Read one target path per line from *list_file*.
+
+    Blank lines and lines starting with ``#`` are skipped.
+
+    :since: 1.2.0
+    """
+    result: list[Path] = []
+    for line in list_file.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if stripped and not stripped.startswith("#"):
+            result.append(Path(stripped))
+    return result
+
+
+def _load_ignore_file(ignore_path: Path, base_dir: Path) -> IgnoreFile | None:
+    """Load an :class:`IgnoreFile` from *ignore_path*, logging failures.
+
+    Returns ``None`` on a missing or non-UTF-8 file instead of raising.
+
+    :since: 1.2.0
+    """
+    try:
+        return IgnoreFile(ignore_path, base_dir=base_dir)
+    except FileNotFoundError:
+        _logger.warning("Ignore file not found at %s", ignore_path)
+        return None
+    except UnicodeDecodeError as exc:
+        _logger.warning("Ignore file at %s is not valid UTF-8: %s", ignore_path, exc)
+        return None
+
+
+def _build_ignore(base_dir: Path) -> IgnoreFile | None:
+    """Build a path-ignore matcher anchored at *base_dir*.
+
+    The ignore filename is resolved from ``config.ini``'s ``[override]
+    ignore-file`` setting under :data:`CONF_DIR`; when that file is missing,
+    the bundled default ``.ignore`` is tried instead.
+
+    :since: 1.2.0
+    """
+    custom_path = Path(CONF_DIR) / _config.get_ignore_file()
+    ignore = _load_ignore_file(custom_path, base_dir)
+    if ignore is not None:
+        return ignore
+    if custom_path == Path(DEFAULT_IGNORE_PATH):
+        return None
+    return _load_ignore_file(Path(DEFAULT_IGNORE_PATH), base_dir)
+
+
+def _resolve_target_paths(
+    paths: tuple[Path, ...], target_list: bool
+) -> tuple[Path, ...]:
+    """Validate *paths* and expand ``--target-list`` into concrete target paths.
+
+    :since: 1.2.0
+    """
+    if not paths:
+        raise click.UsageError("At least one PATH is required.")
+
+    if not target_list:
+        return paths
+
+    if len(paths) != 1 or not paths[0].is_file():
+        raise click.UsageError(
+            "--target-list requires PATH to be a single existing file."
+        )
+    expanded = tuple(_read_target_list(paths[0]))
+    if not expanded:
+        raise click.UsageError("--target-list file contains no target paths.")
+    return expanded
+
+
+def _read_basis_targets(basis_path: Path | None) -> list[Path]:
+    """Read the basis path(s) listed in *basis_path*, if given.
+
+    Absolute entries are resolved (normalising case/symlinks); relative entries
+    (e.g. a bare filename) are left as-is so they can be matched by filename/suffix
+    against the scanned files instead of being resolved against the current
+    working directory.
+
+    :since: 1.2.0
+    """
+    if basis_path is None:
+        return []
+    targets = [
+        p.resolve() if p.is_absolute() else p for p in _read_target_list(basis_path)
+    ]
+    if not targets:
+        raise click.UsageError("--basis file contains no target paths.")
+    return targets
+
+
+def _discover_files(
+    resolved: list[Path], exclude: tuple[str, ...]
+) -> list[tuple[Path, str]]:
+    """Print scan targets and return the discovered ``(file, language)`` pairs.
+
+    :since: 1.2.0
+    """
+    for target_path in resolved:
+        _console.print(f"[dim]Scanning:[/dim] [bold]{target_path}[/bold]")
+    try:
+        base_dir = Path(os.path.commonpath(resolved))
+        if not base_dir.is_dir():
+            base_dir = base_dir.parent
+    except ValueError:
+        base_dir = Path.cwd()
+    ignore_file = _build_ignore(base_dir)
+    return scanner.scan(
+        tuple(resolved), exclude_patterns=exclude, ignore_file=ignore_file
+    )
+
+
 @click.command(
     name="codeecho", context_settings={"help_option_names": ["-h", "--help"]}
 )
@@ -120,6 +245,33 @@ def _parse_types(types_str: str) -> set[int]:
     metavar="PATTERN",
     help="Glob pattern(s) to exclude from scanning (repeatable).",
 )
+@click.option(
+    "--target-list",
+    "target_list",
+    is_flag=True,
+    default=False,
+    help=(
+        "Treat PATH as a single existing file listing target paths (files "
+        "and/or directories), one per line, instead of individual PATH "
+        "arguments. Blank lines and lines starting with '#' are skipped."
+    ),
+)
+@click.option(
+    "--basis",
+    "basis_path",
+    default=None,
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    metavar="FILE",
+    help=(
+        "File listing basis target paths, one per line, same format as "
+        "--target-list. Absolute file/directory entries are added to the scan "
+        "automatically and matched exactly; relative entries (e.g. a bare "
+        "filename) are matched by filename/suffix against any file discovered "
+        "in the scan. The report is filtered to only clone groups that touch "
+        "at least one basis file; groups duplicated purely among basis files "
+        "are flagged as such."
+    ),
+)
 def main(  # pylint: disable=too-many-arguments,too-many-positional-arguments,too-many-locals,invalid-name
     paths: tuple[Path, ...],
     types: str,
@@ -130,11 +282,15 @@ def main(  # pylint: disable=too-many-arguments,too-many-positional-arguments,to
     fmt: str,
     min_tokens: int,
     exclude: tuple[str, ...],
+    target_list: bool,
+    basis_path: Path | None,
 ) -> None:
     """Scan one or more PATH(s) for duplicate and near-duplicate code.
 
     Each PATH may be a file or a directory.  Generates JSON and/or HTML reports,
     then removes the intermediate session data from the embedded database.
+
+    :since: 1.0.0
     """
     _console.print(
         Panel(
@@ -143,23 +299,26 @@ def main(  # pylint: disable=too-many-arguments,too-many-positional-arguments,to
         )
     )
 
-    if not paths:
-        raise click.UsageError("At least one PATH is required.")
-
+    paths = _resolve_target_paths(paths, target_list)
     detect_types = _parse_types(types)
     if output_dir is None:
         output_dir = Path.cwd() / "reports"
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    basis_targets = _read_basis_targets(basis_path)
+
     session_id = str(uuid.uuid4())
     config = {
         "types": types,
         "threshold": threshold,
         "min_tokens": min_tokens,
         "exclude": list(exclude),
+        "basis": [str(p) for p in basis_targets],
     }
-
-    output_dir.mkdir(parents=True, exist_ok=True)
-
     resolved = [p.resolve() for p in paths]
+    for target in basis_targets:
+        if target.is_absolute() and target not in resolved:
+            resolved.append(target)
 
     db_path = Path(get_db_path(str(db_dir) if db_dir else None))
     with SessionDB(db_path=db_path) as session_db:
@@ -167,34 +326,37 @@ def main(  # pylint: disable=too-many-arguments,too-many-positional-arguments,to
             session_id, json.dumps([str(p) for p in resolved]), config
         )
 
-        # ── Phase 1: File discovery ─────────────────────────────────────────
-        for p in resolved:
-            _console.print(f"[dim]Scanning:[/dim] [bold]{p}[/bold]")
-        try:
-            base_dir = Path(os.path.commonpath(resolved))
-            if not base_dir.is_dir():
-                base_dir = base_dir.parent
-        except ValueError:
-            base_dir = Path.cwd()
-        _ignore_file = IgnoreFile(Path(CONF_DIR) / ".ignore", base_dir=base_dir)
-        files = scanner.scan(
-            tuple(resolved), exclude_patterns=exclude, ignore_file=_ignore_file
-        )
-        total_fragments = 0
+        files = _discover_files(resolved, exclude)
 
         if not files:
             _console.print("[yellow]No supported source files found.[/yellow]")
             session_db.delete_session(session_id)
             return
 
-        # ── Phase 2: Parse → Extract → Hash ────────────────────────────────
+        basis_files = None
+        if basis_targets:
+            basis_files = basis_module.resolve_basis_files(files, basis_targets)
+            if not basis_files:
+                _console.print(
+                    "[yellow]Warning: none of the --basis paths matched any scanned files.[/yellow]"
+                )
+
         total_fragments = _process_files(files, session_db, session_id, min_tokens)
 
-        # ── Phase 3: Clone detection ────────────────────────────────────────
         cnt1, cnt2, cnt3 = _detect_clones(
             session_db, session_id, detect_types, threshold
         )
 
+        basis_counts = {1: 0, 2: 0, 3: 0}
+        if basis_files is not None:
+            groups = session_db.get_clone_groups(session_id)
+            groups_with_members = [
+                (g, session_db.get_fragments_for_group(g)) for g in groups
+            ]
+            basis_counts = basis_module.count_basis_groups_by_type(
+                groups_with_members, basis_files
+            )
+
         result = ScanResult(
             session_id=session_id,
             version=__version__,
@@ -204,12 +366,16 @@ def main(  # pylint: disable=too-many-arguments,too-many-positional-arguments,to
             type1_groups=cnt1,
             type2_groups=cnt2,
             type3_groups=cnt3,
+            basis_paths=[str(p) for p in basis_targets],
+            basis_type1_groups=basis_counts[1],
+            basis_type2_groups=basis_counts[2],
+            basis_type3_groups=basis_counts[3],
         )
 
-        # ── Phase 4: Report generation ──────────────────────────────────────
-        written = _write_reports(session_db, result, output_dir, output, fmt)
+        written = _write_reports(
+            session_db, result, output_dir, output, fmt, basis_files
+        )
 
-        # ── Phase 5: Clean up session ───────────────────────────────────────
         session_db.delete_session(session_id)
 
     # ── Summary table (printed after DB is closed) ──────────────────────────
@@ -222,46 +388,72 @@ def _detect_clones(
     detect_types: set[int],
     threshold: float,
 ) -> tuple[int, int, int]:
-    """Run clone detection and return (type1_count, type2_count, type3_count)."""
+    """Run clone detection and return (type1_count, type2_count, type3_count).
+
+    :since: 1.0.0
+    """
     _console.print("[dim]Detecting clones…[/dim]")
     return detect(session_db, session_id, detect_types, threshold)
 
 
-def _write_reports(
+def _write_reports(  # pylint: disable=too-many-arguments,too-many-positional-arguments
     session_db: SessionDB,
     result: ScanResult,
     output_dir: Path,
     output: str,
     fmt: str,
+    basis_files: frozenset[str] | None = None,
 ) -> list[Path]:
-    """Write the requested report formats and return a list of written paths."""
+    """Write the requested report formats and return a list of written paths.
+
+    :since: 1.0.0
+    """
     written: list[Path] = []
     if fmt in ("json", "both"):
         written.append(
-            json_reporter.write(session_db, result, output_dir / f"{output}.json")
+            json_reporter.write(
+                session_db, result, output_dir / f"{output}.json", basis_files
+            )
         )
     if fmt in ("html", "both"):
         written.append(
-            html_reporter.write(session_db, result, output_dir / f"{output}.html")
+            html_reporter.write(
+                session_db, result, output_dir / f"{output}.html", basis_files
+            )
         )
     return written
 
 
 def _print_summary(result: ScanResult, written: list[Path]) -> None:
-    """Print the scan summary table and list of saved report paths."""
+    """Print the scan summary table and list of saved report paths.
+
+    :since: 1.0.0
+    """
+    has_basis = bool(result.basis_paths)
+
+    def _value(count: int, basis_count: int) -> str:
+        return f"{count} ({basis_count})" if has_basis else str(count)
+
     table = Table(title="Scan Summary", show_header=True, header_style="bold magenta")
     table.add_column("Metric", style="dim", min_width=26)
     table.add_column("Value", justify="right", style="bold")
     table.add_row("Files scanned", str(result.files_scanned))
     table.add_row("Fragments extracted", str(result.fragments_extracted))
-    table.add_row("[red]Type-1[/red] clone groups (exact)", str(result.type1_groups))
     table.add_row(
-        "[yellow]Type-2[/yellow] clone groups (structural)", str(result.type2_groups)
+        "[red]Type-1[/red] clone groups (exact)",
+        _value(result.type1_groups, result.basis_type1_groups),
+    )
+    table.add_row(
+        "[yellow]Type-2[/yellow] clone groups (structural)",
+        _value(result.type2_groups, result.basis_type2_groups),
     )
     table.add_row(
-        "[green]Type-3[/green] clone groups (near-duplicate)", str(result.type3_groups)
+        "[green]Type-3[/green] clone groups (near-duplicate)",
+        _value(result.type3_groups, result.basis_type3_groups),
     )
     _console.print(table)
+    if has_basis:
+        _console.print("[dim]Value in parentheses = basis-touching groups.[/dim]")
     _console.print("\n[bold]Reports saved:[/bold]")
     for dest in written:
         _console.print(f"  [cyan]•[/cyan] {dest}")
@@ -277,6 +469,8 @@ def _process_files(
 
     Returns:
         Total number of fragments extracted.
+
+    :since: 1.0.0
     """
     total = 0
     with Progress(