plan 52: reuse archetypes.DefaultRoot + surface List errors

- Drop the duplicate DefaultArchetypeRoot constant in the
  required-structure rule and reuse archetypes.DefaultRoot.
  Single source of truth for the default root name.
- Add Resolver.ListWithErrors that returns both the successfully
  discovered archetypes and the non-ErrNotExist errors from each
  readDir. List keeps its old signature for callers that do not
  care about errors.
- mdsmith archetypes list now surfaces read errors on stderr and
  exits 2 when a root errored with no discoverable archetypes.
- Tests: injected fs.FS that errors on ReadDir for a specific root
  to verify both the error-surfacing and not-exist-is-silent
  branches.

Author: claude

cmd/mdsmith/archetypes.go

@@ -204,8 +204,14 @@ func runArchetypesList(args []string) int {
 		fmt.Fprintf(os.Stderr, "mdsmith: %v\n", err)
 		return 2
 	}
-	entries := resolver.List()
+	entries, listErrs := resolver.ListWithErrors()
+	for _, err := range listErrs {
+		fmt.Fprintf(os.Stderr, "mdsmith: %v\n", err)
+	}
 	if len(entries) == 0 {
+		if len(listErrs) > 0 {
+			return 2
+		}
 		fmt.Fprintf(os.Stderr,
 			"mdsmith: no archetypes found under roots %v\n",
 			resolver.EffectiveRoots())

internal/archetypes/archetypes.go

@@ -139,16 +139,36 @@ func (r *Resolver) osJoin(p string) string {
 // archetype names (see isArchetypeName) are skipped — this keeps
 // README.md, dotfiles, and underscore-prefixed scratch files out of
 // the archetype namespace.
+//
+// List silently ignores every readDir error so it can never return
+// a partial result with an error set. Use ListWithErrors when
+// callers need to distinguish "root does not exist" from "root
+// could not be read".
 func (r *Resolver) List() []Entry {
+	entries, _ := r.ListWithErrors()
+	return entries
+}
+
+// ListWithErrors is like List but also returns every non-ErrNotExist
+// error encountered while reading a root. The entry slice is always
+// populated with the archetypes that were successfully discovered;
+// errors are returned alongside so callers can decide whether to
+// surface them as warnings or fail fast.
+func (r *Resolver) ListWithErrors() ([]Entry, []error) {
 	seen := map[string]bool{}
 	var out []Entry
+	var errs []error
 	for _, root := range r.roots() {
 		cleanRoot := filepath.ToSlash(filepath.Clean(root))
-		entries, err := r.readDir(cleanRoot)
+		dirEntries, err := r.readDir(cleanRoot)
 		if err != nil {
+			if !errors.Is(err, fs.ErrNotExist) {
+				errs = append(errs, fmt.Errorf(
+					"reading archetype root %q: %w", root, err))
+			}
 			continue
 		}
-		for _, e := range entries {
+		for _, e := range dirEntries {
 			if e.IsDir() {
 				continue
 			}
@@ -172,7 +192,7 @@ func (r *Resolver) List() []Entry {
 		}
 	}
 	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
-	return out
+	return out, errs
 }
 
 // isArchetypeName reports whether basename (without the ".md"

internal/archetypes/archetypes_test.go

@@ -282,6 +282,48 @@ func TestValidateRoots_EmptySliceOK(t *testing.T) {
 	assert.NoError(t, ValidateRoots(nil))
 }
 
+// readDirErrFS returns a non-ErrNotExist error from ReadDir for a
+// specific root, exercising ListWithErrors' error-surfacing branch.
+type readDirErrFS struct {
+	fs      fs.FS
+	errRoot string
+	err     error
+}
+
+func (s readDirErrFS) Open(name string) (fs.File, error) {
+	return s.fs.Open(name)
+}
+
+func (s readDirErrFS) ReadDir(name string) ([]fs.DirEntry, error) {
+	if name == s.errRoot {
+		return nil, s.err
+	}
+	return fs.ReadDir(s.fs, name)
+}
+
+func TestResolver_ListWithErrors_ReturnsNonNotExistErrors(t *testing.T) {
+	boom := errors.New("io boom")
+	r := &Resolver{FS: readDirErrFS{
+		fs:      fsWith(map[string]string{"good/story.md": "# ?"}),
+		errRoot: "bad",
+		err:     boom,
+	}, Roots: []string{"bad", "good"}}
+	entries, errs := r.ListWithErrors()
+	require.Len(t, entries, 1)
+	assert.Equal(t, "story", entries[0].Name)
+	require.Len(t, errs, 1)
+	assert.Contains(t, errs[0].Error(), "reading archetype root")
+	assert.True(t, errors.Is(errs[0], boom))
+}
+
+func TestResolver_ListWithErrors_SilentOnNotExist(t *testing.T) {
+	// Missing root is fine — the resolver tolerates empty directories.
+	r := &Resolver{Roots: []string{"missing"}, FS: fsWith(nil)}
+	entries, errs := r.ListWithErrors()
+	assert.Empty(t, entries)
+	assert.Empty(t, errs)
+}
+
 func TestResolver_LookupSkipsDirectoryMatch(t *testing.T) {
 	// A directory named "story.md" under the root must not be treated
 	// as the archetype file.

internal/rules/requiredstructure/rule.go

@@ -28,13 +28,9 @@ func init() {
 type Rule struct {
 	Schema         string   // path to schema file
 	Archetype      string   // name of an archetype schema discovered under ArchetypeRoots
-	ArchetypeRoots []string // directories searched for archetypes; defaults to [DefaultArchetypeRoot]
+	ArchetypeRoots []string // directories searched for archetypes; defaults to [archetypes.DefaultRoot]
 }
 
-// DefaultArchetypeRoot is the directory used when no archetype roots
-// are configured for the rule.
-const DefaultArchetypeRoot = "archetypes"
-
 // ID implements rule.Rule.
 func (r *Rule) ID() string { return "MDS020" }
 
@@ -107,7 +103,7 @@ func (r *Rule) DefaultSettings() map[string]any {
 	return map[string]any{
 		"schema":          "",
 		"archetype":       "",
-		"archetype-roots": []string{DefaultArchetypeRoot},
+		"archetype-roots": []string{archetypes.DefaultRoot},
 	}
 }
 
@@ -237,7 +233,7 @@ func (r *Rule) isSchemaOrArchetypeFile(f *lint.File) bool {
 	}
 	roots := r.ArchetypeRoots
 	if len(roots) == 0 {
-		roots = []string{DefaultArchetypeRoot}
+		roots = []string{archetypes.DefaultRoot}
 	}
 	// Try a plain relative-path match (covers common layouts where
 	// mdsmith runs from the project root) and an absolute-to-RootDir
@@ -282,7 +278,7 @@ func (r *Rule) isSchemaOrArchetypeFile(f *lint.File) bool {
 // the default when the rule's setting is empty.
 func (r *Rule) archetypeRoots() []string {
 	if len(r.ArchetypeRoots) == 0 {
-		return []string{DefaultArchetypeRoot}
+		return []string{archetypes.DefaultRoot}
 	}
 	return r.ArchetypeRoots
 }

internal/rules/requiredstructure/rule_test.go

@@ -8,6 +8,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/jeduden/mdsmith/internal/archetypes"
 	"github.com/jeduden/mdsmith/internal/lint"
 
 	"github.com/stretchr/testify/assert"
@@ -255,7 +256,7 @@ func TestApplySettings_ArchetypeRootsTypedStringSlice(t *testing.T) {
 func TestDefaultSettings_ArchetypeRoots(t *testing.T) {
 	r := &Rule{}
 	assert.Equal(t,
-		[]string{DefaultArchetypeRoot},
+		[]string{archetypes.DefaultRoot},
 		r.DefaultSettings()["archetype-roots"])
 }