claude-dev-env 1.93.1 → 1.95.0

package/skills/log-audit/scripts/collect_log_window.py

@@ -1,199 +0,0 @@
-"""Read the recent window of the hook block log into structured records.
-
-Tails the JSON-lines hook block log every blocking hook appends to, and hands
-back the block events inside a time window as plain records. Picture the audit
-agent waking up: it asks this script for the last few hours of blocks, and gets
-one record per block carrying when it happened, which hook fired, and why. Those
-records feed cluster_recurrences, which groups them by a normalized signature.
-
-Usage:
-    collect_log_window.py --hours 24
-    collect_log_window.py --hours 6 --log-path /path/to/hook-blocks.log
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from collections.abc import Iterable
-from dataclasses import dataclass
-from datetime import datetime, timedelta
-from pathlib import Path
-
-_script_directory = str(Path(__file__).resolve().parent)
-if _script_directory not in sys.path:
-    sys.path.insert(0, _script_directory)
-
-from log_audit_constants.collect_log_window_constants import (  # noqa: E402
-    BLOCK_LEVEL_LABEL,
-    DEFAULT_WINDOW_HOURS,
-    HOOK_BLOCKS_LOG_RELATIVE_PATH,
-    LOG_HOOK_KEY,
-    LOG_REASON_KEY,
-    LOG_TIMESTAMP_KEY,
-    RECORD_LEVEL_KEY,
-    RECORD_MESSAGE_KEY,
-    RECORD_SOURCE_KEY,
-    RECORD_TIMESTAMP_KEY,
-)
-
-
-@dataclass(frozen=True)
-class LogRecord:
-    """One block event read from the hook block log.
-
-    Attributes:
-        timestamp: When the block happened, parsed from the record's ISO string.
-        source: The hook that blocked, taken from the record's hook field.
-        level: The severity label; every hook-block record reads as a block.
-        message: The human-readable block reason.
-    """
-
-    timestamp: datetime
-    source: str
-    level: str
-    message: str
-
-
-def parse_log_line(raw_line: str) -> LogRecord | None:
-    """Parse one hook-block-log line into a LogRecord.
-
-    Args:
-        raw_line: A single line of the JSON-lines hook block log.
-
-    Returns:
-        The parsed record, or None when the line is blank, is not a JSON object,
-        or omits the timestamp, hook, or reason field, or carries a timestamp
-        that does not parse as an ISO datetime.
-    """
-    stripped_line = raw_line.strip()
-    if not stripped_line:
-        return None
-    try:
-        record_fields = json.loads(stripped_line)
-    except json.JSONDecodeError:
-        return None
-    if not isinstance(record_fields, dict):
-        return None
-    timestamp_text = record_fields.get(LOG_TIMESTAMP_KEY)
-    source_text = record_fields.get(LOG_HOOK_KEY)
-    message_text = record_fields.get(LOG_REASON_KEY)
-    if not isinstance(timestamp_text, str):
-        return None
-    if not isinstance(source_text, str) or not isinstance(message_text, str):
-        return None
-    try:
-        parsed_timestamp = datetime.fromisoformat(timestamp_text)
-    except ValueError:
-        return None
-    return LogRecord(
-        timestamp=parsed_timestamp,
-        source=source_text,
-        level=BLOCK_LEVEL_LABEL,
-        message=message_text,
-    )
-
-
-def _records_within_window(
-    all_lines: Iterable[str], window_start: datetime
-) -> list[LogRecord]:
-    """Parse each line and keep the records at or after the window start.
-
-    Args:
-        all_lines: The hook-block-log lines to parse, in file order.
-        window_start: The earliest timestamp a kept record may carry.
-
-    Returns:
-        The in-window records in the order their lines appear.
-    """
-    kept_records: list[LogRecord] = []
-    for each_line in all_lines:
-        parsed_record = parse_log_line(each_line)
-        if parsed_record is None:
-            continue
-        if parsed_record.timestamp >= window_start:
-            kept_records.append(parsed_record)
-    return kept_records
-
-
-def collect_records(log_text: str, window_start: datetime) -> list[LogRecord]:
-    """Parse log text and keep records at or after the window start.
-
-    Args:
-        log_text: The full text of the hook block log.
-        window_start: The earliest timestamp a kept record may carry.
-
-    Returns:
-        The in-window records in the order they appear in the log.
-    """
-    return _records_within_window(log_text.splitlines(), window_start)
-
-
-def read_log_window(
-    log_path: Path, window_hours: int, now: datetime
-) -> list[LogRecord]:
-    """Read the hook block log and return records within the window.
-
-    Args:
-        log_path: Path to the JSON-lines hook block log.
-        window_hours: How many hours back from now to keep.
-        now: The current time the window is measured back from.
-
-    Returns:
-        The in-window records, or an empty list when the log file is absent.
-    """
-    window_start = now - timedelta(hours=window_hours)
-    try:
-        with log_path.open(encoding="utf-8") as log_file:
-            return _records_within_window(log_file, window_start)
-    except FileNotFoundError:
-        return []
-
-
-def _default_log_path() -> Path:
-    """Return the home-relative path of the hook block log."""
-    return Path.home() / HOOK_BLOCKS_LOG_RELATIVE_PATH
-
-
-def _record_as_json_dict(record: LogRecord) -> dict[str, str]:
-    """Render a record as a JSON-ready dict with an ISO timestamp string.
-
-    Args:
-        record: The record to render.
-
-    Returns:
-        A dict of string values keyed by the record's field names.
-    """
-    return {
-        RECORD_TIMESTAMP_KEY: record.timestamp.isoformat(),
-        RECORD_SOURCE_KEY: record.source,
-        RECORD_LEVEL_KEY: record.level,
-        RECORD_MESSAGE_KEY: record.message,
-    }
-
-
-def main() -> int:
-    """Print the recent hook-block records as JSON to stdout.
-
-    Returns:
-        The process exit code; zero on success.
-    """
-    parser = argparse.ArgumentParser(description="Tail the hook block log window.")
-    parser.add_argument("--hours", type=int, default=DEFAULT_WINDOW_HOURS)
-    parser.add_argument("--log-path", type=str, default=None)
-    parsed_arguments = parser.parse_args()
-    log_path = (
-        Path(parsed_arguments.log_path).expanduser().resolve()
-        if parsed_arguments.log_path is not None
-        else _default_log_path()
-    )
-    records = read_log_window(log_path, parsed_arguments.hours, datetime.now())
-    json.dump(
-        [_record_as_json_dict(each_record) for each_record in records], sys.stdout
-    )
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/skills/log-audit/scripts/log_audit_constants/CLAUDE.md

@@ -1,12 +0,0 @@
-# log-audit/scripts/log_audit_constants
-
-Named constants imported by the `log-audit` scripts. Each module holds the tunables for one script, keeping magic values out of the scripts.
-
-## Files
-
-| File | What it holds |
-|---|---|
-| `__init__.py` | Package marker. |
-| `collect_log_window_constants.py` | The hook-block-log path, default window, block level label, and the input and output record key names for `collect_log_window.py`. |
-| `cluster_recurrences_constants.py` | The signature-stripping regexes, recency decay, and timing-regression thresholds for `cluster_recurrences.py`. |
-| `mine_copilot_findings_constants.py` | The reviewer-bot logins, the recent-pulls and per-pull comments endpoint templates, the recent-pull count, and the defect-class keyword and proposal maps for `mine_copilot_findings.py`. |

package/skills/log-audit/scripts/log_audit_constants/cluster_recurrences_constants.py

@@ -1,23 +0,0 @@
-"""Constants for the cluster_recurrences script.
-
-PATH_PATTERN, HASH_PATTERN, DIGIT_PATTERN: regexes stripped from a message, in this
-    order, so records that differ only in a path, hash, or number share one signature.
-SIGNATURE_PLACEHOLDER: the token each stripped span collapses to.
-SECONDS_PER_HOUR: seconds in one hour, dividing a record's age into hours.
-RECENCY_DECAY_BASE: the weight a record carries once it is one half-life old.
-RECENCY_HALF_LIFE_HOURS: age in hours at which a record's weight reaches the decay base.
-TIMING_REGRESSION_RATIO: recent-over-baseline duration ratio that flags a regression.
-MIN_TIMING_SAMPLES_PER_HALF: samples required in the baseline half and the recent half.
-SAMPLE_HALVES: the number of halves a timing series splits into before it can be judged.
-"""
-
-PATH_PATTERN = r"(?:[A-Za-z]:)?(?:[\\/][\w.\-]+)+"
-HASH_PATTERN = r"\b[0-9a-f]{7,40}\b"
-DIGIT_PATTERN = r"\d+"
-SIGNATURE_PLACEHOLDER = "*"
-SECONDS_PER_HOUR = 3600
-RECENCY_DECAY_BASE = 0.5
-RECENCY_HALF_LIFE_HOURS = 24.0
-TIMING_REGRESSION_RATIO = 1.5
-MIN_TIMING_SAMPLES_PER_HALF = 3
-SAMPLE_HALVES = 2

package/skills/log-audit/scripts/log_audit_constants/collect_log_window_constants.py

@@ -1,24 +0,0 @@
-"""Constants for the collect_log_window script.
-
-HOOK_BLOCKS_LOG_RELATIVE_PATH: home-relative path of the JSON-lines hook block log.
-DEFAULT_WINDOW_HOURS: how many hours back a collection reads when no window is given.
-BLOCK_LEVEL_LABEL: the level stamped on every record read from the hook block log.
-LOG_TIMESTAMP_KEY: hook-block-log JSON key holding the ISO-8601 block time.
-LOG_HOOK_KEY: hook-block-log JSON key holding the blocking hook's name.
-LOG_REASON_KEY: hook-block-log JSON key holding the human-readable block reason.
-RECORD_TIMESTAMP_KEY: output-record key holding the ISO-8601 block time.
-RECORD_SOURCE_KEY: output-record key holding the blocking hook's name.
-RECORD_LEVEL_KEY: output-record key holding the severity label.
-RECORD_MESSAGE_KEY: output-record key holding the block reason.
-"""
-
-HOOK_BLOCKS_LOG_RELATIVE_PATH = ".claude/logs/hook-blocks.log"
-DEFAULT_WINDOW_HOURS = 24
-BLOCK_LEVEL_LABEL = "block"
-LOG_TIMESTAMP_KEY = "timestamp"
-LOG_HOOK_KEY = "hook"
-LOG_REASON_KEY = "reason"
-RECORD_TIMESTAMP_KEY = "timestamp"
-RECORD_SOURCE_KEY = "source"
-RECORD_LEVEL_KEY = "level"
-RECORD_MESSAGE_KEY = "message"

package/skills/log-audit/scripts/log_audit_constants/mine_copilot_findings_constants.py

@@ -1,49 +0,0 @@
-"""Constants for the mine_copilot_findings script.
-
-ALL_REVIEWER_BOT_LOGINS: the GitHub logins whose review comments count as defects.
-RECENT_PULLS_ENDPOINT_TEMPLATE: the gh api path for a repo's most recent pulls.
-PULL_COMMENTS_ENDPOINT_TEMPLATE: the gh api path for one pull request's comments.
-RECENT_PULL_COUNT: how many recent pull requests a mining run reads.
-MAX_EXAMPLES_PER_CLUSTER: example comment bodies kept per defect class.
-KEYWORDS_BY_DEFECT_CLASS: lowercased substrings that sort a comment into a defect class.
-PROPOSAL_BY_DEFECT_CLASS: the concrete skill-definition edit proposed for each class.
-"""
-
-ALL_REVIEWER_BOT_LOGINS = ("copilot-pull-request-reviewer[bot]", "cursor[bot]")
-RECENT_PULLS_ENDPOINT_TEMPLATE = (
-    "repos/{repo}/pulls?state=all&sort=updated&direction=desc&per_page={pull_count}"
-)
-PULL_COMMENTS_ENDPOINT_TEMPLATE = (
-    "repos/{repo}/pulls/{pull_number}/comments?per_page=100"
-)
-RECENT_PULL_COUNT = 20
-MAX_EXAMPLES_PER_CLUSTER = 3
-KEYWORDS_BY_DEFECT_CLASS = {
-    "missing-type-hint": ("type hint", "missing annotation", "untyped", "no return type"),
-    "broad-except": ("broad except", "bare except", "except exception", "catch-all except"),
-    "magic-value": ("magic number", "magic value", "hardcoded", "hard-coded"),
-    "unclear-name": ("abbreviation", "unclear name", "rename this", "single-letter"),
-    "missing-docstring": ("missing docstring", "no docstring", "undocumented"),
-}
-PROPOSAL_BY_DEFECT_CLASS = {
-    "missing-type-hint": (
-        "Tighten the code skill's type-hint rule to flag the untyped shape this "
-        "class keeps hitting."
-    ),
-    "broad-except": (
-        "Extend the no-broad-except enforcer pattern to the except shape this "
-        "class keeps hitting."
-    ),
-    "magic-value": (
-        "Extend the magic-value enforcer to the literal shape this class keeps "
-        "hitting."
-    ),
-    "unclear-name": (
-        "Add the abbreviation this class keeps flagging to the banned-identifier "
-        "list."
-    ),
-    "missing-docstring": (
-        "Tighten the public-docstring rule to the surface this class keeps "
-        "hitting."
-    ),
-}

package/skills/log-audit/scripts/mine_copilot_findings.py

@@ -1,302 +0,0 @@
-"""Turn the defects reviewers keep catching into upstream skill-edit proposals.
-
-Copilot and Bugbot flag the same kinds of defect over and over — an untyped
-return here, a broad except there. Each catch is a defect that reached review
-because nothing blocked it at write time. This script reads recent reviewer
-comments, sorts them into defect classes, and for each class names a concrete
-skill or rule edit that would block that class upstream. The proposals are for a
-human to apply through review, not for the agent to commit on its own.
-
-Usage:
-    mine_copilot_findings.py --repo owner/name
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import subprocess
-import sys
-from collections import defaultdict
-from dataclasses import dataclass
-from pathlib import Path
-
-_script_directory = str(Path(__file__).resolve().parent)
-if _script_directory not in sys.path:
-    sys.path.insert(0, _script_directory)
-
-from log_audit_constants.mine_copilot_findings_constants import (  # noqa: E402
-    ALL_REVIEWER_BOT_LOGINS,
-    KEYWORDS_BY_DEFECT_CLASS,
-    MAX_EXAMPLES_PER_CLUSTER,
-    PROPOSAL_BY_DEFECT_CLASS,
-    PULL_COMMENTS_ENDPOINT_TEMPLATE,
-    RECENT_PULL_COUNT,
-    RECENT_PULLS_ENDPOINT_TEMPLATE,
-)
-
-
-class GitHubCommandError(RuntimeError):
-    """Raised when a gh api call fails or returns output that is not JSON."""
-
-
-@dataclass(frozen=True)
-class ReviewerComment:
-    """One review comment left by a reviewer bot.
-
-    Attributes:
-        pull_number: The pull request the comment was left on.
-        author: The reviewer bot's login.
-        body: The comment text.
-    """
-
-    pull_number: int
-    author: str
-    body: str
-
-
-@dataclass(frozen=True)
-class DefectCluster:
-    """The reviewer comments that fall into one defect class.
-
-    Attributes:
-        defect_class: The class name the comments were sorted into.
-        count: How many comments fell into the class.
-        example_bodies: A capped sample of the comment bodies in the class.
-    """
-
-    defect_class: str
-    count: int
-    example_bodies: tuple[str, ...]
-
-
-@dataclass(frozen=True)
-class SkillProposal:
-    """A proposed skill-definition edit that blocks one defect class upstream.
-
-    Attributes:
-        defect_class: The defect class the edit would block.
-        proposal: The concrete edit to make.
-    """
-
-    defect_class: str
-    proposal: str
-
-
-def classify_defect(comment_body: str) -> str | None:
-    """Sort a review comment into a defect class by its keywords.
-
-    Args:
-        comment_body: The review comment text.
-
-    Returns:
-        The first defect class whose keywords appear in the comment, or None
-        when no class matches.
-    """
-    lowered_body = comment_body.lower()
-    for each_defect_class, each_keywords in KEYWORDS_BY_DEFECT_CLASS.items():
-        if any(each_keyword in lowered_body for each_keyword in each_keywords):
-            return each_defect_class
-    return None
-
-
-def cluster_defects(all_comments: list[ReviewerComment]) -> list[DefectCluster]:
-    """Group review comments by defect class and rank by how often each recurs.
-
-    Args:
-        all_comments: The reviewer comments to sort.
-
-    Returns:
-        One cluster per defect class present, most frequent first, each with a
-        capped sample of its comment bodies.
-    """
-    bodies_by_class: dict[str, list[str]] = defaultdict(list)
-    for each_comment in all_comments:
-        defect_class = classify_defect(each_comment.body)
-        if defect_class is None:
-            continue
-        bodies_by_class[defect_class].append(each_comment.body)
-    clusters: list[DefectCluster] = []
-    for each_defect_class, each_bodies in bodies_by_class.items():
-        clusters.append(
-            DefectCluster(
-                defect_class=each_defect_class,
-                count=len(each_bodies),
-                example_bodies=tuple(each_bodies[:MAX_EXAMPLES_PER_CLUSTER]),
-            )
-        )
-    return sorted(clusters, key=lambda cluster: cluster.count, reverse=True)
-
-
-def proposal_for_defect_class(defect_class: str) -> SkillProposal:
-    """Return the skill-edit proposal that blocks a defect class upstream.
-
-    Args:
-        defect_class: The defect class to propose an edit for.
-
-    Returns:
-        The proposal mapped to the class.
-    """
-    return SkillProposal(
-        defect_class=defect_class, proposal=PROPOSAL_BY_DEFECT_CLASS[defect_class]
-    )
-
-
-def _pull_number_from_url(pull_request_url: str) -> int | None:
-    """Read the trailing pull number from a GitHub pull-request URL."""
-    last_segment = pull_request_url.rsplit("/", 1)[-1]
-    try:
-        return int(last_segment)
-    except ValueError:
-        return None
-
-
-def _reviewer_comment_from_payload(payload: object) -> ReviewerComment | None:
-    """Build a ReviewerComment from one gh comment payload, or None to skip it."""
-    if not isinstance(payload, dict):
-        return None
-    user_field = payload.get("user")
-    login = user_field.get("login") if isinstance(user_field, dict) else None
-    body = payload.get("body")
-    pull_request_url = payload.get("pull_request_url")
-    if not isinstance(login, str) or login not in ALL_REVIEWER_BOT_LOGINS:
-        return None
-    if not isinstance(body, str) or not isinstance(pull_request_url, str):
-        return None
-    pull_number = _pull_number_from_url(pull_request_url)
-    if pull_number is None:
-        return None
-    return ReviewerComment(pull_number=pull_number, author=login, body=body)
-
-
-def _flatten_pages(slurped_payload: object) -> list[object]:
-    """Flatten the per-page arrays a gh --slurp response holds into one list.
-
-    Args:
-        slurped_payload: The parsed output of a ``gh api --paginate --slurp``
-            call: a list whose entries are the individual page responses.
-
-    Returns:
-        Every entry across the pages in page order. A page that is itself a list
-        contributes its entries; any other page contributes itself.
-    """
-    flattened_entries: list[object] = []
-    if isinstance(slurped_payload, list):
-        for each_page in slurped_payload:
-            if isinstance(each_page, list):
-                flattened_entries.extend(each_page)
-            else:
-                flattened_entries.append(each_page)
-    return flattened_entries
-
-
-def _run_gh_json(endpoint: str, *, should_paginate: bool = False) -> object:
-    """Run one gh api call for an endpoint and return its parsed JSON payload.
-
-    Args:
-        endpoint: The gh api endpoint path to request.
-        should_paginate: When True, follow pagination with ``--paginate
-            --slurp`` and flatten the per-page arrays into one list, so a list
-            endpoint with more than one page returns every entry rather than
-            only the first page.
-
-    Returns:
-        The parsed JSON payload: the flattened entry list when should_paginate
-        is True, otherwise the single response parsed as-is.
-
-    Raises:
-        GitHubCommandError: When gh is not installed, the gh api call fails, or
-            its output is not JSON.
-    """
-    gh_command = ["gh", "api", endpoint]
-    if should_paginate:
-        gh_command += ["--paginate", "--slurp"]
-    try:
-        completed_process = subprocess.run(
-            gh_command,
-            capture_output=True,
-            text=True,
-            check=True,
-        )
-    except FileNotFoundError as missing_gh_error:
-        raise GitHubCommandError(
-            "gh command not found; install the GitHub CLI to mine reviewer comments"
-        ) from missing_gh_error
-    except subprocess.CalledProcessError as gh_failure_error:
-        raise GitHubCommandError(
-            f"gh api {endpoint} failed: {gh_failure_error.stderr.strip()}"
-        ) from gh_failure_error
-    try:
-        parsed_payload = json.loads(completed_process.stdout)
-    except json.JSONDecodeError as decode_error:
-        raise GitHubCommandError(
-            f"gh api {endpoint} returned output that is not JSON"
-        ) from decode_error
-    if should_paginate:
-        return _flatten_pages(parsed_payload)
-    return parsed_payload
-
-
-def _fetch_recent_pull_numbers(repo: str, pull_count: int) -> list[int]:
-    """Fetch the most recently updated pull numbers, capped at pull_count."""
-    pulls_payload = _run_gh_json(
-        RECENT_PULLS_ENDPOINT_TEMPLATE.format(repo=repo, pull_count=pull_count)
-    )
-    recent_pull_numbers: list[int] = []
-    if isinstance(pulls_payload, list):
-        for each_pull in pulls_payload:
-            if isinstance(each_pull, dict):
-                pull_number = each_pull.get("number")
-                if isinstance(pull_number, int):
-                    recent_pull_numbers.append(pull_number)
-    return recent_pull_numbers
-
-
-def _fetch_pull_comments(repo: str, pull_number: int) -> list[object]:
-    """Fetch one pull request's review comments through gh."""
-    comments_payload = _run_gh_json(
-        PULL_COMMENTS_ENDPOINT_TEMPLATE.format(repo=repo, pull_number=pull_number),
-        should_paginate=True,
-    )
-    if isinstance(comments_payload, list):
-        return list(comments_payload)
-    return []
-
-
-def _fetch_reviewer_comments(repo: str) -> list[ReviewerComment]:
-    """Fetch reviewer-bot comments from the repo's most recent pull requests."""
-    recent_pull_numbers = _fetch_recent_pull_numbers(repo, RECENT_PULL_COUNT)
-    reviewer_comments: list[ReviewerComment] = []
-    for each_pull_number in recent_pull_numbers:
-        for each_payload in _fetch_pull_comments(repo, each_pull_number):
-            parsed_comment = _reviewer_comment_from_payload(each_payload)
-            if parsed_comment is not None:
-                reviewer_comments.append(parsed_comment)
-    return reviewer_comments
-
-
-def main() -> int:
-    """Print one skill-edit proposal per recurring reviewer defect class.
-
-    Returns:
-        The process exit code; zero on success.
-    """
-    parser = argparse.ArgumentParser(
-        description="Mine reviewer defect patterns into skill-edit proposals."
-    )
-    parser.add_argument("--repo", required=True)
-    parsed_arguments = parser.parse_args()
-    try:
-        comments = _fetch_reviewer_comments(parsed_arguments.repo)
-    except GitHubCommandError as gh_error:
-        print(str(gh_error), file=sys.stderr)
-        return 1
-    clusters = cluster_defects(comments)
-    for each_cluster in clusters:
-        proposal = proposal_for_defect_class(each_cluster.defect_class)
-        print(f"{each_cluster.count}\t{each_cluster.defect_class}\t{proposal.proposal}")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())