fix: track docs application package

Author: tae2089

.gitignore

@@ -15,7 +15,7 @@
 # Plugin cache
 .omc/
 
-docs/
+/docs/
 .ccg
 .claude/**
 .python-version

internal/app/docs/autorules.go

@@ -0,0 +1,103 @@
+package docs
+
+import (
+	"sort"
+	"strings"
+	"time"
+
+	"go.yaml.in/yaml/v3"
+)
+
+// AutoRule stores generated warn-only lint state separate from human policy.
+// @intent Twice Rule이 만든 자동 warn 규칙을 사람이 관리하는 설정 파일과 분리 저장한다.
+type AutoRule struct {
+	Pattern  string `yaml:"pattern"`
+	Category string `yaml:"category"`
+	Action   string `yaml:"action"`
+	Auto     bool   `yaml:"auto"`
+	Created  string `yaml:"created,omitempty"`
+}
+
+// AutoRuleSet is the persisted generated-rule document written under .ccg/.
+// @intent generated lint state를 rules YAML shape로 직렬화해 기존 규칙 형태와 호환되게 유지한다.
+type AutoRuleSet struct {
+	Rules []AutoRule `yaml:"rules"`
+}
+
+// LoadAutoRules reads generated auto rules. Missing files return an empty set.
+// @intent generated lint rule 상태 파일이 없을 때도 lint가 정상적으로 동작하게 한다.
+func LoadAutoRules(files StateFiles, path string) (*AutoRuleSet, error) {
+	set := &AutoRuleSet{Rules: []AutoRule{}}
+	data, exists, err := files.ReadPath(path)
+	if err != nil {
+		return nil, err
+	}
+	if !exists {
+		return set, nil
+	}
+	if err := yaml.Unmarshal(data, set); err != nil {
+		return nil, err
+	}
+	if set.Rules == nil {
+		set.Rules = []AutoRule{}
+	}
+	return set, nil
+}
+
+// Upsert adds new generated warn rules for triggered lint keys.
+// @intent 같은 category+pattern 규칙을 중복 기록하지 않고 새 자동 규칙만 추가한다.
+func (s *AutoRuleSet) Upsert(triggered []string) []AutoRule {
+	if s.Rules == nil {
+		s.Rules = []AutoRule{}
+	}
+	existing := make(map[string]struct{}, len(s.Rules))
+	for _, rule := range s.Rules {
+		existing[autoRuleKey(rule.Category, rule.Pattern)] = struct{}{}
+	}
+
+	var added []AutoRule
+	for _, key := range triggered {
+		category, pattern, ok := strings.Cut(key, ":")
+		if !ok || category == "" || pattern == "" {
+			continue
+		}
+		lookup := autoRuleKey(category, pattern)
+		if _, ok := existing[lookup]; ok {
+			continue
+		}
+		rule := AutoRule{
+			Pattern:  pattern,
+			Category: category,
+			Action:   "warn",
+			Auto:     true,
+			Created:  time.Now().Format("2006-01-02"),
+		}
+		s.Rules = append(s.Rules, rule)
+		added = append(added, rule)
+		existing[lookup] = struct{}{}
+	}
+
+	sort.Slice(s.Rules, func(i, j int) bool {
+		if s.Rules[i].Category == s.Rules[j].Category {
+			return s.Rules[i].Pattern < s.Rules[j].Pattern
+		}
+		return s.Rules[i].Category < s.Rules[j].Category
+	})
+	return added
+}
+
+// Save writes generated auto rules, creating parent dirs if needed.
+// @intent generated lint state를 원자적으로 기록해 수동 정책 파일과 분리 유지한다.
+func (s *AutoRuleSet) Save(files StateFiles, path string) error {
+	data, err := yaml.Marshal(s)
+	if err != nil {
+		return err
+	}
+	return files.WritePath(path, data)
+}
+
+// autoRuleKey builds a stable map key for one generated lint rule.
+// @intent deduplicate auto-generated rules by category and pattern before persisting them.
+func autoRuleKey(category, pattern string) string {
+	return category + "\x00" + pattern
+}

internal/app/docs/autorules_test.go

@@ -0,0 +1,123 @@
+package docs
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"go.yaml.in/yaml/v3"
+)
+
+func TestLoadAutoRules_MissingReturnsEmpty(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "auto-rules.yaml")
+
+	set, err := LoadAutoRules(testStateFiles, path)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if set == nil {
+		t.Fatal("expected non-nil set")
+	}
+	if len(set.Rules) != 0 {
+		t.Fatalf("expected empty rules, got %v", set.Rules)
+	}
+}
+
+func TestAutoRuleSet_RoundTripPreservesFields(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "auto-rules.yaml")
+	set := &AutoRuleSet{Rules: []AutoRule{{Pattern: "pkg/a.go::Foo", Category: "unannotated", Action: "warn", Auto: true, Created: "2026-05-03"}}}
+
+	if err := set.Save(testStateFiles, path); err != nil {
+		t.Fatalf("save: %v", err)
+	}
+
+	loaded, err := LoadAutoRules(testStateFiles, path)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if len(loaded.Rules) != 1 {
+		t.Fatalf("expected 1 rule, got %d", len(loaded.Rules))
+	}
+	rule := loaded.Rules[0]
+	if rule.Pattern != "pkg/a.go::Foo" || rule.Category != "unannotated" || rule.Action != "warn" || !rule.Auto || rule.Created != "2026-05-03" {
+		t.Fatalf("unexpected round-trip rule: %+v", rule)
+	}
+}
+
+func TestAutoRuleSet_UpsertAddsNew(t *testing.T) {
+	set := &AutoRuleSet{}
+	added := set.Upsert([]string{"unannotated:pkg/a.go::Foo"})
+
+	if len(added) != 1 {
+		t.Fatalf("expected 1 added rule, got %d", len(added))
+	}
+	if len(set.Rules) != 1 {
+		t.Fatalf("expected 1 stored rule, got %d", len(set.Rules))
+	}
+	rule := set.Rules[0]
+	if rule.Pattern != "pkg/a.go::Foo" {
+		t.Fatalf("pattern = %q, want pkg/a.go::Foo", rule.Pattern)
+	}
+	if rule.Category != "unannotated" || rule.Action != "warn" || !rule.Auto {
+		t.Fatalf("unexpected rule metadata: %+v", rule)
+	}
+	if rule.Created == "" {
+		t.Fatal("expected created date to be populated")
+	}
+}
+
+func TestAutoRuleSet_UpsertIsIdempotent(t *testing.T) {
+	set := &AutoRuleSet{}
+	set.Upsert([]string{"unannotated:pkg/a.go::Foo"})
+	added := set.Upsert([]string{"unannotated:pkg/a.go::Foo"})
+
+	if len(added) != 0 {
+		t.Fatalf("expected no new rules on duplicate upsert, got %d", len(added))
+	}
+	if len(set.Rules) != 1 {
+		t.Fatalf("expected 1 stored rule, got %d", len(set.Rules))
+	}
+}
+
+func TestAutoRuleSet_SaveCreatesParentDir(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "nested", "state", "auto-rules.yaml")
+	set := &AutoRuleSet{}
+	set.Upsert([]string{"missing:pkg/b.go"})
+
+	if err := set.Save(testStateFiles, path); err != nil {
+		t.Fatalf("save: %v", err)
+	}
+	if _, err := os.Stat(path); err != nil {
+		t.Fatalf("expected saved file to exist: %v", err)
+	}
+}
+
+func TestAutoRuleSet_SaveUsesYamlPolicyShape(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "auto-rules.yaml")
+	set := &AutoRuleSet{}
+	set.Upsert([]string{"dead-ref:pkg/c.go::Bar"})
+
+	if err := set.Save(testStateFiles, path); err != nil {
+		t.Fatalf("save: %v", err)
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read: %v", err)
+	}
+	content := string(data)
+	for _, want := range []string{"rules:", "pattern: pkg/c.go::Bar", "category: dead-ref", "action: warn", "auto: true"} {
+		if !strings.Contains(content, want) {
+			t.Fatalf("expected %q in yaml, got:\n%s", want, content)
+		}
+	}
+
+	var loaded AutoRuleSet
+	if err := yaml.Unmarshal(data, &loaded); err != nil {
+		t.Fatalf("expected valid yaml shape, got error: %v", err)
+	}
+	if len(loaded.Rules) != 1 || loaded.Rules[0].Pattern != "pkg/c.go::Bar" {
+		t.Fatalf("unexpected unmarshaled rules: %+v", loaded.Rules)
+	}
+}