rule.go

// Package githooksync implements MDS048, the git-hook-sync rule. It
// reports when the .gitattributes managed block or the
// pre-merge-commit hook drifts from the canonical content derived
// from the project's .mdsmith.yml ignore patterns.
package githooksync

import (
	"bytes"
	"fmt"
	"os"
	"path/filepath"
	"strings"
	"sync"

	"github.com/jeduden/mdsmith/internal/bytelimit"
	"github.com/jeduden/mdsmith/internal/githooks"
	"github.com/jeduden/mdsmith/internal/lint"
	"github.com/jeduden/mdsmith/internal/rule"
)

// hookMaxReadBytes is the byte cap applied to all hook-related file reads
// (pre-merge-commit hook and .gitattributes). Matches the 1 MB cap used
// by every other os.ReadFile call in the codebase via bytelimit. A file
// larger than this limit triggers a diagnostic rather than a full read.
const hookMaxReadBytes int64 = 1024 * 1024

// preMergeMarkerBytes is the package-level byte slice of PreMergeCommitMarker,
// hoisted to avoid re-converting the marker constant to []byte on every call.
var preMergeMarkerBytes = []byte(githooks.PreMergeCommitMarker)

// resolveHooksDir is a package variable so tests can substitute a
// counting stub and assert driftParts resolves the hooks directory
// exactly once per cache miss, instead of once for peekHookSource and
// again for preMergeCommitHookDrift (each a `git rev-parse` subprocess).
var resolveHooksDir = githooks.ResolveHooksDir

func init() {
	rule.Register(&Rule{})
}

// Rule checks that mdsmith-managed git hooks and .gitattributes are
// in sync with the canonical content computed from the project's
// .mdsmith.yml ignore patterns.
//
// The rule is runnable in its zero value: it has no required runtime
// settings, so users can opt in via the bool form `git-hook-sync:
// true`. ApplySettings is still implemented to validate unknown keys
// when the user provides a mapping, but execution does not depend on
// it being called.
type Rule struct{}

// stagingErrors records repos where Fix wrote .gitattributes but the
// follow-up `git add -- .gitattributes` failed (e.g. index.lock
// contention). The on-disk fix already happened, so a plain drift
// re-check would see the file as in sync and stop emitting
// diagnostics — silently leaving the staged tree out of sync with
// the working tree. Surfacing the failure through Check makes it
// retryable: subsequent Fix calls re-run the staging step until it
// succeeds, at which point the entry is cleared.
//
// repoRootCache memoises the result of GitRepoRoot(dir) so per-file
// Check/Fix calls do not respawn `git rev-parse --show-toplevel` for
// every file in the same directory. Entries with a non-nil error are
// also cached so non-repo directories are remembered too. The cache
// is keyed by the directory passed to resolveRepoRoot, not the
// resolved root, so repeated lookups for the same directory reuse
// one git invocation; different subdirectories under the same repo
// may still invoke git separately.
//
// driftCache memoises the per-repo drift messages computed by Check
// (the merge-driver and pre-merge-commit hook sources, excluding the
// dynamic staging-error part). Without it, Check would respawn
// `git config`, re-read the hook script, and re-parse `.mdsmith.yml`
// once per linted file. Fix() invalidates the entry so the next
// Check observes the post-fix state.
var (
	stagingMu     sync.Mutex
	stagingErrors = make(map[string]error)
	repoRootMu    sync.Mutex
	repoRootCache = make(map[string]repoRootEntry)
	driftMu       sync.Mutex
	driftCache    = make(map[string]driftResult)
)

type repoRootEntry struct {
	root string
	err  error
}

// driftResult is the cached output of Check's repo-level drift
// inspection minus the staging-error message, which is checked on
// every call because it can change between Check and Fix calls.
type driftResult struct {
	parts []string
}

// ID implements rule.Rule.
func (r *Rule) ID() string { return "MDS048" }

// Name implements rule.Rule.
func (r *Rule) Name() string { return "git-hook-sync" }

// MutatesGitIndex reports that MDS048's Fix stages .gitattributes via
// an in-process `git add` (see githooks.StageGitattributes), so the
// merge driver must exclude it — the driver runs inside `git merge`,
// which holds .git/index.lock. Implements rule.GitIndexMutator.
func (r *Rule) MutatesGitIndex() bool { return true }

// Category implements rule.Rule.
func (r *Rule) Category() string { return "structural" }

// EnabledByDefault implements rule.Defaultable.
func (r *Rule) EnabledByDefault() bool { return false }

