docguard 0.1.1b4__py3-none-any.whl

docguard-0.1.1b4.dist-info/METADATA

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: docguard
+Version: 0.1.1b4
+Summary: Python companion CLI for bootstrapping the Node-based DocGuard tool in uv-managed projects.
+Author: mobasshir khan
+License: MIT
+License-File: LICENSE
+Keywords: docguard,documentation,git-hooks,pre-commit,uv
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# DocGuard
+
+> **Early beta — expect rough edges.** Documentation-aware pre-commit guard for AI-assisted development.
+
+DocGuard reads your project's markdown docs, looks at staged changes across any text-based language, and blocks commits that contradict the rules you've written down. It is not a linter. It enforces *your* project's documented intent.
+
+```
+BLOCK services/user_service.py:18  [architecture]
+  Direct database call from request handler
+  Cited: docs/architecture.md:23
+    "All database access must go through the repository layer"
+
+Summary: 1 error(s), 0 warning(s).
+Commit blocked. Bypass: git commit --no-verify  or  DOCGUARD_BYPASS=1 git commit
+```
+
+---
+
+## Install
+
+```bash
+npm install --save-dev @mobasshirkhan/docguard
+npx docguard init
+```
+
+For `uv`-managed Python projects, you can bootstrap from this repo through `uvx`:
+
+```bash
+uvx --from git+https://github.com/mobi2400/DocsGuard-.git docguard install
+```
+
+That Python helper installs the npm package in the current repo and then runs `docguard init`. Use `--package-manager` if you want `pnpm`, `yarn`, or `bun` instead of auto-detecting.
+
+`docguard init` will:
+
+- write `.docguard.json`
+- install a `pre-commit` hook (Husky-aware, falls back to `.git/hooks/`)
+- update `.gitignore`
+- pre-warm the local embedding model (~25 MB one-time download)
+
+You also need a Groq API key (free tier works). Three ways to set it:
+
+**`.env` file in your project root (easiest):**
+```
+GROQ_API_KEY=gsk_...
+```
+DocGuard reads `.env` from the repo root automatically. Existing shell env vars are not overridden.
+
+**Or shell session:**
+```bash
+export GROQ_API_KEY=gsk_...
+```
+
+**Or system-wide (Windows):**
+```powershell
+setx GROQ_API_KEY "gsk_..."
+```
+
+Get a key at [console.groq.com](https://console.groq.com). Without one, DocGuard skips semantic checks and lets commits through.
+
+## Requirements
+
+- Node `>= 18.17`
+- Disk: `@xenova/transformers` adds ~70 MB to `node_modules` (local embeddings, no per-commit API cost)
+
+## Usage
+
+The hook runs automatically on every `git commit`. To run manually:
+
+```bash
+docguard check
+```
+
+Bypass:
+
+```bash
+git commit --no-verify          # standard git escape hatch
+DOCGUARD_BYPASS=1 git commit    # explicit, logged to .docguard/bypass.log
+```
+
+Uninstall:
+
+```bash
+docguard uninstall              # removes hook + cache
+docguard uninstall --purge      # also removes .docguard.json
+```
+
+## Configuration
+
+`.docguard.json`:
+
+```json
+{
+  "docs": ["./docs/**/*.md"],
+  "ignore": [
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/__tests__/**",
+    "**/test/**",
+    "**/tests/**",
+    "**/__pycache__/**",
+    "**/.pytest_cache/**",
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**",
+    "**/vendor/**"
+  ],
+  "severity": {
+    "security":     "block",
+    "architecture": "warn",
+    "api-contract": "warn",
+    "naming":       "warn",
+    "style":        "warn"
+  },
+  "priority": {
+    "./docs/architecture.md": "critical"
+  },
+  "llm": {
+    "provider": "groq",
+    "model": "llama-3.3-70b-versatile"
+  },
+  "retrieval": {
+    "topK": 6,
+    "minScore": 0.15
+  },
+  "timeoutMs": 5000
+}
+```
+
+- **severity** — per-category, never per-named-rule. Categories are fixed: `security`, `architecture`, `api-contract`, `naming`, `style`.
+- **priority** — boost retrieval ranking for critical docs.
+- **timeoutMs** — hard cap on the semantic check. On timeout, commit is allowed.
+
+## How it works
+
+1. Reads staged hunks via `git diff --cached`.
+2. Splits configured markdown into ≤1500-char chunks by heading.
+3. Embeds chunks locally with MiniLM (`@xenova/transformers`), cached to `.docguard/cache/`.
+4. Ranks chunks against the diff by cosine + path overlap + priority.
+5. Sends only the top-relevant chunks plus the diff to Groq for judgment.
+6. Validates the response: every violation must cite a `chunk_id` with a quote that is a real substring of the chunk. Otherwise it's downgraded to a warning.
+
+DocGuard is language-agnostic at review time: if Git can stage it as text, DocGuard can compare that diff against your docs. The current package runtime is still Node-based, but the repository under review can be Python, Go, Java, Ruby, PHP, Rust, mixed-language monorepos, or anything similar.
+
+For Python and `uv` users, the companion bootstrap CLI supports:
+
+```bash
+uvx --from git+https://github.com/mobi2400/DocsGuard-.git docguard install
+uvx --from git+https://github.com/mobi2400/DocsGuard-.git docguard check
+uvx --from git+https://github.com/mobi2400/DocsGuard-.git docguard uninstall
+```
+
+## Trust guarantees
+
+- **No telemetry.** Nothing leaves your machine except the redacted diff + relevant doc chunks going to Groq for the semantic check.
+- **Citation-or-downgrade.** Every blocking violation must reference a real chunk and quote real text. Hallucinated citations are auto-downgraded to warn.
+- **DocGuard never blocks on its own bugs.** Internal errors fail open (commit proceeds, error logged).
+- **Bypass is local, visible, and logged.**
+
+## Project docs
+
+- [SPEC.md](SPEC.md) — locked v1 build spec
+- [docguard-v1-phases.md](docguard-v1-phases.md) — phased build plan
+- [docs/explainer.md](docs/explainer.md) — long-form intro
+
+## License
+
+MIT

docguard-0.1.1b4.dist-info/RECORD

@@ -0,0 +1,7 @@
+docguard_bootstrap/__init__.py,sha256=8jDPfyb6nGA6iu_nbGr7qXemQrFMYmQKo1Wc4u6Lo8w,51
+docguard_bootstrap/cli.py,sha256=B-czBR6cxo6THQv1oI_gww028iPRpocnzcRoktmM0bs,5338
+docguard-0.1.1b4.dist-info/METADATA,sha256=T6adRVKip_fjhdOW6PfwdVD4XDjwHsZBErx6Dlk8qxA,6103
+docguard-0.1.1b4.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+docguard-0.1.1b4.dist-info/entry_points.txt,sha256=ziUpRy-tWHwHp5rezxGVBGHGdclKobAj1bL3mf6KFAA,139
+docguard-0.1.1b4.dist-info/licenses/LICENSE,sha256=gCW-u3dos3QJR0zXEQTAt1jTZHda6hEmnVmr_Umeh4A,1071
+docguard-0.1.1b4.dist-info/RECORD,,

docguard-0.1.1b4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

docguard-0.1.1b4.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+dg = docguard_bootstrap.cli:main
+docguard = docguard_bootstrap.cli:main
+docguard-bootstrap = docguard_bootstrap.cli:main

docguard-0.1.1b4.dist-info/licenses/LICENSE

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

docguard_bootstrap/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.1b4"

docguard_bootstrap/cli.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+DOCGUARD_NPM_PACKAGE = "@mobasshirkhan/docguard"
+
+INSTALL_COMMANDS: dict[str, list[str]] = {
+    "npm": ["npm", "install", "--save-dev", DOCGUARD_NPM_PACKAGE],
+    "pnpm": ["pnpm", "add", "-D", DOCGUARD_NPM_PACKAGE],
+    "yarn": ["yarn", "add", "-D", DOCGUARD_NPM_PACKAGE],
+    "bun": ["bun", "add", "-d", DOCGUARD_NPM_PACKAGE],
+}
+
+EXEC_COMMANDS: dict[str, list[str]] = {
+    "npm": ["npx", "docguard"],
+    "pnpm": ["pnpm", "exec", "docguard"],
+    "yarn": ["yarn", "exec", "docguard"],
+    "bun": ["bunx", "docguard"],
+}
+
+PACKAGE_MANAGERS: tuple[str, ...] = ("npm", "pnpm", "yarn", "bun")
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="docguard",
+        description="Bootstrap DocGuard inside a Python or mixed-language repository.",
+    )
+    parser.add_argument(
+        "--cwd",
+        default=".",
+        help="Repository path to operate on. Defaults to the current working directory.",
+    )
+    parser.add_argument(
+        "--package-manager",
+        choices=("auto", *PACKAGE_MANAGERS),
+        default="auto",
+        help="JavaScript package manager to use for installing and running DocGuard.",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    install = subparsers.add_parser(
+        "install",
+        help="Install the npm package and optionally run `docguard init`.",
+    )
+    install.add_argument(
+        "--skip-init",
+        action="store_true",
+        help="Install DocGuard without running `docguard init`.",
+    )
+
+    subparsers.add_parser("init", help="Run `docguard init` through the selected package manager.")
+    subparsers.add_parser("check", help="Run `docguard check` through the selected package manager.")
+    uninstall = subparsers.add_parser(
+        "uninstall",
+        help="Run `docguard uninstall` through the selected package manager.",
+    )
+    uninstall.add_argument(
+        "--purge",
+        action="store_true",
+        help="Also remove `.docguard.json`.",
+    )
+
+    return parser.parse_args(argv)
+
+
+def fail(message: str) -> int:
+    sys.stderr.write(f"docguard: {message}\n")
+    return 1
+
+
+def detect_package_manager(choice: str) -> str:
+    if choice != "auto":
+        return choice
+
+    for manager in PACKAGE_MANAGERS:
+        if shutil.which(manager) is not None:
+            return manager
+
+    raise RuntimeError(
+        "No supported JavaScript package manager found. Install npm, pnpm, yarn, or bun first."
+    )
+
+
+def ensure_repo(path: Path) -> None:
+    if not (path / ".git").exists():
+        raise RuntimeError(f"{path} is not a Git repository. Run this inside your project root.")
+
+
+def ensure_binaries(package_manager: str) -> None:
+    missing: list[str] = []
+    if shutil.which("node") is None:
+        missing.append("node")
+    if shutil.which(package_manager) is None:
+        missing.append(package_manager)
+
+    if package_manager == "npm" and shutil.which("npx") is None:
+        missing.append("npx")
+    if package_manager == "bun" and shutil.which("bunx") is None:
+        missing.append("bunx")
+
+    if missing:
+        joined = ", ".join(missing)
+        raise RuntimeError(f"Missing required executable(s): {joined}.")
+
+
+def resolve_command(command: list[str]) -> list[str]:
+    executable = shutil.which(command[0])
+    if executable is None:
+        raise RuntimeError(f"Executable not found: {command[0]}")
+    return [executable, *command[1:]]
+
+
+def run(command: list[str], cwd: Path) -> None:
+    completed = subprocess.run(resolve_command(command), cwd=str(cwd), check=False)
+    if completed.returncode != 0:
+        rendered = " ".join(command)
+        raise RuntimeError(f"Command failed with exit code {completed.returncode}: {rendered}")
+
+
+def exec_docguard(package_manager: str, cwd: Path, *args: str) -> None:
+    base = EXEC_COMMANDS[package_manager]
+    run([*base, *args], cwd)
+
+
+def handle_install(package_manager: str, cwd: Path, skip_init: bool) -> int:
+    run(INSTALL_COMMANDS[package_manager], cwd)
+    if not skip_init:
+        exec_docguard(package_manager, cwd, "init")
+    return 0
+
+
+def handle_command(args: argparse.Namespace) -> int:
+    cwd = Path(args.cwd).resolve()
+    ensure_repo(cwd)
+    package_manager = detect_package_manager(args.package_manager)
+    ensure_binaries(package_manager)
+
+    if args.command == "install":
+        return handle_install(package_manager, cwd, args.skip_init)
+    if args.command == "init":
+        exec_docguard(package_manager, cwd, "init")
+        return 0
+    if args.command == "check":
+        exec_docguard(package_manager, cwd, "check")
+        return 0
+    if args.command == "uninstall":
+        uninstall_args = ["uninstall"]
+        if args.purge:
+            uninstall_args.append("--purge")
+        exec_docguard(package_manager, cwd, *uninstall_args)
+        return 0
+    return fail(f"Unsupported command: {args.command}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        return handle_command(args)
+    except RuntimeError as err:
+        return fail(str(err))
+    except KeyboardInterrupt:
+        return fail("Interrupted.")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())