contextctl.go

// Copyright 2026 Tyler Pate (TGPSKI)
// SPDX-License-Identifier: GPL-3.0-only
//
// contextctl — deterministic tooling for the Directed Contexts pattern.
//
//	contextctl scan   --repo PATH                 emit a JSON repository inventory
//	contextctl check  --repo PATH [--inventory F] validate the Markdown context set
//	contextctl routes --repo PATH --cases FILE    evaluate route-case fixtures
//	contextctl drift  --repo PATH                 report codebase/context-set drift
//
// The root AGENTS.md routing table is canonical. This tool parses and
// validates the Markdown contract directly; there is no hidden manifest.
// The scanner is read-only: it never writes, never follows symlinks outside
// the repository, and never executes commands found in repository files.
package main

import (
	"encoding/json"
	"flag"
	"fmt"
	"os"
	"path/filepath"
	"regexp"
	"sort"
	"strings"
	"time"
)

func main() {
	if len(os.Args) < 2 {
		usage()
		os.Exit(2)
	}
	var err error
	switch os.Args[1] {
	case "scan":
		err = cmdScan(os.Args[2:])
	case "check":
		err = cmdCheck(os.Args[2:])
	case "routes":
		err = cmdRoutes(os.Args[2:])
	case "drift":
		err = cmdDrift(os.Args[2:])
	case "-h", "--help", "help":
		usage()
	default:
		fmt.Fprintf(os.Stderr, "contextctl: unknown subcommand %q\n", os.Args[1])
		usage()
		os.Exit(2)
	}
	if err != nil {
		fmt.Fprintf(os.Stderr, "contextctl: %v\n", err)
		os.Exit(1)
	}
}

func usage() {
	fmt.Fprint(os.Stderr, `usage:
  contextctl scan   --repo PATH                  emit JSON repository inventory
  contextctl check  --repo PATH [--inventory F]  validate the context set
                    [--max-lines N]
  contextctl routes --repo PATH --cases FILE     evaluate route-case fixtures
  contextctl drift  --repo PATH [--max-age-days N] [--max-lines N] [--min-lines N]
`)
}

// ───────────────────────────── inventory (scan) ─────────────────────────────

// Inventory is the deterministic scan output. Field order is fixed and all
// slices are sorted so identical repository state yields byte-stable JSON.
type Inventory struct {
	Repo           RepoMeta        `json:"repo"`
	PackageRoots   []PackageRoot   `json:"package_roots"`
	Languages      []string        `json:"languages"`
	EntryPoints    []string        `json:"entry_points"`
	Instructions   Instructions    `json:"instruction_surfaces"`
	Codeowners     []CodeownerRule `json:"codeowners_rules"`
	Commands       []Command       `json:"commands"`
	GeneratedPaths []string        `json:"generated_paths"`
	VendoredPaths  []string        `json:"vendored_paths"`
	SymlinkEscapes []string        `json:"symlink_escapes"`
	PolicySignals  []string        `json:"policy_signals"`
	Files          []string        `json:"files"`
}

type RepoMeta struct {
	Name   string `json:"name"`
	HasGit bool   `json:"has_git"`
}

type PackageRoot struct {
	Path      string   `json:"path"`
	Manifests []string `json:"manifests"`
}

type Instructions struct {
	PrimarySurface  string   `json:"primary_surface"`
	RootAgentsMD    bool     `json:"root_agents_md"`
	HasRoutingTable bool     `json:"has_routing_table"`
	NestedAgentsMD  []string `json:"nested_agents_md"`
	HarnessAliases  []string `json:"harness_aliases"`
	Subagents       []string `json:"subagents"`
	NativeAgents    []string `json:"native_agents"`
	Skills          []string `json:"skills"`
	CodeownersPath  string   `json:"codeowners_path"`
}

type CodeownerRule struct {
	Pattern string   `json:"pattern"`
	Owners  []string `json:"owners"`
}

type Command struct {
	Source string `json:"source"`
	Name   string `json:"name"`
}

var skipDirs = map[string]bool{
	".git": true, "node_modules": true, "vendor": true, "dist": true,
	"build": true, "target": true, ".venv": true, "venv": true,
	"__pycache__": true, ".next": true, ".cache": true, ".terraform": true,
	".tox": true, ".mypy_cache": true, ".pytest_cache": true, "coverage": true,
}

var vendorDirNames = map[string]bool{
	"node_modules": true, "vendor": true, ".venv": true, "venv": true,
	".terraform": true,
}

var generatedDirNames = map[string]bool{
	"dist": true, "build": true, "target": true, "__pycache__": true,
	".next": true, "coverage": true,
}

var manifestLang = map[string]string{
	"go.mod":           "go",
	"package.json":     "javascript",
	"tsconfig.json":    "typescript",
	"pyproject.toml":   "python",
	"setup.py":         "python",
	"requirements.txt": "python",
	"Cargo.toml":       "rust",
	"pom.xml":          "java",
	"build.gradle":     "java",
	"Gemfile":          "ruby",
	"composer.json":    "php",
	"CMakeLists.txt":   "c/c++",
}

// packageManifests mark a directory as a package root.
var packageManifests = map[string]bool{
	"go.mod": true, "package.json": true, "pyproject.toml": true,
	"setup.py": true, "Cargo.toml": true, "pom.xml": true,
	"build.gradle": true, "Gemfile": true, "composer.json": true,
	"CMakeLists.txt": true,
}

const maxReadBytes = 1 << 20 // never read repository files larger than 1 MiB

