codelexity 0.1.0__tar.gz

codelexity-0.1.0/LICENSE

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

codelexity-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: codelexity
+Version: 0.1.0
+Summary: A package that measures code complexity in the age of AI slop.
+Keywords: complexity,halstead,maintainability,cyclomatic,static-analysis,metrics
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: networkx>=3.0
+Requires-Dist: pyvis>=0.3.2
+Maintainer: nickgiki
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/nickgiki/codelexity
+Project-URL: Issues, https://github.com/nickgiki/codelexity/issues
+Description-Content-Type: text/markdown
+
+<small>_This project was created with minimal help from AI assistants, mainly for the tests and a couple helper functions. This document is 100% human written._</small>
+
+# `Codelexity`
+
+![version](https://img.shields.io/badge/version-0.1.0-blue)
+![coverage](https://img.shields.io/badge/coverage-78%25-yellow)
+![python](https://img.shields.io/badge/python-3.11%2B-blue)
+
+A python package that helps you measure, visualize and ultimately manage code complexity.
+
+## Motivation
+
+In the age of AI, codebases are becoming messier and more difficult to maintain. `Codelexity` helps you visualize and manage this complexity.
+
+## Quick Start
+
+- Step 1: `uv add codelexity`
+- Step 2: `uv run codelexity <your_package_path> --plot` - this will create a `codelexity.html` that you can open and play with in your browser.
+
+![Codelexity Graph](assets/codelexity_codelexity.png)
+_Codelexity HTML report on the `codelexity` repo_
+
+
+## Intuition
+
+There's a ton of literature describing the relationship between complexity and maintainability of code.
+
+### The basics
+
+[Halstead measures](https://en.wikipedia.org/wiki/Halstead_complexity_measures) are pretty robust in measuring the complexity. All Halstead metrics are derived from 4 numbers:
+
+1. $n_1$ = the number of distinct operators
+2. $n_1$ = the number of distinct operands
+3. $N_2$  = the total number of operators
+4. $N_2$ = the total number of operands
+
+From these, another 7 metrics can be calculated, with most important the **volume**: 
+
+$$V=N*log_2(n)$$
+
+where: 
+- $n = n_1 + n_2$ the vocabulary of the program and 
+- $N = N_1 + N_2$ the length of the program
+
+Another important metric is the [**Mc Cabe Cyclomatic Complexity**](https://en.wikipedia.org/wiki/Cyclomatic_complexity) measured as:
+
+$$M=E-N+2P$$
+
+where $M$ the complexity, $E$ and $N$ the number of edges and nodes in the computation graph and $P$ the number of connected components.
+
+With Halstead's volume and McCabe's complexity one can compute the [**Maintainability Index**](https://ieeexplore.ieee.org/document/242525) computed as:
+
+$$ 171 - 5.2 * log_2(V) - 0.23 * M- 16.2 * log_2(SLOC)+ 50 * \sqrt{2.4 * perCOM}$$
+
+where $SLOC$ the total lines of code and $perCOM$ the % of comments in the code.
+
+Research is divided about how to interpret the score, with most academic sources (i.e. [Ardito et al., 2020](https://onlinelibrary.wiley.com/doi/10.1155/2020/8840389), [Heričko & Šumak, 2023](https://www.mdpi.com/2076-3417/13/5/2972)) citing $MI>=85$ as high, $85>MI>=65$ as medium and $MI<65$ as low and [Microsoft Visual Studio](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-maintainability-index-range-and-meaning) citing $MI>=20$ as high, $20>MI>=10$ as medium and $MI<10$ as low.
+
+This is how the metrics in this repo are calculated.
+
+### Maintainability propagation in the package graph
+
+It is easy to understand that a densly connected dependency graph affects the maintainability. Central nodes (those that are imported from other modules that are reachable downstream) are more likely to cause issues. Therefore central modules that are not easy to maintain affect the maintainability of the whole package.
+
+To measure centrality, `codelexity` uses [Katz centrality](https://networkx.org/documentation/stable/reference/algorithms/generated/networkx.algorithms.centrality.katz_centrality.html). The centrality value is then multiplied by the module length and normalized by the sum of the respective value in all modules. The corresponding value is used as a weight to compute the total Maintainability Index.
+
+### Example - NetworkX
+
+This is a result for the [`networkx` library](https://networkx.org/en/), a large and complex repo. The command used to create the analysis was:
+
+```bash
+codelexity networkx --json --plot
+```
+
+![Codelexity on NetworkX](/assets/codelexity_networkx.png)
+
+Note that the flags `json` and `plot` denote whether the output will be stored as a json named `codelexity.json` and as an html `codelexity.html` in the working directory.
+
+The `codelexity.json` containts aggregate analytics for the whole package and per-module details.
+
+```json
+{
+    "analytics": {
+        "total_lines": 234629,
+        "total_functions": 9555,
+        "total_modules": 624
+    },
+    "modules": {
+        "conftest.py": {
+            "imports": [
+                "<stdlib>/importlib/metadata/__init__.py",
+                "<stdlib>/os.py",
+                "<stdlib>/warnings.py",
+                "__init__.py"
+            ],
+            "total_lines": 262,
+            "empty_lines": 39,
+            "comments": 12,
+            "code_length": 211,
+...
+        }
+```
+
+## Running the tests
+
+The suite lives in `tests/` and uses the standard library's `unittest` — no test dependencies to install.
+
+```sh
+uv run python -m unittest discover        # all tests
+uv run python -m unittest discover -v     # verbose, one line per test
+```
+
+Coverage, which needs no dev dependency either:
+
+```sh
+uv run --with coverage coverage run --source=src -m unittest discover
+uv run --with coverage coverage report
+```

codelexity-0.1.0/README.md

@@ -0,0 +1,118 @@
+<small>_This project was created with minimal help from AI assistants, mainly for the tests and a couple helper functions. This document is 100% human written._</small>
+
+# `Codelexity`
+
+![version](https://img.shields.io/badge/version-0.1.0-blue)
+![coverage](https://img.shields.io/badge/coverage-78%25-yellow)
+![python](https://img.shields.io/badge/python-3.11%2B-blue)
+
+A python package that helps you measure, visualize and ultimately manage code complexity.
+
+## Motivation
+
+In the age of AI, codebases are becoming messier and more difficult to maintain. `Codelexity` helps you visualize and manage this complexity.
+
+## Quick Start
+
+- Step 1: `uv add codelexity`
+- Step 2: `uv run codelexity <your_package_path> --plot` - this will create a `codelexity.html` that you can open and play with in your browser.
+
+![Codelexity Graph](assets/codelexity_codelexity.png)
+_Codelexity HTML report on the `codelexity` repo_
+
+
+## Intuition
+
+There's a ton of literature describing the relationship between complexity and maintainability of code.
+
+### The basics
+
+[Halstead measures](https://en.wikipedia.org/wiki/Halstead_complexity_measures) are pretty robust in measuring the complexity. All Halstead metrics are derived from 4 numbers:
+
+1. $n_1$ = the number of distinct operators
+2. $n_1$ = the number of distinct operands
+3. $N_2$  = the total number of operators
+4. $N_2$ = the total number of operands
+
+From these, another 7 metrics can be calculated, with most important the **volume**: 
+
+$$V=N*log_2(n)$$
+
+where: 
+- $n = n_1 + n_2$ the vocabulary of the program and 
+- $N = N_1 + N_2$ the length of the program
+
+Another important metric is the [**Mc Cabe Cyclomatic Complexity**](https://en.wikipedia.org/wiki/Cyclomatic_complexity) measured as:
+
+$$M=E-N+2P$$
+
+where $M$ the complexity, $E$ and $N$ the number of edges and nodes in the computation graph and $P$ the number of connected components.
+
+With Halstead's volume and McCabe's complexity one can compute the [**Maintainability Index**](https://ieeexplore.ieee.org/document/242525) computed as:
+
+$$ 171 - 5.2 * log_2(V) - 0.23 * M- 16.2 * log_2(SLOC)+ 50 * \sqrt{2.4 * perCOM}$$
+
+where $SLOC$ the total lines of code and $perCOM$ the % of comments in the code.
+
+Research is divided about how to interpret the score, with most academic sources (i.e. [Ardito et al., 2020](https://onlinelibrary.wiley.com/doi/10.1155/2020/8840389), [Heričko & Šumak, 2023](https://www.mdpi.com/2076-3417/13/5/2972)) citing $MI>=85$ as high, $85>MI>=65$ as medium and $MI<65$ as low and [Microsoft Visual Studio](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-maintainability-index-range-and-meaning) citing $MI>=20$ as high, $20>MI>=10$ as medium and $MI<10$ as low.
+
+This is how the metrics in this repo are calculated.
+
+### Maintainability propagation in the package graph
+
+It is easy to understand that a densly connected dependency graph affects the maintainability. Central nodes (those that are imported from other modules that are reachable downstream) are more likely to cause issues. Therefore central modules that are not easy to maintain affect the maintainability of the whole package.
+
+To measure centrality, `codelexity` uses [Katz centrality](https://networkx.org/documentation/stable/reference/algorithms/generated/networkx.algorithms.centrality.katz_centrality.html). The centrality value is then multiplied by the module length and normalized by the sum of the respective value in all modules. The corresponding value is used as a weight to compute the total Maintainability Index.
+
+### Example - NetworkX
+
+This is a result for the [`networkx` library](https://networkx.org/en/), a large and complex repo. The command used to create the analysis was:
+
+```bash
+codelexity networkx --json --plot
+```
+
+![Codelexity on NetworkX](/assets/codelexity_networkx.png)
+
+Note that the flags `json` and `plot` denote whether the output will be stored as a json named `codelexity.json` and as an html `codelexity.html` in the working directory.
+
+The `codelexity.json` containts aggregate analytics for the whole package and per-module details.
+
+```json
+{
+    "analytics": {
+        "total_lines": 234629,
+        "total_functions": 9555,
+        "total_modules": 624
+    },
+    "modules": {
+        "conftest.py": {
+            "imports": [
+                "<stdlib>/importlib/metadata/__init__.py",
+                "<stdlib>/os.py",
+                "<stdlib>/warnings.py",
+                "__init__.py"
+            ],
+            "total_lines": 262,
+            "empty_lines": 39,
+            "comments": 12,
+            "code_length": 211,
+...
+        }
+```
+
+## Running the tests
+
+The suite lives in `tests/` and uses the standard library's `unittest` — no test dependencies to install.
+
+```sh
+uv run python -m unittest discover        # all tests
+uv run python -m unittest discover -v     # verbose, one line per test
+```
+
+Coverage, which needs no dev dependency either:
+
+```sh
+uv run --with coverage coverage run --source=src -m unittest discover
+uv run --with coverage coverage report
+```

codelexity-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "codelexity"
+version = "0.1.0"
+description = "A package that measures code complexity in the age of AI slop."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "networkx>=3.0",
+    "pyvis>=0.3.2",
+]
+keywords = [
+    "complexity",
+    "halstead",
+    "maintainability",
+    "cyclomatic",
+    "static-analysis",
+    "metrics",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Quality Assurance",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[[project.maintainers]]
+name = "nickgiki"
+
+[project.urls]
+Homepage = "https://github.com/nickgiki/codelexity"
+Issues = "https://github.com/nickgiki/codelexity/issues"
+
+[project.scripts]
+codelexity = "codelexity.main:main"
+
+[tool.uv.sources.codelexity]
+path = "src"
+editable = true
+
+[tool.bumpver]
+current_version = "0.1.0"
+version_pattern = "MAJOR.MINOR.PATCH"
+push = false
+
+[tool.bumpver.file_patterns]
+"pyproject.toml" = [
+    'current_version = "{version}"',
+    'version = "{version}"',
+]
+"README.md" = ["version-{version}-"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+]
+
+[tool.ruff.lint.isort]
+force-single-line = false
+order-by-type = true
+
+[build-system]
+requires = ["uv_build>=0.10,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "bumpver>=2026.1132",
+    "prek>=0.4.14",
+    "ruff>=0.16.3",
+]

codelexity-0.1.0/pyproject.toml.orig

@@ -0,0 +1,73 @@
+[project]
+name = "codelexity"
+version = "0.1.0"
+description = "A package that measures code complexity in the age of AI slop."
+readme = "README.md"
+requires-python = ">=3.11"
+maintainers = [{ name = "nickgiki" }]
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    # Only DiGraph, katz_centrality and PowerIterationFailedConvergence are used, all stable since
+    # networkx 3.0; from_nx/save_graph likewise for pyvis. Floors verified with --resolution
+    # lowest-direct, no upper caps.
+    "networkx>=3.0",
+    "pyvis>=0.3.2",
+]
+
+keywords = ["complexity", "halstead", "maintainability", "cyclomatic", "static-analysis", "metrics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Quality Assurance",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/nickgiki/codelexity"
+Issues = "https://github.com/nickgiki/codelexity/issues"
+
+[project.scripts]
+codelexity = "codelexity.main:main"
+
+[tool.uv.sources]
+codelexity = { path = "src", editable = true }
+
+[build-system]
+requires = ["uv_build>=0.10,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "bumpver>=2026.1132",
+    "prek>=0.4.14",
+    "ruff>=0.16.3",
+]
+
+[tool.bumpver]
+current_version = "0.1.0"
+version_pattern = "MAJOR.MINOR.PATCH"
+push = false  # inspect the tag before it leaves the machine
+
+[tool.bumpver.file_patterns]
+# The version appears twice in this file: [project] version and current_version above.
+"pyproject.toml" = ['current_version = "{version}"', 'version = "{version}"']
+"README.md" = ['version-{version}-']
+
+[tool.ruff]
+# Set your preferred line length rule
+line-length = 120
+
+[tool.ruff.lint]
+# E, F = standard errors/warnings
+# I = Isort (handles argument/import sorting rules)
+select = ["E", "F", "I"]
+
+[tool.ruff.lint.isort]
+# Forces arguments/imports into a specific sorted structure
+force-single-line = false
+order-by-type = true
+
+

codelexity-0.1.0/src/codelexity/__init__.py

@@ -0,0 +1,7 @@
+from importlib.metadata import PackageNotFoundError, version
+
+# Read from installed metadata so pyproject.toml stays the only place the version is written.
+try:
+    __version__ = version("codelexity")
+except PackageNotFoundError:  # running from a source checkout that was never installed
+    __version__ = "0.0.0.dev0"

codelexity-0.1.0/src/codelexity/calculations.py

@@ -0,0 +1,194 @@
+import ast
+import dis
+import importlib.machinery
+import re
+import sys
+import sysconfig
+from math import log, sin, sqrt
+from pathlib import Path
+
+from codelexity.halstead import halstead_metrics
+
+MULTILINE_COMMENTS = re.compile(r"^[\t ]*\"\"\".*?\"\"\"|^[\t ]*'''.*?'''", re.DOTALL | re.MULTILINE)
+SINGLE_LINE_COMMENTS = re.compile(r"^[ \t]*#", re.MULTILINE)
+EMPTY_LINES = re.compile("^[ \t]*$", re.MULTILINE)
+
+# One decision point each. BoolOp is counted separately: `a and b and c` is two branches, not one.
+DECISION_POINTS = (
+    ast.If,
+    ast.IfExp,
+    ast.For,
+    ast.AsyncFor,
+    ast.While,
+    ast.ExceptHandler,
+    ast.Assert,
+    ast.match_case,
+)
+
+
+def empty_lines(string: str):
+    return re.findall(EMPTY_LINES, string)
+
+
+def comments_and_docstrings(string: str):
+    return re.findall(SINGLE_LINE_COMMENTS, string) + re.findall(MULTILINE_COMMENTS, string)
+
+
+def functions(string):
+    tree = ast.parse(string)
+    fns = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            fns.append(ast.get_source_segment(string, node))
+    return fns
+
+
+def cyclomatic_complexity(module_source: str):
+    """McCabe complexity for the whole module: one linearly independent path, plus one per branch."""
+    total = 1
+    for node in ast.walk(ast.parse(module_source)):
+        if isinstance(node, DECISION_POINTS):
+            total += 1
+        elif isinstance(node, ast.BoolOp):
+            total += len(node.values) - 1
+        elif isinstance(node, ast.comprehension):
+            total += 1 + len(node.ifs)
+    return total
+
+
+def maintainability_index(module_source: str):
+    """Coleman-Oman index rescaled to 0-100, where higher is more maintainable."""
+    volume = halstead_metrics(module_source)["volume"]
+    comments = len(comments_and_docstrings(module_source))
+    sloc = len(module_source.split("\n")) - len(empty_lines(module_source)) - comments
+    if sloc <= 0 or volume <= 0:
+        return 100.0
+    raw = (
+        171
+        - 5.2 * log(volume)
+        - 0.23 * cyclomatic_complexity(module_source)
+        - 16.2 * log(sloc)
+        + 50 * sin(sqrt(2.4 * comments / sloc))
+    )
+    # ponytail: clamped to 0-100 so it reads as a percentage. The comment term can push raw above
+    # 171, which is why the upper bound is here and not just a max(0, ...).
+    return min(100.0, max(0.0, raw * 100 / 171))
+
+
+def _import_names(code):
+    """Dotted names a code object imports, e.g. `from a.b import c` -> a, a.b, a.b.c."""
+    for name, level, fromlist in dis._find_imports(code):
+        yield name
+        for item in fromlist or ():
+            if item != "*":
+                yield f"{name}.{item}"
+    for const in code.co_consts:
+        if isinstance(const, type(code)):
+            yield from _import_names(const)
+
+
+def _resolve(name, search):
+    """Deepest importable spec for a dotted name, walking package search
+    locations without importing/executing anything."""
+    spec, parts = None, name.split(".")
+    for i in range(len(parts)):
+        locations = spec.submodule_search_locations if spec else search
+        try:
+            found = locations and importlib.machinery.PathFinder.find_spec(".".join(parts[: i + 1]), locations)
+        except KeyError:
+            # ponytail: namespace packages need their own parent in sys.modules
+            # to build a submodule spec; we never import, so treat as unresolved.
+            found = None
+        if not found:
+            break
+        spec = found
+    return spec
+
+
+def imports(module_path, root=None):
+    """Full filesystem paths of the local modules `module_path` imports."""
+    path = Path(module_path).resolve()
+    code = compile(path.read_text(), str(path), "exec")
+    root = Path(root).resolve() if root else path.parent
+    search = sys.path + [str(root), *(str(d) for d in root.rglob("*") if d.is_dir())]
+    names = {n for n in _import_names(code) if n.split(".")[0] not in sys.builtin_module_names}
+    specs = (_resolve(n, search) for n in names)
+    return sorted({s.origin for s in specs if s and s.origin})
+
+
+def analyze_module(path, root=None):
+    pth = Path(path).resolve()
+    st = pth.open().read()
+    total, empty, comments = (
+        len(st.split("\n")),
+        len(empty_lines(st)),
+        len(comments_and_docstrings(st)),
+    )
+    return {
+        "imports": imports(pth, root),
+        "total_lines": total,
+        "empty_lines": empty,
+        "comments": comments,
+        "code_length": total - empty - comments,
+        "contained_function_length": sorted(
+            [len(f.split("\n")) - len(empty_lines(f)) - len(comments_and_docstrings(f)) for f in functions(st)]
+        ),
+        "halstead_metrics": halstead_metrics(st),
+        "maintainability_index": round(maintainability_index(st), 1),
+    }
+
+
+def normalized_path_list(path: str):
+    suffixes = Path(path).suffixes
+    name = Path(path).name
+    path_list = path.split("/")[:-1]
+    for suff in suffixes:
+        name = name.replace(suff, "")
+    return path_list + [name]
+
+
+def shorten(path: Path, root: Path):
+    ANON_BASES = (
+        (sysconfig.get_paths()["stdlib"], "<stdlib>/"),
+        (sysconfig.get_paths()["purelib"], "<site-packages>/"),
+        (Path.home(), "~/"),
+    )
+    for base, tag in ((root, ""), *ANON_BASES):
+        if path.is_relative_to(base):
+            return tag + path.relative_to(base).as_posix()
+    return path.as_posix()
+
+
+def is_valid(module_path: str, include_only, exclude):
+    pathlist = normalized_path_list(module_path)
+    included = not include_only or set(pathlist).isdisjoint(set(include_only))
+    excluded = exclude and set(pathlist).isdisjoint(set(exclude))
+    return included and not excluded
+
+
+def advanced_analysis(package_data: dict):
+    return {
+        "total_lines": sum(d["total_lines"] for d in package_data.values()),
+        "total_functions": sum(len(d["contained_function_length"]) for d in package_data.values()),
+        "total_modules": len(package_data.keys()),
+    }
+
+
+def analyze_package(path, exclude=(), include_only=(), max_recursion=25):
+    module_dict = {}
+    resolved_path = Path(path)
+    for p in resolved_path.rglob("*.py"):
+        if not is_valid(p.as_posix(), exclude, include_only):
+            continue
+        module_data = analyze_module(p, root=resolved_path)
+        module_data["imports"] = [
+            imp_mod for imp_mod in module_data["imports"] if is_valid(imp_mod, exclude, include_only)
+        ]
+        module_dict[p.resolve().as_posix()] = module_data
+        for imp in set(module_data["imports"]).difference(set(module_dict.keys())):
+            module_data = analyze_module(imp, root=resolved_path)
+            module_data["imports"] = [
+                imp_mod for imp_mod in module_data["imports"] if is_valid(imp_mod, exclude, include_only)
+            ]
+            module_dict[imp] = module_data
+    return {"analytics": advanced_analysis(module_dict), "modules": module_dict}

codelexity-0.1.0/src/codelexity/graph.py

@@ -0,0 +1,92 @@
+from pathlib import Path
+
+import networkx as nx
+from pyvis.network import Network
+
+
+def node_data(data: dict):
+    return "\n-".join(f"{k}: {v}" for k, v in data.items() if isinstance(v, (str, int, float)))
+
+
+node_size = lambda num: max(min(num**0.5, 50), 3)
+
+MI_BANDS = ((60, "#97c2fc89"), (20, "#ccb7b789"), (0, "#d0515189"))
+
+
+def mi_color(score):
+    """Position on the light blue -> gray -> red ramp: healthy blue, middling gray, poor red."""
+    for threshold, colour in MI_BANDS:
+        if score >= threshold:
+            return colour
+    return MI_BANDS[-1][-1]
+
+
+def create_graph(package_data: dict):
+    G = nx.DiGraph()
+    for i, (module, data) in enumerate(package_data["modules"].items()):
+        G.add_node(
+            module,
+            label=module.split("/")[-1],
+            title=node_data({"path": module, **data}),
+            size=node_size(data["total_lines"]),
+            maintainability=data["maintainability_index"],
+            color=mi_color(data["maintainability_index"]),
+        )
+    for module, data in package_data["modules"].items():
+        for imported in data["imports"]:
+            # Only edges between analyzed modules. analyze_package stops at depth 1, so deeper
+            # imports have no metrics; add_edge would invent attribute-less nodes for them.
+            if imported in package_data["modules"]:
+                G.add_edge(imported, module)
+    return G
+
+
+def maintainability(G, damping=0.5):
+    """0-100. Importance-weighted mean of raw MI over the modules that carry data."""
+    # Edges pull in transitive imports that were never analyzed, so they have no attributes.
+    try:
+        centrality = nx.katz_centrality(G.reverse(copy=True), alpha=damping)
+    except nx.PowerIterationFailedConvergence:
+        print("Failed to converge!")
+        centrality = dict.fromkeys(G, 1.0)
+    weights = {n: G.nodes[n]["size"] * centrality[n] for n in G.nodes}  # weight by size and centrality
+    weights = {n: v / sum(weights.values()) for n, v in weights.items()}
+    adjusted_m = [G.nodes[n]["maintainability"] * weights[n] for n in G.nodes]
+    return sum(adjusted_m)
+
+
+def create_viz(package_data: dict, fpath: str):
+    G = create_graph(package_data=package_data)
+    maintainability_score = int(round(maintainability(G)))
+
+    net = Network(
+        height="600px",
+        width="100%",
+        notebook=False,
+        directed=True,
+    )
+    net.from_nx(G)
+    net.set_options("""
+        var options = {
+        "physics": {
+            "maxVelocity": 5
+        }
+        }
+        """)
+    net.save_graph(fpath)
+
+    legend = (
+        '<div style="position:fixed;top:10px;left:10px;background:#fff;'
+        "border:1px solid #ccc;padding:8px 12px;"
+        "font-family:ui-monospace,Consolas,monospace;"
+        'letter-spacing:0.2px;font-size:14px;z-index:1000;">'
+        '<div style="font-size:20px;margin-bottom:6px;">Codelexity</div>'
+        f'<div style="font-size:15px;margin-bottom:4px;display:inline-block;'
+        f'background:{mi_color(maintainability_score)};color:#333;padding:2px 10px;border-radius:2px;">'
+        f"Maintainability: {maintainability_score}%</div><br>"
+        f"Total lines of code: {package_data['analytics']['total_lines']}<br>"
+        f"Total modules: {package_data['analytics']['total_modules']}<br>"
+        f"Total functions/methods: {package_data['analytics']['total_functions']}</div>"
+    )
+    path = Path(fpath)
+    path.write_text(path.read_text().replace("<body>", f"<body>\n{legend}", 1))

codelexity-0.1.0/src/codelexity/halstead.py

@@ -0,0 +1,59 @@
+import ast
+from collections import Counter
+from math import log2
+
+IGNORED = (
+    ast.Module,
+    ast.Expr,
+    ast.expr_context,
+    ast.arguments,
+    ast.BinOp,
+    ast.UnaryOp,
+    ast.BoolOp,
+    ast.Compare,
+)
+
+
+def operators_and_operands(module_source: str):
+    """Counts of each distinct operator and operand in `module_source`."""
+    operators, operands = Counter(), Counter()
+    for node in ast.walk(ast.parse(module_source)):
+        if isinstance(node, IGNORED):
+            continue
+        if isinstance(node, ast.Constant):
+            operands[repr(node.value)] += 1
+        elif isinstance(node, ast.Name):
+            operands[node.id] += 1
+        elif isinstance(node, ast.arg):
+            operands[node.arg] += 1
+        elif isinstance(node, ast.alias):
+            operands[node.name] += 1
+        else:
+            operators[type(node).__name__] += 1
+            if isinstance(node, ast.Attribute):
+                operands[node.attr] += 1  # `a.b` is the `.` operator applied to operand `b`
+    return operators, operands
+
+
+def halstead_metrics(module_source: str):
+    operators, operands = operators_and_operands(module_source)
+    distinct_operators, distinct_operands = len(operators), len(operands)
+    total_operators, total_operands = sum(operators.values()), sum(operands.values())
+    vocabulary = distinct_operators + distinct_operands
+    length = total_operators + total_operands
+    volume = length * log2(vocabulary) if vocabulary else 0.0
+    difficulty = (distinct_operators * total_operands) / (2 * distinct_operands) if distinct_operands else 0.0
+    effort = difficulty * volume
+    return {
+        "distinct_operators": distinct_operators,
+        "distinct_operands": distinct_operands,
+        "total_operators": total_operators,
+        "total_operands": total_operands,
+        "vocabulary": vocabulary,
+        "length": length,
+        "volume": volume,
+        "difficulty": difficulty,
+        "effort": effort,
+        "time": effort / 18,
+        "estimated_bugs": volume / 3000,
+    }

codelexity-0.1.0/src/codelexity/main.py

@@ -0,0 +1,72 @@
+import argparse
+import json
+from pathlib import Path
+
+from codelexity.calculations import analyze_package, shorten
+from codelexity.graph import create_viz
+
+HTML_NAME = "codelexity.html"
+JSON_NAME = "codelexity.json"
+
+parser = argparse.ArgumentParser(description="Codelexity helps you measure and visualize the complexity of your code.")
+
+parser.add_argument("filepath", help="The path to the code you want to process.")
+parser.add_argument(
+    "-j",
+    "--json",
+    action="store_true",
+    help=f"Store the codelexity data in a json file `{JSON_NAME}` in the current directory.",
+)
+parser.add_argument(
+    "-p",
+    "--plot",
+    action="store_true",
+    help=f"Store the codelexity interactive plot in an html file `{HTML_NAME}` in the current directory.",
+)
+parser.add_argument(
+    "-i", "--include-only", nargs="+", type=str, default=(), help="Provide the list of packages/modules to be included."
+)
+parser.add_argument(
+    "-e",
+    "--exclude",
+    nargs="+",
+    type=str,
+    default=(".venv", "bin"),
+    help="Provide a list of packages/modules to exclude.",
+)
+parser.add_argument("-a", "--absolute", action="store_true", help="If added all paths will be absolute.")
+
+
+def main():
+    args = parser.parse_args()
+
+    # find and resolve path
+    path = Path(args.filepath).resolve()
+    print(f"Analyzing code in : {path.as_posix()}")
+
+    if not path.exists():
+        raise FileNotFoundError(f"Could not locate: {args.filepath}")
+
+    # analyze code
+    data = analyze_package(path, exclude=args.exclude, include_only=args.include_only)
+
+    if not args.absolute:
+        # Keys and imports shortened together — create_graph matches edges between the two.
+        data["modules"] = {
+            shorten(Path(mod), path): {**d, "imports": [shorten(Path(i), path) for i in d["imports"]]}
+            for mod, d in data["modules"].items()
+        }
+
+    if args.plot:
+        create_viz(data, HTML_NAME)
+        print(f"Interactive plot saved in: `{Path(HTML_NAME).resolve().as_posix()}`")
+
+    if args.json:
+        Path("codelexity.json").write_text(json.dumps(data, indent=4), encoding="utf-8")
+
+    if not (args.plot or args.json):
+        print(json.dumps(data, indent=4))
+
+
+if __name__ == "__main__":
+    main()