path: root/internal/engine/match.go

// SPDX-License-Identifier: GPL-3.0-or-later

package engine

import (
	"context"
	"fmt"
	"io/fs"
	"os"
	"path/filepath"
	"runtime"
	"sort"
	"strings"
	"sync"
	"time"

	"krino/internal/cond"
	"krino/internal/config"
	"krino/internal/plan"
	"krino/internal/scan"
	"krino/internal/xdg"
)

// RuleMatch is one rule that matched a file, and why.
type RuleMatch struct {
	Rule     *Rule
	Captures []string
	Reasons  []string
}

// FileMatch is one file and the rules that did, or did not, match it.
type FileMatch struct {
	File     scan.File
	Rules    []RuleMatch // matching rules in order, ending at the first with (stop)
	Warnings []string    // "<rule>: <warning>", e.g. "acme: content unreadable: needs pdftotext, not installed"
}

// Result is everything Match found in one directory.
type Result struct {
	Dir       *Dir
	Matched   []FileMatch // at least one rule matched; sorted by File.Rel
	Unmatched []FileMatch // no rule matched (Warnings may say why); sorted by File.Rel
	Skipped   []scan.Skipped
	Warnings  []string // directory-level, sorted; e.g. "duplicate: /x/y does not exist"
	Elapsed   time.Duration
}

// Match walks d's root and evaluates every rule against every file found,
// concurrently. Output order never depends on scheduling: results are
// placed by index into a slice the size of the walk, then split into
// Matched and Unmatched keeping that (Rel-sorted) order.
func (e *Engine) Match(ctx context.Context, d *Dir) (*Result, error) {
	started := time.Now()
	now := e.Now()
	excl := e.excludeDirs(d)

	wres, err := scan.Walk(d.Root, walkOptions(d, excl, now))
	if err != nil {
		return nil, err
	}

	run := newMatchRun(e, d, ctx, now, wres.Files)
	fileMatches := make([]FileMatch, len(wres.Files))

	workers := runtime.GOMAXPROCS(0)
	if workers < 1 {
		workers = 1
	}
	var wg sync.WaitGroup
	jobs := make(chan int)
	for w := 0; w < workers; w++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			for i := range jobs {
				fileMatches[i] = evalFile(run, wres.Files[i])
			}
		}()
	}
	for i := range wres.Files {
		jobs <- i
	}
	close(jobs)
	wg.Wait()
	run.drainDupErrors()

	var matched, unmatched []FileMatch
	for _, fm := range fileMatches {
		if len(fm.Rules) > 0 {
			matched = append(matched, fm)
		} else {
			unmatched = append(unmatched, fm)
		}
	}

	warnings := run.warnings()
	sort.Strings(warnings)

	return &Result{
		Dir:       d,
		Matched:   matched,
		Unmatched: unmatched,
		Skipped:   wres.Skipped,
		Warnings:  warnings,
		Elapsed:   time.Since(started),
	}, nil
}

// evalFile evaluates every rule of run.d, in order, against file: matched
// becomes true after the first matching rule, so a later (not (matched))
// test sees it, and evaluation stops right after a matching rule whose
// Stop is set.
func evalFile(run *matchRun, file scan.File) FileMatch {
	f := newFacts(run, file)
	fm := FileMatch{File: file}
	for _, r := range run.d.Rules {
		res := r.Cond.Eval(f)
		for _, w := range res.Warnings {
			fm.Warnings = append(fm.Warnings, r.Name+": "+w)
		}
		if !res.Match {
			continue
		}
		fm.Rules = append(fm.Rules, RuleMatch{Rule: r, Captures: res.Captures, Reasons: res.Reasons})
		f.matched = true
		if r.Conf.Stop {
			break
		}
	}
	return fm
}

// RuleTrace is one rule's outcome in an Explain call.
type RuleTrace struct {
	Rule    *Rule
	Match   bool
	Trace   *cond.Trace // nil when not evaluated
	Stopped string      // "stopped by rule acme" when an earlier (stop) ended the search
}

