feat: resolver files (#16)

* feat(config): resolve source files from resolver documents

When the config has `resolvers` entries, the CLI commands (list, convert,
search, validate) now read the resolver documents and extract their
source file `$ref` entries. This enables using resolver documents as
the sole configuration, without needing to also list source files in
the `files` config field.

Supports both inline sources in `resolutionOrder` entries and named
sets referenced via `$ref: "#/sets/<name>"`.

Assisted-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address review findings for resolver sources

- Exclude resolver sources from in-place conversion to prevent
  accidental rewriting of dependency files
- Deduplicate resolved files by path to prevent duplicate tokens
  when the same file appears in both config files and resolver sources
- Return errors from resolveEntry instead of silently skipping them

Assisted-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address review findings for resolver config

- Extract duplicated dedup function to specifier.DedupResolvedFiles
- Return error for unrecognized resolver entry shapes instead of nil

Assisted-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: strip fragment identifiers from $ref file paths

A $ref like "palette.json#/brand" was being passed through as a full
path including the fragment, producing invalid filesystem paths.
Now strips the fragment before resolving.

Assisted-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: decode JSON Pointer escaping in resolver set references

Refs like "#/sets/brand~1core" or "#/sets/brand%20core" now correctly
resolve to set keys "brand/core" and "brand core" respectively, per
RFC 6901 JSON Pointer and percent-encoding specs.

Assisted-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bennypowers

cmd/convert/convert.go

@@ -202,6 +202,16 @@ func run(cmd *cobra.Command, args []string) error {
 		if err != nil {
 			return fmt.Errorf("error resolving config files: %w", err)
 		}
+
+		// Also resolve sources from resolver documents (not for in-place mode,
+		// which should only rewrite files explicitly listed in config)
+		if !inPlace && len(cfg.Resolvers) > 0 {
+			resolverSources, err := cfg.ResolveResolverSources(specResolver, filesystem, cwd)
+			if err != nil {
+				return fmt.Errorf("error resolving resolver sources: %w", err)
+			}
+			resolvedFiles = specifier.DedupResolvedFiles(append(resolvedFiles, resolverSources...))
+		}
 	} else {
 		for _, arg := range args {
 			rf, err := specResolver.Resolve(arg)

cmd/list/list.go

@@ -96,6 +96,15 @@ func run(cmd *cobra.Command, args []string) error {
 		if err != nil {
 			return fmt.Errorf("error resolving config files: %w", err)
 		}
+
+		// Also resolve sources from resolver documents
+		if len(cfg.Resolvers) > 0 {
+			resolverSources, err := cfg.ResolveResolverSources(specResolver, filesystem, cwd)
+			if err != nil {
+				return fmt.Errorf("error resolving resolver sources: %w", err)
+			}
+			resolvedFiles = specifier.DedupResolvedFiles(append(resolvedFiles, resolverSources...))
+		}
 	} else {
 		for _, arg := range args {
 			rf, err := specResolver.Resolve(arg)

cmd/search/search.go

@@ -106,6 +106,15 @@ func run(cmd *cobra.Command, args []string) error {
 		if err != nil {
 			return fmt.Errorf("error resolving config files: %w", err)
 		}
+
+		// Also resolve sources from resolver documents
+		if len(cfg.Resolvers) > 0 {
+			resolverSources, err := cfg.ResolveResolverSources(specResolver, filesystem, cwd)
+			if err != nil {
+				return fmt.Errorf("error resolving resolver sources: %w", err)
+			}
+			resolvedFiles = specifier.DedupResolvedFiles(append(resolvedFiles, resolverSources...))
+		}
 	} else {
 		for _, file := range files {
 			rf, err := specResolver.Resolve(file)

cmd/validate/validate.go

@@ -63,6 +63,15 @@ func run(cmd *cobra.Command, args []string) error {
 		if err != nil {
 			return fmt.Errorf("error resolving config files: %w", err)
 		}
+
+		// Also resolve sources from resolver documents
+		if len(cfg.Resolvers) > 0 {
+			resolverSources, err := cfg.ResolveResolverSources(specResolver, filesystem, cwd)
+			if err != nil {
+				return fmt.Errorf("error resolving resolver sources: %w", err)
+			}
+			resolvedFiles = specifier.DedupResolvedFiles(append(resolvedFiles, resolverSources...))
+		}
 	} else {
 		for _, arg := range args {
 			rf, err := specResolver.Resolve(arg)

config/resolver_doc.go

@@ -0,0 +1,170 @@
+/*
+Copyright 2026 Benny Powers. All rights reserved.
+Use of this source code is governed by the GPLv3
+license that can be found in the LICENSE file.
+*/
+
+package config
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"path/filepath"
+	"strings"
+
+	asimfs "bennypowers.dev/asimonim/fs"
+	"bennypowers.dev/asimonim/specifier"
+)
+
+// resolverDocument represents the structure of a DTCG resolver document.
+type resolverDocument struct {
+	Version         string            `json:"version"`
+	Sets            map[string]setDef `json:"sets"`
+	ResolutionOrder json.RawMessage   `json:"resolutionOrder"`
+}
+
+// setDef represents a named set in a resolver document.
+type setDef struct {
+	Sources []sourceRef `json:"sources"`
+}
+
+// sourceRef represents a source reference in a resolver document.
+type sourceRef struct {
+	Ref string `json:"$ref"`
+}
+
+// ResolveResolverSources reads resolver documents and returns their source file paths
+// as ResolvedFile entries. Each resolver document is parsed to extract $ref entries
+// from its resolution order, and those paths are resolved relative to the resolver
+// document's directory.
+func (c *Config) ResolveResolverSources(resolver specifier.Resolver, filesystem asimfs.FileSystem, rootDir string) ([]*specifier.ResolvedFile, error) {
+	// First resolve the resolver document paths themselves
+	resolverFiles, err := c.ResolveResolvers(resolver, filesystem, rootDir)
+	if err != nil {
+		return nil, err
+	}
+
+	var result []*specifier.ResolvedFile
+	seen := make(map[string]bool)
+
+	for _, rf := range resolverFiles {
+		sourcePaths, err := extractResolverSourcePaths(filesystem, rf.Path)
+		if err != nil {
+			return nil, fmt.Errorf("failed to extract sources from resolver %s: %w", rf.Specifier, err)
+		}
+
+		for _, srcPath := range sourcePaths {
+			if seen[srcPath] {
+				continue
+			}
+			seen[srcPath] = true
+
+			result = append(result, &specifier.ResolvedFile{
+				Specifier: srcPath,
+				Path:      srcPath,
+				Kind:      specifier.KindLocal,
+			})
+		}
+	}
+
+	return result, nil
+}
+
+// extractResolverSourcePaths reads a resolver document and extracts source file paths.
+func extractResolverSourcePaths(filesystem asimfs.FileSystem, resolverPath string) ([]string, error) {
+	data, err := filesystem.ReadFile(resolverPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read resolver document: %w", err)
+	}
+
+	var doc resolverDocument
+	if err := json.Unmarshal(data, &doc); err != nil {
+		return nil, fmt.Errorf("failed to parse resolver document: %w", err)
+	}
+
+	var entries []json.RawMessage
+	if err := json.Unmarshal(doc.ResolutionOrder, &entries); err != nil {
+		return nil, fmt.Errorf("failed to parse resolutionOrder: %w", err)
+	}
+
+	resolverDir := filepath.Dir(resolverPath)
+	var paths []string
+	seen := make(map[string]bool)
+
+	for i, entry := range entries {
+		entryPaths, err := resolveEntry(entry, doc.Sets)
+		if err != nil {
+			return nil, fmt.Errorf("failed to resolve entry %d: %w", i, err)
+		}
+		for _, p := range entryPaths {
+			absPath := resolveRefPath(p, resolverDir)
+			if !seen[absPath] {
+				seen[absPath] = true
+				paths = append(paths, absPath)
+			}
+		}
+	}
+
+	return paths, nil
+}
+
+// resolveEntry extracts source file paths from a resolution order entry.
+func resolveEntry(entry json.RawMessage, sets map[string]setDef) ([]string, error) {
+	var ref sourceRef
+	if err := json.Unmarshal(entry, &ref); err == nil && ref.Ref != "" {
+		if rawName, ok := strings.CutPrefix(ref.Ref, "#/sets/"); ok {
+			setName := unescapeJSONPointer(rawName)
+			set, exists := sets[setName]
+			if !exists {
+				return nil, fmt.Errorf("referenced set %q not found", setName)
+			}
+			return fileRefsFromSources(set.Sources), nil
+		}
+	}
+
+	var inlineSet struct {
+		Sources []sourceRef `json:"sources"`
+	}
+	if err := json.Unmarshal(entry, &inlineSet); err == nil && len(inlineSet.Sources) > 0 {
+		return fileRefsFromSources(inlineSet.Sources), nil
+	}
+
+	return nil, fmt.Errorf("unrecognized resolution order entry: %s", string(entry))
+}
+
+// fileRefsFromSources extracts file paths from source $ref entries,
+// filtering out JSON pointer references.
+func fileRefsFromSources(sources []sourceRef) []string {
+	var paths []string
+	for _, src := range sources {
+		if src.Ref == "" || strings.HasPrefix(src.Ref, "#") {
+			continue
+		}
+		// Strip any fragment identifier (e.g., "palette.json#/brand" → "palette.json")
+		path, _, _ := strings.Cut(src.Ref, "#")
+		if path != "" {
+			paths = append(paths, path)
+		}
+	}
+	return paths
+}
+
+// unescapeJSONPointer decodes a JSON Pointer token per RFC 6901:
+// percent-decoding first, then replacing ~1 with / and ~0 with ~.
+func unescapeJSONPointer(s string) string {
+	if unescaped, err := url.PathUnescape(s); err == nil {
+		s = unescaped
+	}
+	s = strings.ReplaceAll(s, "~1", "/")
+	s = strings.ReplaceAll(s, "~0", "~")
+	return s
+}
+
+// resolveRefPath resolves a $ref path relative to the resolver document's directory.
+func resolveRefPath(refPath, resolverDir string) string {
+	if filepath.IsAbs(refPath) {
+		return filepath.Clean(refPath)
+	}
+	return filepath.Clean(filepath.Join(resolverDir, refPath))
+}