harness-lint 0.1.0__tar.gz

harness_lint-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: harness-lint
+Version: 0.1.0
+Summary: PBH生态的第一个果实工具 — AI生成代码缺陷静态检查器
+Author-email: renjianguojinqianfan <18108097611@163.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# harness-lint
+
+> PBH 生态的第一个果实工具 — 专门检测 AI 生成代码中典型坏习惯的静态检查器。
+
+## 快速开始
+
+```bash
+pip install -e ".[dev]"
+make verify
+```
+
+## 开发命令
+
+| 命令 | 说明 |
+|------|------|
+| `make verify` | lint + 测试 + 覆盖率 |
+| `make test` | 运行测试 |
+| `make lint` | 代码风格检查 |
+| `make fix` | 自动修复风格问题 |
+
+## 项目结构
+
+```
+harness-lint/
+├── src/harness_lint/   # 主代码
+├── tests/                # 测试
+├── tasks/                # 任务拆解
+├── docs/                 # 文档
+├── AGENTS.md             # AI 协作协议
+├── Makefile
+└── pyproject.toml
+```
+
+## AI 协作
+
+本项目遵循 PBH 协议。AI 助手请阅读 `AGENTS.md` 了解项目规则和工作准则。
+
+## 许可证
+
+MIT

harness_lint-0.1.0/README.md

@@ -0,0 +1,40 @@
+# harness-lint
+
+> PBH 生态的第一个果实工具 — 专门检测 AI 生成代码中典型坏习惯的静态检查器。
+
+## 快速开始
+
+```bash
+pip install -e ".[dev]"
+make verify
+```
+
+## 开发命令
+
+| 命令 | 说明 |
+|------|------|
+| `make verify` | lint + 测试 + 覆盖率 |
+| `make test` | 运行测试 |
+| `make lint` | 代码风格检查 |
+| `make fix` | 自动修复风格问题 |
+
+## 项目结构
+
+```
+harness-lint/
+├── src/harness_lint/   # 主代码
+├── tests/                # 测试
+├── tasks/                # 任务拆解
+├── docs/                 # 文档
+├── AGENTS.md             # AI 协作协议
+├── Makefile
+└── pyproject.toml
+```
+
+## AI 协作
+
+本项目遵循 PBH 协议。AI 助手请阅读 `AGENTS.md` 了解项目规则和工作准则。
+
+## 许可证
+
+MIT

