docs: 📝 LLAP

Author: robvanderleek

.github/workflows/main.yml

@@ -0,0 +1,20 @@
+name: main
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout sources'
+        uses: actions/checkout@v4
+
+      - name: 'Deploy docs'
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REQUIREMENTS: requirements.txt

.gitignore

@@ -0,0 +1,2 @@
+site/
+.DS_Store

LICENSE

@@ -1 +1 @@
-# getcodelimit.github.io
+# Code Limit Documentation

README.md

@@ -0,0 +1,49 @@
+{"version": 2, "width": 80, "height": 25, "timestamp": 1712420376, "env": {"SHELL": "/bin/zsh", "TERM": "xterm-256color"}}
+[0.372445, "o", "\u001b]2;rob@mahler:~/projects/opensource/fastapi\u0007\u001b]1;..ource/fastapi\u0007"]
+[0.372945, "o", "\u001b]0;~/projects/opensource/fastapi\u0007"]
+[0.376495, "o", "\r\n"]
+[0.376679, "o", "\u001b[0m\u001b[27m\u001b[24m\u001b[J\u001b[34m~/projects/opensource/fastapi\u001b[39m\r\n\r\u001b[35m❯\u001b[39m \u001b[K"]
+[0.376864, "o", "\u001b[?1h\u001b="]
+[0.377014, "o", "\u001b[?2004h"]
+[0.425151, "o", "\r\r\u001b[A\u001b[0m\u001b[27m\u001b[24m\u001b[J\u001b[34m~/projects/opensource/fastapi\u001b[39m \u001b[38;5;242mmaster\u001b[38;5;218m\u001b[39m\r\n\r\u001b[35m❯\u001b[39m \u001b[K"]
+[1.704691, "o", "c"]
+[2.220527, "o", "\bco"]
+[2.466128, "o", "d"]
+[2.511853, "o", "e"]
+[2.646861, "o", "l"]
+[2.735853, "o", "i"]
+[2.955499, "o", "m"]
+[3.019103, "o", "i"]
+[3.593736, "o", "t"]
+[3.654651, "o", " "]
+[3.976152, "o", "r"]
+[4.02638, "o", "e"]
+[4.088613, "o", "p"]
+[4.142272, "o", "o"]
+[4.540734, "o", "r"]
+[5.204344, "o", "t"]
+[5.386895, "o", " "]
+[6.078544, "o", "."]
+[6.734379, "o", "\u001b[?1l\u001b>"]
+[6.735087, "o", "\u001b[?2004l\r\r\n"]
+[6.737336, "o", "\u001b]2;codelimit report .\u0007\u001b]1;codelimit\u0007"]
+[6.737727, "o", "\u001b]0;fastapi: codelimit report .\u0007"]
+[6.996205, "o", "\u001b[1mfastapi/applications.py\u001b[0m\u001b[36m:\u001b[0m64\u001b[36m:\u001b[0m5\u001b[36m:\u001b[0m 317 \u001b[31m✖\u001b[0m __init__\r\n"]
+[6.996294, "o", "\u001b[1mfastapi/param_functions.py\u001b[0m\u001b[36m:\u001b[0m1263\u001b[36m:\u001b[0m1\u001b[36m:\u001b[0m 229 \u001b[31m✖\u001b[0m Body\r\n"]
+[6.996347, "o", "\u001b[1mfastapi/param_functions.py\u001b[0m\u001b[36m:\u001b[0m643\u001b[36m:\u001b[0m1\u001b[36m:\u001b[0m 222 \u001b[31m✖\u001b[0m Header\r\n"]
+[6.996423, "o", "\u001b[1mfastapi/param_functions.py\u001b[0m\u001b[36m:\u001b[0m1592\u001b[36m:\u001b[0m1\u001b[36m:\u001b[0m 222 \u001b[31m✖\u001b[0m Form\r\n"]
+[6.996499, "o", "\u001b[1mfastapi/param_functions.py\u001b[0m\u001b[36m:\u001b[0m1906\u001b[36m:\u001b[0m1\u001b[36m:\u001b[0m 222 \u001b[31m✖\u001b[0m File\r\n"]
+[6.996571, "o", "\u001b[1mfastapi/param_functions.py\u001b[0m\u001b[36m:\u001b[0m11\u001b[36m:\u001b[0m1\u001b[36m:\u001b[0m 216 \u001b[31m✖\u001b[0m Path\r\n"]
+[6.996638, "o", "\u001b[1mfastapi/param_functions.py\u001b[0m\u001b[36m:\u001b[0m339\u001b[36m:\u001b[0m1\u001b[36m:\u001b[0m 215 \u001b[31m✖\u001b[0m Query\r\n"]
+[6.996719, "o", "\u001b[1mfastapi/param_functions.py\u001b[0m\u001b[36m:\u001b[0m959\u001b[36m:\u001b[0m1\u001b[36m:\u001b[0m 215 \u001b[31m✖\u001b[0m Cookie\r\n"]
+[6.996783, "o", "\u001b[1mfastapi/encoders.py\u001b[0m\u001b[36m:\u001b[0m102\u001b[36m:\u001b[0m1\u001b[36m:\u001b[0m 191 \u001b[31m✖\u001b[0m jsonable_encoder\r\n"]
+[6.996855, "o", "\u001b[1mfastapi/openapi/utils.py\u001b[0m\u001b[36m:\u001b[0m215\u001b[36m:\u001b[0m1\u001b[36m:\u001b[0m 183 \u001b[31m✖\u001b[0m get_openapi_path\r\n"]
+[6.997954, "o", "\u001b[1;36m57\u001b[0m\u001b[1m more rows, use --full option to get all rows\u001b[0m\r\n"]
+[7.017025, "o", "\u001b]2;rob@mahler:~/projects/opensource/fastapi\u0007\u001b]1;..ource/fastapi\u0007"]
+[7.017091, "o", "\u001b]0;~/projects/opensource/fastapi\u0007"]
+[7.018383, "o", "\r\n"]
+[7.018456, "o", "\u001b[0m\u001b[27m\u001b[24m\u001b[J\u001b[34m~/projects/opensource/fastapi\u001b[39m \u001b[38;5;242mmaster\u001b[38;5;218m\u001b[39m\r\n\r\u001b[35m❯\u001b[39m "]
+[7.018496, "o", "\u001b[K"]
+[7.018593, "o", "\u001b[?1h\u001b="]
+[7.018651, "o", "\u001b[?2004h"]
+[9.288505, "o", "\u001b[?2004l\r\r\n"]