// Explanation is why (or why not) krino would act on one file.
type Explanation struct {
	Dir   *Dir
	File  scan.File
	Skip  string // why krino would not look at this file at all; "" when it would
	Rules []RuleTrace
}

// Explain reports, for one file, whether krino's ordinary scan would ever
// reach it and how every rule of its directory evaluates against it. Rules
// are traced in order even when Skip is set, so a user can see what would
// match if the file were looked at; a rule reached after an earlier
// matching (stop) is recorded as Stopped, with no trace.
func (e *Engine) Explain(ctx context.Context, path string) (*Explanation, error) {
	abs, err := filepath.Abs(path)
	if err != nil {
		return nil, err
	}
	abs = filepath.Clean(abs)

	d := e.dirFor(abs)
	if d == nil {
		return nil, fmt.Errorf("%s is not inside any included directory", path)
	}

	info, err := os.Lstat(abs)
	if err != nil {
		return nil, err
	}
	if info.Mode()&fs.ModeSymlink != 0 || !info.Mode().IsRegular() {
		return nil, fmt.Errorf("%s is not a regular file", path)
	}

	rel, err := filepath.Rel(d.Root, abs)
	if err != nil {
		return nil, err
	}
	rel = filepath.ToSlash(rel)

	sf := scan.File{
		Path:    abs,
		Rel:     rel,
		Name:    filepath.Base(abs),
		Size:    info.Size(),
		ModTime: info.ModTime(),
		Mode:    info.Mode(),
	}

	now := e.Now()
	excl := e.excludeDirs(d)
	skip := explainSkip(d, sf, excl, now)

	run := newMatchRun(e, d, ctx, now, e.filesForExplain(d, sf, excl, now))
	f := newFacts(run, sf)

	var rules []RuleTrace
	stoppedBy := ""
	for _, r := range d.Rules {
		if stoppedBy != "" {
			rules = append(rules, RuleTrace{Rule: r, Stopped: "stopped by rule " + stoppedBy})
			continue
		}
		trace := r.Cond.Explain(f)
		match := trace.Value
		if match {
			f.matched = true
		}
		rules = append(rules, RuleTrace{Rule: r, Match: match, Trace: trace})
		if match && r.Conf.Stop {
			stoppedBy = r.Name
		}
	}

	return &Explanation{Dir: d, File: sf, Skip: skip, Rules: rules}, nil
}

// filesForExplain returns the file set Explain's duplicate checks run
// against: the directory's ordinary scan, plus the explained file itself
// when that scan would not have reached it (it is busy, ignored, too new,
// excluded, or beyond recursive/max-depth) - so (duplicate ...) always has
// a real answer for the file being explained, and sees the same siblings
// Match would.
func (e *Engine) filesForExplain(d *Dir, sf scan.File, excl []string, now time.Time) []scan.File {
	wres, err := scan.Walk(d.Root, walkOptions(d, excl, now))
	if err != nil {
		return []scan.File{sf}
	}
	for _, wf := range wres.Files {
		if wf.Path == sf.Path {
			return wres.Files
		}
	}
	return append(append([]scan.File{}, wres.Files...), sf)
}

// walkOptions builds the scan.Options both Match and Explain's
// filesForExplain walk d's root with, so the two never drift apart.
func walkOptions(d *Dir, excl []string, now time.Time) scan.Options {
	return scan.Options{
		Recursive: d.Settings.Recursive,
		MaxDepth:  d.Settings.MaxDepth,
		Ignore:    d.Ignore,
		Exclude:   excl,
		Busy:      d.Settings.Busy,
		MinAge:    d.Settings.MinAge,
		Now:       now,
	}
}

