Merge pull request #50 from git-pkgs/expand-resources

Expand resource detection with grouped community files

Author: andrew

CONTRIBUTING.md

@@ -156,9 +156,23 @@ The knowledge base is validated on every test run. Malformed TOML will fail the
 Files prefixed with `_` in ecosystem directories are shared config, not tool definitions:
 
 - `_shared/_scripts.toml` - script source definitions (Makefile, package.json)
-- `_shared/_resources.toml` - project resource file patterns (README, LICENSE, etc.)
+- `_shared/_resources.toml` - repository document patterns (README, LICENSE, CODEOWNERS, FUNDING, etc.)
 - `_shared/_layout.toml` - source and test directory patterns
 - `_shared/_style.toml` - style config files and inference settings
 - `_shared/_runtimes.toml` - runtime version file patterns
 - `_shared/_manifests.toml` - manifest file list for dependency detection
 - `_shared/_ci.toml` - CI matrix parsing configuration
+
+A resource entry in `_resources.toml` looks like this:
+
+```toml
+[[resources]]
+[resources.resource]
+name = "Contributing"
+field = "contributing"
+group = "community"
+patterns = ["contributing", "contributing.md", "contributing.txt", "contributing.rst"]
+dirs = ["docs", ".github", ".gitlab"]
+```
+
+`field` is the JSON key the path is written to. `group` places it under one of `legal`, `community`, `security`, or `metadata`; omit it for top-level fields like `readme` and `license`. `patterns` are matched case-insensitively against directory listings, so list each pattern once in lowercase. List explicit extensions rather than a trailing glob for prose files so `support.md` matches but `docs/Support-Tiers.md` does not. `dirs` lists extra directories to search after the repo root; root always wins on a tie.

README.md

@@ -96,8 +96,8 @@ Layout:      cmd/
              OS: ubuntu-latest, macos-latest, windows-latest (CI matrix)
 
 Resources:   README.md
-Resources:   CONTRIBUTING.md
 Resources:   LICENSE (MIT)
+Community:   CONTRIBUTING.md
 
 Git:         branch main  71 commits
              origin: git@github.com:user/myproject.git