// Check implements rule.Rule.
func (r *Rule) Check(f *lint.File) []lint.Diagnostic {
	// Skip when there is no on-disk file to anchor repo discovery.
	// stdin and other in-memory inputs have f.FS == nil and a
	// synthetic f.Path like "<stdin>"; if we used filepath.Dir on
	// that, the rule would scan whatever git repo happens to be
	// the process working directory and emit drift unrelated to
	// the content being linted.
	if f.FS == nil {
		return nil
	}

	// Resolve the repo root from the directory of the file being
	// linted so the rule does not depend on the process working
	// directory. When a file is not inside a git repo, skip silently.
	repoRoot, err := r.resolveRepoRoot(filepath.Dir(f.Path))
	if err != nil {
		return nil
	}

	// Look up the cached drift inspection first. Without this, every
	// linted markdown file would respawn `git config`, re-read the
	// hook script, and re-parse `.mdsmith.yml`; over a large repo
	// that becomes O(files) git subprocesses + YAML parses for a
	// single repo-level diagnostic. Fix() invalidates the cache
	// entry so the post-fix state is observed.
	parts := r.driftParts(repoRoot)
	// A previous Fix may have written .gitattributes but failed to
	// stage it. Surface that as a diagnostic so the next Fix call is
	// triggered to retry the staging.
	if err := stagingError(repoRoot); err != nil {
		parts = append(parts, fmt.Sprintf(
			".gitattributes was regenerated but `git add` failed: %v "+
				"(run `git add -- .gitattributes` or re-run mdsmith fix to retry)",
			err,
		))
	}
	if len(parts) == 0 {
		return nil
	}

	// Anchor the diagnostic to the .gitattributes path (the
	// repo-level artifact this rule checks) rather than the
	// markdown file the engine happened to be linting. Drift is a
	// repo-level concern, and pointing every duplicate report at
	// the same artifact path lets downstream tooling collapse them
	// by (file, line, ruleID) and makes the source of the warning
	// explicit in the diagnostic output.
	diagPath := filepath.Join(repoRoot, ".gitattributes")
	return []lint.Diagnostic{{
		File:     diagPath,
		Line:     1,
		Column:   1,
		RuleID:   r.ID(),
		RuleName: r.Name(),
		Severity: lint.Warning,
		Message:  strings.Join(parts, "; "),
	}}
}

// hookSource describes the state of the pre-merge-commit hook for
// the cheap pre-check in Check. Distinguishing "not installed"
// (ENOENT) from "couldn't read" lets the rule still surface IO
// errors via preMergeCommitHookDrift even when the merge driver
// isn't registered.
type hookSource int

const (
	hookSourceAbsent hookSource = iota
	hookSourceManaged
	hookSourceUnmanaged
	hookSourceUnreadable
)

// peekHookSource reports the current state of the pre-merge-commit
// hook without parsing its contents. hooksDir is the repo's resolved
// hooks directory (githooks.ResolveHooksDir), passed in so a caller
// that also needs it (driftParts) resolves it once rather than
// spawning a second `git rev-parse` for the same repo.
func peekHookSource(hooksDir string) hookSource {
	hookPath := filepath.Join(hooksDir, "pre-merge-commit")
	data, err := bytelimit.ReadFileLimited(hookPath, hookMaxReadBytes)
	if err != nil {
		if os.IsNotExist(err) {
			return hookSourceAbsent
		}
		return hookSourceUnreadable
	}
	if bytes.Contains(data, preMergeMarkerBytes) {
		return hookSourceManaged
	}
	return hookSourceUnmanaged
}

// driftParts returns the cached drift messages for repoRoot,
// computing them on a cache miss. The result excludes the dynamic
// staging-error part (Check appends that on every call so a
// staging failure recorded after the first inspection is still
// surfaced). Fix() invalidates the cache entry so the post-fix
// state is observed; without invalidation a successful Fix would
// still report stale drift.
func (r *Rule) driftParts(repoRoot string) []string {
	driftMu.Lock()
	if cached, ok := driftCache[repoRoot]; ok {
		driftMu.Unlock()
		return cached.parts
	}
	driftMu.Unlock()

	hasDriver := githooks.HasMdsmithMergeDriver(repoRoot)
	hooksDir := resolveHooksDir(repoRoot)
	hookState := peekHookSource(hooksDir)
	// Early-exit when the user has not opted in (no driver) and the hook
	// is not mdsmith-managed. hookSourceUnreadable (file too large, bad
	// perms) is included in the early-exit: we cannot verify the hook's
	// state, but since no driver is registered the user has not opted into
	// mdsmith hook management, so there is nothing to report.
	if !hasDriver && hookState != hookSourceManaged {
		driftMu.Lock()
		driftCache[repoRoot] = driftResult{}
		driftMu.Unlock()
		return nil
	}

	expectedGlobs := githooks.LoadGlobs(repoRoot)
	var parts []string
	if msg := r.mergeDriverDrift(repoRoot, hasDriver, expectedGlobs); msg != "" {
		parts = append(parts, msg)
	}
	if msg := r.preMergeCommitHookDrift(hooksDir); msg != "" {
		parts = append(parts, msg)
	}

	driftMu.Lock()
	driftCache[repoRoot] = driftResult{parts: parts}
	driftMu.Unlock()
	return parts
}

