fork-meter 1.0.0__tar.gz

fork_meter-1.0.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 1.0.0 - 2026-08-21
+
+### Added
+
+- Initial release of fork-meter.
+- Command-line interface via `fork-meter` script.
+- Cyclomatic complexity measurement by counting decision points and branching paths in source code.
+- Logging via `logenrich` with configurable log directory (`FORK_METER_CONFIG_DIR`).
+- Configuration directory bootstrapping via `env-dir-bootstrap`.

fork_meter-1.0.0/LICENSE

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

fork_meter-1.0.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: fork-meter
+Version: 1.0.0
+Summary: A command-line tool that measures cyclomatic complexity by counting decision points and branching paths in source code.
+License: MIT License
+         
+         Copyright (c) 2026 Ron Webb
+         
+         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.
+License-File: LICENSE
+Requires-Python: >=3.14
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: braincraft (>=1.2.0,<2.0.0)
+Requires-Dist: click (>=8.4.2,<9.0.0)
+Requires-Dist: env-dir-bootstrap (>=1.0.0,<2.0.0)
+Requires-Dist: jinja2 (>=3.1.0,<4.0.0)
+Requires-Dist: logenrich (>=1.0.1,<2.0.0)
+Requires-Dist: rich (>=15.0.0,<16.0.0)
+Requires-Dist: tree-sitter (>=0.26.0,<0.27.0)
+Requires-Dist: tree-sitter-go (>=0.25.0,<0.26.0)
+Requires-Dist: tree-sitter-gosu (>=0.2.0,<0.3.0)
+Requires-Dist: tree-sitter-java (>=0.23.5,<0.24.0)
+Requires-Dist: tree-sitter-javascript (>=0.25.0,<0.26.0)
+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
+
+# fork-meter
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](CHANGELOG.md)
+
+A command-line tool that measures cyclomatic complexity by counting decision points and branching paths in source code.
+
+## Requirements
+
+- Python `>=3.14`
+
+## Installation
+
+```bash
+pip install fork-meter
+```
+
+## Supported Languages
+
+| Language | Grammar |
+|----------|---------|
+| Python | tree-sitter-python |
+| JavaScript | tree-sitter-javascript |
+| TypeScript | tree-sitter-typescript |
+| Java | tree-sitter-java |
+| Go | tree-sitter-go |
+| Gosu | tree-sitter-gosu |
+
+## Usage
+
+```
+fork-meter [OPTIONS] PATHS...
+```
+
+`PATHS` may be files or directories; directories are scanned recursively.
+
+### Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--max INT` | `10` | Report functions with complexity strictly above this value |
+| `--output NAME` | `fork-meter-output` | Base name for output files (no extension) |
+| `--output-dir DIR` | `<cwd>/reports` | Directory for output files |
+| `--format [json\|html\|both]` | `both` | Output format |
+| `--exclude PATTERN` | — | Glob pattern to exclude from scanning (repeatable) |
+| `-V, --version` | | Show version and exit |
+| `-h, --help` | | Show help and exit |
+
+### Example
+
+```bash
+# Scan a project, flag anything above complexity 5, write HTML only
+fork-meter src/ --max 5 --format html --exclude "**/*_test.py"
+```
+
+Output:
+
+```
+fork-meter done in 0.08s
+  ✓ reports/fork-meter-output.html
+```
+
+## Complexity Scale
+
+| Range | Colour | Risk |
+|-------|--------|------|
+| 1 – 5 | 🟢 Green | Low |
+| 6 – 10 | 🟡 Yellow | Moderate |
+| 11 – 15 | 🟠 Orange | High |
+| 16 + | 🔴 Red | Critical |
+
+## Output Formats
+
+- **HTML** — self-contained interactive report with a sortable complexity table.
+- **JSON** — machine-readable report suitable for CI integration.
+
+## Configuration
+
+`fork-meter` bootstraps its log/config directory automatically. Override the location with:
+
+```bash
+export FORK_METER_CONFIG_DIR=/path/to/dir
+```
+
+## Development
+
+### Setup
+
+```bash
+poetry install
+```
+
+### Format and Lint
+
+```bash
+poetry run black fork_meter; poetry run pylint fork_meter
+```
+
+### Run Tests with Coverage
+
+```bash
+poetry run pytest --cov=fork_meter tests --cov-report html
+```
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
+

fork_meter-1.0.0/README.md