func cmdScan(args []string) error {
	fs := flag.NewFlagSet("scan", flag.ExitOnError)
	repo := fs.String("repo", "", "path to the target repository root")
	fs.Parse(args)
	if *repo == "" {
		return fmt.Errorf("scan: --repo is required")
	}
	inv, err := scanRepo(*repo)
	if err != nil {
		return err
	}
	out, err := json.MarshalIndent(inv, "", "  ")
	if err != nil {
		return err
	}
	fmt.Println(string(out))
	return nil
}

func scanRepo(root string) (*Inventory, error) {
	absRoot, err := filepath.Abs(root)
	if err != nil {
		return nil, err
	}
	info, err := os.Stat(absRoot)
	if err != nil || !info.IsDir() {
		return nil, fmt.Errorf("scan: %s is not a directory", root)
	}

	inv := &Inventory{Repo: RepoMeta{Name: filepath.Base(absRoot)}}
	if st, err := os.Stat(filepath.Join(absRoot, ".git")); err == nil && st.IsDir() {
		inv.Repo.HasGit = true
	}

	pkgRoots := map[string][]string{}
	langs := map[string]bool{}
	entryPoints := map[string]bool{}

	walkErr := filepath.WalkDir(absRoot, func(path string, d os.DirEntry, err error) error {
		if err != nil {
			return nil // unreadable entries are skipped, not fatal
		}
		rel, _ := filepath.Rel(absRoot, path)
		rel = filepath.ToSlash(rel)
		if rel == "." {
			return nil
		}
		name := d.Name()

		if d.Type()&os.ModeSymlink != 0 {
			target, rerr := filepath.EvalSymlinks(path)
			if rerr != nil || !strings.HasPrefix(target+string(os.PathSeparator), absRoot+string(os.PathSeparator)) {
				inv.SymlinkEscapes = append(inv.SymlinkEscapes, rel)
			}
			if d.IsDir() {
				return filepath.SkipDir // never descend through symlinks
			}
			inv.Files = append(inv.Files, rel)
			return nil
		}

		if d.IsDir() {
			if skipDirs[name] {
				if vendorDirNames[name] {
					inv.VendoredPaths = append(inv.VendoredPaths, rel)
				} else if generatedDirNames[name] {
					inv.GeneratedPaths = append(inv.GeneratedPaths, rel)
				}
				return filepath.SkipDir
			}
			return nil
		}

		inv.Files = append(inv.Files, rel)
		dir := filepath.ToSlash(filepath.Dir(rel))

		if packageManifests[name] {
			pkgRoots[dir] = append(pkgRoots[dir], name)
		}
		if lang, ok := manifestLang[name]; ok {
			langs[lang] = true
		}
		switch {
		case name == "main.go":
			entryPoints[dir] = true
		case strings.HasPrefix(name, "Dockerfile"):
			entryPoints[rel] = true
		case strings.HasPrefix(rel, ".github/workflows/"):
			entryPoints[rel] = true
		}
		return nil
	})
	if walkErr != nil {
		return nil, walkErr
	}

	sort.Strings(inv.Files)
	inv.Languages = sortedKeys(langs)
	for _, dir := range sortedKeys2(pkgRoots) {
		ms := pkgRoots[dir]
		sort.Strings(ms)
		inv.PackageRoots = append(inv.PackageRoots, PackageRoot{Path: dir, Manifests: ms})
	}
	inv.EntryPoints = sortedKeys(entryPoints)
	sort.Strings(inv.GeneratedPaths)
	sort.Strings(inv.VendoredPaths)
	sort.Strings(inv.SymlinkEscapes)

	scanInstructionSurfaces(absRoot, inv)
	scanCodeowners(absRoot, inv)
	scanCommands(absRoot, inv)
	scanPolicySignals(absRoot, inv)
	normalizeEmpty(inv)
	return inv, nil
}

func scanInstructionSurfaces(root string, inv *Inventory) {
	ins := &inv.Instructions
	for _, f := range inv.Files {
		base := filepath.Base(f)
		switch {
		case f == "AGENTS.md":
			ins.RootAgentsMD = true
			if body, err := readSmall(filepath.Join(root, f)); err == nil {
				ins.HasRoutingTable = strings.Contains(body, "Load this context")
			}
		case base == "AGENTS.md":
			ins.NestedAgentsMD = append(ins.NestedAgentsMD, f)
		case base == "CLAUDE.md" || base == "CODEX.md" || base == "GEMINI.md" || base == ".cursorrules":
			ins.HarnessAliases = append(ins.HarnessAliases, f)
		}
		switch {
		case strings.HasPrefix(f, ".subagents/"):
			ins.Subagents = append(ins.Subagents, f)
		case strings.HasPrefix(f, ".claude/agents/") || strings.HasPrefix(f, ".github/agents/") ||
			strings.HasPrefix(f, ".opencode/agents/"):
			ins.NativeAgents = append(ins.NativeAgents, f)
		case base == "SKILL.md":
			ins.Skills = append(ins.Skills, f)
		}
	}
	sort.Strings(ins.NestedAgentsMD)
	sort.Strings(ins.HarnessAliases)
	sort.Strings(ins.Subagents)
	sort.Strings(ins.NativeAgents)
	sort.Strings(ins.Skills)
	ins.PrimarySurface = primaryInstructionSurface(ins)
}

// primaryInstructionSurface names the root file an agent should read first, by
// precedence: the Context Router, then a root SKILL.md (skill repositories),
// then a router-less root AGENTS.md, then the first root harness alias. Empty
// when the repository has no root instruction surface.
func primaryInstructionSurface(ins *Instructions) string {
	if ins.RootAgentsMD && ins.HasRoutingTable {
		return "AGENTS.md"
	}
	for _, s := range ins.Skills {
		if s == "SKILL.md" {
			return "SKILL.md"
		}
	}
	if ins.RootAgentsMD {
		return "AGENTS.md"
	}
	for _, a := range ins.HarnessAliases {
		if !strings.Contains(a, "/") {
			return a
		}
	}
	return ""
}

