feat(github): implement FileReader interface (#80)

Implement FileReader conformance on the GitHub client: GetFileContent,
ListContents, path helpers, base64 decode. Includes compile-time
conformance checks for both PRReader and FileReader.

Requires PR B (#102). Part 3 of 3 for #80.

github/files.go

@@ -8,8 +8,16 @@ import (
 	"net/url"
 	"path"
 	"strings"
+
+	"gitea.weiker.me/rodin/review-bot/vcs"
 )
 
+// GetFileContent fetches a file from a repo at the given ref.
+// Delegates to GetFileContentAtRef with the provided ref.
+func (c *Client) GetFileContent(ctx context.Context, owner, repo, filePath, ref string) (string, error) {
+	return c.GetFileContentAtRef(ctx, owner, repo, filePath, ref)
+}
+
 // GetFileContentAtRef fetches a file at a specific ref from a repo.
 // If ref is empty, the query parameter is omitted (uses default branch).
 //
@@ -46,6 +54,58 @@ func (c *Client) GetFileContentAtRef(ctx context.Context, owner, repo, filePath,
 	return decoded, nil
 }
 
+// ListContents lists files and directories at a given path in a repo.
+// Returns the directory listing from the GitHub contents API.
+// If the path points to a single file (not a directory), the API returns
+// a JSON object instead of an array; this is handled by returning a
+// single-element slice.
+func (c *Client) ListContents(ctx context.Context, owner, repo, filePath string) ([]vcs.ContentEntry, error) {
+	escaped, err := escapePath(filePath)
+	if err != nil {
+		return nil, fmt.Errorf("invalid file path: %w", err)
+	}
+	reqURL := fmt.Sprintf("%s/repos/%s/%s/contents/%s",
+		c.baseURL, url.PathEscape(owner), url.PathEscape(repo), escaped)
+	body, err := c.doGet(ctx, reqURL)
+	if err != nil {
+		return nil, fmt.Errorf("list contents %s: %w", filePath, err)
+	}
+
+	type entry struct {
+		Name string `json:"name"`
+		Path string `json:"path"`
+		Type string `json:"type"`
+	}
+
+	// The GitHub contents API returns an array for directories and an object
+	// for single files. Try array first (common case), then fall back to object.
+	// An empty array ([]) is valid — it represents an empty directory — and
+	// results in a zero-length slice returned without error.
+	var entries []entry
+	if err := json.Unmarshal(body, &entries); err != nil {
+		var single entry
+		if err2 := json.Unmarshal(body, &single); err2 != nil {
+			return nil, fmt.Errorf("parse contents JSON: as array: %v; as object: %w", err, err2)
+		}
+		// Guard against empty objects ({}) or unexpected shapes that
+		// unmarshal successfully but carry no useful data.
+		if single.Name == "" && single.Path == "" && single.Type == "" {
+			return nil, fmt.Errorf("parse contents JSON: unexpected response format")
+		}
+		entries = []entry{single}
+	}
+
+	result := make([]vcs.ContentEntry, len(entries))
+	for i, e := range entries {
+		result[i] = vcs.ContentEntry{
+			Name: e.Name,
+			Path: e.Path,
+			Type: e.Type,
+		}
+	}
+	return result, nil
+}
+
 // escapePath validates and encodes a slash-separated file path for use in
 // GitHub API URLs. Returns an error if the path contains dot-segments ("."
 // or "..") or resolves to a path outside the repository root.