@@ -0,0 +1,107 @@
+# fork-meter
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](CHANGELOG.md)
+
+A command-line tool that measures cyclomatic complexity by counting decision points and branching paths in source code.
+
+## Requirements
+
+- Python `>=3.14`
+
+## Installation
+
+```bash
+pip install fork-meter
+```
+
+## Supported Languages
+
+| Language | Grammar |
+|----------|---------|
+| Python | tree-sitter-python |
+| JavaScript | tree-sitter-javascript |
+| TypeScript | tree-sitter-typescript |
+| Java | tree-sitter-java |
+| Go | tree-sitter-go |
+| Gosu | tree-sitter-gosu |
+
+## Usage
+
+```
+fork-meter [OPTIONS] PATHS...
+```
+
+`PATHS` may be files or directories; directories are scanned recursively.
+
+### Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--max INT` | `10` | Report functions with complexity strictly above this value |
+| `--output NAME` | `fork-meter-output` | Base name for output files (no extension) |
+| `--output-dir DIR` | `<cwd>/reports` | Directory for output files |
+| `--format [json\|html\|both]` | `both` | Output format |
+| `--exclude PATTERN` | — | Glob pattern to exclude from scanning (repeatable) |
+| `-V, --version` | | Show version and exit |
+| `-h, --help` | | Show help and exit |
+
+### Example
+
+```bash
+# Scan a project, flag anything above complexity 5, write HTML only
+fork-meter src/ --max 5 --format html --exclude "**/*_test.py"
+```
+
+Output:
+
+```
+fork-meter done in 0.08s
+  ✓ reports/fork-meter-output.html
+```
+
+## Complexity Scale
+
+| Range | Colour | Risk |
+|-------|--------|------|
+| 1 – 5 | 🟢 Green | Low |
+| 6 – 10 | 🟡 Yellow | Moderate |
+| 11 – 15 | 🟠 Orange | High |
+| 16 + | 🔴 Red | Critical |
+
+## Output Formats
+
+- **HTML** — self-contained interactive report with a sortable complexity table.
+- **JSON** — machine-readable report suitable for CI integration.
+
+## Configuration
+
+`fork-meter` bootstraps its log/config directory automatically. Override the location with:
+
+```bash
+export FORK_METER_CONFIG_DIR=/path/to/dir
+```
+
+## Development
+
+### Setup
+
+```bash
+poetry install
+```
+
+### Format and Lint
+
+```bash
+poetry run black fork_meter; poetry run pylint fork_meter
+```
+
+### Run Tests with Coverage
+
+```bash
+poetry run pytest --cov=fork_meter tests --cov-report html
+```
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

fork_meter-1.0.0/fork_meter/__init__.py

@@ -0,0 +1,26 @@
+"""
+fork_meter package.
+
+A command-line tool that measures cyclomatic complexity by counting
+decision points and branching paths in source code.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+from env_dir_bootstrap import EnvDirBootstrap
+from logenrich import setup_logger
+
+__version__ = "1.0.0"
+
+_bootstrapper = EnvDirBootstrap(
+    env_var="FORK_METER_CONFIG_DIR",
+    resources=["logging.ini"],
+    package="fork_meter",
+)
+
+_bootstrapper.setup()
+
+CONF_DIR = str(_bootstrapper.get_dir())
+
+setup_logger("fork_meter", conf_dir=CONF_DIR)

fork_meter-1.0.0/fork_meter/__main__.py

@@ -0,0 +1,121 @@
+"""
+Entry point for the fork-meter command-line tool.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import logging
+import time
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from . import __version__
+from .analyzer import analyze
+from .reporter import html_reporter, json_reporter
+
+_logger = logging.getLogger(__name__)
+_console = Console()
+
+_CC_STYLE = {
+    (1, 5): "green",
+    (6, 10): "yellow",
+    (11, 15): "orange3",
+    (16, 9999): "red",
+}
+
+
+def _print_elapsed(elapsed: float, written: list[Path]) -> None:
+    """Print a single-line elapsed status with report paths."""
+    _console.print(
+        f"[bold cyan]fork-meter[/bold cyan] done in [bold]{elapsed:.2f}s[/bold]"
+    )
+    for path in written:
+        _console.print(f"  [green]\u2713[/green] {path}")
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.argument("paths", nargs=-1, required=True, type=click.Path(exists=True))
+@click.option(
+    "--max",
+    "max_threshold",
+    default=10,
+    show_default=True,
+    metavar="INT",
+    help="Report functions with complexity strictly above this value.",
+)
+@click.option(
+    "--output",
+    "output_name",
+    default="fork-meter-output",
+    show_default=True,
+    metavar="NAME",
+    help="Base name for output files (no extension).",
+)
+@click.option(
+    "--output-dir",
+    default=None,
+    type=click.Path(),
+    metavar="DIR",
+    help="Directory for output files. Defaults to <cwd>/reports.",
+)
+@click.option(
+    "--format",
+    "output_format",
+    default="both",
+    type=click.Choice(["json", "html", "both"], case_sensitive=False),
+    show_default=True,
+    help="Output format.",
+)
+@click.option(
+    "--exclude",
+    multiple=True,
+    metavar="PATTERN",
+    help="Glob pattern to exclude from scanning (repeatable).",
+)
+@click.version_option(version=__version__, prog_name="fork-meter")
+def main(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    paths: tuple[str, ...],
+    max_threshold: int,
+    output_name: str,
+    output_dir: str | None,
+    output_format: str,
+    exclude: tuple[str, ...],
+) -> None:
+    """Measure cyclomatic complexity of source code.
+
+    PATH arguments may be files or directories; directories are scanned recursively.
+    Only functions with complexity strictly above --max are included in the report.
+    """
+    _logger.info("fork-meter started")
+
+    resolved_paths = tuple(Path(p) for p in paths)
+    out_dir = Path(output_dir) if output_dir else Path.cwd() / "reports"
+
+    start = time.monotonic()
+    result = analyze(
+        resolved_paths, exclude_patterns=exclude, max_threshold=max_threshold
+    )
+
+    written: list[Path] = []
+    if output_format in ("json", "both"):
+        written.append(
+            json_reporter.write(
+                result,
+                [str(p) for p in resolved_paths],
+                max_threshold,
+                out_dir / f"{output_name}.json",
+            )
+        )
+    if output_format in ("html", "both"):
+        written.append(
+            html_reporter.write(result, max_threshold, out_dir / f"{output_name}.html")
+        )
+
+    _print_elapsed(time.monotonic() - start, written)
+
+
+if __name__ == "__main__":
+    main()  # pylint: disable=no-value-for-parameter