docs/assets/easy.png

@@ -0,0 +1,74 @@
+# Configuration
+
+## Excluding functions
+
+Functions can be excluded from analysis by putting a `# nocl` comment on the
+line above the start of the function, or at any line of the function header.
+
+For example, to ignore a function with a `# nocl` comment above the start of
+the function:
+
+```python
+# nocl
+def some_function():
+    ...
+```
+
+Or you can ignore a function by putting a `# nocl` comment on any line of the
+header:
+
+```python
+def some_function():  # nocl
+    ...
+```
+
+```python
+def some_functions(
+        some_numbers: list[int]
+) -> int:  # nocl
+    ...
+```
+
+## Excluding files
+
+Files can be excluded from analysis by using the `--exclude` option.
+This option can be used multiple times and takes a [glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) as a
+value, for example:
+
+```shell
+codelimit --exclude "*.generated.py" --exclude "docs/*" ...
+```
+
+The `--exclude` option extends the default exclusion list.
+The default exclusion list is:
+
+```python
+[
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+    "test",
+    "tests",
+]
+```

docs/assets/favicon.png

@@ -0,0 +1,64 @@
+# Development
+
+After installing dependencies with `poetry install`, Code Limit can be run from
+the repository root like this:
+
+```shell
+poetry run codelimit
+```
+
+For example, to check a codebase at `~/projects/fastapi` run:
+
+```shell
+poetry run codelimit scan ~/projects/fastapi
+```
+
+## Local installation using pipx
+
+To install the development repository locally run:
+
+```shell
+pipx install .
+```
+
+To install the `main` branch locally run:
+
+```shell
+pipx install git+https://github.com/getcodelimit/codelimit.git
+```
+
+Or to install another branch locally run:
+
+```shell
+pip install git+https://github.com/getcodelimit/codelimit.git@issue-123
+```
+
+## Building the binary distribution
+
+Generate a self-contained binary:
+
+```shell
+poetry run poe bundle
+```
+
+## Static documentation
+
+Generating the static documentation:
+
+```shell
+poetry run mkdocs build
+```
+
+See the output:
+
+```shell
+poetry run mkdocs serve
+```
+
+Terminal sessions in the documentation are recorded with the [Asciinema
+CLI](https://docs.asciinema.org/getting-started/) and stored in the `assets`
+folder:
+
+```shell
+asciinema rec scan.cast
+```

docs/assets/hard-to-maintain.png

@@ -0,0 +1,41 @@
+# F.A.Q.
+
+### Q. What programming languages does Code Limit support?
+
+Currently Code Limit supports these programming languages:
+
+- C
+- C++
+- Java
+- JavaScript
+- Python
+- TypeScript
+
+### Q. How does Code Limit compare to ...
+
+**Black**
+
+[Black](https://github.com/psf/black) is a code formatter and can run alongside Code Limit.
+
+**Flake8**
+
+[Flake8](https://github.com/PyCQA/flake8) is a linter and can run alongside
+Code Limit. Flake8 can be extended with third-party plugins.
+
+**Lizard**
+
+[Lizard](https://github.com/terryyin/lizard) is a code quality tool that
+measures cyclomatic complexity and code duplication.The tool is more used for
+reporting than monitoring during development.
+
+**Radon**
+
+[Radon](https://github.com/rubik/radon) is a code quality tool that computes
+various metrics. Radon calculates cyclomatic complexity for functions but not
+lines of code. The tool is more used for reporting than monitoring during
+development.
+
+**Ruff**
+
+[Ruff](https://github.com/astral-sh/ruff) is a linter and can run alongside
+Code Limit. Ruff has no linting rule for function length.

docs/assets/logo.png

@@ -0,0 +1,47 @@
+# Introduction
+
+Code Limit is a tool for developers with one goal: _it tells the developer when
+it’s time to refactor_.
+
+Code Limit measures the lines of code for each function in your codebase and
+assigns each function to a category:
+
+| Easy | Verbose | Hard-to-maintain <span style="color: #e5832f;">&#x26A0;</span> | Unmaintainable <span style="color: #ff0000;">&#x2716;</span> |
+| :---: | :---: | :---: | :---: |
+| 1 - 15 lines of code | 16 - 30 lines of code | 31 - 60 lines of code | 60+ lines of code |
+| ![](assets/easy.png){: style="height:136px;width:230px"} | ![](assets/verbose.png){: style="height:189px;width:230px"} | ![](assets/hard-to-maintain.png){: style="height:294px;width:230px"} | ![](assets/unmaintainable.png){: style="height:564px;width:230px"} |
+
+As the table above shows, functions with more than 60 lines of code (comments
+and empty lines are not counted) are _unmaintainable_, and _need_ to be
+refactored. Functions with more than 30 lines of code run a risk of turning
+into unmaintainable functions over time, you should keep an eye on them and
+refactor if possible. Functions in the first two categories are fine and don't
+need refactoring.
+
+Function length is just one code metric, but it is a very important code
+metric. Short functions are easy to understand, easy to test, easy to re-use.
+For example, code duplication is another important code metric but duplication
+is much easier to prevent and fix if your functions are short.
+
+<figure markdown>
+    <div align="center">
+        <img src="assets/unmaintainable-code.jpg" width="500"/>
+    <figcaption>Unmaintainable code. Looks easy; should be done in half an hour I reckon <a href="https://twitter.com/KenScambler/status/477322711039893504">[source]</a></figcaption>
+    </div>
+</figure>
+
+Function length is a simple code metric, so simple you can count it by hand.
+It's also a (fairly) non-controversial metric, most developers agree longer
+functions are harder to maintain. Also, there's always a refactoring possible
+to make functions smaller.
+
+Because function length is such a simple code metric, many code quality tools
+measure it. But these tools measure a lot more metrics, sometimes so much
+metrics that developers are overwhemled and loose focus on the metrics that
+matter most.
+
+Code Limit measures only function length but it tries to be the best developer
+tool for measuring it. By notifying developers when it's time to refactor, Code
+Limit prevents unmaintainable code.
+
+Keep your software maintainable and start using Code Limit today!