Merge pull request 'feat(#141): validate-docmap subcommand' (#156) from issue-141 into main

Reviewed-on: #156
Reviewed-by: security-review-bot <10+security-review-bot@noreply.gitea.weiker.me>

CYCLE_STATUS_2026-05-15-1442.md

@@ -0,0 +1,38 @@
+# Dev-Loop Cycle Status — 2026-05-15 14:42 UTC
+
+**Cron ID:** 5342ac81-4bbc-4e4c-a123-347a7788d50c  
+**Cycle:** review-bot-dev-loop (4-hour schedule)  
+**Status:** ✅ **STEADY STATE** — All systems nominal, repo healthy
+
+## Health Check Summary
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Main branch | ✅ Current | HEAD at 8ab45be (synced) |
+| Working tree | ✅ Clean | No uncommitted changes |
+| Test suite | ✅ All pass | 100% pass rate (go test ./...) |
+| Code coverage | ✅ 76.7% | Above baseline target |
+| Open issues | ✅ None | No assigned work |
+| Open PRs | ✅ None | All merged |
+| Remote sync | ✅ On-time | Up-to-date with origin/main |
+
+## Actions This Cycle
+
+- ✅ Fetched origin/main — up-to-date
+- ✅ Ran full test suite — all pass
+- ✅ Calculated code coverage — 76.7%
+- ✅ Checked for new issues/PRs — none found
+- ✅ Verified working tree clean
+
+## Backlog Opportunities
+
+1. **Integration tests** — cmd/review-bot coverage (53.3% → target 80%)
+2. **Performance profiling** — doc-map filtering optimization
+3. **Documentation** — Composite action examples
+
+## Recommendation
+
+**No new assignments.** Repo ready for next feature work. Standing by.
+
+---
+Generated: 2026-05-15 14:42 UTC | Cron: review-bot-dev-loop

cmd/review-bot/validatedocmap.go

@@ -61,6 +61,13 @@ func validateDocmapPath(localPath, resolvedRoot string) error {
 		return fmt.Errorf("symlinks are not allowed")
 	}
 
+	// Reject anything that is not a regular file (directories, FIFOs, device
+	// nodes, etc.) — ParseDocMapConfig expects a plain YAML file and would
+	// produce a confusing error on non-regular entries.
+	if !fi.Mode().IsRegular() {
+		return fmt.Errorf("docmap must be a regular file")
+	}
+
 	// Confine to resolvedRoot: use the fully-resolved path so that a directory
 	// symlink inside the repo cannot carry the path outside the root.
 	rel, err := filepath.Rel(resolvedRoot, resolvedPath)
@@ -171,6 +178,9 @@ func runValidateDocmap(args []string) int {
 		// Normalize Windows-style backslashes to forward slashes so that
 		// changed-file paths from git on Windows match doc-map globs.
 		f = strings.ReplaceAll(f, "\\", "/")
+		// Strip a leading "./" emitted by non-git tools (e.g. `find`) so that
+		// paths like "./cmd/foo.go" match doc-map globs written as "cmd/**".
+		f = strings.TrimPrefix(f, "./")
 		if !review.FileCoveredByDocMap(cfg, f) {
 			uncovered = append(uncovered, f)
 		}
@@ -189,7 +199,7 @@ func runValidateDocmap(args []string) int {
 	staleDocs := checkStaleDocs(cfg, resolvedRoot)
 	if len(staleDocs) > 0 {
 		failed = true
-		fmt.Fprintln(errWriter, "ERROR: stale docmap docs: entries (paths do not exist):")
+		fmt.Fprintln(errWriter, "ERROR: stale docmap entries (paths do not exist):")
 		for _, d := range staleDocs {
 			fmt.Fprintf(errWriter, "  %s\n", d)
 		}

cmd/review-bot/validatedocmap_test.go

@@ -599,3 +599,53 @@ func TestValidateDocmapPath_DirSymlinkBypass(t *testing.T) {
 		t.Error("expected rejection of dir-symlink bypass, got nil error")
 	}
 }
+
+// TestValidateDocmapPath_NonRegularFile verifies that --docmap pointing at a
+// non-regular file (e.g. a directory) is rejected with a clear error before
+// ParseDocMapConfig is called.
+func TestValidateDocmapPath_NonRegularFile(t *testing.T) {
+	dir := t.TempDir()
+
+	// Use the directory itself as the docmap path — directories pass Lstat but
+	// are not regular files.
+	reviewBotDir := filepath.Join(dir, ".review-bot")
+	if err := os.MkdirAll(reviewBotDir, 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+
+	code, _, stderr := stdinValidateDocmap(t,
+		"",
+		[]string{"--docmap", reviewBotDir, "--repo-root", dir},
+	)
+	if code != 2 {
+		t.Errorf("expected exit 2 for directory docmap, got %d; stderr: %q", code, stderr)
+	}
+	if !strings.Contains(stderr, "regular file") && !strings.Contains(stderr, "invalid") {
+		t.Errorf("expected regular-file rejection in stderr, got %q", stderr)
+	}
+}
+
+// TestRunValidateDocmap_DotSlashPrefix verifies that paths emitted with a
+// leading "./" (e.g. from `find` or `ls`) match doc-map globs correctly.
+// Without TrimPrefix, "./cmd/foo.go" would not match the pattern "cmd/**".
+func TestRunValidateDocmap_DotSlashPrefix(t *testing.T) {
+	dir := t.TempDir()
+	makeDocFile(t, dir, "docs/foo.md")
+
+	docmap := makeDocmapInDir(t, dir, `
+mappings:
+  - paths:
+      - "cmd/**"
+    docs:
+      - docs/foo.md
+`)
+
+	// File with a leading "./" should be treated as covered.
+	code, _, stderr := stdinValidateDocmap(t,
+		"./cmd/foo.go\n",
+		[]string{"--docmap", docmap, "--repo-root", dir},
+	)
+	if code != 0 {
+		t.Errorf("expected exit 0 for './' prefixed covered file, got %d; stderr: %q", code, stderr)
+	}
+}