fork_meter-1.0.0/fork_meter/analyzer.py

@@ -0,0 +1,349 @@
+"""
+Cyclomatic complexity analyzer using tree-sitter AST traversal.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import logging
+from bisect import bisect_left
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from tree_sitter import Language, Node, Query, QueryCursor
+
+from . import parser as _parser
+from . import scanner as _scanner
+from .models import ComplexityResult
+
+_logger = logging.getLogger(__name__)
+
+# Per-language S-expression queries selecting named functions, methods, and constructors.
+_FRAGMENT_QUERIES: dict[str, str] = {
+    "Python": "(function_definition) @fragment",
+    "JavaScript": "[(function_declaration) (method_definition)] @fragment",
+    "TypeScript": "[(function_declaration) (method_definition)] @fragment",
+    "Java": "[(method_declaration) (constructor_declaration)] @fragment",
+    "Go": "[(function_declaration) (method_declaration)] @fragment",
+    "Gosu": "[(function_declaration) (constructor_declaration)] @fragment",
+}
+
+# Node types that represent a branching decision point per language.
+_DECISION_NODES: dict[str, frozenset[str]] = {
+    "Python": frozenset(
+        {
+            "if_statement",
+            "elif_clause",
+            "for_statement",
+            "while_statement",
+            "except_clause",
+            "conditional_expression",
+            "case_clause",
+        }
+    ),
+    "JavaScript": frozenset(
+        {
+            "if_statement",
+            "for_statement",
+            "for_in_statement",
+            "for_of_statement",
+            "while_statement",
+            "do_statement",
+            "catch_clause",
+            "switch_case",
+            "ternary_expression",
+        }
+    ),
+    "TypeScript": frozenset(
+        {
+            "if_statement",
+            "for_statement",
+            "for_in_statement",
+            "for_of_statement",
+            "while_statement",
+            "do_statement",
+            "catch_clause",
+            "switch_case",
+            "ternary_expression",
+        }
+    ),
+    "Java": frozenset(
+        {
+            "if_statement",
+            "for_statement",
+            "enhanced_for_statement",
+            "while_statement",
+            "do_statement",
+            "catch_clause",
+            "switch_label",
+            "ternary_expression",
+        }
+    ),
+    "Go": frozenset({"if_statement", "for_statement", "case_clause", "comm_clause"}),
+    "Gosu": frozenset(
+        {
+            "if_statement",
+            "for_statement",
+            "while_statement",
+            "do_while_statement",
+            "catch_clause",
+            "switch_label",
+            "ternary_expression",
+        }
+    ),
+}
+
+# Node types whose subtrees are pruned during decision-point counting (nested code units).
+_NESTED_STOP_TYPES: dict[str, frozenset[str]] = {
+    "Python": frozenset({"function_definition", "class_definition"}),
+    "JavaScript": frozenset(
+        {
+            "function_declaration",
+            "function_expression",
+            "arrow_function",
+            "method_definition",
+            "class_declaration",
+        }
+    ),
+    "TypeScript": frozenset(
+        {
+            "function_declaration",
+            "function_expression",
+            "arrow_function",
+            "method_definition",
+            "class_declaration",
+        }
+    ),
+    "Java": frozenset(
+        {
+            "method_declaration",
+            "constructor_declaration",
+            "class_declaration",
+            "lambda_expression",
+        }
+    ),
+    "Go": frozenset({"function_declaration", "method_declaration", "func_literal"}),
+    "Gosu": frozenset(
+        {"function_declaration", "constructor_declaration", "class_declaration"}
+    ),
+}
+
+# AST node types that represent a class body, used when walking up the parent chain.
+_CLASS_NODE_TYPES: frozenset[str] = frozenset(
+    {
+        "class_definition",  # Python
+        "class_declaration",  # JavaScript, TypeScript, Java, Gosu
+    }
+)
+
+_FRAGMENT_TYPE_MAP: dict[str, str] = {
+    "function_definition": "function",
+    "function_declaration": "function",
+    "method_definition": "method",
+    "method_declaration": "method",
+    "constructor_declaration": "constructor",
+}
+
+
+@dataclass
+class AnalysisResult:
+    """Aggregated output of a complexity analysis run.
+
+    :param files_scanned: Number of source files processed.
+    :param functions_analyzed: Total named code blocks measured before threshold filtering.
+    :param results: Complexity results with ``complexity > max_threshold``.
+    """
+
+    files_scanned: int
+    functions_analyzed: int
+    results: list[ComplexityResult] = field(default_factory=list)
+
+
+def _get_name(node: Node) -> str | None:
+    """Return the declared name of *node*, or ``None`` for anonymous code blocks."""
+    name_node = node.child_by_field_name("name")
+    if name_node is None:
+        return None
+    return name_node.text.decode("utf-8", errors="replace")
+
+
+def _get_parent_class_go(node: Node) -> str | None:
+    """Return the receiver type name for a Go ``method_declaration``."""
+    receiver = node.child_by_field_name("receiver")
+    if receiver is None:
+        return None
+    for child in receiver.children:
+        if child.type == "parameter_declaration":
+            type_node = child.child_by_field_name("type")
+            if type_node is None:
+                continue
+            if type_node.type == "pointer_type":
+                # *Foo — get the named inner type (skip the '*' token)
+                for inner in reversed(type_node.children):
+                    if inner.is_named:
+                        return inner.text.decode("utf-8", errors="replace")
+            return type_node.text.decode("utf-8", errors="replace")
+    return None
+
+
+def _get_parent_class(node: Node, language: str) -> str | None:
+    """Return the enclosing class name, or ``None`` for top-level code blocks."""
+    if language == "Go" and node.type == "method_declaration":
+        return _get_parent_class_go(node)
+    current = node.parent
+    while current is not None:
+        if current.type in _CLASS_NODE_TYPES:
+            name_node = current.child_by_field_name("name")
+            if name_node is not None:
+                return name_node.text.decode("utf-8", errors="replace")
+        current = current.parent
+    return None
+
+
+def _resolve_fragment_type(node: Node, language: str, parent_class: str | None) -> str:
+    """Return the fragment type string for *node*."""
+    raw = _FRAGMENT_TYPE_MAP.get(node.type, "function")
+    # Python uses function_definition for both functions and methods.
+    if (
+        language == "Python"
+        and node.type == "function_definition"
+        and parent_class is not None
+    ):
+        return "method"
+    return raw
+
+
+def _count_decisions(
+    node: Node, decision_nodes: frozenset[str], stop_types: frozenset[str]
+) -> int:
+    """Recursively count decision-point nodes under *node*, pruning at *stop_types*.
+
+    :param node: AST node to walk (typically the function/method root).
+    :param decision_nodes: Node type names that each add one to the complexity count.
+    :param stop_types: Node types whose entire subtrees are excluded (nested code units).
+    :returns: Total decision points found within *node*'s subtree.
+    """
+    count = 0
+    for child in node.children:
+        if child.type in stop_types:
+            continue
+        if child.type in decision_nodes:
+            count += 1
+        count += _count_decisions(child, decision_nodes, stop_types)
+    return count
+
+
+def _compile_query(lang: Language, pattern: str, language_name: str) -> Query | None:
+    """Return a compiled tree-sitter Query, or ``None`` on failure."""
+    try:
+        return Query(lang, pattern)
+    except Exception as exc:  # pylint: disable=broad-exception-caught
+        _logger.warning("Failed to compile query for %s: %s", language_name, exc)
+        return None
+
+
+def _capture_fragments(tree, language: str) -> list[Node]:
+    """Run the fragment query for *language* against *tree* and return matched nodes."""
+    lang_obj = _parser.get_language(language)
+    if lang_obj is None:
+        return []
+    query_str = _FRAGMENT_QUERIES.get(language)
+    if query_str is None:
+        return []
+    query = _compile_query(lang_obj, query_str, language)
+    if query is None:
+        return []
+    cursor = QueryCursor(query)
+    captures = cursor.captures(tree.root_node)
+    nodes: list[Node] = list(captures.get("fragment", []))
+    del cursor, captures
+    return nodes
+
+
+def _build_result(
+    node: Node,
+    file_path: str,
+    language: str,
+    newline_offsets: list[int],
+) -> ComplexityResult | None:
+    """Return a :class:`~fork_meter.models.ComplexityResult` for *node*, or ``None`` if anonymous."""
+    name = _get_name(node)
+    if name is None:
+        return None
+    parent_class = _get_parent_class(node, language)
+    fragment_type = _resolve_fragment_type(node, language, parent_class)
+    decision_nodes = _DECISION_NODES.get(language, frozenset())
+    stop_types = _NESTED_STOP_TYPES.get(language, frozenset())
+    complexity = 1 + _count_decisions(node, decision_nodes, stop_types)
+    return ComplexityResult(
+        file_path=file_path,
+        language=language,
+        fragment_type=fragment_type,
+        name=name,
+        parent_class=parent_class,
+        start_line=bisect_left(newline_offsets, node.start_byte) + 1,
+        end_line=bisect_left(newline_offsets, node.end_byte) + 1,
+        complexity=complexity,
+    )
+
+
+def analyze_file(file_path: Path, language: str) -> list[ComplexityResult]:
+    """Parse *file_path* and return a complexity result for each named code block.
+
+    :param file_path: Path to a source file.
+    :param language: Language name matching :data:`fork_meter.scanner.EXTENSION_TO_LANGUAGE`.
+    :returns: Unsorted list of :class:`~fork_meter.models.ComplexityResult` objects.
+    """
+    try:
+        source_bytes = file_path.read_bytes()
+    except OSError as exc:
+        _logger.warning("Cannot read %s: %s", file_path, exc)
+        return []
+
+    tree = _parser.parse(source_bytes, language)
+    if tree is None:
+        return []
+
+    # Keep `tree` alive for the duration of node traversal; nodes reference its C memory.
+    fragment_nodes = _capture_fragments(tree, language)
+    newline_offsets = [i for i, b in enumerate(source_bytes) if b == ord(b"\n")]
+
+    results: list[ComplexityResult] = []
+    for node in fragment_nodes:
+        built = _build_result(node, str(file_path), language, newline_offsets)
+        if built is not None:
+            results.append(built)
+
+    _logger.debug("Analyzed %d code blocks in %s", len(results), file_path.name)
+    return results
+
+
+def analyze(
+    paths: tuple[Path, ...],
+    exclude_patterns: tuple[str, ...] = (),
+    max_threshold: int = 10,
+) -> AnalysisResult:
+    """Scan *paths*, compute cyclomatic complexity, and filter results by threshold.
+
+    :param paths: File or directory paths to scan.
+    :param exclude_patterns: Glob patterns to exclude from scanning.
+    :param max_threshold: Only include results with complexity strictly above this value.
+    :returns: :class:`AnalysisResult` with summary counts and filtered results.
+    """
+    files = _scanner.scan(paths, exclude_patterns)
+    all_results: list[ComplexityResult] = []
+    for file_path, language in files:
+        all_results.extend(analyze_file(file_path, language))
+
+    filtered = [r for r in all_results if r.complexity > max_threshold]
+    _logger.info(
+        "Files: %d | Functions: %d | Above threshold: %d",
+        len(files),
+        len(all_results),
+        len(filtered),
+    )
+    return AnalysisResult(
+        files_scanned=len(files),
+        functions_analyzed=len(all_results),
+        results=filtered,
+    )

fork_meter-1.0.0/fork_meter/logging.ini

@@ -0,0 +1,29 @@
+[loggers]
+keys=root
+
+[handlers]
+keys=consoleHandler,fileHandler
+
+[formatters]
+keys=logFormatter,consoleFormatter
+
+[logger_root]
+level=INFO
+handlers=consoleHandler,fileHandler
+
+[handler_consoleHandler]
+level=ERROR
+class=StreamHandler
+formatter=consoleFormatter
+args=(sys.stderr,)
+
+[handler_fileHandler]
+class=FileHandler
+formatter=logFormatter
+args=('fork_meter.log', 'a')
+
+[formatter_logFormatter]
+format=%(asctime)s [%(levelname)s] %(name)s - %(message)s
+
+[formatter_consoleFormatter]
+format=%(asctime)s - %(name)s - %(levelname)s - %(message)s

fork_meter-1.0.0/fork_meter/models.py

@@ -0,0 +1,37 @@
+"""
+Data models for fork-meter cyclomatic complexity analysis.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ComplexityResult:  # pylint: disable=too-many-instance-attributes
+    """Cyclomatic complexity measurement for a single named code block.
+
+    :param file_path: Absolute path to the source file.
+    :param language: Language name (e.g. ``"Python"``).
+    :param fragment_type: Code block kind: ``"function"``, ``"method"``, or ``"constructor"``.
+    :param name: Declared name of the code block.
+    :param parent_class: Enclosing class name, or ``None`` for top-level functions.
+    :param start_line: 1-based line where the code block starts.
+    :param end_line: 1-based line where the code block ends.
+    :param complexity: Cyclomatic complexity (≥ 1).
+    """
+
+    file_path: str
+    language: str
+    fragment_type: str
+    name: str
+    parent_class: str | None
+    start_line: int
+    end_line: int
+    complexity: int
+
+    @property
+    def line_count(self) -> int:
+        """Return the number of source lines spanned by this code block."""
+        return self.end_line - self.start_line + 1