harness_lint-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "harness-lint"
+version = "0.1.0"
+description = "PBH生态的第一个果实工具 — AI生成代码缺陷静态检查器"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    {name = "renjianguojinqianfan", email = "18108097611@163.com"},
+]
+dependencies = [
+    "typer>=0.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+]
+
+[project.scripts]
+"harness-lint" = "harness_lint.cli:cli"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-v --cov=src --cov-fail-under=85"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+exclude = [".harness/", "configs/", "tests/fixtures/"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "C4", "SIM"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

harness_lint-0.1.0/setup.cfg

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

harness_lint-0.1.0/src/harness_lint/__init__.py

@@ -0,0 +1,3 @@
+"""harness_lint package."""
+
+__version__ = "0.1.0"

harness_lint-0.1.0/src/harness_lint/accumulator.py

@@ -0,0 +1,142 @@
+"""Deviation cost accumulation mechanism for Harness-Lint.
+
+Provides pattern-based cost escalation: repeated violations of the same
+rule trigger elevated warnings and, in the evaluate phase, severity
+upgrades to Error.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+
+from harness_lint.rules.base import Rule, Violation
+
+
+@dataclass(frozen=True)
+class PatternWarning:
+    """A pattern-level warning for repeated rule violations.
+
+    Attributes:
+        rule_id: The identifier of the rule that was repeatedly violated.
+        count: Total number of occurrences for this rule.
+        suggestion: Human-readable guidance referencing AGENTS.md.
+        description: Human-readable rule name (from Rule.name).
+    """
+
+    rule_id: str
+    count: int
+    suggestion: str
+    description: str = ""
+
+
+def _count_violations(violations: list[Violation]) -> dict[str, int]:
+    """Count violations per rule_id."""
+    counts: dict[str, int] = defaultdict(int)
+    for v in violations:
+        counts[v.rule_id] += 1
+    return counts
+
+
+def _collect_first_refs(
+    violations: list[Violation],
+    elevated_rule_ids: set[str],
+) -> dict[str, str]:
+    """Collect first agente_ref per elevated rule."""
+    first_refs: dict[str, str] = {}
+    for v in violations:
+        if v.rule_id in elevated_rule_ids and v.rule_id not in first_refs:
+            first_refs[v.rule_id] = v.agente_ref
+    return first_refs
+
+
+def _build_pattern_warnings(
+    counts: dict[str, int],
+    elevated_rule_ids: set[str],
+    first_refs: dict[str, str],
+    rule_map: dict[str, Rule],
+) -> list[PatternWarning]:
+    """Build pattern warnings for elevated rules."""
+    return [
+        PatternWarning(
+            rule_id=rid,
+            count=counts[rid],
+            suggestion=f"建议在 {first_refs[rid]} 中明确相关规范",
+            description=rule_map[rid].name if rid in rule_map else rid,
+        )
+        for rid in sorted(elevated_rule_ids)
+    ]
+
+
+def _process_violations(
+    violations: list[Violation],
+    elevated_rule_ids: set[str],
+    counts: dict[str, int],
+    phase: str | None,
+) -> list[Violation]:
+    """Update severity/phenomenon for elevated rules."""
+    processed: list[Violation] = []
+    for v in violations:
+        if v.rule_id in elevated_rule_ids:
+            new_severity = "Error" if phase == "evaluate" else v.severity
+            new_phenomenon = f"该冲突已持续出现 {counts[v.rule_id]} 次，尚未解决"
+            processed.append(
+                Violation(
+                    file=v.file,
+                    line=v.line,
+                    column=v.column,
+                    rule_id=v.rule_id,
+                    severity=new_severity,
+                    phenomenon=new_phenomenon,
+                    attribution=v.attribution,
+                    agente_ref=v.agente_ref,
+                )
+            )
+        else:
+            processed.append(v)
+    return processed
+
+
+def apply_accumulation(
+    violations: list[Violation],
+    phase: str | None,
+    rules: list[Rule] | None = None,
+    threshold: int = 3,
+) -> tuple[list[Violation], list[PatternWarning]]:
+    """Apply cost accumulation to violations.
+
+    Counts violations per *rule_id*. For rules whose count meets or
+    exceeds *threshold*:
+
+    - *phase* == ``"evaluate"``: upgrade severity to ``"Error"``
+    - Otherwise: keep severity but update phenomenon
+    - In both cases: generate a :class:`PatternWarning`
+
+    Args:
+        violations: Raw violations collected by the checker.
+        phase: Current PBH phase (``"execute"``, ``"evaluate"``, or None).
+        rules: Optional list of rules to look up rule names for descriptions.
+        threshold: Minimum count before escalation (default 3).
+
+    Returns:
+        Tuple of (processed_violations, pattern_warnings).
+    """
+    if not violations:
+        return [], []
+
+    rule_map: dict[str, Rule] = {}
+    if rules:
+        for r in rules:
+            rule_map[r.rule_id] = r
+
+    counts = _count_violations(violations)
+    elevated_rule_ids = {rid for rid, cnt in counts.items() if cnt >= threshold}
+    first_refs = _collect_first_refs(violations, elevated_rule_ids)
+    pattern_warnings = _build_pattern_warnings(
+        counts, elevated_rule_ids, first_refs, rule_map
+    )
+    processed = _process_violations(
+        violations, elevated_rule_ids, counts, phase
+    )
+
+    return processed, pattern_warnings

harness_lint-0.1.0/src/harness_lint/attribution.py

@@ -0,0 +1,66 @@
+"""Attribution validation for Harness-Lint rules and violations.
+
+Provides utilities to verify that every rule and every violation carries
+a complete attribution chain pointing back to AGENTS.md.
+"""
+
+from __future__ import annotations
+
+from harness_lint.rules.base import Rule, Violation
+
+
+def validate_rule_attribution(rule: Rule) -> list[str]:
+    """Validate a rule's attribution chain.
+
+    Args:
+        rule: The rule to validate.
+
+    Returns:
+        A list of error messages. An empty list means the rule passes
+        validation.
+    """
+    errors: list[str] = []
+    if not rule.agente_ref:
+        errors.append(f"{rule.rule_id}: agente_ref is empty")
+    if not rule.attribution:
+        errors.append(f"{rule.rule_id}: attribution is empty")
+    if rule.agente_ref and not rule.agente_ref.startswith("AGENTS.md"):
+        errors.append(f"{rule.rule_id}: agente_ref must start with 'AGENTS.md'")
+    return errors
+
+
+def validate_violation(violation: Violation) -> list[str]:
+    """Validate a violation's full attribution chain.
+
+    Args:
+        violation: The violation to validate.
+
+    Returns:
+        A list of error messages. An empty list means the violation passes
+        validation.
+    """
+    errors: list[str] = []
+    if not violation.phenomenon:
+        errors.append("phenomenon is empty")
+    if not violation.attribution:
+        errors.append("attribution is empty")
+    if not violation.agente_ref:
+        errors.append("agente_ref is empty")
+    if violation.agente_ref and not violation.agente_ref.startswith("AGENTS.md"):
+        errors.append("agente_ref must start with 'AGENTS.md'")
+    return errors
+
+
+def validate_ruleset(rules: list[Rule]) -> list[str]:
+    """Validate all rules in a ruleset.
+
+    Args:
+        rules: List of rules to validate.
+
+    Returns:
+        Aggregated error messages from all rules.
+    """
+    all_errors: list[str] = []
+    for rule in rules:
+        all_errors.extend(validate_rule_attribution(rule))
+    return all_errors

harness_lint-0.1.0/src/harness_lint/checker.py

@@ -0,0 +1,126 @@
+"""Checker engine: file traversal, AST parsing, and rule execution."""
+
+from __future__ import annotations
+
+import ast
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from harness_lint.accumulator import apply_accumulation
+
+if TYPE_CHECKING:
+    from harness_lint.accumulator import PatternWarning
+    from harness_lint.rules.base import Rule, Violation
+
+_DEFAULT_IGNORE_DIRS = {
+    ".git",
+    "__pycache__",
+    ".venv",
+    ".mypy_cache",
+    ".pytest_cache",
+}
+
+
+class Context:
+    """Simplified context object for phase-aware rule activation."""
+
+    def __init__(
+        self,
+        phase: str | None = None,
+        harness_version: str | None = None,
+        hint: str = "",
+    ) -> None:
+        """Initialize context with optional phase.
+
+        Args:
+            phase: The current PBH phase ("plan", "execute", "evaluate", "done", or None).
+            harness_version: The harness version from progress.json, if present.
+            hint: Human-readable hint based on the current phase.
+        """
+        self.phase = phase
+        self.harness_version = harness_version
+        self.hint = hint
+
+
+def collect_files(path: str) -> list[str]:
+    """Recursively collect Python files, applying default ignore patterns.
+
+    Args:
+        path: Root directory to scan.
+
+    Returns:
+        Sorted list of absolute file paths for all ``.py`` files found
+        under *path*, excluding files inside default ignored directories.
+    """
+    result: list[str] = []
+    root = Path(path)
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [
+            d for d in dirnames if d not in _DEFAULT_IGNORE_DIRS
+        ]
+        for filename in filenames:
+            if filename.endswith(".py"):
+                result.append(str(Path(dirpath) / filename))
+
+    return sorted(result)
+
+
+def _is_rule_active(rule: Rule, phase: str | None) -> bool:
+    """Determine whether a rule is active for the given phase.
+
+    Args:
+        rule: The rule to evaluate.
+        phase: Current phase ("execute", "evaluate", or None).
+
+    Returns:
+        True if the rule should be executed for the given phase.
+    """
+    if phase is None:
+        return True
+    return phase in rule.phases
+
+
+def check(
+    path: str, context: Context, rules: list[Rule]
+) -> tuple[list[Violation], list[PatternWarning]]:
+    """Check all Python files in *path* against activated rules.
+
+    Args:
+        path: Root directory to scan.
+        context: Phase-aware context controlling rule activation.
+        rules: List of rules to (potentially) apply.
+
+    Returns:
+        Tuple of (sorted violations, pattern warnings). Violations are
+        sorted by file path. Pattern warnings are generated for rules
+        whose violation count meets or exceeds the escalation threshold.
+        Invalid Python syntax is silently skipped rather than raising.
+    """
+    files = collect_files(path)
+    active_rules = [r for r in rules if _is_rule_active(r, context.phase)]
+    all_violations: list[Violation] = []
+
+    for file_path in files:
+        try:
+            with open(file_path, encoding="utf-8") as f:
+                content = f.read()
+        except OSError:
+            continue
+
+        try:
+            tree = ast.parse(content)
+        except SyntaxError:
+            continue
+
+        for rule in active_rules:
+            violations = rule.check(file_path, content, tree)
+            if violations:
+                all_violations.extend(violations)
+
+    sorted_violations = sorted(all_violations, key=lambda v: v.file)
+    processed_violations, pattern_warnings = apply_accumulation(
+        sorted_violations, phase=context.phase, rules=active_rules
+    )
+    return processed_violations, pattern_warnings

harness_lint-0.1.0/src/harness_lint/cli.py

@@ -0,0 +1,130 @@
+"""CLI entry point for Harness-Lint."""
+
+from __future__ import annotations
+
+import typer
+
+from harness_lint.accumulator import PatternWarning
+from harness_lint.checker import check, collect_files
+from harness_lint.degradation import format_degradation_notice, is_harness_lint_enabled
+from harness_lint.pbh_adapter import get_context
+from harness_lint.reporter import format_json, format_summary, format_terminal
+from harness_lint.rules import HL001EvalRule, HL201FunctionLengthRule
+from harness_lint.rules.base import Rule, Violation
+
+app = typer.Typer()
+
+
+def _get_default_rules() -> list[Rule]:
+    """Return the built-in rule instances."""
+    return [HL001EvalRule(), HL201FunctionLengthRule()]
+
+
+def _has_errors(violations: list[Violation]) -> bool:
+    """Check if any violation has Error severity."""
+    return any(v.severity == "Error" for v in violations)
+
+
+def _has_warnings(violations: list[Violation]) -> bool:
+    """Check if any violation has Warning severity."""
+    return any(v.severity == "Warning" for v in violations)
+
+
+def version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        typer.echo("harness-lint 0.1.0")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-v",
+        help="Show version and exit.",
+        is_eager=True,
+        callback=version_callback,
+    ),
+) -> None:
+    """Harness-Lint CLI."""
+
+
+def _handle_degradation() -> None:
+    """Check if harness-lint is enabled and exit early if not."""
+    if is_harness_lint_enabled():
+        return
+    notice = format_degradation_notice()
+    if notice:
+        typer.echo(notice)
+    else:
+        typer.echo("当前未启用 Harness-Lint")
+    raise typer.Exit(code=0)
+
+
+def _format_output(
+    violations: list[Violation],
+    files_checked: int,
+    pattern_warnings: list[PatternWarning],
+    fmt: str,
+    phase: str | None,
+) -> str:
+    """Format violations according to the requested output format."""
+    if fmt == "json":
+        return format_json(
+            violations, files_checked, pattern_warnings, phase=phase
+        )
+    if fmt == "summary":
+        return format_summary(
+            violations, files_checked, pattern_warnings, phase=phase
+        )
+    return format_terminal(
+        violations, files_checked, pattern_warnings, phase=phase
+    )
+
+
+def _determine_exit_code(violations: list[Violation], strict: bool) -> int:
+    """Return the exit code based on violations and strict mode."""
+    if _has_errors(violations):
+        return 1
+    if strict and _has_warnings(violations):
+        return 1
+    return 0
+
+
+@app.command()
+def run(
+    path: str = typer.Argument(".", help="Target directory to lint."),
+    fmt: str = typer.Option(
+        "terminal",
+        "--format",
+        help="Output format: terminal, json, summary.",
+    ),
+    strict: bool = typer.Option(
+        False,
+        "--strict",
+        help="Treat warnings as errors for exit code.",
+    ),
+) -> None:
+    """Run Harness-Lint against the given path."""
+    _handle_degradation()
+
+    context = get_context(path)
+    rules = _get_default_rules()
+    files = collect_files(path)
+    files_checked = len(files)
+
+    violations, pattern_warnings = check(path, context, rules)
+
+    output = _format_output(
+        violations, files_checked, pattern_warnings, fmt, context.phase
+    )
+    typer.echo(output)
+
+    raise typer.Exit(code=_determine_exit_code(violations, strict))
+
+
+def cli() -> None:
+    """Entry point for setuptools console script."""
+    app()