nouls 0.1.1__tar.gz

nouls-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,117 @@
+name: CI and Publish
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras --frozen
+
+      - name: Lint with ruff
+        run: uv run ruff check .
+
+      - name: Format check with ruff
+        run: uv run ruff format --check .
+
+      - name: Type check with basedpyright
+        run: uv run basedpyright
+
+      - name: Run unit tests (parallel)
+        run: uv run pytest -m unit -n auto --cov=src/nouls --cov-report=term-missing
+
+      - name: Run integration tests (sequential)
+        run: uv run pytest -m integration --cov=src/nouls --cov-append --cov-report=term-missing
+
+  publish:
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nouls
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras --frozen
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version
+        run: uv run bump-my-version bump patch
+
+      - name: Push version bump
+        run: git push --follow-tags
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  docs:
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras --frozen
+
+      - name: Build docs
+        run: uv run zensical build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

nouls-0.1.1/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv
+venv/
+ENV/
+env/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.pytype/
+.pyre/
+.basedpyright/
+
+# Ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log
+.env
+.env.local

nouls-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,94 @@
+default_language_version:
+  python: python3
+default_stages: [pre-commit]
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: check-yaml
+        args: [--unsafe]
+      - id: check-json
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: check-ast
+      - id: check-docstring-first
+      - id: debug-statements
+      - id: name-tests-test
+        args: [--pytest-test-first]
+      - id: detect-private-key
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.47.0
+    hooks:
+      - id: markdownlint
+        args: [--fix, --disable, MD013, MD024, MD033, MD036, MD040, MD041, MD060, --]
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.12.1
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+
+  - repo: https://github.com/benomahony/nasa-lsp
+    rev: v0.1.7
+    hooks:
+      - id: nasa-lsp
+        exclude: ^tests/
+
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff-format
+        entry: uv run ruff format
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: ruff
+        name: ruff
+        entry: uv run ruff check --fix --exit-non-zero-on-fix
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: basedpyright
+        name: basedpyright
+        entry: uv run basedpyright
+        language: system
+        types: [python]
+        pass_filenames: true
+        require_serial: true
+      - id: vulture
+        name: vulture
+        entry: uv run vulture src/nouls/ --min-confidence 80
+        language: system
+        types: [python]
+        files: ^src/nouls/
+        pass_filenames: false
+        require_serial: true
+      - id: bandit
+        name: bandit
+        entry: uv run bandit -c pyproject.toml -r src/nouls/
+        language: system
+        files: ^src/nouls/
+        exclude: ^tests/
+        pass_filenames: false
+      - id: cliqa
+        name: cliqa
+        entry: uv run cliqa analyze nouls
+        language: system
+        files: ^(pyproject\.toml|src/.*\.py)$
+        pass_filenames: false
+        require_serial: true
+      - id: deptry
+        name: deptry
+        entry: uv run deptry . --extend-exclude "\.venv|tests"
+        language: system
+        pass_filenames: false
+        require_serial: true

nouls-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

nouls-0.1.1/.skills/nouls/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: nouls
+description: Help users work with nouls, the semantic linter and language server built on TypeSafe yes/no questions. Use when the user asks about nouls rules, configuration, thresholds, labels or stats, or wants to add a rule or language.
+---
+
+# nouls Skill
+
+This skill helps you work with nouls.
+
+## When to Use This Skill
+
+Use this skill when:
+
+- User asks about nouls features or capabilities
+- User wants to add or tune a rule in `nouls.yaml`
+- User wants to add a language through tree-sitter node types
+- User needs help with the nouls CLI or language server
+- User wants to label findings or read `nouls stats`
+
+## Project Information
+
+- **Description**: Semantic linter and language server that asks TypeSafe yes/no questions about every function
+- **Author**: Ben O'Mahony
+- **Documentation**: See docs/index.md for full documentation
+- **Source**: src/nouls/
+
+## Quick Reference
+
+### CLI Usage
+
+```bash
+nouls check src/
+nouls rules
+nouls label src/app.py 42 unit_mismatch false
+nouls review unit_mismatch
+nouls stats thresholds --ask
+nouls serve
+```
+
+### Rule shape
+
+```yaml
+rules:
+  ledger_sign:
+    question: Does the function add a debit where the domain requires subtracting it, or the reverse?
+    message: Debit and credit signs look inverted
+    severity: error
+    threshold: 0.9
+    languages: [python]
+    files: ["*/ledger/*.py"]
+```
+
+Questions must be a single yes/no judgement about the function in the `function` state field. Never ask for a number.
+
+## Resources
+
+- Check docs/index.md for comprehensive documentation
+- Check llms.txt for LLM-friendly documentation summary
+- Check src/nouls/defaults.yaml for built in languages and rules
+- Check src/nouls/ for implementation details