fork_meter-1.0.0/fork_meter/parser.py

@@ -0,0 +1,79 @@
+"""
+Tree-sitter parser wrapper providing one cached Language per grammar.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import logging
+from functools import lru_cache
+
+from tree_sitter import Language, Parser, Tree
+
+_logger = logging.getLogger(__name__)
+
+
+def _build_language(  # pylint: disable=too-many-return-statements
+    language_name: str,
+) -> Language | None:
+    """Instantiate the tree-sitter Language for *language_name*."""
+    match language_name:
+        case "Python":
+            import tree_sitter_python as m  # pylint: disable=import-outside-toplevel
+
+            return Language(m.language())
+        case "JavaScript":
+            import tree_sitter_javascript as m  # pylint: disable=import-outside-toplevel
+
+            return Language(m.language())
+        case "TypeScript":
+            import tree_sitter_typescript as m  # pylint: disable=import-outside-toplevel
+
+            return Language(m.language_typescript())
+        case "Java":
+            import tree_sitter_java as m  # pylint: disable=import-outside-toplevel
+
+            return Language(m.language())
+        case "Gosu":
+            import tree_sitter_gosu as m  # pylint: disable=import-outside-toplevel
+
+            return Language(m.language())
+        case "Go":
+            import tree_sitter_go as m  # pylint: disable=import-outside-toplevel
+
+            return Language(m.language())
+        case _:
+            return None
+
+
+@lru_cache(maxsize=None)
+def get_language(language_name: str) -> Language | None:
+    """Return a cached Language for *language_name*, or ``None`` if unavailable."""
+    try:
+        lang = _build_language(language_name)
+    except Exception as exc:  # pylint: disable=broad-exception-caught
+        _logger.warning("Failed to load grammar for %s: %s", language_name, exc)
+        return None
+    if lang is None:
+        _logger.warning("No tree-sitter grammar for language: %s", language_name)
+    return lang
+
+
+def parse(source_bytes: bytes, language_name: str) -> Tree | None:
+    """Parse *source_bytes* with the grammar for *language_name*.
+
+    Creates a fresh :class:`~tree_sitter.Parser` per call to avoid internal-state
+    corruption across files in tree-sitter 0.26+.
+
+    :param source_bytes: UTF-8-encoded source code.
+    :param language_name: Language name as used by :data:`fork_meter.scanner.EXTENSION_TO_LANGUAGE`.
+    :returns: Parsed :class:`tree_sitter.Tree`, or ``None`` if the grammar is unavailable.
+    """
+    lang = get_language(language_name)
+    if lang is None:
+        _logger.warning("Skipping parse — no grammar for %s", language_name)
+        return None
+    tree = Parser(lang).parse(source_bytes)
+    if tree.root_node.has_error:
+        _logger.debug("Parse errors detected in %s source.", language_name)
+    return tree

fork_meter-1.0.0/fork_meter/reporter/__init__.py

@@ -0,0 +1,6 @@
+"""
+Report writers for fork-meter complexity analysis.
+
+:author: Ron Webb
+:since: 1.0.0
+"""

fork_meter-1.0.0/fork_meter/reporter/html_reporter.py

@@ -0,0 +1,182 @@
+"""
+HTML reporter for fork-meter complexity analysis.
+
+Produces a self-contained, interactive HTML file with a sortable complexity table.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+
+from jinja2 import Environment
+
+from .. import __version__
+from ..analyzer import AnalysisResult
+
+_logger = logging.getLogger(__name__)
+
+_TEMPLATE = """\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>fork-meter — Complexity Report</title>
+  <style>
+    :root {
+      --bg: #e8eaed; --surface: #f0f2f5; --overlay: #dde0e6;
+      --text: #2c2f3a; --subtext: #5a6070; --accent: #5b21b6;
+      --border: #c4c8d0;
+      --green: #16a34a; --yellow: #d97706; --orange: #ea580c; --red: #dc2626;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      background: var(--bg); color: var(--text);
+      font-family: 'Segoe UI', system-ui, sans-serif; padding: 2rem;
+    }
+    h1 { color: var(--accent); font-size: 1.6rem; margin-bottom: 0.25rem; }
+    .meta { color: var(--subtext); font-size: 0.8rem; margin-bottom: 1.75rem; }
+    .summary { display: flex; gap: 1rem; flex-wrap: wrap; margin-bottom: 1.75rem; }
+    .card {
+      background: var(--surface); border: 1px solid var(--border);
+      border-radius: 8px; padding: 1rem 1.5rem; min-width: 140px;
+    }
+    .card .label {
+      color: var(--subtext); font-size: 0.7rem;
+      text-transform: uppercase; letter-spacing: 0.08em; margin-bottom: 0.35rem;
+    }
+    .card .value { font-size: 2rem; font-weight: 700; color: var(--accent); }
+    .empty { color: var(--green); margin-top: 2rem; }
+    table { width: 100%; border-collapse: collapse; background: var(--surface); border-radius: 8px; overflow: hidden; box-shadow: 0 1px 4px rgba(0,0,0,.08); }
+    thead { background: var(--overlay); }
+    th {
+      padding: 0.75rem 1rem; text-align: left; color: var(--subtext);
+      font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.06em;
+      cursor: pointer; user-select: none; white-space: nowrap;
+    }
+    th:hover { color: var(--text); }
+    th.sort-asc::after  { content: ' ↑'; color: var(--accent); }
+    th.sort-desc::after { content: ' ↓'; color: var(--accent); }
+    td { padding: 0.6rem 1rem; border-top: 1px solid var(--border); font-size: 0.875rem; }
+    tr:hover td { background: var(--overlay); }
+    .file { color: var(--subtext); font-size: 0.8rem; word-break: break-all; }
+    .name { font-weight: 600; }
+    .tag {
+      display: inline-block; padding: 0.15rem 0.5rem; border-radius: 4px;
+      font-size: 0.7rem; background: var(--overlay); color: var(--subtext);
+    }
+    .cc { font-weight: 700; font-size: 1rem; }
+    .cc-low  { color: var(--green);  }
+    .cc-med  { color: var(--yellow); }
+    .cc-high { color: var(--orange); }
+    .cc-crit { color: var(--red);    }
+  </style>
+</head>
+<body>
+  <h1>fork-meter</h1>
+  <p class="meta">
+    Generated {{ generated_at }}&nbsp;&middot;&nbsp;
+    fork-meter v{{ version }}&nbsp;&middot;&nbsp;
+    Threshold: complexity &gt; {{ max_threshold }}
+  </p>
+  <div class="summary">
+    <div class="card">
+      <div class="label">Files Scanned</div>
+      <div class="value">{{ files_scanned }}</div>
+    </div>
+    <div class="card">
+      <div class="label">Functions Analyzed</div>
+      <div class="value">{{ functions_analyzed }}</div>
+    </div>
+    <div class="card">
+      <div class="label">Above Threshold</div>
+      <div class="value">{{ results | length }}</div>
+    </div>
+  </div>
+  {% if results %}
+  <table id="tbl">
+    <thead>
+      <tr>
+        <th data-col="0">File</th>
+        <th data-col="1">Class</th>
+        <th data-col="2">Code Block</th>
+        <th data-col="3">Type</th>
+        <th data-col="4">Lines</th>
+        <th data-col="5">Complexity</th>
+      </tr>
+    </thead>
+    <tbody>
+      {% for r in results %}
+      <tr>
+        <td class="file">{{ r.file_path }}</td>
+        <td>{{ r.parent_class if r.parent_class else '\u2014' }}</td>
+        <td class="name">{{ r.name }}</td>
+        <td><span class="tag">{{ r.fragment_type }}</span></td>
+        <td>{{ r.line_count }}</td>
+        <td class="cc {% if r.complexity <= 5 %}cc-low
+                      {%- elif r.complexity <= 10 %}cc-med
+                      {%- elif r.complexity <= 15 %}cc-high
+                      {%- else %}cc-crit{% endif %}">{{ r.complexity }}</td>
+      </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+  {% else %}
+  <p class="empty">&#10003; No functions exceed the complexity threshold of {{ max_threshold }}.</p>
+  {% endif %}
+  <script>
+    (function () {
+      var tbl = document.getElementById('tbl');
+      if (!tbl) { return; }
+      var sc = 5, sd = -1;
+      function sortBy(col) {
+        if (sc === col) { sd *= -1; } else { sc = col; sd = (col >= 4) ? -1 : 1; }
+        var tb = tbl.querySelector('tbody');
+        var rows = Array.prototype.slice.call(tb.rows);
+        rows.sort(function (a, b) {
+          var av = a.cells[col].textContent.trim();
+          var bv = b.cells[col].textContent.trim();
+          if (col >= 4) { return (parseInt(av, 10) - parseInt(bv, 10)) * sd; }
+          return av.localeCompare(bv) * sd;
+        });
+        rows.forEach(function (r) { tb.appendChild(r); });
+        tbl.querySelectorAll('th').forEach(function (th, i) {
+          th.classList.remove('sort-asc', 'sort-desc');
+          if (i === sc) { th.classList.add(sd === 1 ? 'sort-asc' : 'sort-desc'); }
+        });
+      }
+      tbl.querySelectorAll('th').forEach(function (th) {
+        th.addEventListener('click', function () { sortBy(parseInt(th.dataset.col, 10)); });
+      });
+      sortBy(5);
+    }());
+  </script>
+</body>
+</html>"""
+
+
+def write(result: AnalysisResult, max_threshold: int, output_path: Path) -> Path:
+    """Render the complexity report as a self-contained HTML file.
+
+    :param result: Aggregated analysis output.
+    :param max_threshold: Complexity threshold used for filtering.
+    :param output_path: Destination ``.html`` file path.
+    :returns: Resolved path of the written file.
+    """
+    env = Environment(autoescape=True)
+    template = env.from_string(_TEMPLATE)
+    html = template.render(
+        generated_at=datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC"),
+        version=__version__,
+        max_threshold=max_threshold,
+        files_scanned=result.files_scanned,
+        functions_analyzed=result.functions_analyzed,
+        results=result.results,
+    )
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(html, encoding="utf-8")
+    _logger.info("HTML report written to %s", output_path)
+    return output_path.resolve()