// mergeDriverDrift returns a human-readable description of any drift
// between the .gitattributes managed block and the canonical block
// derived from .mdsmith.yml. The check only runs when
// `merge.mdsmith.driver` is registered, so repos that have not opted
// in are not flagged. Returns an empty string when no drift is
// detected.
//
// hasDriver is taken as a parameter rather than re-probed via
// HasMdsmithMergeDriver so Check does not pay an extra `git config`
// subprocess per linted file: the caller has already computed it.
//
// A non-ENOENT read error is surfaced as drift rather than silently
// passing, so permission/IO failures cannot mask real misconfiguration.
func (r *Rule) mergeDriverDrift(repoRoot string, hasDriver bool, expected githooks.Globs) string {
	if !hasDriver {
		return ""
	}
	data, err := bytelimit.ReadFileLimited(filepath.Join(repoRoot, ".gitattributes"), hookMaxReadBytes)
	if err != nil && !os.IsNotExist(err) {
		return fmt.Sprintf(
			"cannot verify merge-driver assignments because .gitattributes could not be read: %v",
			err,
		)
	}
	installed, ok := githooks.ExtractGlobs(string(data))
	if !ok {
		return fmt.Sprintf(
			"merge.mdsmith.driver is registered but .gitattributes has no managed block "+
				"(should contain include patterns: %s; exclude patterns: %s)",
			strings.Join(expected.Include, ", "),
			describeGlobs(expected.Exclude),
		)
	}
	if githooks.GlobsEqual(installed, expected) {
		return ""
	}
	return fmt.Sprintf(
		".gitattributes managed block is out of sync "+
			"(has include: %s, exclude: %s; should have include: %s, exclude: %s)",
		describeGlobs(installed.Include),
		describeGlobs(installed.Exclude),
		describeGlobs(expected.Include),
		describeGlobs(expected.Exclude),
	)
}

// describeGlobs returns a printable representation of patterns so
// "(none)" is shown for an empty list rather than a blank field.
func describeGlobs(patterns []string) string {
	if len(patterns) == 0 {
		return "(none)"
	}
	return strings.Join(patterns, ", ")
}

// preMergeCommitHookDrift returns a human-readable description of any
// drift between the installed pre-merge-commit hook and the canonical
// hook content. Returns an empty string if no hook is installed, the
// hook is not mdsmith-managed, or the content matches. A non-ENOENT
// read error is surfaced rather than silently passing so permission
// or IO failures cannot mask real drift. hooksDir is the repo's
// resolved hooks directory, shared with peekHookSource by driftParts
// so the two checks spawn only one `git rev-parse` per repo instead
// of one each.
func (r *Rule) preMergeCommitHookDrift(hooksDir string) string {
	hookPath := filepath.Join(hooksDir, "pre-merge-commit")
	data, err := bytelimit.ReadFileLimited(hookPath, hookMaxReadBytes)
	if err != nil {
		if os.IsNotExist(err) {
			return ""
		}
		return fmt.Sprintf(
			"cannot verify pre-merge-commit hook because %s could not be read: %v",
			hookPath, err,
		)
	}
	// Cheap bytes check before the string conversion; avoids allocating the
	// full hook file content as a string for unmanaged hooks.
	if !bytes.Contains(data, preMergeMarkerBytes) {
		return ""
	}
	hook := string(data)
	// The canonical hook content depends on the absolute path of the
	// mdsmith binary that originally installed it. Comparing only the
	// portions that are independent of that path (the marker plus the
	// glob-based fix invocation pattern) keeps drift detection
	// hermetic across machines while still catching missing or
	// outdated hook content.
	if githooks.HookMatchesCanonical(hook) {
		return ""
	}
	return "pre-merge-commit hook is out of sync with the glob-based template " +
		"(re-run `mdsmith pre-merge-commit install` to update it)"
}