nouls-0.1.1/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.5
+Name: nouls
+Version: 0.1.1
+Summary: Semantic linter and language server that asks TypeSafe yes/no questions about every function
+Author-email: Ben O'Mahony <bomarni@gmail.com>
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: cyclopts>=4.25.2
+Requires-Dist: lsprotocol>=2025.0.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pygls>=2.1.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: tree-sitter-language-pack>=1.20.0
+Requires-Dist: tree-sitter>=0.26.0
+Requires-Dist: typesafe-sdk>=0.6.0
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7.0; extra == 'dev'
+Requires-Dist: basedpyright>=1.10.0; extra == 'dev'
+Requires-Dist: bump-my-version>=0.28.0; extra == 'dev'
+Requires-Dist: cliqa>=0.1.0; extra == 'dev'
+Requires-Dist: deptry>=0.12.0; extra == 'dev'
+Requires-Dist: prek>=0.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest-examples>=0.0.10; extra == 'dev'
+Requires-Dist: pytest-testmon>=2.0.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Requires-Dist: vulture>=2.11; extra == 'dev'
+Requires-Dist: zensical>=0.0.10; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.2.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# nouls
+
+A semantic linter and language server for the problems deterministic tools cannot see.
+
+nouls splits every file into functions with tree-sitter and asks [TypeSafe](https://docs.typesafe.ai) a batch of yes/no questions about each one. A rule fires when the probability of yes reaches its threshold. Every question is scored independently, so one call per function answers every rule, and unchanged functions are never asked again.
+
+The default rules target intent, not syntax:
+
+| Rule | Severity |
+| --- | --- |
+| `name_behaviour_mismatch` | warning |
+| `docstring_drift` | warning |
+| `query_with_side_effect` | warning |
+| `partial_failure` | warning |
+| `check_then_act` | warning |
+| `missing_authorisation` | warning |
+| `non_idempotent_retry` | error |
+| `unit_mismatch` | error |
+| `boundary_error` | error |
+| `misleading_error` | info |
+| `mixed_abstraction` | info |
+
+Anything ruff, a type checker or a security scanner already catches is deliberately out of scope.
+
+Test files also get rules drawn from Kent Beck's [Test Desiderata](https://testdesiderata.com). Each asks whether a test violates one property.
+
+| Rule | Desideratum | Severity |
+| --- | --- | --- |
+| `test_not_isolated` | Isolated | warning |
+| `test_not_composable` | Composable | info |
+| `test_nondeterministic` | Deterministic | error |
+| `test_slow` | Fast | warning |
+| `test_hard_to_write` | Writable | info |
+| `test_unreadable` | Readable | info |
+| `test_not_behavioural` | Behavioural | error |
+| `test_structure_sensitive` | Structure insensitive | warning |
+| `test_not_automated` | Automated | error |
+| `test_not_specific` | Specific | warning |
+| `test_not_predictive` | Predictive | warning |
+| `test_not_inspiring` | Inspiring | warning |
+
+They only run on files matching the default test patterns, such as `test_*.py`, `*_test.go`, `*.spec.ts`, `*Test.java` and `*/tests/*.rs`. Rust unit tests inside `mod tests` in a source file are not matched.
+
+## Installation
+
+```bash
+uv tool install nouls --index typesafe=https://pypi.typesafe.ai/
+export TYPESAFE_API_KEY="your-api-key"
+```
+
+## Usage
+
+```bash
+nouls check src/
+nouls rules
+nouls serve
+nouls label src/billing.py 42 unit_mismatch false
+nouls review unit_mismatch
+nouls stats rules
+nouls stats hotspots
+nouls stats cost
+nouls stats thresholds unit_mismatch --ask
+```
+
+`check` prints `path:line:column: severity [rule] message (probability)` and exits 1 when an error level rule fires. Set `show_probability: false` to drop the probability from both the command line and editor diagnostics.
+
+## Store
+
+Every answer lives in one SQLite file, `~/.cache/nouls/nouls.db` by default, shared by the language server, the command line and every repo on the machine. It runs in WAL mode, so several processes can use it at once.
+
+- `answers` caches one probability per model, question and function source. Rewording a rule only re-asks that rule. Editing a function only re-asks that function.
+- `observations` holds the latest answer for every rule on every function in every file checked.
+- `labels` holds your verdicts. A finding labelled `false` is no longer reported for that function.
+- `runs` records questions asked, cache hits and tokens for every file checked.
+
+## Labels and thresholds
+
+Label findings from the editor with the `not a problem` and `confirm finding` code actions, from the command line with `nouls label`, or in bulk with `nouls review`. `review` shows unlabelled functions for one rule, sampled evenly across probability bands, so the labels cover misses as well as hits.
+
+`nouls stats thresholds` compares your labels with the current wording of each question and prints precision and recall at a range of thresholds. Labels belong to the rule, not the wording, so you can rewrite a question, run `nouls stats thresholds --ask` to re-ask it for every labelled function, and compare.
+
+`nouls stats rules` shows how often each rule fires, how many answers sit in the ambiguous 0.35 to 0.65 band, and a histogram of probabilities. A well posed question piles up at both ends.
+
+For anything else, attach the store read only from DuckDB:
+
+```sql
+ATTACH '~/.cache/nouls/nouls.db' AS nouls (TYPE sqlite, READ_ONLY);
+SELECT rule, quantile_cont(probability, [0.1, 0.5, 0.9]) FROM nouls.observations GROUP BY rule;
+```
+
+## Configuration
+
+nouls merges its built in defaults with the first `nouls.yaml`, `nouls.yml`, `.nouls.yaml` or `.nouls.yml` found walking up from the target, or the file passed with `--config`. Maps merge key by key, so you only write what changes.
+
+```yaml
+model: jev-latest
+threshold: 0.8
+concurrency: 8
+debounce_ms: 1000
+show_probability: true
+lint_on: change
+store: ~/.cache/nouls/nouls.db
+exclude: [".*", node_modules, __pycache__, target, dist, build, venv]
+
+languages:
+  kotlin:
+    grammar: kotlin
+    extensions: [.kt, .kts]
+    units: [function_declaration]
+
+rules:
+  mixed_abstraction:
+    enabled: false
+  unit_mismatch:
+    threshold: 0.9
+  ledger_sign:
+    question: Does the function add a debit where the domain requires subtracting it, or the reverse?
+    message: Debit and credit signs look inverted
+    severity: error
+    languages: [python, go]
+  test_not_isolated:
+    files: ["*_test.py", "*/integration/*.py"]
+```
+
+`lint_on: save` stops the language server checking while you type. `store` moves the SQLite file.
+
+`files` limits a rule to file names or paths matching any of its globs. Setting it replaces the default list.
+
+Languages are pure configuration. `grammar` is any name from [tree-sitter-language-pack](https://github.com/Goldziher/tree-sitter-language-pack), and `units` lists the node types to send as individual questions. The diagnostic sits on the node's `name` field, or its first line when it has none.
+
+Every question is answered against this state:
+
+```json
+{"language": "python", "function": "<source of the unit>"}
+```
+
+Write questions as a single yes/no judgement about that function.
+
+## Neovim
+
+```lua
+vim.lsp.config("nouls", {
+  cmd = { "nouls", "serve" },
+  filetypes = { "python", "javascript", "typescript", "typescriptreact", "go", "rust", "java", "c", "cpp", "lua", "ruby" },
+  root_markers = { "nouls.yaml", ".nouls.yaml", ".git" },
+})
+vim.lsp.enable("nouls")
+```
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run prek install
+uv run prek run --all-files
+uv run pytest
+```
+
+## AI Integration
+
+An MCP server for the docs lives in `src/nouls/mcp_server.py`:
+
+```bash
+claude mcp add nouls --transport stdio uv run --with mcp python src/nouls/mcp_server.py
+```
+
+A Claude Code Agent Skill lives in `.skills/nouls`:
+
+```bash
+claude skill add .skills/nouls
+```