agent-rules-lint 0.1.1__py3-none-any.whl

agent_rules_lint/__init__.py

@@ -0,0 +1,3 @@
+"""Lint AI agent instruction files."""
+
+__version__ = "0.1.1"

agent_rules_lint/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_rules_lint/cli.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+
+from . import __version__
+from .linter import LintResult, lint_path
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agent-rules-lint",
+        description="Lint AI agent instruction files such as AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions.",
+    )
+    parser.add_argument("path", nargs="?", default=".", help="Repository or directory to scan.")
+    parser.add_argument("--format", choices=("text", "json"), default="text", help="Output format.")
+    parser.add_argument("--max-chars", type=int, default=12000, help="Warn when a file exceeds this many characters.")
+    parser.add_argument("--warnings-as-errors", action="store_true", help="Exit non-zero when warnings are found.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def render_text(result: LintResult) -> str:
+    lines = [
+        f"agent-rules-lint checked {len(result.files_checked)} file(s)",
+        f"errors={result.error_count} warnings={result.warning_count} info={result.info_count}",
+    ]
+    if result.files_checked:
+        lines.append("")
+        lines.append("Files:")
+        for file in result.files_checked:
+            lines.append(f"  - {file}")
+
+    if result.findings:
+        lines.append("")
+        lines.append("Findings:")
+        for finding in result.findings:
+            location = finding.file
+            if finding.line is not None:
+                location = f"{location}:{finding.line}"
+            lines.append(f"  [{finding.severity}] {location} {finding.rule}: {finding.message}")
+    else:
+        lines.append("")
+        lines.append("No findings.")
+
+    return "\n".join(lines)
+
+
+def exit_code(result: LintResult, warnings_as_errors: bool) -> int:
+    if result.error_count:
+        return 1
+    if warnings_as_errors and result.warning_count:
+        return 1
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    result = lint_path(Path(args.path), max_chars=args.max_chars)
+
+    if args.format == "json":
+        print(result.to_json())
+    else:
+        print(render_text(result))
+
+    return exit_code(result, warnings_as_errors=args.warnings_as_errors)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

agent_rules_lint/linter.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+import fnmatch
+import json
+import re
+from typing import Iterable
+
+
+DEFAULT_PATTERNS = (
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    ".cursorrules",
+    ".cursor/rules/*.md",
+    ".github/copilot-instructions.md",
+    ".github/instructions/*.md",
+)
+
+DEFAULT_IGNORE_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "venv",
+    "node_modules",
+    "__pycache__",
+    "dist",
+    "build",
+}
+
+SECRET_PATTERNS = (
+    re.compile(r"\bghp_[A-Za-z0-9_]{20,}\b"),
+    re.compile(r"\bgho_[A-Za-z0-9_]{20,}\b"),
+    re.compile(r"\bgithub_pat_[A-Za-z0-9_]{20,}\b"),
+    re.compile(r"\bsk-[A-Za-z0-9_-]{20,}\b"),
+    re.compile(r"\bAKIA[0-9A-Z]{16}\b"),
+    re.compile(r"-----BEGIN (RSA |OPENSSH |EC |DSA )?PRIVATE KEY-----"),
+)
+
+RISKY_COMMAND_PATTERNS = (
+    re.compile(r"\brm\s+-rf\s+[/~$*]", re.IGNORECASE),
+    re.compile(r"\bgit\s+reset\s+--hard\b", re.IGNORECASE),
+    re.compile(r"\bgit\s+clean\s+-fdx\b", re.IGNORECASE),
+    re.compile(r"\bRemove-Item\b.+\b-Recurse\b.+\b-Force\b", re.IGNORECASE),
+    re.compile(r"\bcurl\b.+\|\s*(bash|sh)\b", re.IGNORECASE),
+    re.compile(r"\bwget\b.+\|\s*(bash|sh)\b", re.IGNORECASE),
+)
+
+PROMPT_INJECTION_PATTERNS = (
+    re.compile(r"ignore (all )?(previous|prior|above) instructions", re.IGNORECASE),
+    re.compile(r"reveal (the )?(system|developer) (prompt|message)", re.IGNORECASE),
+    re.compile(r"bypass (safety|policy|guardrails)", re.IGNORECASE),
+)
+
+SECTION_HINTS = {
+    "purpose": ("purpose", "goal", "objective", "what this does", "overview", "目标", "目的"),
+    "scope": ("scope", "when to use", "applies to", "boundaries", "范围", "适用"),
+    "commands": ("commands", "scripts", "verification", "tests", "test", "build", "命令", "验证", "测试"),
+    "safety": ("safety", "security", "secrets", "do not", "never", "安全", "密钥", "不要"),
+    "style": ("style", "formatting", "conventions", "tone", "风格", "格式", "约定"),
+}
+
+
+@dataclass(frozen=True)
+class Finding:
+    file: str
+    severity: str
+    rule: str
+    message: str
+    line: int | None = None
+
+    def to_dict(self) -> dict:
+        data = {
+            "file": self.file,
+            "severity": self.severity,
+            "rule": self.rule,
+            "message": self.message,
+        }
+        if self.line is not None:
+            data["line"] = self.line
+        return data
+
+
+@dataclass
+class LintResult:
+    root: str
+    files_checked: list[str] = field(default_factory=list)
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def error_count(self) -> int:
+        return sum(1 for finding in self.findings if finding.severity == "error")
+
+    @property
+    def warning_count(self) -> int:
+        return sum(1 for finding in self.findings if finding.severity == "warning")
+
+    @property
+    def info_count(self) -> int:
+        return sum(1 for finding in self.findings if finding.severity == "info")
+
+    def to_dict(self) -> dict:
+        return {
+            "root": self.root,
+            "files_checked": self.files_checked,
+            "summary": {
+                "errors": self.error_count,
+                "warnings": self.warning_count,
+                "info": self.info_count,
+            },
+            "findings": [finding.to_dict() for finding in self.findings],
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=2)
+
+
+def discover_instruction_files(root: Path, patterns: Iterable[str] = DEFAULT_PATTERNS) -> list[Path]:
+    root = root.resolve()
+    matches: list[Path] = []
+    normalized_patterns = tuple(pattern.replace("\\", "/") for pattern in patterns)
+
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        if any(part in DEFAULT_IGNORE_DIRS for part in path.relative_to(root).parts):
+            continue
+        relative = path.relative_to(root).as_posix()
+        if any(fnmatch.fnmatch(relative, pattern) for pattern in normalized_patterns):
+            matches.append(path)
+
+    return sorted(matches, key=lambda item: item.relative_to(root).as_posix())
+
+
+def lint_path(root: Path, max_chars: int = 12000) -> LintResult:
+    root = root.resolve()
+    result = LintResult(root=str(root))
+    files = discover_instruction_files(root)
+
+    if not files:
+        result.findings.append(
+            Finding(
+                file=".",
+                severity="warning",
+                rule="no-instruction-files",
+                message="No known agent instruction files found.",
+            )
+        )
+        return result
+
+    for path in files:
+        relative = path.relative_to(root).as_posix()
+        result.files_checked.append(relative)
+        result.findings.extend(lint_file(path, root, max_chars=max_chars))
+
+    return result
+
+
+def lint_file(path: Path, root: Path, max_chars: int = 12000) -> list[Finding]:
+    relative = path.relative_to(root).as_posix()
+    text = path.read_text(encoding="utf-8", errors="replace")
+    lines = text.splitlines()
+    findings: list[Finding] = []
+
+    if not text.strip():
+        findings.append(Finding(relative, "error", "empty-file", "Instruction file is empty."))
+        return findings
+
+    if len(text) > max_chars:
+        findings.append(
+            Finding(
+                relative,
+                "warning",
+                "too-long",
+                f"Instruction file is {len(text)} characters; consider splitting or tightening it.",
+            )
+        )
+
+    if not re.search(r"^#\s+\S+", text, flags=re.MULTILINE):
+        findings.append(Finding(relative, "warning", "missing-title", "Add a top-level heading."))
+
+    present_sections = detect_sections(text)
+    for section in ("purpose", "scope", "commands", "safety"):
+        if section not in present_sections:
+            findings.append(
+                Finding(
+                    relative,
+                    "info",
+                    f"missing-{section}",
+                    f"Consider adding a clear {section} section.",
+                )
+            )
+
+    findings.extend(scan_patterns(relative, lines, SECRET_PATTERNS, "error", "secret-like-value", "Looks like a secret or private key."))
+    findings.extend(scan_patterns(relative, lines, RISKY_COMMAND_PATTERNS, "warning", "risky-command", "Risky command should include explicit safeguards or approval rules."))
+    findings.extend(scan_patterns(relative, lines, PROMPT_INJECTION_PATTERNS, "warning", "prompt-injection", "Instruction resembles prompt-injection language."))
+    findings.extend(scan_weak_language(relative, lines))
+    findings.extend(scan_absolute_claims(relative, lines))
+    findings.extend(scan_conflicts(relative, lines))
+
+    return findings
+
+
+def detect_sections(text: str) -> set[str]:
+    lowered = text.lower()
+    present: set[str] = set()
+    for section, hints in SECTION_HINTS.items():
+        if any(hint in lowered for hint in hints):
+            present.add(section)
+    return present
+
+
+def scan_patterns(
+    relative: str,
+    lines: list[str],
+    patterns: Iterable[re.Pattern[str]],
+    severity: str,
+    rule: str,
+    message: str,
+) -> list[Finding]:
+    findings: list[Finding] = []
+    for line_number, line in enumerate(lines, start=1):
+        if any(pattern.search(line) for pattern in patterns):
+            findings.append(Finding(relative, severity, rule, message, line_number))
+    return findings
+
+
+def scan_weak_language(relative: str, lines: list[str]) -> list[Finding]:
+    findings: list[Finding] = []
+    pattern = re.compile(r"\b(try to|maybe|if possible|do your best|尽量|可能的话)\b", re.IGNORECASE)
+    for line_number, line in enumerate(lines, start=1):
+        if pattern.search(line):
+            findings.append(
+                Finding(
+                    relative,
+                    "info",
+                    "weak-language",
+                    "Vague language can make agent behavior inconsistent.",
+                    line_number,
+                )
+            )
+    return findings
+
+
+def scan_absolute_claims(relative: str, lines: list[str]) -> list[Finding]:
+    findings: list[Finding] = []
+    pattern = re.compile(r"\b(always|never|must|禁止|必须|永远|绝不)\b", re.IGNORECASE)
+    for line_number, line in enumerate(lines, start=1):
+        if pattern.search(line) and len(line) > 180:
+            findings.append(
+                Finding(
+                    relative,
+                    "info",
+                    "long-absolute-rule",
+                    "Long absolute rules are hard to follow; split into short, testable bullets.",
+                    line_number,
+                )
+            )
+    return findings
+
+
+def scan_conflicts(relative: str, lines: list[str]) -> list[Finding]:
+    text = "\n".join(lines).lower()
+    findings: list[Finding] = []
+    conflict_pairs = (
+        ("always ask", "never ask"),
+        ("always commit", "never commit"),
+        ("always browse", "never browse"),
+        ("must use python", "never use python"),
+        ("必须询问", "不要询问"),
+    )
+    for left, right in conflict_pairs:
+        if left in text and right in text:
+            findings.append(
+                Finding(
+                    relative,
+                    "warning",
+                    "possible-conflict",
+                    f"Possible conflicting instructions: '{left}' and '{right}'.",
+                )
+            )
+    return findings

