rule.go

package concisenessscoring

import (
	"fmt"
	"strings"
	"sync"

	"github.com/jeduden/mdsmith/internal/lint"
	"github.com/jeduden/mdsmith/internal/mdtext"
	"github.com/jeduden/mdsmith/internal/rule"
	"github.com/jeduden/mdsmith/internal/rules/astutil"
	"github.com/jeduden/mdsmith/internal/rules/settings"
	"github.com/jeduden/mdsmith/pkg/goldmark/ast"
)

const (
	defaultMinScore = 0.20
	defaultMinWords = 20
)

var (
	scorerOnce      sync.Once
	globalScorer    *Scorer
	scorerErr       error
	errReportedOnce sync.Once
)

func loadScorer() (*Scorer, error) {
	scorerOnce.Do(func() {
		globalScorer, scorerErr = NewScorer()
	})
	return globalScorer, scorerErr
}

func init() {
	rule.Register(&Rule{
		MinScore: defaultMinScore,
		MinWords: defaultMinWords,
	})
}

// Rule checks paragraph conciseness using the embedded classifier.
type Rule struct {
	MinScore float64
	MinWords int
}

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

// Name implements rule.Rule.
func (r *Rule) Name() string { return "conciseness-scoring" }

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

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

// Check implements rule.Rule.
func (r *Rule) Check(f *lint.File) []lint.Diagnostic {
	scorer, err := loadScorer()
	if err != nil {
		return r.loadErrorDiag(f, err)
	}

	var diags []lint.Diagnostic
	_ = ast.Walk(f.AST, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
		if !entering {
			return ast.WalkContinue, nil
		}
		para, ok := n.(*ast.Paragraph)
		if !ok {
			return ast.WalkContinue, nil
		}
		if astutil.IsTable(para, f) {
			return ast.WalkContinue, nil
		}

		text := mdtext.ExtractPlainText(para, f.Source)
		// Cheap word count gates the classifier work: paragraphs
		// below MinWords cannot trigger a diagnostic regardless of
		// their score, and the classifier's regex-driven cue
		// detection is the dominant alloc-budget cost when it
		// fires (~400 allocs/paragraph on the alloc-budget gate
		// fixture). countClassifierTokens is a zero-alloc byte
		// scan that mirrors the classifier's `[a-z0-9']+` regex
		// (applied to the lowercased text) so the gate cannot
		// skip a paragraph the classifier would have run on.
		// Plan 195 task 13.
		if countClassifierTokens(text) < r.MinWords {
			return ast.WalkContinue, nil
		}
		result := scorer.Score(text)
		if result.WordCount < r.MinWords || result.Conciseness >= r.MinScore {
			return ast.WalkContinue, nil
		}

		line := astutil.ParagraphLine(para, f)
		examples := formatExamples(result.Cues)
		var cuesSuffix string
		if examples != "" {
			cuesSuffix = "; reduce verbose cues (e.g., " + examples + ")"
		}
		message := fmt.Sprintf(
			"conciseness score too low (%.2f < %.2f); target >= %.2f%s",
			result.Conciseness, r.MinScore, r.MinScore, cuesSuffix,
		)

		diags = append(diags, lint.Diagnostic{
			File:     f.Path,
			Line:     line,
			Column:   1,
			RuleID:   r.ID(),
			RuleName: r.Name(),
			Severity: lint.Warning,
			Message:  message,
		})
		return ast.WalkContinue, nil
	})
	return diags
}

func (r *Rule) loadErrorDiag(
	f *lint.File, err error,
) []lint.Diagnostic {
	var diag []lint.Diagnostic
	errReportedOnce.Do(func() {
		diag = []lint.Diagnostic{{
			File:     f.Path,
			Line:     1,
			Column:   1,
			RuleID:   r.ID(),
			RuleName: r.Name(),
			Severity: lint.Error,
			Message: fmt.Sprintf(
				"classifier load failed: %v", err,
			),
		}}
	})
	return diag
}

func formatExamples(examples []string) string {
	if len(examples) == 0 {
		return ""
	}
	limit := 2
	if len(examples) < limit {
		limit = len(examples)
	}
	values := make([]string, 0, limit)
	for i := 0; i < limit; i++ {
		values = append(values, fmt.Sprintf("%q", examples[i]))
	}
	return strings.Join(values, ", ")
}

// ApplySettings implements rule.Configurable.
func (r *Rule) ApplySettings(s map[string]any) error {
	for k, v := range s {
		switch k {
		case "min-score":
			if err := r.setMinScore(v); err != nil {
				return err
			}
		case "min-words":
			if err := r.setMinWords(v); err != nil {
				return err
			}
		default:
			return fmt.Errorf("conciseness-scoring: unknown setting %q", k)
		}
	}
	return nil
}

func (r *Rule) setMinScore(v any) error {
	n, ok := settings.ToFloat(v)
	if !ok {
		return fmt.Errorf(
			"conciseness-scoring: min-score must be a number, got %T",
			v,
		)
	}
	if n <= 0 || n > 1 {
		return fmt.Errorf(
			"conciseness-scoring: min-score must be > 0 and <= 1, got %.2f",
			n,
		)
	}
	r.MinScore = n
	return nil
}

func (r *Rule) setMinWords(v any) error {
	n, ok := settings.ToInt(v)
	if !ok {
		return fmt.Errorf(
			"conciseness-scoring: min-words must be an integer, got %T",
			v,
		)
	}
	if n <= 0 {
		return fmt.Errorf(
			"conciseness-scoring: min-words must be > 0, got %d",
			n,
		)
	}
	r.MinWords = n
	return nil
}

// DefaultSettings implements rule.Configurable.
func (r *Rule) DefaultSettings() map[string]any {
	return map[string]any{
		"min-score": defaultMinScore,
		"min-words": defaultMinWords,
	}
}

// countClassifierTokens counts non-overlapping byte runs matching
// the classifier's word regex `[a-z0-9']+` applied to the
// lowercased text. The classifier's WordCount comes from
// regexp.FindAllString on the lowercased input, so this counter
// matches that semantics byte-for-byte without the per-call
// regex allocation. Used to gate the classifier call without
// the divergence mdtext.CountWords (whitespace-only splitter)
// introduces — the whitespace splitter counts `hello-world` as
// one token while the classifier sees two, which could
// under-count and skip paragraphs the classifier would have
// flagged.
func countClassifierTokens(text string) int {
	n := 0
	inToken := false
	for i := 0; i < len(text); i++ {
		c := text[i]
		if (c >= 'a' && c <= 'z') ||
			(c >= 'A' && c <= 'Z') ||
			(c >= '0' && c <= '9') ||
			c == '\'' {
			if !inToken {
				inToken = true
				n++
			}
		} else {
			inToken = false
		}
	}
	return n
}

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