// Fix implements rule.FixableRule. It regenerates the .gitattributes
// managed block from the canonical glob set when the merge driver is
// registered. The pre-merge-commit hook is not auto-fixed because it
// is an executable script and modifying executable files during
// automated fixes could be surprising or unsafe. Users must run
// `mdsmith pre-merge-commit install` manually to update the hook.
//
// The fix only runs when f.FS != nil (a real file, not stdin) and
// when the repository has opted into the merge driver via
// `git config merge.mdsmith.driver`. If neither condition holds, the
// original file content is returned unchanged.
//
// Fix short-circuits via a GlobsEqual check when .gitattributes is
// already in sync, so linting many files in the same repo does not
// trigger redundant rewrites. Subsequent calls may still do real
// work in two cases: drift has reappeared (e.g. an external tool
// changed the managed block), or a previous staging attempt failed
// and needs retrying.
func (r *Rule) Fix(f *lint.File) []byte {
	// Skip stdin and other in-memory inputs (same logic as Check).
	if f.FS == nil {
		return f.Source
	}

	// A dry-run must not touch .gitattributes or the git index.
	// The fix engine instead asks PredictDryRunFix below for the
	// diagnostics a real run would have cleared, so the dry-run
	// exit code still matches a real run.
	if f.DryRun {
		return f.Source
	}

	repoRoot, err := r.resolveRepoRoot(filepath.Dir(f.Path))
	if err != nil {
		return f.Source
	}

	// Whatever Fix decides, the cached drift result for this repo
	// is now stale (the on-disk state may have changed). Drop the
	// entry so the next Check re-reads the repo. Doing this even
	// when Fix short-circuits keeps the cache coherent if the
	// driver is registered between calls or an external tool
	// rewrites .gitattributes.
	defer func() {
		driftMu.Lock()
		delete(driftCache, repoRoot)
		driftMu.Unlock()
	}()

	// Only fix when the merge driver is registered. If the driver
	// isn't set up, there's no .gitattributes to repair.
	if !githooks.HasMdsmithMergeDriver(repoRoot) {
		return f.Source
	}

	expected := githooks.LoadGlobs(repoRoot)
	attrPath := filepath.Join(repoRoot, ".gitattributes")

	// When .gitattributes is already in sync, skip the rewrite. If a
	// previous run failed to stage, retry the staging step now so the
	// pending error is given a chance to clear without forcing a
	// redundant write.
	data, err := bytelimit.ReadFileLimited(attrPath, hookMaxReadBytes)
	if err == nil {
		installed, ok := githooks.ExtractGlobs(string(data))
		if ok && githooks.GlobsEqual(installed, expected) {
			if stagingError(repoRoot) != nil {
				stage(repoRoot)
			}
			return f.Source
		}
	}

	// Write the corrected .gitattributes. Any successful write flows
	// through the staging path so the index always reflects the
	// updated working-tree content; a transient write failure simply
	// leaves the tree unchanged so the next Fix call can retry.
	if err := githooks.WriteGitattributes(attrPath, expected); err != nil {
		return f.Source
	}

	// Stage the regenerated .gitattributes so the pre-merge-commit
	// hook flow includes it in the merge commit alongside the
	// markdown files mdsmith fix touched. The error is recorded in
	// stagingErrors so Check can keep emitting a diagnostic until a
	// later Fix call's staging attempt succeeds.
	stage(repoRoot)

	// Return original file content unchanged (the fix is in
	// .gitattributes, not in the markdown file being linted).
	return f.Source
}

// PredictDryRunFix implements rule.DryRunPredictor. A real-run Fix
// would write .gitattributes and stage it, clearing every drift and
// stale-staging diagnostic Check currently reports. Re-running Check
// on the same file returns exactly that set, so the fix engine can
// subtract those diagnostics from the dry-run remaining set without
// performing the underlying side effect.
func (r *Rule) PredictDryRunFix(f *lint.File) []lint.Diagnostic {
	return r.Check(f)
}

// stage attempts to stage .gitattributes and records the outcome in
// stagingErrors so Check can surface a persistent failure.
func stage(repoRoot string) {
	err := githooks.StageGitattributes(repoRoot)
	stagingMu.Lock()
	defer stagingMu.Unlock()
	if err != nil {
		stagingErrors[repoRoot] = err
		return
	}
	delete(stagingErrors, repoRoot)
}