func scanCodeowners(root string, inv *Inventory) {
	for _, cand := range []string{".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS"} {
		body, err := readSmall(filepath.Join(root, cand))
		if err != nil {
			continue
		}
		inv.Instructions.CodeownersPath = cand
		for _, line := range strings.Split(body, "\n") {
			line = strings.TrimSpace(line)
			if line == "" || strings.HasPrefix(line, "#") {
				continue
			}
			fields := strings.Fields(line)
			if len(fields) < 2 {
				continue
			}
			inv.Codeowners = append(inv.Codeowners, CodeownerRule{Pattern: fields[0], Owners: fields[1:]})
		}
		break
	}
}

var makeTargetRE = regexp.MustCompile(`^([A-Za-z0-9][A-Za-z0-9_./-]*):(?:[^=]|$)`)

func scanCommands(root string, inv *Inventory) {
	if body, err := readSmall(filepath.Join(root, "Makefile")); err == nil {
		seen := map[string]bool{}
		for _, line := range strings.Split(body, "\n") {
			if m := makeTargetRE.FindStringSubmatch(line); m != nil && !seen[m[1]] {
				seen[m[1]] = true
			}
		}
		for _, t := range sortedKeys(seen) {
			inv.Commands = append(inv.Commands, Command{Source: "makefile", Name: t})
		}
	}
	if body, err := readSmall(filepath.Join(root, "package.json")); err == nil {
		var pkg struct {
			Scripts map[string]string `json:"scripts"`
		}
		if json.Unmarshal([]byte(body), &pkg) == nil {
			names := make([]string, 0, len(pkg.Scripts))
			for n := range pkg.Scripts {
				names = append(names, n)
			}
			sort.Strings(names)
			for _, n := range names {
				inv.Commands = append(inv.Commands, Command{Source: "package.json", Name: n})
			}
		}
	}
}

func scanPolicySignals(root string, inv *Inventory) {
	signals := map[string]bool{}
	for _, f := range inv.Files {
		base := filepath.Base(f)
		switch {
		case f == "SECURITY.md" || base == ".trivyignore" || base == ".snyk" || base == ".semgrepignore" || base == ".security-context.yaml":
			signals["security:"+f] = true
		case strings.HasPrefix(f, ".github/workflows/"):
			signals["operations:.github/workflows"] = true
		case strings.HasPrefix(base, "Dockerfile"):
			signals["operations:"+f] = true
		case base == ".golangci.yml" || base == ".eslintrc.json" || base == ".eslintrc.js" || base == "ruff.toml" || base == ".ruff.toml":
			signals["quality:"+f] = true
		case strings.HasSuffix(base, "_test.go") || strings.HasPrefix(f, "tests/") || strings.HasPrefix(f, "test/"):
			signals["quality:tests"] = true
		}
	}
	inv.PolicySignals = sortedKeys(signals)
}

// normalizeEmpty replaces nil slices so JSON renders [] instead of null.
func normalizeEmpty(inv *Inventory) {
	if inv.PackageRoots == nil {
		inv.PackageRoots = []PackageRoot{}
	}
	if inv.Languages == nil {
		inv.Languages = []string{}
	}
	if inv.EntryPoints == nil {
		inv.EntryPoints = []string{}
	}
	if inv.Instructions.NestedAgentsMD == nil {
		inv.Instructions.NestedAgentsMD = []string{}
	}
	if inv.Instructions.HarnessAliases == nil {
		inv.Instructions.HarnessAliases = []string{}
	}
	if inv.Instructions.Subagents == nil {
		inv.Instructions.Subagents = []string{}
	}
	if inv.Instructions.NativeAgents == nil {
		inv.Instructions.NativeAgents = []string{}
	}
	if inv.Instructions.Skills == nil {
		inv.Instructions.Skills = []string{}
	}
	if inv.Codeowners == nil {
		inv.Codeowners = []CodeownerRule{}
	}
	if inv.Commands == nil {
		inv.Commands = []Command{}
	}
	if inv.GeneratedPaths == nil {
		inv.GeneratedPaths = []string{}
	}
	if inv.VendoredPaths == nil {
		inv.VendoredPaths = []string{}
	}
	if inv.SymlinkEscapes == nil {
		inv.SymlinkEscapes = []string{}
	}
	if inv.PolicySignals == nil {
		inv.PolicySignals = []string{}
	}
	if inv.Files == nil {
		inv.Files = []string{}
	}
}

// ─────────────────────── markdown contract parsing ──────────────────────────

// Context is one parsed .subagents/AGENTS-*.md module.
type Context struct {
	File         string // repo-relative path
	Name         string
	Kind         string // domain | policy
	Description  string
	Sections     map[string][]string
	SectionOrder []string
	OwnedGlobs   []string
	LastReviewed string
	LineCount    int
	Body         string
}

// Router is the parsed root AGENTS.md.
type Router struct {
	File           string
	PrimaryRows    []RouterRow
	OverlayRows    []RouterRow
	UniversalRules []string
	Links          []string // all relative link targets in the file
	Body           string
}

type RouterRow struct {
	Signal string   // column 1
	Target string   // link target from column 2
	Globs  []string // code spans from column 3
}

var (
	linkRE     = regexp.MustCompile(`\[([^\]]*)\]\(([^)\s]+)\)`)
	codeSpanRE = regexp.MustCompile("`([^`]+)`")
	reviewedRE = regexp.MustCompile(`Last reviewed:\s*(\d{4}-\d{2}-\d{2})`)
)

