claude-dev-env 1.24.0 → 1.25.0

package/hooks/validators/test_magic_value_checks.py

@@ -1,15 +1,22 @@
 """Tests for magic value detection."""
 
 import ast
+import tempfile
+from pathlib import Path
 
 import pytest
 
 from magic_value_checks import (
     check_magic_values,
+    validate_file,
 )
 from validator_base import Violation
 
 
+MAGIC_NUMBER_SOURCE = "x = 42\n"
+NON_TEST_TEMPDIR_PREFIX = "src_"
+
+
 GOOD_NAMED_CONSTANTS = '''
 API_TIMEOUT_MS = 5000
 HASH_DELIMITER = "__"
@@ -29,8 +36,23 @@ ALLOWED_SMALL_NUMBERS = '''
 def process():
     count = 0
     increment = 1
-    doubled = count * 2
-    return count + 1
+    negative = -1
+    return count + increment + negative
+'''
+
+ALLOWED_NEGATIVE_ONE_IN_BINARY_EXPRESSION = '''
+def process(total):
+    return total * -1
+'''
+
+ALLOWED_NEGATIVE_ONE_IN_RETURN = '''
+def process():
+    return -1
+'''
+
+BAD_NEGATIVE_LITERAL_TWO = '''
+def process():
+    return total * -2
 '''
 
 ALLOWED_EMPTY_STRING = '''
