Lint improvements: enhance document file collection with namespace manifest support and add tests for foreign document handling

Author: tae2089

internal/docs/lint.go

@@ -1,13 +1,15 @@
 package docs
 
 import (
+	"encoding/json"
 	"fmt"
 	"os"
 	"path/filepath"
 	"sort"
 	"strings"
 
 	"github.com/tae2089/code-context-graph/internal/ccgref"
+	"github.com/tae2089/code-context-graph/internal/ctxns"
 	"github.com/tae2089/code-context-graph/internal/model"
 	"github.com/tae2089/code-context-graph/internal/pathutil"
 )
@@ -52,35 +54,9 @@ func (g *Generator) Lint() (*LintReport, error) {
 	report := &LintReport{}
 
 	// 1. Collect all .md doc files from the output directory.
-	docFiles := map[string]os.FileInfo{} // source path → FileInfo of .md
-	if _, err := os.Stat(g.OutDir); err == nil {
-		err := filepath.Walk(g.OutDir, func(path string, info os.FileInfo, err error) error {
-			if err != nil || info.IsDir() {
-				return err
-			}
-			if !strings.HasSuffix(path, ".md") {
-				return nil
-			}
-
-			rel, _ := filepath.Rel(g.OutDir, path)
-			rel = filepath.ToSlash(rel)
-
-			// Skip index.md — it's not a per-file doc.
-			if rel == "index.md" {
-				return nil
-			}
-
-			// Strip .md suffix to get the source path.
-			srcPath := strings.TrimSuffix(rel, ".md")
-			if len(g.Exclude) > 0 && pathutil.MatchExcludes(g.Exclude, srcPath) {
-				return nil
-			}
-			docFiles[srcPath] = info
-			return nil
-		})
-		if err != nil {
-			return nil, fmt.Errorf("walk docs dir: %w", err)
-		}
+	docFiles, err := g.lintDocFiles()
+	if err != nil {
+		return nil, err
 	}
 
 	// 2. Collect all source file paths from the graph (distinct file_path
@@ -301,6 +277,90 @@ func (g *Generator) Lint() (*LintReport, error) {
 	return report, nil
 }
 
+// @intent collect only the Markdown files that belong to the active docs namespace.
+// @domainRule named namespaces trust their scoped manifest; without one, foreign docs in the shared output dir are ignored.
+func (g *Generator) lintDocFiles() (map[string]os.FileInfo, error) {
+	docFiles := map[string]os.FileInfo{} // source path -> FileInfo of .md
+	if m, ok, err := g.loadLintManifest(); err != nil {
+		return nil, err
+	} else if ok {
+		for _, rel := range m.Files {
+			rel = filepath.ToSlash(rel)
+			if rel == "index.md" || !strings.HasSuffix(rel, ".md") {
+				continue
+			}
+			srcPath := strings.TrimSuffix(rel, ".md")
+			if len(g.Exclude) > 0 && pathutil.MatchExcludes(g.Exclude, srcPath) {
+				continue
+			}
+			full, err := safeDocOutputPath(g.OutDir, rel)
+			if err != nil {
+				return nil, err
+			}
+			info, err := os.Stat(full)
+			if err != nil {
+				if os.IsNotExist(err) {
+					continue
+				}
+				return nil, err
+			}
+			if !info.IsDir() {
+				docFiles[srcPath] = info
+			}
+		}
+		return docFiles, nil
+	}
+	if g.Namespace != "" && ctxns.Normalize(g.Namespace) != ctxns.DefaultNamespace {
+		return docFiles, nil
+	}
+	if _, err := os.Stat(g.OutDir); err == nil {
+		err := filepath.Walk(g.OutDir, func(path string, info os.FileInfo, err error) error {
+			if err != nil || info.IsDir() {
+				return err
+			}
+			if !strings.HasSuffix(path, ".md") {
+				return nil
+			}
+
+			rel, _ := filepath.Rel(g.OutDir, path)
+			rel = filepath.ToSlash(rel)
+
+			// Skip index.md — it's not a per-file doc.
+			if rel == "index.md" {
+				return nil
+			}
+
+			// Strip .md suffix to get the source path.
+			srcPath := strings.TrimSuffix(rel, ".md")
+			if len(g.Exclude) > 0 && pathutil.MatchExcludes(g.Exclude, srcPath) {
+				return nil
+			}
+			docFiles[srcPath] = info
+			return nil
+		})
+		if err != nil {
+			return nil, fmt.Errorf("walk docs dir: %w", err)
+		}
+	}
+	return docFiles, nil
+}
+
+// @intent load the active namespace manifest for lint without hiding whether it exists.
+func (g *Generator) loadLintManifest() (*manifest, bool, error) {
+	data, err := os.ReadFile(g.manifestPath())
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, false, nil
+		}
+		return nil, false, err
+	}
+	m := &manifest{}
+	if err := json.Unmarshal(data, m); err != nil {
+		return nil, false, err
+	}
+	return m, true, nil
+}
+
 // ccgRefExists checks whether a parsed ccg:// @see ref resolves to graph data.
 // @intent let docs lint validate cross-namespace refs while keeping local @see lookup semantics unchanged.
 func (g *Generator) ccgRefExists(ref ccgref.Ref) (bool, error) {

internal/docs/lint_test.go

@@ -662,3 +662,51 @@ func TestLint_RespectsNamespace(t *testing.T) {
 		t.Fatalf("missing = %v, want only alpha file", report.Missing)
 	}
 }
+
+func TestLint_NamedNamespaceIgnoresForeignDocsWithoutManifest(t *testing.T) {
+	db := newLintTestDB(t)
+	outDir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(outDir, "internal"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(outDir, "internal", "foreign.go.md"), []byte("# internal/foreign.go\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	db.Create(&model.Node{Namespace: "trace", QualifiedName: "trace.Context", Kind: model.NodeKindFunction, Name: "Context", FilePath: "context.go", StartLine: 1, EndLine: 10, Hash: "h1", Language: "go"})
+
+	gen := &Generator{DB: db, OutDir: outDir, Namespace: "trace"}
+	report, err := gen.Lint()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(report.Orphans) != 0 {
+		t.Fatalf("orphans = %v, want none from foreign docs", report.Orphans)
+	}
+	if len(report.Missing) != 1 || report.Missing[0] != "context.go" {
+		t.Fatalf("missing = %v, want only trace source", report.Missing)
+	}
+}
+
+func TestLint_NamedNamespaceUsesScopedManifest(t *testing.T) {
+	db := newLintTestDB(t)
+	outDir := t.TempDir()
+	db.Create(&model.Node{Namespace: "trace", QualifiedName: "trace.Context", Kind: model.NodeKindFunction, Name: "Context", FilePath: "context.go", StartLine: 1, EndLine: 10, Hash: "h1", Language: "go"})
+	if err := os.WriteFile(filepath.Join(outDir, "context.go.md"), []byte("# context.go\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(outDir, "foreign.go.md"), []byte("# foreign.go\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	gen := &Generator{DB: db, OutDir: outDir, Namespace: "trace"}
+	if err := gen.saveManifest([]string{"context.go.md", "index.md"}); err != nil {
+		t.Fatal(err)
+	}
+	report, err := gen.Lint()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(report.Orphans) != 0 || len(report.Missing) != 0 {
+		t.Fatalf("report = orphans:%v missing:%v, want clean manifest-scoped docs", report.Orphans, report.Missing)
+	}
+}