func parseFrontmatter(lines []string) (meta map[string]string, bodyStart int) {
	meta = map[string]string{}
	if len(lines) == 0 || strings.TrimSpace(lines[0]) != "---" {
		return meta, 0
	}
	for i := 1; i < len(lines); i++ {
		if strings.TrimSpace(lines[i]) == "---" {
			return meta, i + 1
		}
		if k, v, ok := strings.Cut(lines[i], ":"); ok {
			key := strings.TrimSpace(k)
			val := strings.Trim(strings.TrimSpace(v), `"'`)
			if key != "" && !strings.HasPrefix(key, "#") {
				meta[key] = val
			}
		}
	}
	return map[string]string{}, 0 // unterminated frontmatter: treat as body
}

func parseContextFile(repoRoot, relPath string) (*Context, []string) {
	var problems []string
	body, err := readSmall(filepath.Join(repoRoot, filepath.FromSlash(relPath)))
	if err != nil {
		return nil, []string{fmt.Sprintf("%s: unreadable: %v", relPath, err)}
	}
	lines := strings.Split(body, "\n")
	ctx := &Context{File: relPath, Sections: map[string][]string{}, LineCount: len(lines), Body: body}

	meta, bodyStart := parseFrontmatter(lines)
	ctx.Name = meta["name"]
	ctx.Kind = meta["kind"]
	ctx.Description = meta["description"]
	if ctx.Name == "" {
		problems = append(problems, fmt.Sprintf("%s: frontmatter missing `name`", relPath))
	}
	if ctx.Kind != "domain" && ctx.Kind != "policy" {
		problems = append(problems, fmt.Sprintf("%s: frontmatter `kind` must be domain or policy, got %q", relPath, ctx.Kind))
	}
	if ctx.Description == "" {
		problems = append(problems, fmt.Sprintf("%s: frontmatter missing `description`", relPath))
	}

	current := ""
	for _, line := range lines[bodyStart:] {
		if strings.HasPrefix(line, "## ") {
			current = strings.TrimSpace(strings.TrimPrefix(line, "## "))
			ctx.SectionOrder = append(ctx.SectionOrder, current)
			continue
		}
		if current != "" {
			ctx.Sections[current] = append(ctx.Sections[current], line)
		}
	}

	for _, line := range ctx.Sections["Owned paths"] {
		trimmed := strings.TrimSpace(line)
		if !strings.HasPrefix(trimmed, "- ") {
			continue
		}
		if m := codeSpanRE.FindStringSubmatch(trimmed); m != nil {
			ctx.OwnedGlobs = append(ctx.OwnedGlobs, m[1])
		}
	}

	if m := reviewedRE.FindStringSubmatch(body); m != nil {
		if _, terr := time.Parse("2006-01-02", m[1]); terr != nil {
			problems = append(problems, fmt.Sprintf("%s: invalid review date %q", relPath, m[1]))
		} else {
			ctx.LastReviewed = m[1]
		}
	} else {
		problems = append(problems, fmt.Sprintf("%s: missing `Last reviewed: YYYY-MM-DD` footer", relPath))
	}
	return ctx, problems
}

var domainSections = []string{
	"Scope", "Load or spawn", "Owned paths", "Exclusions",
	"Architecture and invariants", "Common mistakes", "Verification", "Adjacent contexts",
}

var policySections = []string{
	"Scope", "Policy surface", "Affected contexts", "Invariants", "Activation", "Review checklist",
}

func parseRouter(repoRoot string) (*Router, []string) {
	rel := "AGENTS.md"
	body, err := readSmall(filepath.Join(repoRoot, rel))
	if err != nil {
		return nil, []string{fmt.Sprintf("%s: missing root router: %v", rel, err)}
	}
	r := &Router{File: rel, Body: body}
	lines := strings.Split(body, "\n")

	r.PrimaryRows = parseRoutingTable(lines, "Load this context")
	r.OverlayRows = parseRoutingTable(lines, "Add this context")

	inUniversal := false
	for _, line := range lines {
		if strings.HasPrefix(line, "## ") {
			inUniversal = strings.Contains(line, "Universal rules")
			continue
		}
		if inUniversal {
			t := strings.TrimSpace(line)
			if strings.HasPrefix(t, "- ") {
				r.UniversalRules = append(r.UniversalRules, strings.TrimSpace(strings.TrimPrefix(t, "- ")))
			}
		}
	}
	for _, m := range linkRE.FindAllStringSubmatch(body, -1) {
		target := m[2]
		if strings.Contains(target, "://") || strings.HasPrefix(target, "#") || strings.HasPrefix(target, "mailto:") {
			continue
		}
		r.Links = append(r.Links, strings.Split(target, "#")[0])
	}
	return r, nil
}

// parseRoutingTable extracts rows from the first Markdown table whose header
// row contains marker. Column layout: signal | context link | third column.
func parseRoutingTable(lines []string, marker string) []RouterRow {
	var rows []RouterRow
	inTable := false
	for _, line := range lines {
		trimmed := strings.TrimSpace(line)
		isRow := strings.HasPrefix(trimmed, "|")
		if !inTable {
			if isRow && strings.Contains(trimmed, marker) {
				inTable = true
			}
			continue
		}
		if !isRow {
			break
		}
		cells := splitTableRow(trimmed)
		if len(cells) < 2 || strings.HasPrefix(strings.ReplaceAll(cells[0], " ", ""), "---") {
			continue
		}
		row := RouterRow{Signal: cells[0]}
		if m := linkRE.FindStringSubmatch(cells[1]); m != nil {
			row.Target = strings.Split(m[2], "#")[0]
		}
		if len(cells) > 2 {
			for _, g := range codeSpanRE.FindAllStringSubmatch(cells[2], -1) {
				row.Globs = append(row.Globs, g[1])
			}
		}
		if row.Target != "" || row.Signal != "" {
			rows = append(rows, row)
		}
	}
	return rows
}