// stagingError returns the most recent unsuccessful staging attempt
// for repoRoot, or nil if the last attempt succeeded (or there has
// been none).
func stagingError(repoRoot string) error {
	stagingMu.Lock()
	defer stagingMu.Unlock()
	return stagingErrors[repoRoot]
}

// gitRepoRoot is the package-level seam tests use to drive the
// double-check branch deterministically. Production resolves the
// root with findGitRoot — a stat walk, not a `git rev-parse`
// subprocess: the per-directory cache still spawned one git process
// per distinct directory, which dominated repo-wide checks of trees
// with hundreds of directories. The test in rule_test.go swaps in a
// blocking stub so it can populate the cache mid-flight and force
// the second cache check to fire.
var gitRepoRoot = findGitRoot

// findGitRoot returns the closest ancestor of dir (inclusive) that
// contains a .git entry — a directory for ordinary repositories, a
// file for linked worktrees and submodules — matching what
// `git -C dir rev-parse --show-toplevel` reports for those layouts.
// Errors when no ancestor has one, mirroring git's non-repo failure.
func findGitRoot(dir string) (string, error) {
	if dir == "" {
		dir = "."
	}
	abs, err := filepath.Abs(dir)
	if err != nil {
		return "", err
	}
	for cur := abs; ; {
		if _, err := os.Stat(filepath.Join(cur, ".git")); err == nil {
			return cur, nil
		}
		parent := filepath.Dir(cur)
		if parent == cur {
			return "", fmt.Errorf("not a git repository (or any parent): %s", abs)
		}
		cur = parent
	}
}

// resolveRepoRoot wraps githooks.GitRepoRoot with a per-directory
// cache so the per-file diagnostic flow does not respawn
// `git rev-parse --show-toplevel` for every linted file in the same
// repo. Failures (the linted file is not inside a git repo) are
// cached too so a directory tree without a `.git` ancestor is also
// only probed once.
//
// The mutex is released across the (potentially slow) `git rev-parse`
// subprocess so concurrent Check/Fix calls on unrelated directories
// are not serialised behind a single git invocation. A second
// directory triggering the same lookup may run git in parallel; the
// double-check after re-acquiring the lock makes the first writer
// win without hurting correctness.
func (r *Rule) resolveRepoRoot(dir string) (string, error) {
	repoRootMu.Lock()
	if entry, ok := repoRootCache[dir]; ok {
		repoRootMu.Unlock()
		return entry.root, entry.err
	}
	repoRootMu.Unlock()

	root, err := gitRepoRoot(dir)

	repoRootMu.Lock()
	defer repoRootMu.Unlock()
	if entry, ok := repoRootCache[dir]; ok {
		// A concurrent caller populated the cache while we were
		// running `git rev-parse`; honour their result so callers
		// observe a single source of truth.
		return entry.root, entry.err
	}
	repoRootCache[dir] = repoRootEntry{root: root, err: err}
	return root, err
}

// RepoScopedDiagnostics implements rule.RepoScoped. git-hook-sync
// anchors every diagnostic to the repository .gitattributes path,
// independent of the host file being linted, so the same
// (File, Line, Column, RuleID, Message) tuple recurs for every
// markdown file in the repo. DedupeDiagnostics collapses these
// duplicates; this marker lets the engine skip that allocation when
// git-hook-sync is disabled.
func (r *Rule) RepoScopedDiagnostics() bool { return true }

// ApplySettings implements rule.Configurable. The rule has no runtime
// settings, so this only rejects unknown keys when a user supplies a
// mapping. The rule executes regardless of whether ApplySettings is
// invoked, so a bool-only enable (`git-hook-sync: true`) also works.
func (r *Rule) ApplySettings(settings map[string]any) error {
	for k := range settings {
		return fmt.Errorf("git-hook-sync: unknown setting %q", k)
	}
	return nil
}

// DefaultSettings implements rule.Configurable.
func (r *Rule) DefaultSettings() map[string]any {
	return map[string]any{}
}

var (
	_ rule.Configurable    = (*Rule)(nil)
	_ rule.Defaultable     = (*Rule)(nil)
	_ rule.FixableRule     = (*Rule)(nil)
	_ rule.DryRunPredictor = (*Rule)(nil)
	_ rule.RepoScoped      = (*Rule)(nil)
)

// FixTitle implements rule.QuickFixTitler.
func (r *Rule) FixTitle() string { return "Regenerate .gitattributes block" }