@@ -241,6 +241,12 @@ brief enrich --verbose .
 
 Data sources: [ecosyste.ms](https://ecosyste.ms) for published package metadata, [endoflife.date](https://endoflife.date) for runtime lifecycle, [OpenSSF Scorecard](https://securityscorecards.dev) for repo security.
 
+## Resources
+
+Alongside the toolchain, brief picks up the conventional documents that describe how a project is run. README, changelog, roadmap, license (with detected SPDX identifier), and agent instructions are reported at the top level. Everything else is grouped: legal covers copyright, NOTICE, DCO, and CLA files; community covers contributing guides, code of conduct, support, governance, maintainers, authors, CODEOWNERS, and DEI statements; security covers the security policy, threat model, and audit reports; metadata covers machine-readable files like FUNDING, CITATION.cff, publiccode.yml, codemeta.json, and .zenodo.json.
+
+Matching is case-insensitive and checks the repo root first, then `docs/`, `.github/`, and `.gitlab/`. Paths in the output are repo-relative, so a funding file found under `.github/` is reported as `.github/FUNDING.yml` rather than just the basename. In JSON the groups appear as nested objects under `resources.legal`, `resources.community`, `resources.security`, and `resources.metadata`.
+
 <!-- brief:tools:start (generated by: brief list -readme tools) -->
 ## What it detects
 

brief.go

@@ -99,14 +99,56 @@ type PlatformInfo struct {
 	CIMatrixOS          []string            `json:"ci_matrix_os,omitempty"`
 }
 
-// ResourceInfo describes project resource files.
+// ResourceInfo describes project resource files. Paths are relative to the
+// repository root.
 type ResourceInfo struct {
-	Readme       string `json:"readme,omitempty"`
-	Contributing string `json:"contributing,omitempty"`
-	Changelog    string `json:"changelog,omitempty"`
-	License      string `json:"license,omitempty"`
-	LicenseType  string `json:"license_type,omitempty"`
-	Security     string `json:"security,omitempty"`
+	Readme      string `json:"readme,omitempty"`
+	Changelog   string `json:"changelog,omitempty"`
+	Roadmap     string `json:"roadmap,omitempty"`
+	License     string `json:"license,omitempty"`
+	LicenseType string `json:"license_type,omitempty"`
+	Agents      string `json:"agents,omitempty"`
+
+	Legal     map[string]string `json:"legal,omitempty"`
+	Community map[string]string `json:"community,omitempty"`
+	Security  map[string]string `json:"security,omitempty"`
+	Metadata  map[string]string `json:"metadata,omitempty"`
+}
+
+// Group returns the map for the named resource group, creating it if needed.
+// Returns nil for unknown group names.
+func (r *ResourceInfo) Group(name string) map[string]string {
+	switch name {
+	case "legal":
+		if r.Legal == nil {
+			r.Legal = map[string]string{}
+		}
+		return r.Legal
+	case "community":
+		if r.Community == nil {
+			r.Community = map[string]string{}
+		}
+		return r.Community
+	case "security":
+		if r.Security == nil {
+			r.Security = map[string]string{}
+		}
+		return r.Security
+	case "metadata":
+		if r.Metadata == nil {
+			r.Metadata = map[string]string{}
+		}
+		return r.Metadata
+	}
+	return nil
+}
+
+// Empty reports whether no resources were found.
+func (r *ResourceInfo) Empty() bool {
+	return r.Readme == "" && r.Changelog == "" && r.Roadmap == "" &&
+		r.License == "" && r.Agents == "" &&
+		len(r.Legal) == 0 && len(r.Community) == 0 &&
+		len(r.Security) == 0 && len(r.Metadata) == 0
 }
 
 // GitInfo describes the git repository state.

detect/detect.go

@@ -8,6 +8,7 @@ import (
 	"io"
 	"os"
 	"os/exec"
+	"path"
 	"path/filepath"
 	"sort"
 	"strings"
@@ -47,6 +48,7 @@ type Engine struct {
 
 	// Lazily populated caches
 	fileExts    map[string]int // cached file extension counts in the project
+	dirCache    map[string][]string
 	depsLoaded  bool
 	runtimeDeps map[string]bool // all runtime/unscoped dependency names
 	devDeps     map[string]bool // development/test/build dependency names
@@ -1002,38 +1004,86 @@ func (e *Engine) detectResources() *brief.ResourceInfo {
 	}
 
 	res := &brief.ResourceInfo{}
-	found := false
 
 	for _, rd := range e.KB.Resources {
-		for _, pattern := range rd.Resource.Patterns {
-			if matches := e.globMatch(pattern); len(matches) > 0 {
-				found = true
-				match := filepath.Base(matches[0])
-				switch rd.Resource.Field {
-				case "readme":
-					res.Readme = match
-				case "contributing":
-					res.Contributing = match
-				case "changelog":
-					res.Changelog = match
-				case "license":
-					res.License = match
-					res.LicenseType = detectLicenseType(matches[0])
-				case "security":
-					res.Security = match
-				}
-				break
+		abs, rel := e.findResource(rd.Resource)
+		if rel == "" {
+			continue
+		}
+		if rd.Resource.Group != "" {
+			if g := res.Group(rd.Resource.Group); g != nil {
+				g[rd.Resource.Field] = rel
 			}
+			continue
+		}
+		switch rd.Resource.Field {
+		case "readme":
+			res.Readme = rel
+		case "changelog":
+			res.Changelog = rel
+		case "roadmap":
+			res.Roadmap = rel
+		case "license":
+			res.License = rel
+			res.LicenseType = detectLicenseType(abs)
+		case "agents":
+			res.Agents = rel
 		}
 	}
 
-	if !found {
+	if res.Empty() {
 		return nil
 	}
-
 	return res
 }
 
+// findResource searches for the first file matching any of the resource's
+// patterns, in the repo root and then each configured subdirectory. Matching
+// is case-insensitive. It returns the absolute path and the path relative to
+// the repo root.
+func (e *Engine) findResource(r kb.ResourceInfo) (abs, rel string) {
+	dirs := append([]string{"."}, r.Dirs...)
+	for _, dir := range dirs {
+		entries := e.dirFiles(dir)
+		for _, pattern := range r.Patterns {
+			lp := strings.ToLower(pattern)
+			for _, name := range entries {
+				if ok, _ := filepath.Match(lp, strings.ToLower(name)); !ok {
+					continue
+				}
+				relPath := name
+				if dir != "." {
+					relPath = path.Join(dir, name)
+				}
+				return filepath.Join(e.Root, filepath.FromSlash(relPath)), relPath
+			}
+		}
+	}
+	return "", ""
+}
+
+// dirFiles returns the regular file names in dir (relative to e.Root),
+// caching results per directory.
+func (e *Engine) dirFiles(dir string) []string {
+	if e.dirCache == nil {
+		e.dirCache = map[string][]string{}
+	}
+	if cached, ok := e.dirCache[dir]; ok {
+		return cached
+	}
+	var names []string
+	entries, err := os.ReadDir(filepath.Join(e.Root, filepath.FromSlash(dir)))
+	if err == nil {
+		for _, ent := range entries {
+			if !ent.IsDir() {
+				names = append(names, ent.Name())
+			}
+		}
+	}
+	e.dirCache[dir] = names
+	return names
+}
+
 // detectPlatforms checks for runtime version files and CI matrices.
 func (e *Engine) detectPlatforms() *brief.PlatformInfo {
 	platforms := &brief.PlatformInfo{
@@ -1161,15 +1211,6 @@ func toStringSlice(v any) []string {
 	}
 }
 
-// globMatch returns files matching a glob pattern relative to the project root.
-func (e *Engine) globMatch(pattern string) []string {
-	matches, err := filepath.Glob(filepath.Join(e.Root, pattern))
-	if err != nil {
-		return nil
-	}
-	return matches
-}
-
 // detectGit extracts git repository metadata by shelling out to git.
 // Returns nil if git is not installed or the directory is not a git repo.
 func (e *Engine) detectGit(absPath string) *brief.GitInfo {

detect/detect_test.go

@@ -119,6 +119,114 @@ func TestRubyResources(t *testing.T) {
 	}
 }
 
+func TestResourceGroups(t *testing.T) {
+	dir := t.TempDir()
+	touch := func(p string) {
+		full := filepath.Join(dir, p)
+		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(full, []byte("x"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	touch("README.md")
+	touch("CHANGELOG.md")
+	touch("AGENTS.md")
+	touch("NOTICE")
+	touch("CONTRIBUTING.md")
+	touch(".github/CODE_OF_CONDUCT.md")
+	touch(".github/CODEOWNERS")
+	touch(".github/FUNDING.yml")
+	touch("docs/SECURITY.md")
+	touch("CITATION.cff")
+
+	engine := New(loadKB(t), dir)
+	r, err := engine.Run()
+	if err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	res := r.Resources
+	if res == nil {
+		t.Fatal("expected resources")
+	}
+
+	if res.Readme != "README.md" {
+		t.Errorf("readme = %q", res.Readme)
+	}
+	if res.Agents != "AGENTS.md" {
+		t.Errorf("agents = %q", res.Agents)
+	}
+	if res.Legal["notice"] != "NOTICE" {
+		t.Errorf("legal.notice = %q", res.Legal["notice"])
+	}
+	if res.Community["contributing"] != "CONTRIBUTING.md" {
+		t.Errorf("community.contributing = %q", res.Community["contributing"])
+	}
+	if res.Community["code_of_conduct"] != ".github/CODE_OF_CONDUCT.md" {
+		t.Errorf("community.code_of_conduct = %q", res.Community["code_of_conduct"])
+	}
+	if res.Community["codeowners"] != ".github/CODEOWNERS" {
+		t.Errorf("community.codeowners = %q", res.Community["codeowners"])
+	}
+	if res.Security["policy"] != "docs/SECURITY.md" {
+		t.Errorf("security.policy = %q", res.Security["policy"])
+	}
+	if res.Metadata["funding"] != ".github/FUNDING.yml" {
+		t.Errorf("metadata.funding = %q", res.Metadata["funding"])
+	}
+	if res.Metadata["citation"] != "CITATION.cff" {
+		t.Errorf("metadata.citation = %q", res.Metadata["citation"])
+	}
+}
+
+func TestResourceCaseInsensitive(t *testing.T) {
+	dir := t.TempDir()
+	for _, p := range []string{"ReadMe.rst", "Security.MD", ".github/Code_Of_Conduct.md"} {
+		full := filepath.Join(dir, p)
+		_ = os.MkdirAll(filepath.Dir(full), 0o755)
+		if err := os.WriteFile(full, []byte("x"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	engine := New(loadKB(t), dir)
+	r, err := engine.Run()
+	if err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	if r.Resources == nil {
+		t.Fatal("expected resources")
+	}
+	if r.Resources.Readme != "ReadMe.rst" {
+		t.Errorf("readme = %q", r.Resources.Readme)
+	}
+	if r.Resources.Security["policy"] != "Security.MD" {
+		t.Errorf("security.policy = %q", r.Resources.Security["policy"])
+	}
+	if r.Resources.Community["code_of_conduct"] != ".github/Code_Of_Conduct.md" {
+		t.Errorf("code_of_conduct = %q", r.Resources.Community["code_of_conduct"])
+	}
+}
+
+func TestResourceRootBeatsSubdir(t *testing.T) {
+	dir := t.TempDir()
+	for _, p := range []string{"CONTRIBUTING.md", ".github/CONTRIBUTING.md"} {
+		full := filepath.Join(dir, p)
+		_ = os.MkdirAll(filepath.Dir(full), 0o755)
+		if err := os.WriteFile(full, []byte("x"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	engine := New(loadKB(t), dir)
+	r, err := engine.Run()
+	if err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	if got := r.Resources.Community["contributing"]; got != "CONTRIBUTING.md" {
+		t.Errorf("expected root CONTRIBUTING.md to win, got %q", got)
+	}
+}
+
 func TestRubyPlatforms(t *testing.T) {
 	r := rubyReport(t)
 	if r.Platforms == nil {