func splitTableRow(row string) []string {
	row = strings.Trim(row, "|")
	parts := strings.Split(row, "|")
	out := make([]string, len(parts))
	for i, p := range parts {
		out[i] = strings.TrimSpace(p)
	}
	return out
}

// ───────────────────────── ownership glob matching ──────────────────────────

// normGlob reduces a pattern to (base, isTree). `dir/**` and `dir/` are
// subtree claims; anything else is an exact file claim.
func normGlob(g string) (base string, isTree bool) {
	g = strings.TrimPrefix(strings.TrimSpace(g), "./")
	switch {
	case strings.HasSuffix(g, "/**"):
		return strings.TrimSuffix(g, "/**"), true
	case strings.HasSuffix(g, "/"):
		return strings.TrimSuffix(g, "/"), true
	default:
		return g, false
	}
}

// globMatches reports whether pattern covers path. A path with a trailing
// slash is a directory reference and also matches patterns beneath it.
func globMatches(pattern, path string) bool {
	base, isTree := normGlob(pattern)
	pathIsDir := strings.HasSuffix(path, "/")
	p := strings.TrimSuffix(strings.TrimPrefix(path, "./"), "/")
	if isTree {
		if p == base || strings.HasPrefix(p, base+"/") {
			return true
		}
		if pathIsDir && strings.HasPrefix(base, p+"/") {
			return true // task dir encloses the owned subtree
		}
		return false
	}
	if p == base {
		return true
	}
	return pathIsDir && strings.HasPrefix(base, p+"/")
}

// globsOverlap reports whether two ownership claims can cover the same file.
func globsOverlap(a, b string) bool {
	ab, at := normGlob(a)
	bb, bt := normGlob(b)
	switch {
	case at && bt:
		return ab == bb || strings.HasPrefix(ab, bb+"/") || strings.HasPrefix(bb, ab+"/")
	case at:
		return bb == ab || strings.HasPrefix(bb, ab+"/")
	case bt:
		return ab == bb || strings.HasPrefix(ab, bb+"/")
	default:
		return ab == bb
	}
}

// pathExists checks a glob base against the filesystem or an inventory list.
func pathExists(repoRoot, glob string, invFiles []string) bool {
	base, isTree := normGlob(glob)
	if len(invFiles) > 0 {
		for _, f := range invFiles {
			if f == base || (isTree && strings.HasPrefix(f, base+"/")) {
				return true
			}
		}
		return false
	}
	st, err := os.Stat(filepath.Join(repoRoot, filepath.FromSlash(base)))
	if err != nil {
		return false
	}
	if isTree {
		return st.IsDir()
	}
	return true
}

// ─────────────────────────── context set loading ────────────────────────────

type ContextSet struct {
	Root     string
	Router   *Router
	Contexts []*Context // sorted by file name
	ByName   map[string]*Context
	Problems []string
}

func loadContextSet(repoRoot string) *ContextSet {
	cs := &ContextSet{Root: repoRoot, ByName: map[string]*Context{}}

	router, probs := parseRouter(repoRoot)
	cs.Problems = append(cs.Problems, probs...)
	cs.Router = router

	subDir := filepath.Join(repoRoot, ".subagents")
	entries, err := os.ReadDir(subDir)
	if err != nil {
		cs.Problems = append(cs.Problems, ".subagents/: missing directory")
		return cs
	}
	var names []string
	for _, e := range entries {
		if !e.IsDir() && strings.HasPrefix(e.Name(), "AGENTS-") && strings.HasSuffix(e.Name(), ".md") {
			names = append(names, e.Name())
		}
	}
	sort.Strings(names)
	for _, n := range names {
		ctx, probs := parseContextFile(repoRoot, ".subagents/"+n)
		cs.Problems = append(cs.Problems, probs...)
		if ctx == nil {
			continue
		}
		cs.Contexts = append(cs.Contexts, ctx)
		if ctx.Name != "" {
			if prev, dup := cs.ByName[ctx.Name]; dup {
				cs.Problems = append(cs.Problems, fmt.Sprintf("%s: duplicate context name %q (also %s)", ctx.File, ctx.Name, prev.File))
			} else {
				cs.ByName[ctx.Name] = ctx
			}
		}
	}
	return cs
}

func (cs *ContextSet) domains() []*Context {
	var out []*Context
	for _, c := range cs.Contexts {
		if c.Kind == "domain" {
			out = append(out, c)
		}
	}
	return out
}

// ownersOf returns the sorted names of domain contexts owning path.
func (cs *ContextSet) ownersOf(path string) []string {
	seen := map[string]bool{}
	for _, c := range cs.domains() {
		for _, g := range c.OwnedGlobs {
			if globMatches(g, path) {
				seen[c.Name] = true
			}
		}
	}
	return sortedKeys(seen)
}

// ──────────────────────────────── check ─────────────────────────────────────

func cmdCheck(args []string) error {
	fs := flag.NewFlagSet("check", flag.ExitOnError)
	repo := fs.String("repo", "", "path to the target repository root")
	invPath := fs.String("inventory", "", "scan JSON to validate path existence against (instead of disk)")
	maxLines := fs.Int("max-lines", 400, "maximum lines per context guide")
	fs.Parse(args)
	if *repo == "" {
		return fmt.Errorf("check: --repo is required")
	}

	var invFiles []string
	if *invPath != "" {
		data, err := os.ReadFile(*invPath)
		if err != nil {
			return fmt.Errorf("check: %v", err)
		}
		var inv Inventory
		if err := json.Unmarshal(data, &inv); err != nil {
			return fmt.Errorf("check: parsing inventory: %v", err)
		}
		invFiles = inv.Files
	}

	findings := runCheck(*repo, invFiles, *maxLines)
	for _, f := range findings {
		fmt.Println("FAIL " + f)
	}
	if len(findings) > 0 {
		return fmt.Errorf("check: %d finding(s)", len(findings))
	}
	fmt.Println("OK   context set is valid")
	return nil
}