@@ -39,6 +61,114 @@ def process():
     return result
 '''
 
+BAD_LITERAL_TWO = '''
+def process():
+    doubled = something * 2
+    return doubled
+'''
+
+BAD_LITERAL_ONE_HUNDRED = '''
+def process():
+    percentage = fraction * 100
+    return percentage
+'''
+
+ALLOWED_NEGATIVE_UPPER_CONSTANT_ASSIGNMENT = '''
+LIMIT = -100
+OFFSET = -5
+'''
+
+ALLOWED_TYPED_NEGATIVE_UPPER_CONSTANT = '''
+LIMIT: int = -100
+OFFSET: int = -5
+'''
+
+DOUBLE_NEGATED_LITERAL = '''
+def process():
+    return --5
+'''
+
+DICT_VALUED_CONSTANT = '''
+SETTINGS = {"timeout": 30, "retries": 5}
+'''
+
+TUPLE_VALUED_CONSTANT = '''
+RETRY_DELAYS = (2, 4, 8)
+'''
+
+LIST_VALUED_CONSTANT = '''
+PORTS = [8080, 8443, 9000]
+'''
+
+NESTED_DICT_VALUED_CONSTANT = '''
+CONFIG = {"db": {"port": 5432}}
+'''
+
+ANNOTATED_SCALAR_CONSTANT = '''
+TIMEOUT_MS: int = 5000
+'''
+
+ANNOTATED_DICT_VALUED_CONSTANT = '''
+SETTINGS: dict[str, int] = {"timeout": 30}
+'''
+
+NON_CONSTANT_ASSIGNMENT_IN_FUNCTION = '''
+def configure():
+    delay = 30
+    return delay
+'''
+
+SCALAR_MAGIC_NUMBER_OUTSIDE_CONSTANT = '''
+def compute():
+    return 30 + 5000
+'''
+
+LEADING_UNDERSCORE_TARGET = '''
+_PRIVATE = {"timeout": 30}
+'''
+
+DOUBLE_UNDERSCORE_TARGET = '''
+__PRIVATE = {"timeout": 30}
+'''
+
+NON_CONTAINER_RHS_CALL = '''
+CONFIG = some_factory(30, retries=5)
+'''
+
+NON_CONTAINER_RHS_BINOP = '''
+WINDOW = base + 5000
+'''
+
+TUPLE_TARGET_ASSIGNMENT = '''
+A, B = 1, 30
+'''
+
+AUG_ASSIGN_UPPER_SNAKE = '''
+COUNTER = 0
+COUNTER += 30
+'''
+
+CLASS_BODY_UPPER_SNAKE_CONSTANT = '''
+class Foo:
+    TIMEOUT = 30
+'''
+
+ANNOTATED_LITERAL_TYPE = '''
+X: Literal[42] = 42
+'''
+
+TRUE_LITERAL_IN_FUNCTION = '''
+def configure():
+    is_enabled = True
+    return is_enabled
+'''
+
+FALSE_LITERAL_IN_FUNCTION = '''
+def configure():
+    is_disabled = False
+    return is_disabled
+'''
+
 
 class TestMagicValues:
     def test_named_constants_pass(self) -> None:
@@ -57,7 +187,231 @@ class TestMagicValues:
         violations = check_magic_values(tree, "test.py")
         assert violations == []
 
+    def test_negative_one_allowed_in_binary_expression(self) -> None:
+        tree = ast.parse(ALLOWED_NEGATIVE_ONE_IN_BINARY_EXPRESSION)
+        violations = check_magic_values(tree, "test.py")
+        assert violations == []
+
+    def test_negative_one_allowed_in_return_expression(self) -> None:
+        tree = ast.parse(ALLOWED_NEGATIVE_ONE_IN_RETURN)
+        violations = check_magic_values(tree, "test.py")
+        assert violations == []
+
+    def test_negative_literal_two_is_flagged_with_signed_value(self) -> None:
+        tree = ast.parse(BAD_NEGATIVE_LITERAL_TWO)
+        violations = check_magic_values(tree, "test.py")
+        assert len(violations) == 1
+        assert "-2" in violations[0].message
+
     def test_empty_string_allowed(self) -> None:
         tree = ast.parse(ALLOWED_EMPTY_STRING)
         violations = check_magic_values(tree, "test.py")
         assert violations == []
+
+    def test_check_magic_values_should_flag_literal_two_in_function_body(self) -> None:
+        tree = ast.parse(BAD_LITERAL_TWO)
+        violations = check_magic_values(tree, "test.py")
+        assert len(violations) == 1
+        assert "2" in violations[0].message
+
+    def test_check_magic_values_should_flag_literal_one_hundred_in_function_body(self) -> None:
+        tree = ast.parse(BAD_LITERAL_ONE_HUNDRED)
+        violations = check_magic_values(tree, "test.py")
+        assert len(violations) == 1
+        assert "100" in violations[0].message
+
+    def test_negative_upper_constant_assignment_allowed(self) -> None:
+        tree = ast.parse(ALLOWED_NEGATIVE_UPPER_CONSTANT_ASSIGNMENT)
+        violations = check_magic_values(tree, "test.py")
+        assert violations == []
+
+    def test_typed_negative_upper_constant_allowed(self) -> None:
+        tree = ast.parse(ALLOWED_TYPED_NEGATIVE_UPPER_CONSTANT)
+        violations = check_magic_values(tree, "test.py")
+        assert violations == []
+
+    def test_double_negation_reports_collapsed_positive_value(self) -> None:
+        tree = ast.parse(DOUBLE_NEGATED_LITERAL)
+        violations = check_magic_values(tree, "test.py")
+        assert len(violations) == 1
+        assert "5" in violations[0].message
+        assert "-5" not in violations[0].message
+
+    def test_should_exempt_numbers_inside_dict_valued_constant(self) -> None:
+        tree = ast.parse(DICT_VALUED_CONSTANT)
+        violations = check_magic_values(tree, "test.py")
+        assert violations == []
+
+    def test_should_exempt_numbers_inside_tuple_valued_constant(self) -> None:
+        tree = ast.parse(TUPLE_VALUED_CONSTANT)
+        violations = check_magic_values(tree, "test.py")
+        assert violations == []
+
+    def test_should_exempt_numbers_inside_list_valued_constant(self) -> None:
+        tree = ast.parse(LIST_VALUED_CONSTANT)
+        violations = check_magic_values(tree, "test.py")
+        assert violations == []
+
+    def test_should_exempt_numbers_inside_nested_dict_valued_constant(self) -> None:
+        tree = ast.parse(NESTED_DICT_VALUED_CONSTANT)
+        violations = check_magic_values(tree, "test.py")
+        assert violations == []
+
+    def test_should_exempt_numbers_inside_annotated_upper_snake_constant(self) -> None:
+        tree = ast.parse(ANNOTATED_SCALAR_CONSTANT)
+        violations = check_magic_values(tree, "test.py")
+        assert violations == []
+
+    def test_should_exempt_numbers_inside_annotated_dict_valued_constant(self) -> None:
+        tree = ast.parse(ANNOTATED_DICT_VALUED_CONSTANT)
+        violations = check_magic_values(tree, "test.py")
+        assert violations == []
+
+    def test_should_still_flag_numbers_in_function_body_assignments(self) -> None:
+        tree = ast.parse(NON_CONSTANT_ASSIGNMENT_IN_FUNCTION)
+        violations = check_magic_values(tree, "test.py")
+        assert len(violations) == 1
+        assert "30" in violations[0].message
+
+    def test_should_still_flag_scalar_magic_number_outside_constant(self) -> None:
+        tree = ast.parse(SCALAR_MAGIC_NUMBER_OUTSIDE_CONSTANT)
+        violations = check_magic_values(tree, "test.py")
+        flagged_numbers = {violation.message for violation in violations}
+        assert any("30" in message for message in flagged_numbers)
+        assert any("5000" in message for message in flagged_numbers)
+
+    def test_should_flag_literal_under_single_leading_underscore_target(self) -> None:
+        tree = ast.parse(LEADING_UNDERSCORE_TARGET)
+        violations = check_magic_values(tree, "test.py")
+        assert any("30" in violation.message for violation in violations)
+
+    def test_should_flag_literal_under_double_leading_underscore_target(self) -> None:
+        tree = ast.parse(DOUBLE_UNDERSCORE_TARGET)
+        violations = check_magic_values(tree, "test.py")
+        assert any("30" in violation.message for violation in violations)
+
+    def test_should_flag_literal_under_non_container_call_rhs(self) -> None:
+        tree = ast.parse(NON_CONTAINER_RHS_CALL)
+        violations = check_magic_values(tree, "test.py")
+        flagged_numbers = {violation.message for violation in violations}
+        assert any("30" in message for message in flagged_numbers)
+        assert any("5" in message for message in flagged_numbers)
+
+    def test_should_flag_literal_under_non_container_binop_rhs(self) -> None:
+        tree = ast.parse(NON_CONTAINER_RHS_BINOP)
+        violations = check_magic_values(tree, "test.py")
+        assert any("5000" in violation.message for violation in violations)
+
+    def test_tuple_target_assignment_flags_literal_when_no_upper_snake_target(
+        self,
+    ) -> None:
+        tree = ast.parse(TUPLE_TARGET_ASSIGNMENT)
+        violations = check_magic_values(tree, "test.py")
+        assert any("30" in violation.message for violation in violations)
+
+    def test_aug_assign_on_upper_snake_target_is_not_exempt(self) -> None:
+        tree = ast.parse(AUG_ASSIGN_UPPER_SNAKE)
+        violations = check_magic_values(tree, "test.py")
+        assert any("30" in violation.message for violation in violations)
+
+    def test_class_body_upper_snake_constant_is_exempt(self) -> None:
+        tree = ast.parse(CLASS_BODY_UPPER_SNAKE_CONSTANT)
+        violations = check_magic_values(tree, "test.py")
+        assert violations == []
+
+    def test_annotated_literal_type_flags_literal_inside_subscript_annotation(
+        self,
+    ) -> None:
+        tree = ast.parse(ANNOTATED_LITERAL_TYPE)
+        violations = check_magic_values(tree, "test.py")
+        assert any("42" in violation.message for violation in violations)
+
+    def test_check_magic_values_should_not_flag_True_literal(self) -> None:
+        tree = ast.parse(TRUE_LITERAL_IN_FUNCTION)
+        violations = check_magic_values(tree, "test.py")
+        assert violations == []
+
+    def test_check_magic_values_should_not_flag_False_literal(self) -> None:
+        tree = ast.parse(FALSE_LITERAL_IN_FUNCTION)
+        violations = check_magic_values(tree, "test.py")
+        assert violations == []
+
+
+class TestValidateFilePathExemptions:
+    def test_validate_file_should_skip_test_underscore_py_files(
+        self, tmp_path: Path
+    ) -> None:
+        tests_directory = tmp_path / "tests"
+        tests_directory.mkdir()
+        test_module_path = tests_directory / "test_foo.py"
+        test_module_path.write_text(MAGIC_NUMBER_SOURCE, encoding="utf-8")
+
+        assert validate_file(test_module_path) == []
+
+    def test_validate_file_should_skip_config_directory(
+        self, tmp_path: Path
+    ) -> None:
+        config_directory = tmp_path / "config"
+        config_directory.mkdir()
+        constants_path = config_directory / "constants.py"
+        constants_path.write_text(MAGIC_NUMBER_SOURCE, encoding="utf-8")
+
+        assert validate_file(constants_path) == []
+
+    def test_validate_file_should_skip_settings_py(self, tmp_path: Path) -> None:
+        settings_path = tmp_path / "settings.py"
+        settings_path.write_text(MAGIC_NUMBER_SOURCE, encoding="utf-8")
+
+        assert validate_file(settings_path) == []
+
+    def test_validate_file_should_skip_uppercase_config_directory(
+        self, tmp_path: Path
+    ) -> None:
+        """Case-insensitive match so Config/ on case-preserving filesystems skips."""
+        uppercase_config_directory = tmp_path / "Config"
+        uppercase_config_directory.mkdir()
+        constants_path = uppercase_config_directory / "constants.py"
+        constants_path.write_text(MAGIC_NUMBER_SOURCE, encoding="utf-8")
+
+        assert validate_file(constants_path) == []
+
+    def test_validate_file_should_skip_mixed_case_tests_directory(
+        self, tmp_path: Path
+    ) -> None:
+        """Case-insensitive match so src/Tests/ short-circuits the same way src/tests/ does."""
+        mixed_case_tests_directory = tmp_path / "Tests"
+        mixed_case_tests_directory.mkdir()
+        test_module_path = mixed_case_tests_directory / "test_foo.py"
+        test_module_path.write_text(MAGIC_NUMBER_SOURCE, encoding="utf-8")
+
+        assert validate_file(test_module_path) == []
+
+    def test_validate_file_should_skip_conftest_helpers(
+        self, tmp_path: Path
+    ) -> None:
+        """Naked ``conftest`` substring matches conftest_helpers.py and similar."""
+        conftest_helpers_path = tmp_path / "conftest_helpers.py"
+        conftest_helpers_path.write_text(MAGIC_NUMBER_SOURCE, encoding="utf-8")
+
+        assert validate_file(conftest_helpers_path) == []
+
+    def test_validate_file_should_still_scan_production_py_files(self) -> None:
+        """Use tempfile with a non-test prefix instead of the pytest tmp_path fixture.
+
+        pytest's tmp_path produces directories like ``pytest-of-<user>/pytest-N/
+        test_validate_file_should_still_scan_production_py_files0/`` whose names
+        contain ``test_`` and ``pytest-`` -- both match TEST_PATH_PATTERNS, so
+        validate_file would short-circuit via is_test_file and make this
+        regression a false green.
+        """
+        with tempfile.TemporaryDirectory(
+            prefix=NON_TEST_TEMPDIR_PREFIX
+        ) as temporary_root:
+            source_directory = Path(temporary_root) / "src"
+            source_directory.mkdir()
+            production_path = source_directory / "app.py"
+            production_path.write_text(MAGIC_NUMBER_SOURCE, encoding="utf-8")
+
+            violations = validate_file(production_path)
+            assert len(violations) == 1
+            assert "42" in violations[0].message

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.24.0",
+    "version": "1.25.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/gh-body-file.md

@@ -33,17 +33,26 @@ subprocess.run(["gh", "pr", "create", "--title", "My PR", "--body-file", body_pa
 
 ### PowerShell (Windows — preferred for this repo)
 
+`Set-Content -Encoding utf8` writes UTF-8-**with-BOM** on Windows PowerShell 5.1,
+which causes `gh` to treat the leading BOM as part of the first heading character
+and can corrupt rendering. Use the BOM-free pattern below — it works on both
+Windows PowerShell 5.1 and PowerShell 7+.
+
 ```powershell
 $bodyPath = [System.IO.Path]::ChangeExtension((New-TemporaryFile).FullName, '.md')
-@'
+$body = @'
 ## Summary
 
 Fixes `foo` by updating `bar`.
-'@ | Set-Content -Path $bodyPath -Encoding utf8
+'@
+[IO.File]::WriteAllText($bodyPath, $body, [Text.UTF8Encoding]::new($false))
 
 gh pr create --title "My PR" --body-file $bodyPath
 ```
 
+On PowerShell 7+ you can alternatively use `Set-Content -Encoding utf8NoBOM`,
+but the `[IO.File]::WriteAllText` pattern above is version-agnostic.
+
 ### Bash
 
 Safe Bash patterns are intentionally omitted from this rule file. This repo

package/skills/searching-obsidian-vault/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: searching-obsidian-vault
+description: >-
+  Retrieves Obsidian vault context from %USERPROFILE%/SessionLog/ via the
+  configured mcp__obsidian__* server. Searches sessions/, decisions/, and
+  Research/. Use when the user says "yesterday", "last night", "the other
+  day", "earlier today", "this morning", "a few days ago", "last week",
+  "this past week", "a while back", "recently", "recent session", "last
+  session", or "previous session"; when the user asks why existing code
+  was built a certain way or whether an approach was tried before; when
+  starting a session in a git repo whose name matches a project folder
+  under sessions/; or when the user names a specific component, decision,
+  gotcha, or prior research note.
+---
+
+# Obsidian Vault
+
+## Overview
+
+Invoke this skill when prior session history, decisions, or research from
+the Obsidian vault would change how the current task is executed. Load it
+on demand rather than keeping the full vault policy always-on.
+
+The retrieval *mechanics* live in `/recall`. The
+`vault_context_retrieved` frontmatter bookkeeping lives in `/session-log`
+Step 2. This skill's job is to make the vault search happen at the right
+moments so the downstream flag can be set honestly.
+
+## Trigger Conditions
+
+Invoke automatically when any of the following holds:
+
+- The user says "yesterday", "last night", "the other day", "earlier
+  today", "this morning", "a few days ago", "last week", "this past
+  week", "a while back", "recently", "recent session", "last session",
+  or "previous session".
+- The user asks why existing code was built a certain way, or whether an
+  approach was tried before.
+- A new session starts in a git repo whose name matches a project folder
+  under `sessions/`.
+- The user names a specific component, feature, or architectural decision
+  that a session or decision note might exist for.
+- The user mentions "session", "decision", "gotcha", "superseded", or
+  "prior research" by name.
+
+Skip the skill for isolated lookups with no project history (e.g. one-off
+utility scripts, pure syntax questions, fresh repos with no
+`sessions/[project]/` folder).
+
+## Search Algorithm
+
+1. **Search by frontmatter first.** Call `mcp__obsidian__search_notes` with
+   `searchFrontmatter: true` and the project name (inferred from the git
+   remote, working directory, or topic under discussion). Then search by
+   content keywords such as `blocked`, `superseded`, `decision`, `gotcha`,
+   plus task-specific terms (component names, error messages, library names).
+
+   Concrete example:
+
+   ```xml
+   <invoke name="mcp__obsidian__search_notes">
+     <parameter name="query">claude-code-config</parameter>
+     <parameter name="searchFrontmatter">true</parameter>
+   </invoke>
+
+   <invoke name="mcp__obsidian__search_notes">
+     <parameter name="query">superseded decision themes-pr-stack</parameter>
+   </invoke>
+   ```
+
+2. **Scope to the three vault folders.**
+   - `sessions/` — session reports (`type: session-report`, `project`,
+     `session`, `date`, `status`, `blocked`, `tags`).
+   - `decisions/` — decision notes (`type: decision|procedural|fact|gotcha`,
+     `project`, `date`, `status: Active|Superseded`, `tags`).
+   - `Research/` — deep research documents.
+
+3. **Read the top 3–5 hits.** Use `mcp__obsidian__read_note` for single notes
+   or `mcp__obsidian__read_multiple_notes` for several at once. Prefer recent
+   notes over older ones, and prefer decision notes and session summaries
+   over raw research.
+
+4. **Summarise the relevant prior context** inline before proceeding with
+   the work, so the user can see what prior history shaped the current
+   approach. Call out any decision marked `status: Superseded`.
+
+5. **Record the outcome for `/session-log`.** Set
+   `vault_context_retrieved: true` if any `mcp__obsidian__*` read or search
+   tool was used productively (at least one relevant note surfaced and
+   informed the work). Set it to `false` if the vault was unreachable or no
+   relevant notes were found.
+
+## Session-End Integration
+
+At the end of substantive sessions, offer to run `/session-log`. Step 2 of
+`/session-log` already auto-detects vault MCP calls and writes the
+`vault_context_retrieved` field into frontmatter. This skill's contribution
+is to ensure those MCP calls actually happen when they should, so the flag
+ends up `true` whenever genuine prior context exists.
+
+## Frontmatter Requirement
+
+Any session note written via `/session-log` after invoking this skill must
+include:
+
+```yaml
+vault_context_retrieved: true   # or false
+```
+
+`true` means a `mcp__obsidian__*` read or search tool was used productively
+during the session. `false` means the vault was unreachable or no relevant
+notes existed.
+
+## Vault Location
+
+The vault lives at `%USERPROFILE%/SessionLog/` on this workspace
+(expanding to the user's Windows profile directory). It is accessed
+entirely through the `mcp__obsidian__*` MCP server, whose own
+configuration holds the concrete path; `OBSIDIAN_VAULT_PATH` serves the
+same role on systems that resolve the vault outside the MCP server. This
+skill does not read the filesystem directly and must not hard-code a
+user-specific path like `C:/Users/<name>/SessionLog/` in code it
+produces — expand `%USERPROFILE%` (or read `OBSIDIAN_VAULT_PATH`) at run
+time.
+
+## Related Skills
+
+- `/recall` performs the retrieval mechanics end-to-end with user-facing
+  output.
+- `/session-log` consumes the `vault_context_retrieved` flag this skill is
+  responsible for keeping honest.