arklint 0.1.0__tar.gz

arklint-0.1.0/LICENSE

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

arklint-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: arklint
+Version: 0.1.0
+Summary: The architectural rulebook for your codebase. Prevention, not detection.
+License-Expression: MIT
+Keywords: architecture,linting,cli,code-quality,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: pathspec>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+# Arklint
+
+> The architectural rulebook for your codebase. Prevention, not detection.
+
+[![PyPI version](https://badge.fury.io/py/arklint.svg)](https://pypi.org/project/arklint/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+
+---
+
+Arklint enforces **architectural rules** before bad code ever lands — whether written by AI agents or humans. It's language-agnostic, runs locally with zero cloud dependency, and takes 60 seconds to set up.
+
+```
+$ arklint check
+
+Arklint v0.1.0 — Scanning 142 files against 5 rules...
+
+  ✗ FAIL  no-direct-db-in-routes
+         API routes must not import database modules directly
+         routes/users.py → imports 'sqlalchemy' — blocked by this rule
+         routes/orders.py → imports 'psycopg2' — blocked by this rule
+
+  ✗ FAIL  single-http-client
+         conflicting packages — keep exactly one of requests, httpx
+
+  ⚠ WARN  no-print-statements
+         services/email.py:45 → banned pattern matched: 'print('
+
+  ✓ PASS  models-in-models-dir
+  ✓ PASS  layered-architecture
+
+────────────────────────────────────────────────────────
+Results: 2 errors, 1 warning, 2 passed
+────────────────────────────────────────────────────────
+```
+
+## Why Arklint
+
+| Other tools | Arklint |
+|---|---|
+| Review **after** code is written (PR comments) | Enforce **before** (pre-commit, CI gate) |
+| Focus on syntax, style, security | Focus on **architecture and boundaries** |
+| SaaS, $15–30/user/month | Open-source, free, runs locally |
+| Complex setup | `arklint init` → working in 60 seconds |
+
+Arklint is **not** a linter (ESLint/Ruff), **not** a security scanner (Semgrep/Snyk), and **not** an AI reviewer (CodeRabbit). It operates at the architecture level — patterns, conventions, and structural rules that no existing tool enforces.
+
+---
+
+## Installation
+
+```bash
+pip install arklint
+```
+
+## Quick start
+
+```bash
+# 1. Generate a starter config
+arklint init
+
+# 2. Edit .arklint.yml to match your architecture (takes 2 minutes)
+
+# 3. Run a check
+arklint check
+
+# 4. Add to pre-commit or CI
+arklint check --strict   # exits 1 on warnings too
+```
+
+---
+
+## Rule types
+
+### `boundary` — Import restrictions between directories
+
+Prevent files in source directories from importing blocked packages.
+
+```yaml
+- id: no-direct-db-in-routes
+  type: boundary
+  description: "API routes must not import the database layer directly"
+  source: "routes/**"
+  blocked_imports:
+    - "sqlalchemy"
+    - "psycopg2"
+    - "pymongo"
+  severity: error
+```
+
+### `dependency` — Control what packages are in the project
+
+Detect conflicting or banned dependencies in `requirements.txt`, `package.json`, `go.mod`, and more.
+
+```yaml
+- id: single-http-client
+  type: dependency
+  description: "Pick one HTTP client and stick with it"
+  allow_only_one_of:
+    - "requests"
+    - "httpx"
+    - "aiohttp"
+  severity: error
+```
+
+### `file-pattern` — Code patterns only allowed in specific directories
+
+```yaml
+- id: models-in-models-dir
+  type: file-pattern
+  description: "Data models must live in models/ or schemas/"
+  pattern: 'class\s+\w*(Model|Schema)\s*[:(]'
+  allowed_in:
+    - "models/**"
+    - "schemas/**"
+  severity: warning
+```
+
+### `pattern-ban` — Ban a pattern across the codebase
+
+```yaml
+- id: no-print-statements
+  type: pattern-ban
+  description: "Use structured logging, not print()"
+  pattern: 'print\('
+  exclude:
+    - "tests/**"
+    - "scripts/**"
+  severity: warning
+```
+
+### `layer-boundary` — Enforce layered architecture
+
+Control which layers are allowed to import from which.
+
+```yaml
+- id: layered-architecture
+  type: layer-boundary
+  description: "Enforce routes → services → repositories"
+  layers:
+    - name: routes
+      path: "routes/**"
+    - name: services
+      path: "services/**"
+    - name: repositories
+      path: "repositories/**"
+  allowed_dependencies:
+    routes: [services]
+    services: [repositories]
+    repositories: []
+  severity: error
+```
+
+---
+
+## CLI reference
+
+```
+arklint init              Create a starter .arklint.yml
+arklint init --force      Overwrite existing config
+
+arklint check             Scan from current directory
+arklint check ./src       Scan a specific directory
+arklint check --strict    Exit 1 on warnings too
+arklint check --json      Machine-readable JSON output
+arklint check -c path/to/.arklint.yml   Use a specific config
+```
+
+## CI integration
+
+```yaml
+# GitHub Actions
+- name: Arklint
+  run: |
+    pip install arklint
+    arklint check --strict
+```
+
+## pre-commit
+
+```yaml
+- repo: local
+  hooks:
+    - id: arklint
+      name: arklint
+      entry: arklint check
+      language: python
+      pass_filenames: false
+```
+
+---
+
+## Supported languages
+
+Import extraction works for: Python, JavaScript, TypeScript, Go, Ruby, Rust, Java, C#, PHP.
+
+Dependency parsing works for: `requirements.txt`, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

arklint-0.1.0/README.md

@@ -0,0 +1,203 @@
+# Arklint
+
+> The architectural rulebook for your codebase. Prevention, not detection.
+
+[![PyPI version](https://badge.fury.io/py/arklint.svg)](https://pypi.org/project/arklint/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+
+---
+
+Arklint enforces **architectural rules** before bad code ever lands — whether written by AI agents or humans. It's language-agnostic, runs locally with zero cloud dependency, and takes 60 seconds to set up.
+
+```
+$ arklint check
+
+Arklint v0.1.0 — Scanning 142 files against 5 rules...
+
+  ✗ FAIL  no-direct-db-in-routes
+         API routes must not import database modules directly
+         routes/users.py → imports 'sqlalchemy' — blocked by this rule
+         routes/orders.py → imports 'psycopg2' — blocked by this rule
+
+  ✗ FAIL  single-http-client
+         conflicting packages — keep exactly one of requests, httpx
+
+  ⚠ WARN  no-print-statements
+         services/email.py:45 → banned pattern matched: 'print('
+
+  ✓ PASS  models-in-models-dir
+  ✓ PASS  layered-architecture
+
+────────────────────────────────────────────────────────
+Results: 2 errors, 1 warning, 2 passed
+────────────────────────────────────────────────────────
+```
+
+## Why Arklint
+
+| Other tools | Arklint |
+|---|---|
+| Review **after** code is written (PR comments) | Enforce **before** (pre-commit, CI gate) |
+| Focus on syntax, style, security | Focus on **architecture and boundaries** |
+| SaaS, $15–30/user/month | Open-source, free, runs locally |
+| Complex setup | `arklint init` → working in 60 seconds |
+
+Arklint is **not** a linter (ESLint/Ruff), **not** a security scanner (Semgrep/Snyk), and **not** an AI reviewer (CodeRabbit). It operates at the architecture level — patterns, conventions, and structural rules that no existing tool enforces.
+
+---
+
+## Installation
+
+```bash
+pip install arklint
+```
+
+## Quick start
+
+```bash
+# 1. Generate a starter config
+arklint init
+
+# 2. Edit .arklint.yml to match your architecture (takes 2 minutes)
+
+# 3. Run a check
+arklint check
+
+# 4. Add to pre-commit or CI
+arklint check --strict   # exits 1 on warnings too
+```
+
+---
+
+## Rule types
+
+### `boundary` — Import restrictions between directories
+
+Prevent files in source directories from importing blocked packages.
+
+```yaml
+- id: no-direct-db-in-routes
+  type: boundary
+  description: "API routes must not import the database layer directly"
+  source: "routes/**"
+  blocked_imports:
+    - "sqlalchemy"
+    - "psycopg2"
+    - "pymongo"
+  severity: error
+```
+
+### `dependency` — Control what packages are in the project
+
+Detect conflicting or banned dependencies in `requirements.txt`, `package.json`, `go.mod`, and more.
+
+```yaml
+- id: single-http-client
+  type: dependency
+  description: "Pick one HTTP client and stick with it"
+  allow_only_one_of:
+    - "requests"
+    - "httpx"
+    - "aiohttp"
+  severity: error
+```
+
+### `file-pattern` — Code patterns only allowed in specific directories
+
+```yaml
+- id: models-in-models-dir
+  type: file-pattern
+  description: "Data models must live in models/ or schemas/"
+  pattern: 'class\s+\w*(Model|Schema)\s*[:(]'
+  allowed_in:
+    - "models/**"
+    - "schemas/**"
+  severity: warning
+```
+
+### `pattern-ban` — Ban a pattern across the codebase
+
+```yaml
+- id: no-print-statements
+  type: pattern-ban
+  description: "Use structured logging, not print()"
+  pattern: 'print\('
+  exclude:
+    - "tests/**"
+    - "scripts/**"
+  severity: warning
+```
+
+### `layer-boundary` — Enforce layered architecture
+
+Control which layers are allowed to import from which.
+
+```yaml
+- id: layered-architecture
+  type: layer-boundary
+  description: "Enforce routes → services → repositories"
+  layers:
+    - name: routes
+      path: "routes/**"
+    - name: services
+      path: "services/**"
+    - name: repositories
+      path: "repositories/**"
+  allowed_dependencies:
+    routes: [services]
+    services: [repositories]
+    repositories: []
+  severity: error
+```
+
+---
+
+## CLI reference
+
+```
+arklint init              Create a starter .arklint.yml
+arklint init --force      Overwrite existing config
+
+arklint check             Scan from current directory
+arklint check ./src       Scan a specific directory
+arklint check --strict    Exit 1 on warnings too
+arklint check --json      Machine-readable JSON output
+arklint check -c path/to/.arklint.yml   Use a specific config
+```
+
+## CI integration
+
+```yaml
+# GitHub Actions
+- name: Arklint
+  run: |
+    pip install arklint
+    arklint check --strict
+```
+
+## pre-commit
+
+```yaml
+- repo: local
+  hooks:
+    - id: arklint
+      name: arklint
+      entry: arklint check
+      language: python
+      pass_filenames: false
+```
+
+---
+
+## Supported languages
+
+Import extraction works for: Python, JavaScript, TypeScript, Go, Ruby, Rust, Java, C#, PHP.
+
+Dependency parsing works for: `requirements.txt`, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

arklint-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "arklint"
+version = "0.1.0"
+description = "The architectural rulebook for your codebase. Prevention, not detection."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = ["architecture", "linting", "cli", "code-quality", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "PyYAML>=6.0",
+    "pathspec>=0.12.0",
+]
+
+[project.scripts]
+arklint = "arklint.cli:app"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

arklint-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

arklint-0.1.0/src/arklint/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

arklint-0.1.0/src/arklint/cli.py

@@ -0,0 +1,173 @@
+"""Arklint CLI entry point.
+
+Commands
+--------
+arklint init    Create a starter .arklint.yml in the current directory.
+arklint check   Scan the codebase against all configured rules.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from arklint import __version__
+from arklint.config import load_config, ConfigError
+from arklint.engine import run_rules
+from arklint.init_templates import STARTER_TEMPLATE
+from arklint.reporter import console, err_console, print_header, print_report
+from arklint.scanner import collect_files
+
+
+app = typer.Typer(
+    name="arklint",
+    help="The architectural rulebook for your codebase. Prevention, not detection.",
+    add_completion=False,
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+
+# ---------------------------------------------------------------------------
+# arklint init
+# ---------------------------------------------------------------------------
+
+@app.command()
+def init(
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Overwrite an existing .arklint.yml."
+    ),
+) -> None:
+    """Create a starter [bold].arklint.yml[/bold] in the current directory."""
+    target = Path.cwd() / ".arklint.yml"
+
+    if target.exists() and not force:
+        err_console.print(
+            "[yellow].arklint.yml already exists.[/yellow] "
+            "Use [bold]--force[/bold] to overwrite."
+        )
+        raise typer.Exit(1)
+
+    target.write_text(STARTER_TEMPLATE)
+    console.print(
+        "[bold green]✓[/bold green] Created [cyan].arklint.yml[/cyan] with starter rules.\n"
+        "  Edit it to match your architecture, then run [bold]arklint check[/bold]."
+    )
+
+
+# ---------------------------------------------------------------------------
+# arklint check
+# ---------------------------------------------------------------------------
+
+@app.command()
+def check(
+    path: Optional[Path] = typer.Argument(
+        None,
+        help="Directory to scan. Defaults to the current directory.",
+        show_default=False,
+    ),
+    config: Optional[Path] = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to .arklint.yml. Auto-discovered if omitted.",
+    ),
+    strict: bool = typer.Option(
+        False,
+        "--strict",
+        help="Treat warnings as errors (exit code 1).",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit violations as JSON (useful for CI integrations).",
+    ),
+) -> None:
+    """Scan the codebase against your architectural rules."""
+    scan_root = (path or Path.cwd()).resolve()
+
+    try:
+        cfg = load_config(config)
+    except ConfigError as exc:
+        err_console.print(f"[bold red]Config error:[/bold red] {exc}")
+        raise typer.Exit(2) from exc
+
+    files = collect_files(scan_root)
+
+    if json_output:
+        _check_json(cfg, files, scan_root, strict)
+        return
+
+    print_header(__version__, len(files), len(cfg.rules))
+    results = run_rules(cfg, files, scan_root=scan_root)
+    errors, warnings = print_report(results, scan_root)
+
+    if errors > 0 or (strict and warnings > 0):
+        raise typer.Exit(1)
+
+
+# ---------------------------------------------------------------------------
+# --version flag (attached to the root callback)
+# ---------------------------------------------------------------------------
+
+@app.callback(invoke_without_command=True)
+def _root(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False, "--version", "-v", is_eager=True, help="Show version and exit."
+    ),
+) -> None:
+    if version:
+        console.print(f"arklint v{__version__}")
+        raise typer.Exit()
+    if ctx.invoked_subcommand is None:
+        console.print(ctx.get_help())
+
+
+# ---------------------------------------------------------------------------
+# JSON output helper
+# ---------------------------------------------------------------------------
+
+def _check_json(cfg, files, scan_root, strict: bool) -> None:
+    import json
+
+    results = run_rules(cfg, files, scan_root=scan_root)
+    output = []
+    errors = 0
+    warnings = 0
+    for result in results:
+        for v in result.violations:
+            try:
+                rel = str(v.file.relative_to(scan_root))
+            except ValueError:
+                rel = str(v.file)
+            output.append(
+                {
+                    "rule": v.rule_id,
+                    "severity": v.severity,
+                    "file": rel,
+                    "line": v.line,
+                    "message": v.message,
+                }
+            )
+            if v.severity == "error":
+                errors += 1
+            else:
+                warnings += 1
+
+    console.print(json.dumps(output, indent=2))
+    if errors > 0 or (strict and warnings > 0):
+        raise typer.Exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Entrypoint
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()