func runCheck(repoRoot string, invFiles []string, maxLines int) []string {
	cs := loadContextSet(repoRoot)
	findings := append([]string{}, cs.Problems...)
	if cs.Router == nil {
		return findings
	}

	// Required sections per kind; policy contexts must not claim paths.
	for _, c := range cs.Contexts {
		required := domainSections
		if c.Kind == "policy" {
			required = policySections
		}
		for _, sec := range required {
			if _, ok := c.Sections[sec]; !ok {
				findings = append(findings, fmt.Sprintf("%s: missing required section `## %s`", c.File, sec))
			}
		}
		if c.Kind == "policy" {
			if _, ok := c.Sections["Owned paths"]; ok {
				findings = append(findings, fmt.Sprintf("%s: policy overlay must not have an `## Owned paths` section", c.File))
			}
		}
		if c.Kind == "domain" && len(c.OwnedGlobs) == 0 {
			findings = append(findings, fmt.Sprintf("%s: domain context declares no owned paths", c.File))
		}
		if c.LineCount > maxLines {
			findings = append(findings, fmt.Sprintf("%s: %d lines exceeds limit %d (split candidate)", c.File, c.LineCount, maxLines))
		}
		// Verification / review checklist must be concrete.
		checkSec, item := "Verification", "command or path in backticks"
		if c.Kind == "policy" {
			checkSec, item = "Review checklist", "checklist item"
		}
		if lines, ok := c.Sections[checkSec]; ok {
			concrete := false
			for _, l := range lines {
				if c.Kind == "policy" && strings.Contains(l, "- [ ]") {
					concrete = true
				}
				if c.Kind == "domain" && codeSpanRE.MatchString(l) {
					concrete = true
				}
			}
			if !concrete {
				findings = append(findings, fmt.Sprintf("%s: `## %s` has no concrete %s", c.File, checkSec, item))
			}
		}
	}

	// Router link resolution (all relative links).
	for _, target := range cs.Router.Links {
		if !fileExistsRel(repoRoot, target, invFiles, cs) {
			findings = append(findings, fmt.Sprintf("AGENTS.md: link target %s does not resolve", target))
		}
	}

	// Router tables ↔ context files.
	routed := map[string]string{} // context file -> table ("primary"|"overlay")
	for _, row := range cs.Router.PrimaryRows {
		routed[row.Target] = "primary"
		c := cs.contextByFile(row.Target)
		if c == nil {
			findings = append(findings, fmt.Sprintf("AGENTS.md: routing row %q links %s which is not a parseable context", row.Signal, row.Target))
			continue
		}
		if c.Kind != "domain" {
			findings = append(findings, fmt.Sprintf("AGENTS.md: primary routing row links %s (kind %s); only domain contexts belong in the primary table", row.Target, c.Kind))
		}
		for _, g := range row.Globs {
			if !containsGlob(c.OwnedGlobs, g) {
				findings = append(findings, fmt.Sprintf("AGENTS.md: Owns column lists `%s` for %s but the context does not declare it", g, row.Target))
			}
		}
	}
	for _, row := range cs.Router.OverlayRows {
		routed[row.Target] = "overlay"
		c := cs.contextByFile(row.Target)
		if c == nil {
			findings = append(findings, fmt.Sprintf("AGENTS.md: overlay row %q links %s which is not a parseable context", row.Signal, row.Target))
			continue
		}
		if c.Kind != "policy" {
			findings = append(findings, fmt.Sprintf("AGENTS.md: overlay row links %s (kind %s); only policy contexts belong in the overlay table", row.Target, c.Kind))
		}
	}
	for _, c := range cs.Contexts {
		if _, ok := routed[c.File]; !ok {
			findings = append(findings, fmt.Sprintf("%s: not referenced by any routing table in AGENTS.md", c.File))
		}
	}

	// Index agreement.
	indexPath := filepath.Join(repoRoot, ".subagents", "README.md")
	if body, err := readSmall(indexPath); err != nil {
		findings = append(findings, ".subagents/README.md: missing index")
	} else {
		indexed := map[string]bool{}
		for _, m := range linkRE.FindAllStringSubmatch(body, -1) {
			t := strings.Split(m[2], "#")[0]
			if strings.HasPrefix(t, "AGENTS-") {
				indexed[t] = true
				if cs.contextByFile(".subagents/"+t) == nil {
					findings = append(findings, fmt.Sprintf(".subagents/README.md: links %s which does not exist", t))
				}
			}
		}
		for _, c := range cs.Contexts {
			if !indexed[strings.TrimPrefix(c.File, ".subagents/")] {
				findings = append(findings, fmt.Sprintf(".subagents/README.md: does not index %s", c.File))
			}
		}
	}

	// Ownership disjointness.
	findings = append(findings, ownershipOverlaps(cs)...)

	// Owned paths must exist.
	for _, c := range cs.domains() {
		for _, g := range c.OwnedGlobs {
			if !pathExists(repoRoot, g, invFiles) {
				findings = append(findings, fmt.Sprintf("%s: owned path `%s` does not exist", c.File, g))
			}
		}
	}

	// Adjacent / affected links resolve to real contexts.
	for _, c := range cs.Contexts {
		sec := "Adjacent contexts"
		if c.Kind == "policy" {
			sec = "Affected contexts"
		}
		for _, line := range c.Sections[sec] {
			for _, m := range linkRE.FindAllStringSubmatch(line, -1) {
				t := strings.Split(m[2], "#")[0]
				if strings.Contains(t, "://") {
					continue
				}
				if cs.contextByFile(".subagents/"+t) == nil {
					findings = append(findings, fmt.Sprintf("%s: `## %s` links %s which is not a context in this set", c.File, sec, t))
				}
			}
		}
	}

	// Universal rules must not be duplicated into guides.
	for _, rule := range cs.Router.UniversalRules {
		if len(rule) < 20 {
			continue
		}
		for _, c := range cs.Contexts {
			if strings.Contains(c.Body, rule) {
				findings = append(findings, fmt.Sprintf("%s: duplicates universal rule %q from AGENTS.md; universal rules are inherited", c.File, truncate(rule, 60)))
			}
		}
	}

	return findings
}