agent_rules_lint-0.1.1.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: agent-rules-lint
+Version: 0.1.1
+Summary: Lint AI agent instruction files such as AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions.
+Project-URL: Homepage, https://github.com/Uky0Yang/agent-rules-lint
+Project-URL: Repository, https://github.com/Uky0Yang/agent-rules-lint
+Project-URL: Issues, https://github.com/Uky0Yang/agent-rules-lint/issues
+Project-URL: Changelog, https://github.com/Uky0Yang/agent-rules-lint/blob/main/CHANGELOG.md
+Author: Ukyo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,copilot,cursor,developer-tools,lint,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# agent-rules-lint
+
+[![PyPI](https://img.shields.io/pypi/v/agent-rules-lint)](https://pypi.org/project/agent-rules-lint/)
+[![Python](https://img.shields.io/pypi/pyversions/agent-rules-lint)](https://pypi.org/project/agent-rules-lint/)
+[![CI](https://github.com/Uky0Yang/agent-rules-lint/actions/workflows/ci.yml/badge.svg)](https://github.com/Uky0Yang/agent-rules-lint/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Lint AI agent instruction files before they confuse your coding agent.
+
+`agent-rules-lint` is a small, dependency-free Python CLI that scans files such as `AGENTS.md`, `CLAUDE.md`, Cursor rules, and GitHub Copilot instructions for common quality and safety problems.
+
+## Why
+
+Recent high-growth developer repos show a clear pattern: teams are adding more agent skills, rule files, memory files, and coding-agent playbooks. The missing piece is a quick quality gate for those instructions.
+
+Bad agent instructions are expensive. They can be too long, vague, contradictory, unsafe, or accidentally include secrets. This tool gives you a fast local and CI check before those rules affect real work.
+
+## What It Checks
+
+- Common instruction files:
+  - `AGENTS.md`
+  - `CLAUDE.md`
+  - `GEMINI.md`
+  - `.cursorrules`
+  - `.cursor/rules/*.md`
+  - `.github/copilot-instructions.md`
+  - `.github/instructions/*.md`
+- Secret-like values
+- Risky shell and Git commands
+- Prompt-injection-like language
+- Missing title
+- Missing purpose, scope, command, or safety guidance
+- Vague language
+- Files that are too long for practical agent use
+- A small set of obvious contradictory rules
+
+## Install
+
+Run it without installing:
+
+```bash
+uvx agent-rules-lint .
+```
+
+Or install it as an isolated CLI:
+
+```bash
+pipx install agent-rules-lint
+agent-rules-lint .
+```
+
+Standard pip installation also works:
+
+```bash
+python -m pip install agent-rules-lint
+```
+
+For local development:
+
+```bash
+python -m pip install -e .
+```
+
+## Usage
+
+Scan the current repository:
+
+```bash
+agent-rules-lint .
+```
+
+Return JSON for CI or custom reports:
+
+```bash
+agent-rules-lint . --format json
+```
+
+Fail CI on warnings:
+
+```bash
+agent-rules-lint . --warnings-as-errors
+```
+
+Change the long-file threshold:
+
+```bash
+agent-rules-lint . --max-chars 8000
+```
+
+## Example Output
+
+```text
+agent-rules-lint checked 1 file(s)
+errors=0 warnings=1 info=2
+
+Files:
+  - AGENTS.md
+
+Findings:
+  [warning] AGENTS.md:42 risky-command: Risky command should include explicit safeguards or approval rules.
+  [info] AGENTS.md missing-safety: Consider adding a clear safety section.
+```
+
+## CI
+
+Add this to GitHub Actions:
+
+```yaml
+name: Lint agent rules
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  lint-agent-rules:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.0
+      - uses: actions/setup-python@v6.3.0
+        with:
+          python-version: "3.12"
+      - run: pipx run agent-rules-lint . --warnings-as-errors
+```
+
+## Design Principles
+
+- No model calls
+- No network calls
+- No dependencies
+- Safe to run in CI
+- Findings should be specific enough to act on
+- Warnings should improve instruction quality, not enforce one writing style
+
+## Current Limitations
+
+- Conflict detection is intentionally conservative and only catches obvious pairs.
+- It does not estimate real tokenizer counts; it uses character length as a practical proxy.
+- It does not validate whether an instruction is correct for a specific tool.
+
+## Development
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m agent_rules_lint .
+```
+
+## Agent OSS Toolkit
+
+This project is part of a small toolkit for building and launching agent-ready open-source repositories:
+
+- [agent-repo-kit](https://github.com/Uky0Yang/agent-repo-kit): scaffold launch-ready, AI-agent-friendly repositories
+- [oss-launch-check](https://github.com/Uky0Yang/oss-launch-check): audit whether a repository is ready to launch as open source
+- [repo-context-card](https://github.com/Uky0Yang/repo-context-card): generate compact repository context cards for coding agents
+- [agent-rules-lint](https://github.com/Uky0Yang/agent-rules-lint): lint AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions
+- [awesome-ai-agents-zh](https://github.com/Uky0Yang/awesome-ai-agents-zh): Chinese AI Agents / MCP / AI DevTools directory
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

agent_rules_lint-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+agent_rules_lint/__init__.py,sha256=l5U8ogAsFaBaSMZ5cXevA-NplExp0w6FiD7ViaYuu28,62
+agent_rules_lint/__main__.py,sha256=PSQ4rpL0dG6f-qH4N7H-gD9igQkdHzH4yVZDcW8lfZo,80
+agent_rules_lint/cli.py,sha256=p2gYnrDGDpzTMbbX3Ysb8_o3Pzehsx-yCsN7mswiy1c,2434
+agent_rules_lint/linter.py,sha256=jkHZCaikGIFjDvSk5a7wB8u1b_Hzyd0nJ2oF_8Ala28,9498
+agent_rules_lint-0.1.1.dist-info/METADATA,sha256=NS2php8QAFVxrIkjT0zQYaaOJ8giLs1FTvauaHjZ5ws,5688
+agent_rules_lint-0.1.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+agent_rules_lint-0.1.1.dist-info/entry_points.txt,sha256=Fsvlfc1uKJEcYfOWer795pEkNDzCG2jlMnaXUbbjs8M,63
+agent_rules_lint-0.1.1.dist-info/licenses/LICENSE,sha256=bz40dlj4pNYWq2XDJAm42nrzAgR8y2Yi5PCRzKDnzbw,1061
+agent_rules_lint-0.1.1.dist-info/RECORD,,

agent_rules_lint-0.1.1.dist-info/WHEEL

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

agent_rules_lint-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-rules-lint = agent_rules_lint.cli:main

agent_rules_lint-0.1.1.dist-info/licenses/LICENSE

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