// dirFor returns the configured Dir whose root most specifically (longest
// root wins) contains abs, or nil if none does.
func (e *Engine) dirFor(abs string) *Dir {
	var best *Dir
	var bestRoot string
	for _, d := range e.Dirs {
		root := filepath.Clean(d.Root)
		if abs != root && !strings.HasPrefix(abs, root+string(filepath.Separator)) {
			continue
		}
		if best == nil || len(root) > len(bestRoot) {
			best, bestRoot = d, root
		}
	}
	return best
}

// explainSkip decides, in priority order, why krino's ordinary scan would
// not reach sf, or "" if it would.
func explainSkip(d *Dir, sf scan.File, excl []string, now time.Time) string {
	segs := strings.Split(sf.Rel, "/")
	if !d.Settings.Recursive && len(segs) > 1 {
		return "in a subdirectory, and recursive is off"
	}
	if d.Settings.MaxDepth > 0 && len(segs) > d.Settings.MaxDepth {
		return "deeper than max-depth"
	}
	if insideAny(sf.Path, excl) {
		return "inside a rule destination, which krino never scans"
	}
	if d.Ignore != nil && d.Ignore.Match(sf.Rel, false) {
		return "ignored"
	}
	if isBusy(sf.Path, d.Settings.Busy) {
		return "busy"
	}
	if now.Sub(sf.ModTime) < d.Settings.MinAge {
		return "too new"
	}
	return ""
}

// insideAny reports whether path is dir itself, or inside it, for any dir
// in dirs.
func insideAny(path string, dirs []string) bool {
	for _, dir := range dirs {
		if path == dir || strings.HasPrefix(path, dir+string(filepath.Separator)) {
			return true
		}
	}
	return false
}

// isBusy reports whether path has a sibling named path+suffix, for any
// configured busy suffix - the mark of an in-progress download.
func isBusy(path string, suffixes []string) bool {
	for _, suf := range suffixes {
		if _, err := os.Lstat(path + suf); err == nil {
			return true
		}
	}
	return false
}

// excludeDirs computes the directories Match and Explain never enter: each
// rule's copy/move destination, the Trash, and the directory holding the
// main config file - each kept only when it lies strictly inside d's root
// (C3: root itself is not "inside" it here - a rule cannot exclude the very
// directory being scanned. cmd/krino/render.go's relToRoot answers a
// different question, whether a destination is root or beneath it for
// display purposes, and there root does count as inside; the two are each
// correct for their own question, so do not "unify" them).
// A destination with no template placeholder excludes exactly that
// directory; a destination with a placeholder excludes only the static
// part before its first "{", cut back to a full path component (its last
// "/"), since anything from there on varies per file - spec 8.1: "Work/
// Acme/{mtime:%Y}" excludes "Work/Acme", and "Work/Acme-{mtime:%Y}"
// (the placeholder mid-segment) excludes "Work".
func (e *Engine) excludeDirs(d *Dir) []string {
	root := filepath.Clean(d.Root)
	var out []string
	add := func(p string) {
		if p == "" {
			return
		}
		p = filepath.Clean(p)
		if strings.HasPrefix(p, root+string(filepath.Separator)) {
			out = append(out, p)
		}
	}
	for _, r := range d.Rules {
		for _, a := range r.Conf.Actions {
			if a.Kind != config.Copy && a.Kind != config.Move {
				continue
			}
			prefix := a.Arg
			if idx := strings.IndexByte(prefix, '{'); idx >= 0 {
				prefix = prefix[:idx]
				if idx2 := strings.LastIndexByte(prefix, '/'); idx2 >= 0 {
					prefix = prefix[:idx2]
				} else {
					// The very first path component is itself templated
					// (e.g. "{year}-Stuff"): nothing about the destination
					// is known statically, so there is nothing to exclude.
					prefix = ""
				}
			}
			add(plan.ResolveDir(prefix, root))
		}
	}
	add(filepath.Join(xdg.DataHome(), "Trash"))
	add(filepath.Dir(e.MainFile))
	return out
}