@tanagram/cli 0.1.6 → 0.1.8

package/README.md

@@ -90,16 +90,40 @@ tanagram help
 
 **Smart Caching:** Policies are cached and automatically resynced when instruction files change (detected via MD5 hash).
 
-## Commands
+### Commands
 
 - **`run`** (default) - Check git changes against policies with auto-sync
 - **`sync`** - Manually sync all instruction files to cache
 - **`list`** - View all cached policies (shows enforceable vs unenforceable)
 - **`help`** - Show usage information
 
+### Claude Code Hook
+You can install the CLI as a Claude Code [hook](https://code.claude.com/docs/en/hooks) to have Claude automatically iterate on Tanagram's output. Add the following to your `~/.claude/settings.json` (user settings) or `.claude/settings.json` (project settings):
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "tanagram"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If you have existing hooks, you can merge this hook into your existing config.
+
+
 ## How It Works
 
-1. **Finds instruction files** - Searches for `AGENTS.md`, `POLICIES.md` in your git repository
+1. **Finds instruction files** - Searches for `AGENTS.md`, `POLICIES.md`, `CLAUDE.md` in your git repository
 2. **Checks cache** - Loads cached policies and MD5 hashes from `.tanagram/`
 3. **Auto-syncs** - Detects file changes via MD5 and automatically resyncs if needed
 4. **LLM extraction** - Uses Claude AI to extract ALL policies from instruction files

package/checker/matcher.go

@@ -21,7 +21,7 @@ type Violation struct {
 
 // CheckResult contains all violations found
 type CheckResult struct {
-	Violations []Violation
+	Violations   []Violation
 	TotalChecked int
 }
 
@@ -89,3 +89,52 @@ func FormatViolations(result *CheckResult) string {
 
 	return output.String()
 }
+
+// FormatClaudeInstructions formats violations as actionable instructions for Claude Code
+// to automatically fix via exit code 2 hook behavior
+func FormatClaudeInstructions(result *CheckResult) string {
+	if len(result.Violations) == 0 {
+		return ""
+	}
+
+	// Group violations by file
+	violationsByFile := make(map[string][]Violation)
+	for _, v := range result.Violations {
+		violationsByFile[v.File] = append(violationsByFile[v.File], v)
+	}
+
+	// Sort files for consistent output
+	files := make([]string, 0, len(violationsByFile))
+	for file := range violationsByFile {
+		files = append(files, file)
+	}
+	sort.Strings(files)
+
+	var output strings.Builder
+	output.WriteString("POLICY VIOLATIONS DETECTED - PLEASE FIX\n\n")
+	output.WriteString(fmt.Sprintf("Found %d policy violation(s) that need to be fixed:\n\n", len(result.Violations)))
+
+	for _, file := range files {
+		violations := violationsByFile[file]
+
+		// Sort violations by line number
+		sort.Slice(violations, func(i, j int) bool {
+			return violations[i].LineNumber < violations[j].LineNumber
+		})
+
+		output.WriteString(fmt.Sprintf("File: %s\n", file))
+
+		for _, v := range violations {
+			output.WriteString(fmt.Sprintf("\n  Line %d:\n", v.LineNumber))
+			output.WriteString(fmt.Sprintf("    Code: %s\n", v.Code))
+			output.WriteString(fmt.Sprintf("    Policy: %s\n", v.PolicyName))
+			output.WriteString(fmt.Sprintf("    Issue: %s\n", v.Message))
+			output.WriteString(fmt.Sprintf("    Action: Review and fix this code to comply with the policy.\n"))
+		}
+		output.WriteString("\n")
+	}
+
+	output.WriteString("Please fix all violations listed above and ensure the code complies with all policies.\n")
+
+	return output.String()
+}

package/checker/matcher_test.go

@@ -0,0 +1,215 @@
+package checker
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestFormatViolations_NoViolations(t *testing.T) {
+	result := &CheckResult{
+		Violations:   []Violation{},
+		TotalChecked: 10,
+	}
+
+	output := FormatViolations(result)
+	expected := "✓ No policy violations found"
+
+	if output != expected {
+		t.Errorf("Expected %q, got %q", expected, output)
+	}
+}
+
+func TestFormatViolations_WithViolations(t *testing.T) {
+	result := &CheckResult{
+		Violations: []Violation{
+			{
+				File:       "main.go",
+				LineNumber: 10,
+				PolicyName: "No hardcoded secrets",
+				Message:    "Potential hardcoded API key detected",
+				Code:       "apiKey := \"sk-1234567890\"",
+			},
+			{
+				File:       "config.go",
+				LineNumber: 5,
+				PolicyName: "Use environment variables",
+				Message:    "Configuration should use environment variables",
+				Code:       "var token = \"abc123\"",
+			},
+		},
+		TotalChecked: 50,
+	}
+
+	output := FormatViolations(result)
+
+	// Check that output contains expected elements
+	if !strings.Contains(output, "✗ Found 2 policy violation(s)") {
+		t.Errorf("Expected violation count in output, got: %s", output)
+	}
+	if !strings.Contains(output, "main.go") {
+		t.Errorf("Expected file name 'main.go' in output")
+	}
+	if !strings.Contains(output, "config.go") {
+		t.Errorf("Expected file name 'config.go' in output")
+	}
+	if !strings.Contains(output, "10:") {
+		t.Errorf("Expected line number 10 in output")
+	}
+	if !strings.Contains(output, "Potential hardcoded API key detected") {
+		t.Errorf("Expected violation message in output")
+	}
+}
+
+func TestFormatClaudeInstructions_NoViolations(t *testing.T) {
+	result := &CheckResult{
+		Violations:   []Violation{},
+		TotalChecked: 10,
+	}
+
+	output := FormatClaudeInstructions(result)
+
+	if output != "" {
+		t.Errorf("Expected empty string for no violations, got: %s", output)
+	}
+}
+
+func TestFormatClaudeInstructions_WithViolations(t *testing.T) {
+	result := &CheckResult{
+		Violations: []Violation{
+			{
+				File:       "main.go",
+				LineNumber: 10,
+				PolicyName: "No hardcoded secrets",
+				Message:    "Potential hardcoded API key detected",
+				Code:       "apiKey := \"sk-1234567890\"",
+			},
+			{
+				File:       "main.go",
+				LineNumber: 15,
+				PolicyName: "No hardcoded secrets",
+				Message:    "Potential hardcoded password detected",
+				Code:       "password := \"secret123\"",
+			},
+			{
+				File:       "config.go",
+				LineNumber: 5,
+				PolicyName: "Use environment variables",
+				Message:    "Configuration should use environment variables",
+				Code:       "var token = \"abc123\"",
+			},
+		},
+		TotalChecked: 50,
+	}
+
+	output := FormatClaudeInstructions(result)
+
+	// Check header
+	if !strings.Contains(output, "POLICY VIOLATIONS DETECTED - PLEASE FIX") {
+		t.Errorf("Expected header in output")
+	}
+
+	// Check violation count
+	if !strings.Contains(output, "Found 3 policy violation(s)") {
+		t.Errorf("Expected violation count in output, got: %s", output)
+	}
+
+	// Check file names
+	if !strings.Contains(output, "File: main.go") {
+		t.Errorf("Expected 'File: main.go' in output")
+	}
+	if !strings.Contains(output, "File: config.go") {
+		t.Errorf("Expected 'File: config.go' in output")
+	}
+
+	// Check line numbers
+	if !strings.Contains(output, "Line 10:") {
+		t.Errorf("Expected 'Line 10:' in output")
+	}
+	if !strings.Contains(output, "Line 15:") {
+		t.Errorf("Expected 'Line 15:' in output")
+	}
+	if !strings.Contains(output, "Line 5:") {
+		t.Errorf("Expected 'Line 5:' in output")
+	}
+
+	// Check policy names
+	if !strings.Contains(output, "Policy: No hardcoded secrets") {
+		t.Errorf("Expected policy name in output")
+	}
+	if !strings.Contains(output, "Policy: Use environment variables") {
+		t.Errorf("Expected policy name in output")
+	}
+
+	// Check code snippets
+	if !strings.Contains(output, "Code: apiKey := \"sk-1234567890\"") {
+		t.Errorf("Expected code snippet in output")
+	}
+
+	// Check issue messages
+	if !strings.Contains(output, "Issue: Potential hardcoded API key detected") {
+		t.Errorf("Expected issue message in output")
+	}
+
+	// Check action instruction
+	if !strings.Contains(output, "Action: Review and fix this code to comply with the policy.") {
+		t.Errorf("Expected action instruction in output")
+	}
+
+	// Check footer
+	if !strings.Contains(output, "Please fix all violations listed above and ensure the code complies with all policies.") {
+		t.Errorf("Expected footer instruction in output")
+	}
+}
+
+func TestFormatClaudeInstructions_MultipleFilesGroupedAndSorted(t *testing.T) {
+	result := &CheckResult{
+		Violations: []Violation{
+			{
+				File:       "z_file.go",
+				LineNumber: 20,
+				PolicyName: "Policy Z",
+				Message:    "Issue Z",
+				Code:       "code z",
+			},
+			{
+				File:       "a_file.go",
+				LineNumber: 30,
+				PolicyName: "Policy A2",
+				Message:    "Issue A2",
+				Code:       "code a2",
+			},
+			{
+				File:       "a_file.go",
+				LineNumber: 10,
+				PolicyName: "Policy A1",
+				Message:    "Issue A1",
+				Code:       "code a1",
+			},
+		},
+		TotalChecked: 50,
+	}
+
+	output := FormatClaudeInstructions(result)
+
+	// Files should be sorted alphabetically
+	aFileIndex := strings.Index(output, "File: a_file.go")
+	zFileIndex := strings.Index(output, "File: z_file.go")
+
+	if aFileIndex == -1 || zFileIndex == -1 {
+		t.Errorf("Expected both file names in output")
+	}
+	if aFileIndex >= zFileIndex {
+		t.Errorf("Expected files to be sorted alphabetically (a_file.go before z_file.go)")
+	}
+
+	// Within a file, violations should be sorted by line number
+	line10Index := strings.Index(output, "Line 10:")
+	line30Index := strings.Index(output, "Line 30:")
+
+	if line10Index == -1 || line30Index == -1 {
+		t.Errorf("Expected both line numbers in output")
+	}
+	if line10Index >= line30Index {
+		t.Errorf("Expected violations to be sorted by line number (10 before 30)")
+	}
+}

package/commands/run.go

@@ -47,7 +47,7 @@ func Run() error {
 	}
 
 	if len(instructionFiles) == 0 {
-		return fmt.Errorf("no instruction files found (looking for AGENTS.md, POLICIES.md, etc.)")
+		return fmt.Errorf("no instruction files found (looking for AGENTS.md, POLICIES.md, CLAUDE.md)")
 	}
 
 	// Load cache
@@ -196,14 +196,21 @@ func Run() error {
 	ctx := context.Background()
 	result := checker.CheckChanges(ctx, diffResult.Changes, policies)
 
-	// Output results
-	output := checker.FormatViolations(result)
-	fmt.Print(output)
-
-	// Exit with error if violations found
+	// Handle results based on whether violations were found
 	if len(result.Violations) > 0 {
-		os.Exit(1)
+		// Format and output violations to stderr
+		violationOutput := checker.FormatViolations(result)
+		fmt.Fprint(os.Stderr, violationOutput)
+
+		// Format and output Claude-friendly instructions to stderr
+		claudeInstructions := checker.FormatClaudeInstructions(result)
+		fmt.Fprint(os.Stderr, claudeInstructions)
+
+		// Exit with code 2 to trigger Claude Code hook behavior
+		os.Exit(2)
 	}
 
+	// No violations found - output success message
+	fmt.Println("✓ No policy violations found")
 	return nil
 }

package/commands/sync.go

@@ -28,7 +28,7 @@ func Sync() error {
 	}
 
 	if len(instructionFiles) == 0 {
-		return fmt.Errorf("no instruction files found (looking for AGENTS.md, POLICIES.md, etc.)")
+		return fmt.Errorf("no instruction files found (looking for AGENTS.md, POLICIES.md, CLAUDE.md)")
 	}
 
 	fmt.Printf("Found %d instruction file(s)\n", len(instructionFiles))
@@ -137,12 +137,12 @@ func Sync() error {
 }
 
 // FindInstructionFiles searches for instruction files in the git repository
-// Looks for: AGENTS.md, POLICIES.md, and .md files in .tanagram/policies/
+// Looks for: AGENTS.md, POLICIES.md, CLAUDE.md
 func FindInstructionFiles(gitRoot string) ([]string, error) {
 	var files []string
 
 	// Common instruction file names to look for
-	commonNames := []string{"AGENTS.md", "POLICIES.md"}
+	commonNames := []string{"AGENTS.md", "POLICIES.md", "CLAUDE.md"}
 
 	// Directories to skip
 	skipDirs := map[string]bool{

package/main.go

@@ -56,7 +56,7 @@ EXAMPLES:
   tanagram list         # View all cached policies
 
 INSTRUCTION FILES:
-  Tanagram looks for instruction files like AGENTS.md or POLICIES.md
+  Tanagram looks for instruction files like AGENTS.md, POLICIES.md, or CLAUDE.md
   in your git repository. Policies are cached and automatically resynced
   when files change.
 `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanagram/cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Tanagram - Catch sloppy code before it ships",
   "main": "index.js",
   "bin": {