func ownershipOverlaps(cs *ContextSet) []string {
	var findings []string
	doms := cs.domains()
	for i := 0; i < len(doms); i++ {
		for j := i + 1; j < len(doms); j++ {
			for _, ga := range doms[i].OwnedGlobs {
				for _, gb := range doms[j].OwnedGlobs {
					if globsOverlap(ga, gb) {
						findings = append(findings, fmt.Sprintf(
							"ownership overlap: `%s` (%s) vs `%s` (%s); every path needs exactly one primary owner",
							ga, doms[i].File, gb, doms[j].File))
					}
				}
			}
		}
	}
	return findings
}

func (cs *ContextSet) contextByFile(rel string) *Context {
	rel = strings.TrimPrefix(rel, "./")
	for _, c := range cs.Contexts {
		if c.File == rel {
			return c
		}
	}
	return nil
}

func fileExistsRel(repoRoot, target string, invFiles []string, cs *ContextSet) bool {
	target = strings.TrimPrefix(target, "./")
	if cs.contextByFile(target) != nil {
		return true
	}
	if len(invFiles) > 0 {
		for _, f := range invFiles {
			if f == target {
				return true
			}
		}
		// Inventory describes the source repo; generated files (index,
		// route cases) are checked on disk in the context-set tree.
	}
	_, err := os.Stat(filepath.Join(repoRoot, filepath.FromSlash(target)))
	return err == nil
}

func containsGlob(globs []string, g string) bool {
	for _, x := range globs {
		if x == g {
			return true
		}
	}
	return false
}

// ──────────────────────────────── routes ────────────────────────────────────

type RouteCase struct {
	Task             string   `json:"task"`
	Paths            []string `json:"paths"`
	ExpectedPrimary  []string `json:"expected_primary"`
	ExpectedOverlays []string `json:"expected_overlays"`
	RecommendedMode  string   `json:"recommended_mode"`
}

var validModes = map[string]bool{
	"inline": true, "spawn-single": true, "spawn-multiple": true, "ask": true,
}

func cmdRoutes(args []string) error {
	fs := flag.NewFlagSet("routes", flag.ExitOnError)
	repo := fs.String("repo", "", "path to the target repository root")
	cases := fs.String("cases", "", "route-cases JSON file")
	fs.Parse(args)
	if *repo == "" || *cases == "" {
		return fmt.Errorf("routes: --repo and --cases are required")
	}

	data, err := os.ReadFile(*cases)
	if err != nil {
		return fmt.Errorf("routes: %v", err)
	}
	var rcs []RouteCase
	if err := json.Unmarshal(data, &rcs); err != nil {
		return fmt.Errorf("routes: parsing cases: %v", err)
	}
	cs := loadContextSet(*repo)
	if cs.Router == nil {
		return fmt.Errorf("routes: %s has no parseable root AGENTS.md", *repo)
	}

	failures := 0
	for i, rc := range rcs {
		probs := evaluateRouteCase(cs, rc)
		if len(probs) == 0 {
			fmt.Printf("PASS case %02d: %s\n", i+1, rc.Task)
			continue
		}
		failures++
		fmt.Printf("FAIL case %02d: %s\n", i+1, rc.Task)
		for _, p := range probs {
			fmt.Printf("     %s\n", p)
		}
	}
	fmt.Printf("%d/%d route cases passed\n", len(rcs)-failures, len(rcs))
	if failures > 0 {
		return fmt.Errorf("routes: %d case(s) failed", failures)
	}
	return nil
}

func evaluateRouteCase(cs *ContextSet, rc RouteCase) []string {
	var probs []string
	if strings.TrimSpace(rc.Task) == "" {
		probs = append(probs, "case has an empty task description")
	}
	if !validModes[rc.RecommendedMode] {
		probs = append(probs, fmt.Sprintf("recommended_mode %q is not one of inline|spawn-single|spawn-multiple|ask", rc.RecommendedMode))
	}
	for _, name := range rc.ExpectedPrimary {
		c := cs.ByName[name]
		switch {
		case c == nil:
			probs = append(probs, fmt.Sprintf("expected primary context %q does not exist", name))
		case c.Kind != "domain":
			probs = append(probs, fmt.Sprintf("expected primary context %q has kind %s, not domain", name, c.Kind))
		}
	}
	for _, name := range rc.ExpectedOverlays {
		c := cs.ByName[name]
		switch {
		case c == nil:
			probs = append(probs, fmt.Sprintf("expected overlay %q does not exist", name))
		case c.Kind != "policy":
			probs = append(probs, fmt.Sprintf("expected overlay %q has kind %s, not policy", name, c.Kind))
		}
	}
	if len(rc.Paths) == 0 {
		return probs // semantic case: existence checks only
	}

	computed := map[string]bool{}
	for _, p := range rc.Paths {
		owners := cs.ownersOf(p)
		if len(owners) == 0 {
			probs = append(probs, fmt.Sprintf("path %q matches no domain context (unowned)", p))
		}
		for _, o := range owners {
			computed[o] = true
		}
	}
	want := map[string]bool{}
	for _, n := range rc.ExpectedPrimary {
		want[n] = true
	}
	for _, n := range sortedKeys(computed) {
		if !want[n] {
			probs = append(probs, fmt.Sprintf("ownership computes context %q which is not in expected_primary", n))
		}
	}
	for _, n := range rc.ExpectedPrimary {
		if !computed[n] {
			probs = append(probs, fmt.Sprintf("expected primary %q owns none of the case paths", n))
		}
	}
	return probs
}

