tags.go

package codegraph

import (
	"fmt"
	"path"
	"regexp"
	"slices"
	"sort"
	"strings"

	"github.com/compforge/codegraph/internal/language"
	"github.com/compforge/codegraph/pkg"
)

type Tag = pkg.Tag

const (
	UnknownTag       = pkg.UnknownTag
	SourceTag        = pkg.SourceTag
	DocumentationTag = pkg.DocumentationTag
	VersionTag       = pkg.VersionTag
	ResourceTag      = pkg.ResourceTag
	ToolingTag       = pkg.ToolingTag
	ConfigTag        = pkg.ConfigTag
	ManifestTag      = pkg.ManifestTag
	LockfileTag      = pkg.LockfileTag
	GeneratedTag     = pkg.GeneratedTag
	TestTag          = pkg.TestTag
	TestFixtureTag   = pkg.TestFixtureTag
	DependencyTag    = pkg.DependencyTag
	BuildOutputTag   = pkg.BuildOutputTag
	CacheTag         = pkg.CacheTag
	MinifiedTag      = pkg.MinifiedTag
)

// TagRule assigns Name to each Document or Directory whose snapshot-relative
// slash-separated path matches Pattern. Directory paths have no trailing slash;
// the root is ".". Patterns use Go regular expressions (unanchored unless specified).
// Languages optionally restricts matches to grammar names recognized from the path;
// an empty list adds no language restriction. It never loads parsers or source bytes.
// +spec=All matching rules accumulate by name, with no precedence or inheritance.
type TagRule struct {
	Name      Tag
	Pattern   string
	Languages []string
}

// BuiltinTagRules returns a fresh rule set for common repository material.
// Callers may append custom rules or supply a replacement through Options.TagRules.
// Tags describe path conventions; consumers decide whether to exclude material.
// +spec=Test tags use naming conventions and shared language recognition, not a separate extension list or proof of execution.
// +why=Consumers extend shared classification instead of replacing tags to express admission or review policy.
// +spec=Generated tags recognize explicit output naming conventions without reading content or requiring parser support.
// +link=component://docs/document.md
// +case=generated_document_tags
func BuiltinTagRules() []TagRule {
	return []TagRule{
		{Name: ManifestTag, Pattern: `(^|/)(go\.mod|go\.work|pyproject\.toml|package\.json)$`},
		{Name: VersionTag, Pattern: `(^|/)VERSION$`},
		{Name: LockfileTag, Pattern: `(^|/)(go\.sum|go\.work\.sum|uv\.lock|poetry\.lock|Pipfile\.lock|pdm\.lock|pylock(\.[^/]+)?\.toml|package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|Cargo\.lock|Gemfile\.lock|composer\.lock)$`},
		{Name: GeneratedTag, Pattern: `(?i)\.generated\.[^/]+$`},
		{Name: GeneratedTag, Pattern: `(?i)\.(gen\.go|pb(\.gw)?\.go)$`},
		{Name: GeneratedTag, Pattern: `(?i)_pb2(_grpc)?\.pyi?$`},
		{Name: GeneratedTag, Pattern: `(?i)\.(pb\.(cc|h)|pb-c\.(c|h))$`},
		{Name: GeneratedTag, Pattern: `(?i)(\.capnp\.(h|c\+\+|go|ts)|_capnp\.(rs|py))$`},
		// Source maps need no grammar; a bare .map or declaration file is ambiguous.
		{Name: GeneratedTag, Pattern: `(?i)\.(js|jsx|mjs|cjs|css|d\.(ts|mts|cts))\.map$`},
		{Name: GeneratedTag, Pattern: `(?i)(^|/)kitex_gen(/|$)`},
		{Name: TestTag, Pattern: `(?i)(^|/)[^/]*_test\.(go|rs)$`},
		{Name: TestTag, Pattern: `(?i)(^|/)(test_[^/]*|[^/]*_test)\.py$`},
		{Name: TestTag, Pattern: `(^|/)[^/]*\.(test|spec)\.[^/]+$`, Languages: []string{"javascript", "typescript", "tsx"}},
		{Name: TestTag, Pattern: `(^|/)__tests__/`, Languages: []string{"javascript", "typescript", "tsx"}},
		{Name: TestTag, Pattern: `(?i)(^|/)[^/]*_spec\.rb$`},
		{Name: TestTag, Pattern: `(^|/)[^/]*Tests?\.java$|(^|/)src/test/.*\.(java|kt)$`},
		{Name: TestTag, Pattern: `(?i)\.test\.ets$`},
		{Name: TestFixtureTag, Pattern: `(^|/)(testdata|fixtures|snapshots|__snapshots__)(/|$)`},
		{Name: DependencyTag, Pattern: `(?i)(^|/)(vendor|node_modules|oh_modules|bower_components|\.pnpm-store|\.bundle|\.venv|venv|site-packages|pods|carthage)(/|$)`},
		{Name: DependencyTag, Pattern: `(?i)(^|/)\.yarn/(cache|unplugged|releases|sdks)(/|$)|(^|/)\.pnp\.(cjs|loader\.mjs)$|(^|/)[^/]*\.egg-info(/|$)`},
		{Name: BuildOutputTag, Pattern: `(?i)(^|/)(dist|\.next|\.nuxt|\.svelte-kit|\.astro|\.docusaurus|target|\.build|obj)(/|$)|(^|/)coverage/lcov-report(/|$)`},
		{Name: CacheTag, Pattern: `(?i)(^|/)(\.cache|__pycache__|\.pytest_cache|\.mypy_cache|\.ruff_cache|\.happypack|\.turbo|\.angular|\.parcel-cache|\.gradle|\.tox|\.dart_tool|\.terraform|\.stack-work)(/|$)`},
		{Name: MinifiedTag, Pattern: `(?i)\.min\.(js|css)$`},
		{Name: ToolingTag, Pattern: `(^|/)(\.git|\.svn|\.idea|\.vscode|\.codebase|\.devloop|\.codex|\.claude|\.agents|\.cursor)(/|$)`},
		{Name: ConfigTag, Pattern: `(^|/)(\.dockerignore|\.gitignore|\.ignore|\.gitattributes|\.editorconfig|\.env(\.[^/]+)?)$`},
		{Name: ToolingTag, Pattern: `(^|/)(AGENTS|CLAUDE|GEMINI)\.md$`},
	}
}