fork_meter-1.0.0/fork_meter/reporter/json_reporter.py

@@ -0,0 +1,60 @@
+"""
+JSON reporter for fork-meter complexity analysis.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .. import __version__
+from ..analyzer import AnalysisResult
+
+_logger = logging.getLogger(__name__)
+
+
+def write(
+    result: AnalysisResult,
+    scan_paths: list[str],
+    max_threshold: int,
+    output_path: Path,
+) -> Path:
+    """Write *result* to a JSON file at *output_path*.
+
+    :param result: Aggregated analysis output.
+    :param scan_paths: Original paths supplied by the user.
+    :param max_threshold: Complexity threshold used for filtering.
+    :param output_path: Destination ``.json`` file path.
+    :returns: Resolved path of the written file.
+    """
+    payload = {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "version": __version__,
+        "scan_paths": scan_paths,
+        "max_threshold": max_threshold,
+        "summary": {
+            "files_scanned": result.files_scanned,
+            "functions_analyzed": result.functions_analyzed,
+            "above_threshold": len(result.results),
+        },
+        "results": [
+            {
+                "file_path": r.file_path,
+                "language": r.language,
+                "fragment_type": r.fragment_type,
+                "name": r.name,
+                "parent_class": r.parent_class,
+                "start_line": r.start_line,
+                "end_line": r.end_line,
+                "complexity": r.complexity,
+            }
+            for r in result.results
+        ],
+    }
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    _logger.info("JSON report written to %s", output_path)
+    return output_path.resolve()

fork_meter-1.0.0/fork_meter/scanner.py

@@ -0,0 +1,122 @@
+"""
+File-system scanner that discovers source files for complexity analysis.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import fnmatch
+import logging
+from pathlib import Path
+
+from braincraft import IgnoreFile
+
+_logger = logging.getLogger(__name__)
+
+EXTENSION_TO_LANGUAGE: dict[str, str] = {
+    ".py": "Python",
+    ".js": "JavaScript",
+    ".mjs": "JavaScript",
+    ".cjs": "JavaScript",
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".java": "Java",
+    ".go": "Go",
+    ".gs": "Gosu",
+    ".gsx": "Gosu",
+}
+
+_DEFAULT_EXCLUDE_DIRS: frozenset[str] = frozenset(
+    {
+        ".git",
+        ".svn",
+        ".hg",
+        ".venv",
+        "venv",
+        "env",
+        ".env",
+        "__pycache__",
+        "node_modules",
+        "build",
+        "dist",
+        "target",
+        "out",
+        ".tox",
+        ".pytest_cache",
+        "htmlcov",
+        ".mypy_cache",
+        ".ruff_cache",
+    }
+)
+
+
+def scan(
+    paths: tuple[Path, ...],
+    exclude_patterns: tuple[str, ...] = (),
+    ignore_file: IgnoreFile | None = None,
+) -> list[tuple[Path, str]]:
+    """Walk *paths* and return ``(path, language)`` pairs for supported source files.
+
+    :param paths: File or directory paths to scan.
+    :param exclude_patterns: fnmatch-style glob patterns whose matching paths are skipped.
+    :param ignore_file: Optional gitignore-style filter; matched paths are skipped.
+    :returns: List of ``(absolute_path, language_name)`` tuples.
+    """
+    results: list[tuple[Path, str]] = []
+    seen: set[Path] = set()
+
+    for path in paths:
+        path = path.resolve()
+        _logger.debug("Scanning: %s", path)
+        if path.is_file():
+            if path in seen or _matches_any(path, exclude_patterns):
+                continue
+            seen.add(path)
+            if ignore_file is not None and ignore_file.is_ignored(path):
+                _logger.debug("Ignored (ignore file): %s", path)
+                continue
+            if language := EXTENSION_TO_LANGUAGE.get(path.suffix.lower()):
+                results.append((path, language))
+        elif path.is_dir():
+            for entry in _walk(path, exclude_patterns, ignore_file):
+                if entry not in seen:
+                    seen.add(entry)
+                    if language := EXTENSION_TO_LANGUAGE.get(entry.suffix.lower()):
+                        results.append((entry, language))
+
+    _logger.debug("Found %d source files across %d path(s)", len(results), len(paths))
+    return results
+
+
+def _walk(
+    root: Path,
+    exclude_patterns: tuple[str, ...],
+    ignore_file: IgnoreFile | None,
+):
+    """Yield source file paths, skipping excluded directories and glob-matched files."""
+    try:
+        for child in sorted(root.iterdir()):
+            if child.is_dir():
+                if child.name in _DEFAULT_EXCLUDE_DIRS:
+                    continue
+                if _matches_any(child, exclude_patterns):
+                    continue
+                if ignore_file is not None and ignore_file.is_ignored(child):
+                    _logger.debug("Ignored (ignore file): %s", child)
+                    continue
+                yield from _walk(child, exclude_patterns, ignore_file)
+            elif child.is_file():
+                if _matches_any(child, exclude_patterns):
+                    continue
+                if ignore_file is not None and ignore_file.is_ignored(child):
+                    _logger.debug("Ignored (ignore file): %s", child)
+                    continue
+                yield child
+    except PermissionError as exc:
+        _logger.warning("Permission denied reading %s: %s", root, exc)
+
+
+def _matches_any(path: Path, patterns: tuple[str, ...]) -> bool:
+    """Return ``True`` if *path* matches any fnmatch-style pattern in *patterns*."""
+    path_str = str(path)
+    return any(fnmatch.fnmatch(path_str, p) for p in patterns)

