Default the manifest to index.mf and keep it out of its own listing (closes #100)

mfer gen now writes index.mf instead of .index.mf, the name fetch
requests and the README calls the standard filename. Given a
directory, check, freshen, list and export look only for index.mf;
.index.mf is no longer recognized. Because index.mf is not hidden, gen
and freshen now leave the manifest they write out of its own listing by
file identity (os.SameFile), so it is recognized however its path is
spelled, through a symlink included, while an ordinary file of the same
name elsewhere in the tree is still listed.

Model: opus-5-5

internal/cli/entry_test.go

@@ -8,6 +8,7 @@ import (
 	"io"
 	"math/rand"
 	"os"
+	"path/filepath"
 	"sync"
 	"testing"
 
@@ -638,43 +639,79 @@ func TestGenerateFailsWithoutForceWhenOutputExists(t *testing.T) {
 	assert.Equal(t, "existing", string(content), "original file should be preserved")
 }
 
+// manifestPaths returns the file paths listed by the manifest at path.
+func manifestPaths(t *testing.T, fs afero.Fs, path string) []string {
+	t.Helper()
+
+	manifest, err := mfer.NewManifestFromFile(fs, path)
+	require.NoError(t, err)
+
+	paths := make([]string, 0, len(manifest.Files()))
+	for _, f := range manifest.Files() {
+		paths = append(paths, f.GetPath())
+	}
+
+	return paths
+}
+
 // TestGenerateLeavesOutputOutOfListing overwrites an output file inside the
-// scanned tree with --force: the old file is not listed, while a file named
-// index.mf in a subdirectory still is.
+// scanned tree with --force: the old file is not listed, even when the tree
+// is named through a symlink, while a file named index.mf in a subdirectory
+// still is. The output file is recognized by file identity, which needs
+// the real filesystem.
 func TestGenerateLeavesOutputOutOfListing(t *testing.T) {
 	t.Parallel()
 
-	for name, output := range map[string]string{
-		"default name":                 "/testdir/index.mf",
-		"other name in a subdirectory": "/testdir/sub/listing.mf",
+	// Paths are relative to a temp dir holding data/tree and link, a
+	// symlink to data.
+	for name, tc := range map[string]struct{ input, output string }{
+		"default name":                 {"data/tree", "data/tree/index.mf"},
+		"other name in a subdirectory": {"data/tree", "data/tree/sub/listing.mf"},
+		"tree named through a symlink": {"link/tree", "data/tree/index.mf"},
 	} {
 		t.Run(name, func(t *testing.T) {
 			t.Parallel()
 
-			fs := afero.NewMemMapFs()
-			require.NoError(t, fs.MkdirAll("/testdir/sub", 0o755))
-			writeTestFile(t, fs, "/testdir/readme.txt", "hello")
-			writeTestFile(t, fs, "/testdir/sub/index.mf", "an ordinary file")
+			root := t.TempDir()
+			tree := filepath.Join(root, "data", "tree")
+			output := filepath.Join(root, tc.output)
+
+			fs := afero.NewOsFs()
+			require.NoError(t, fs.MkdirAll(filepath.Join(tree, "sub"), 0o750))
+			require.NoError(t, os.Symlink(filepath.Join(root, "data"), filepath.Join(root, "link")))
+			writeTestFile(t, fs, filepath.Join(tree, "readme.txt"), "hello")
+			writeTestFile(t, fs, filepath.Join(tree, "sub", "index.mf"), "an ordinary file")
 			writeTestFile(t, fs, output, "previous manifest")
 
 			opts := testOpts([]string{
-				testApp, cmdGenerate, "-q", "--force", "-o", output, testDir,
+				testApp, cmdGenerate, "-q", "--force", "-o", output, filepath.Join(root, tc.input),
 			}, fs)
 			require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
 
-			manifest, err := mfer.NewManifestFromFile(fs, output)
-			require.NoError(t, err)
-
-			paths := make([]string, 0, len(manifest.Files()))
-			for _, f := range manifest.Files() {
-				paths = append(paths, f.GetPath())
-			}
-
-			assert.ElementsMatch(t, []string{"readme.txt", "sub/index.mf"}, paths)
+			assert.ElementsMatch(t, []string{"readme.txt", "sub/index.mf"},
+				manifestPaths(t, fs, output))
 		})
 	}
 }
 
+// TestGenerateDefaultOutputLeftOutOfListing runs gen with --force and no
+// other arguments, so it scans the current directory and writes the
+// relative path index.mf: the index.mf already there is not listed.
+//
+//nolint:paralleltest // changes the process-global working directory
+func TestGenerateDefaultOutputLeftOutOfListing(t *testing.T) {
+	chdirTemp(t)
+
+	fs := afero.NewOsFs()
+	writeTestFile(t, fs, "readme.txt", "hello")
+	writeTestFile(t, fs, "index.mf", "previous manifest")
+
+	opts := testOpts([]string{testApp, cmdGenerate, "-q", "--force"}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	assert.Equal(t, []string{"readme.txt"}, manifestPaths(t, fs, "index.mf"))
+}
+
 func TestGenerateAtomicWriteUsesTemp(t *testing.T) {
 	t.Parallel()
 

internal/cli/freshen.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"io"
 	"io/fs"
+	"os"
 	"path/filepath"
 	"time"
 
@@ -56,7 +57,7 @@ type freshenEntry struct {
 type freshenScanner struct {
 	fs              afero.Fs
 	absBase         string
-	manifestBase    string
+	manifestInfo    fs.FileInfo // the manifest being freshened
 	includeDotfiles bool
 	followSymlinks  bool
 	showProgress    bool
@@ -156,11 +157,6 @@ func (s *freshenScanner) walk(path string, info fs.FileInfo, walkErr error) erro
 			"freshen: failed to compute relative path for %s: %w", path, err)
 	}
 
-	// Skip the manifest file itself
-	if relPath == s.manifestBase {
-		return nil
-	}
-
 	// Handle dotfiles
 	if !s.includeDotfiles && mfer.IsHiddenPath(filepath.ToSlash(relPath)) {
 		if info.IsDir() {
@@ -185,6 +181,12 @@ func (s *freshenScanner) walk(path string, info fs.FileInfo, walkErr error) erro
 		info = realInfo
 	}
 
+	// Skip the manifest file itself, however its path is spelled; gen
+	// leaves out its output file the same way.
+	if os.SameFile(info, s.manifestInfo) {
+		return nil
+	}
+
 	s.scanCount++
 
 	// Check against existing manifest
@@ -364,17 +366,22 @@ func (mfa *CLIApp) freshenScan(
 	startScan := time.Now()
 	showProgress := ctx.Bool("progress")
 
+	manifestInfo, err := mfa.Fs.Stat(manifestPath)
+	if err != nil {
+		return nil, 0, fmt.Errorf("freshen: %w", err)
+	}
+
 	scanner := &freshenScanner{
 		fs:              mfa.Fs,
 		absBase:         absBase,
-		manifestBase:    filepath.Base(manifestPath),
+		manifestInfo:    manifestInfo,
 		includeDotfiles: ctx.Bool("include-dotfiles"),
 		followSymlinks:  ctx.Bool("follow-symlinks"),
 		showProgress:    showProgress,
 		existingByPath:  existingByPath,
 	}
 
-	err := afero.Walk(mfa.Fs, absBase, scanner.walk)
+	err = afero.Walk(mfa.Fs, absBase, scanner.walk)
 
 	if showProgress {
 		log.ProgressDone()

internal/cli/freshen_test.go

@@ -5,6 +5,7 @@ import (
 	"bytes"
 	"context"
 	"os"
+	"path/filepath"
 	"testing"
 	"time"
 
@@ -29,7 +30,7 @@ func (s stubFileInfo) IsDir() bool        { return false }
 func (s stubFileInfo) Sys() any           { return nil }
 
 // setupFreshenDir populates /testdir with two files, scans it, and
-// writes the resulting manifest to /testdir/.index.mf.
+// writes the resulting manifest to /testdir/index.mf.
 func setupFreshenDir(t *testing.T, fs afero.Fs) {
 	t.Helper()
 
@@ -48,7 +49,7 @@ func setupFreshenDir(t *testing.T, fs afero.Fs) {
 
 	// Write manifest to filesystem
 	require.NoError(t,
-		afero.WriteFile(fs, "/testdir/.index.mf", manifestBuf.Bytes(), 0o644))
+		afero.WriteFile(fs, "/testdir/index.mf", manifestBuf.Bytes(), 0o644))
 }
 
 func TestFreshenUnchanged(t *testing.T) {
@@ -58,7 +59,7 @@ func TestFreshenUnchanged(t *testing.T) {
 	setupFreshenDir(t, fs)
 
 	// Parse manifest to verify
-	manifest, err := mfer.NewManifestFromFile(fs, "/testdir/.index.mf")
+	manifest, err := mfer.NewManifestFromFile(fs, "/testdir/index.mf")
 	require.NoError(t, err)
 	assert.Len(t, manifest.Files(), 2)
 }
@@ -70,7 +71,7 @@ func TestFreshenWithChanges(t *testing.T) {
 	setupFreshenDir(t, fs)
 
 	// Verify initial manifest has 2 files
-	manifest, err := mfer.NewManifestFromFile(fs, "/testdir/.index.mf")
+	manifest, err := mfer.NewManifestFromFile(fs, "/testdir/index.mf")
 	require.NoError(t, err)
 	assert.Len(t, manifest.Files(), 2)
 
@@ -95,6 +96,34 @@ func TestFreshenWithChanges(t *testing.T) {
 	assert.Equal(t, "modified content2", string(content))
 }
 
+// TestFreshenLeavesManifestOutOfListing freshens a manifest kept in a
+// subdirectory of the tree it lists: the manifest is not listed, while an
+// ordinary file of the same name at the top of the tree is. The manifest
+// is recognized by file identity, which needs the real filesystem.
+func TestFreshenLeavesManifestOutOfListing(t *testing.T) {
+	t.Parallel()
+
+	root := t.TempDir()
+	manifestPath := filepath.Join(root, "sub", "listing.mf")
+
+	fs := afero.NewOsFs()
+	require.NoError(t, fs.MkdirAll(filepath.Join(root, "sub"), 0o750))
+	writeTestFile(t, fs, filepath.Join(root, "readme.txt"), "hello")
+	writeTestFile(t, fs, filepath.Join(root, "listing.mf"), "an ordinary file")
+
+	opts := testOpts([]string{testApp, cmdGenerate, "-q", "-o", manifestPath, root}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	// A new file gives freshen something to write.
+	writeTestFile(t, fs, filepath.Join(root, "new.txt"), "new")
+
+	opts = testOpts([]string{testApp, "freshen", "-q", testFlagBase, root, manifestPath}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	assert.ElementsMatch(t, []string{"readme.txt", "listing.mf", "new.txt"},
+		manifestPaths(t, fs, manifestPath))
+}
+
 // TestFreshenRecordEntryMtimePresence pins the behavior of recordEntry
 // with respect to MFFilePath.Mtime, which is a message pointer with
 // proto3 field presence and may legitimately be absent.

mfer/checker_test.go

@@ -360,7 +360,7 @@ func TestFindExtraFilesSkipsManifestAndDotfiles(t *testing.T) {
 	manifestFiles := map[string][]byte{
 		testFile1: []byte("in manifest"),
 	}
-	createTestManifest(t, fs, "/data/.index.mf", manifestFiles)
+	createTestManifest(t, fs, "/data/index.mf", manifestFiles)
 	createFilesOnDisk(t, fs, map[string][]byte{
 		testFile1: []byte("in manifest"),
 	})
@@ -371,7 +371,7 @@ func TestFindExtraFilesSkipsManifestAndDotfiles(t *testing.T) {
 	require.NoError(t, fs.MkdirAll("/data", 0o755))
 	require.NoError(t, afero.WriteFile(fs, "/data/extra.txt", []byte("extra"), 0o644))
 
-	chk, err := NewChecker("/data/.index.mf", "/data", fs)
+	chk, err := NewChecker("/data/index.mf", "/data", fs)
 	require.NoError(t, err)
 
 	results := make(chan Result, 10)
@@ -383,7 +383,7 @@ func TestFindExtraFilesSkipsManifestAndDotfiles(t *testing.T) {
 		extras = append(extras, r)
 	}
 
-	// Should only report extra.txt, not .hidden, .config/settings, or .index.mf
+	// Should only report extra.txt, not .hidden, .config/settings, or index.mf
 	for _, e := range extras {
 		t.Logf("extra: %s", e.Path)
 	}
@@ -528,7 +528,7 @@ func TestFindExtraFilesSkipsDotfiles(t *testing.T) {
 	files := map[string][]byte{
 		testFile1: []byte("in manifest"),
 	}
-	createTestManifest(t, fs, "/data/.index.mf", files)
+	createTestManifest(t, fs, "/data/index.mf", files)
 	createFilesOnDisk(t, fs, files)
 
 	// Add dotfiles and manifest file on disk
@@ -537,7 +537,7 @@ func TestFindExtraFilesSkipsDotfiles(t *testing.T) {
 	require.NoError(t,
 		afero.WriteFile(fs, "/data/.git/config", []byte("git config"), 0o644))
 
-	chk, err := NewChecker("/data/.index.mf", "/data", fs)
+	chk, err := NewChecker("/data/index.mf", "/data", fs)
 	require.NoError(t, err)
 
 	results := make(chan Result, 10)

mfer/scanner.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"io"
 	"io/fs"
+	"os"
 	"path"
 	"path/filepath"
 	"strings"
@@ -58,8 +59,12 @@ type ScannerOptions struct {
 	// Seed, if set, derives a deterministic UUID from this seed.
 	Seed string
 	// OutputPath, if set, is the file the manifest will be written to.
-	// Enumeration skips that one file, so a manifest written inside the
-	// scanned tree, or one it replaces there, is never listed.
+	// If that file exists when the scanner is created, enumeration leaves
+	// it out however its path is spelled (through a symlink, a hard link,
+	// or in different letter case), so a manifest being replaced is never
+	// listed.
+	// Files are matched with os.SameFile, which only recognizes files on
+	// the operating system's filesystem.
 	OutputPath string
 }
 
@@ -79,7 +84,7 @@ type Scanner struct {
 	totalBytes FileSize // cached sum of all file sizes
 	options    *ScannerOptions
 	fs         afero.Fs
-	outputPath string // options.OutputPath made absolute; "" when unset
+	outputInfo fs.FileInfo // the existing output file; nil when there is none
 }
 
 // NewScanner creates a new Scanner with default options.
@@ -105,9 +110,12 @@ func NewScannerWithOptions(opts *ScannerOptions) *Scanner {
 	}
 
 	if opts.OutputPath != "" {
-		// Abs fails only when there is no working directory, and then a
-		// relative output path could not be written either.
-		s.outputPath, _ = filepath.Abs(opts.OutputPath)
+		// If the output file cannot be stat'd, normally because it does
+		// not exist yet, there is nothing to leave out.
+		info, err := s.fs.Stat(opts.OutputPath)
+		if err == nil {
+			s.outputInfo = info
+		}
 	}
 
 	return s
@@ -421,11 +429,6 @@ func (s *Scanner) enumerateFileWithInfo(
 	// Compute absolute path for file reading
 	absPath := filepath.Join(basePath, cleanPath)
 
-	// The manifest being written is not one of the files it lists.
-	if absPath == s.outputPath {
-		return nil
-	}
-
 	// Handle symlinks
 	if info.Mode()&fs.ModeSymlink != 0 {
 		if !s.options.FollowSymLinks {
@@ -453,6 +456,11 @@ func (s *Scanner) enumerateFileWithInfo(
 		info = realInfo
 	}
 
+	// The manifest being written is not one of the files it lists.
+	if s.outputInfo != nil && os.SameFile(info, s.outputInfo) {
+		return nil
+	}
+
 	entry := &FileEntry{
 		Path:    RelFilePath(cleanPath),
 		AbsPath: AbsFilePath(absPath),