// ──────────────────────────────── drift ─────────────────────────────────────

func cmdDrift(args []string) error {
	fs := flag.NewFlagSet("drift", flag.ExitOnError)
	repo := fs.String("repo", "", "path to the target repository root")
	maxAge := fs.Int("max-age-days", 180, "maximum age of Last reviewed dates")
	maxLines := fs.Int("max-lines", 400, "split threshold in lines")
	minLines := fs.Int("min-lines", 25, "merge threshold in lines")
	fs.Parse(args)
	if *repo == "" {
		return fmt.Errorf("drift: --repo is required")
	}

	cs := loadContextSet(*repo)
	if cs.Router == nil {
		return fmt.Errorf("drift: %s has no parseable root AGENTS.md", *repo)
	}
	inv, err := scanRepo(*repo)
	if err != nil {
		return err
	}

	var errsFound, warns []string
	report := func(sev string, format string, a ...any) {
		msg := fmt.Sprintf(format, a...)
		if sev == "ERROR" {
			errsFound = append(errsFound, msg)
		} else {
			warns = append(warns, msg)
		}
	}

	// New unowned packages (repo root itself is exempt: its files are
	// typically split across contexts).
	for _, pr := range inv.PackageRoots {
		if pr.Path == "." {
			continue
		}
		if len(cs.ownersOf(pr.Path+"/")) == 0 {
			report("WARN", "unowned package root: %s (manifests: %s)", pr.Path, strings.Join(pr.Manifests, ", "))
		}
	}

	// Deleted or renamed owned paths.
	for _, c := range cs.domains() {
		for _, g := range c.OwnedGlobs {
			if !pathExists(*repo, g, nil) {
				report("ERROR", "%s: owned path `%s` no longer exists", c.File, g)
			}
		}
	}

	// Newly overlapping patterns.
	for _, f := range ownershipOverlaps(cs) {
		report("ERROR", "%s", f)
	}

	// Stale review dates.
	cutoff := time.Now().AddDate(0, 0, -*maxAge)
	for _, c := range cs.Contexts {
		if c.LastReviewed == "" {
			continue // check already flags the missing footer
		}
		if t, err := time.Parse("2006-01-02", c.LastReviewed); err == nil && t.Before(cutoff) {
			report("WARN", "%s: last reviewed %s, older than %d days", c.File, c.LastReviewed, *maxAge)
		}
	}

	// Verification commands that reference missing make targets.
	makeTargets := map[string]bool{}
	for _, cmd := range inv.Commands {
		if cmd.Source == "makefile" {
			makeTargets[cmd.Name] = true
		}
	}
	for _, c := range cs.Contexts {
		for _, line := range c.Sections["Verification"] {
			for _, m := range codeSpanRE.FindAllStringSubmatch(line, -1) {
				fields := strings.Fields(m[1])
				if len(fields) >= 2 && fields[0] == "make" && !strings.HasPrefix(fields[1], "-") {
					if len(makeTargets) > 0 && !makeTargets[fields[1]] {
						report("ERROR", "%s: verification references `%s` but Makefile has no target %q", c.File, m[1], fields[1])
					}
				}
			}
		}
	}

	// New entry points or trust surfaces not covered by any owner.
	for _, ep := range inv.EntryPoints {
		probe := ep
		if !strings.Contains(filepath.Base(ep), ".") {
			probe = ep + "/" // directory-shaped entry point
		}
		if len(cs.ownersOf(probe)) == 0 {
			report("WARN", "unowned entry point or trust surface: %s", ep)
		}
	}

	// Split / merge thresholds.
	for _, c := range cs.Contexts {
		if c.LineCount > *maxLines {
			report("WARN", "%s: %d lines exceeds split threshold %d", c.File, c.LineCount, *maxLines)
		}
		if c.LineCount < *minLines {
			report("WARN", "%s: %d lines below merge threshold %d", c.File, c.LineCount, *minLines)
		}
	}

	for _, m := range errsFound {
		fmt.Println("ERROR " + m)
	}
	for _, m := range warns {
		fmt.Println("WARN  " + m)
	}
	if len(errsFound) > 0 {
		return fmt.Errorf("drift: %d error(s), %d warning(s)", len(errsFound), len(warns))
	}
	if len(warns) == 0 {
		fmt.Println("OK    no drift detected")
	} else {
		fmt.Printf("OK    no errors; %d warning(s)\n", len(warns))
	}
	return nil
}

// ─────────────────────────────── helpers ────────────────────────────────────

func readSmall(path string) (string, error) {
	st, err := os.Stat(path)
	if err != nil {
		return "", err
	}
	if st.Size() > maxReadBytes {
		return "", fmt.Errorf("file exceeds %d bytes; skipped", maxReadBytes)
	}
	data, err := os.ReadFile(path)
	if err != nil {
		return "", err
	}
	return string(data), nil
}

func sortedKeys(m map[string]bool) []string {
	out := make([]string, 0, len(m))
	for k := range m {
		out = append(out, k)
	}
	sort.Strings(out)
	return out
}

func sortedKeys2(m map[string][]string) []string {
	out := make([]string, 0, len(m))
	for k := range m {
		out = append(out, k)
	}
	sort.Strings(out)
	return out
}

func truncate(s string, n int) string {
	if len(s) <= n {
		return s
	}
	return s[:n] + "…"
}