fork_meter-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "fork-meter"
+version = "1.0.0"
+description = "A command-line tool that measures cyclomatic complexity by counting decision points and branching paths in source code."
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.14"
+dependencies = [
+    "logenrich (>=1.0.1,<2.0.0)",
+    "env-dir-bootstrap (>=1.0.0,<2.0.0)",
+    "tree-sitter (>=0.26.0,<0.27.0)",
+    "tree-sitter-python (>=0.25.0,<0.26.0)",
+    "tree-sitter-javascript (>=0.25.0,<0.26.0)",
+    "tree-sitter-typescript (>=0.23.2,<0.24.0)",
+    "tree-sitter-java (>=0.23.5,<0.24.0)",
+    "tree-sitter-go (>=0.25.0,<0.26.0)",
+    "tree-sitter-gosu (>=0.2.0,<0.3.0)",
+    "click (>=8.4.2,<9.0.0)",
+    "rich (>=15.0.0,<16.0.0)",
+    "jinja2 (>=3.1.0,<4.0.0)",
+    "braincraft (>=1.2.0,<2.0.0)"
+]
+
+[project.scripts]
+fork-meter = "fork_meter.__main__:main"
+
+[dependency-groups]
+dev = [
+    "black (>=26.5.1,<27.0.0)",
+    "pylint (>=4.0.5,<5.0.0)",
+    "pytest (>=9.0.3,<10.0.0)",
+    "pytest-cov (>=7.1.0,<8.0.0)"
+]
+
+[tool.poetry]
+packages = [{include = "fork_meter"}]
+include = ["fork_meter/logging.ini", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=fork_meter tests --cov-report html --cov-fail-under=90"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"