type compiledTagRule struct {
	name      Tag
	pattern   *regexp.Regexp
	languages []string
}

// TagMatcher applies compiled path rules without reading files or constructing a graph.
// It is immutable after construction and safe for concurrent Match calls.
// The zero value has no path rules; DocumentTags still classifies formats.
type TagMatcher struct {
	rules []compiledTagRule
}

// NewTagMatcher validates and compiles rules. Nil selects BuiltinTagRules;
// an explicit empty slice disables path tags. Later changes to rules do not affect
// the matcher. Invalid regular expressions and blank names return an error.
// +why=Graph construction and consumers share one path classification implementation.
func NewTagMatcher(rules []TagRule) (*TagMatcher, error) {
	if rules == nil {
		rules = BuiltinTagRules()
	}
	out := make([]compiledTagRule, 0, len(rules))
	for i, rule := range rules {
		if strings.TrimSpace(string(rule.Name)) == "" {
			return nil, fmt.Errorf("tag rule %d: name is required", i)
		}
		pattern, err := regexp.Compile(rule.Pattern)
		if err != nil {
			return nil, fmt.Errorf("tag rule %d (%q): %w", i, rule.Name, err)
		}
		out = append(out, compiledTagRule{name: rule.Name, pattern: pattern, languages: slices.Clone(rule.Languages)})
	}
	return &TagMatcher{rules: out}, nil
}

// Match returns all matching tags, deduplicated and sorted by name, or nil if none match.
// Path must be a normalized snapshot-relative, slash-separated path; directory
// paths have no trailing slash and the root is ".". Match does not normalize paths.
// The returned slice belongs to the caller. Tags are not inherited from ancestors.
func (m *TagMatcher) Match(path string) []Tag {
	var tags []Tag
	seen := map[Tag]bool{}
	for _, rule := range m.rules {
		if seen[rule.name] || !rule.pattern.MatchString(path) {
			continue
		}
		if len(rule.languages) > 0 && !slices.Contains(rule.languages, Language(path)) {
			continue
		}
		seen[rule.name] = true
		tags = append(tags, rule.name)
	}
	sort.Slice(tags, func(i, j int) bool { return tags[i] < tags[j] })
	return tags
}

// DocumentTags combines format classification with direct path tags without parsing
// content. Gitlinks remain opaque and skip format classification, even at source paths.
// Empty TagRules disables path rules, not format classification or the unknown fallback.
// +spec=Documents with no format or direct path tags receive UnknownTag; Match and Directory tags have no fallback.
// +why=Consumers can count unclassified materials using the same tag vocabulary as classified documents.
// +link=component://docs/document.md
// +case=unknown_document_tags
func (m *TagMatcher) DocumentTags(d Document) []Tag {
	tags := m.Match(d.Path)
	if d.Gitlink == "" {
		if tag := Tag(language.MaterialTag(d.Path)); tag != "" && !slices.Contains(tags, tag) {
			tags = append(tags, tag)
			slices.Sort(tags)
		}
	}
	if len(tags) == 0 {
		return []Tag{UnknownTag}
	}
	return tags
}

// ExcludedBy returns the first matching exclusion tag on the document or an
// ancestor directory, or empty when admitted. It does not inherit directory tags
// into DocumentTags. Document paths must be normalized snapshot-relative paths.
// +spec=Consumers and Builder apply the same material exclusions before parsing and document budgets.
func (m *TagMatcher) ExcludedBy(d Document, excluded []Tag) Tag {
	if len(excluded) == 0 {
		return ""
	}
	for _, tag := range m.DocumentTags(d) {
		if slices.Contains(excluded, tag) {
			return tag
		}
	}
	for current := path.Dir(d.Path); ; current = path.Dir(current) {
		for _, tag := range m.Match(current) {
			if slices.Contains(excluded, tag) {
				return tag
			}
		}
		if current == "." {
			return ""
		}
	}
}