tool: checksums of a folder - checksum-write and checksum-check

CHANGELOG.md

@@ -24,6 +24,17 @@ because it turns other people's test suites red.
   <checksum>`. A checksum that does not match ends with code 7, the same as
   `tfg verify`. The file is only read. `tfg tool list` and `tfg tool show
   <id>` say what there is, both with `--json`.
+- **Checksums of a whole folder.** `tfg tool checksum-write <folder>` writes
+  SHA256SUMS beside the files, byte for byte what `sha256sum` writes, so
+  `sha256sum -c` checks it later. It never writes over a checksum file that is
+  there, and a folder with anything in it that cannot be read gets no checksum
+  file at all, with everything that could not be read named. `tfg tool
+  checksum-check <SHA256SUMS>` checks every file a checksum file lists. It
+  reads what `sha256sum` and `shasum` write, and names the lines that are not
+  checksums, such as those of a signature, rather than failing on them. Links,
+  pipes and anything else that is not a file are left out and named, never
+  opened. Both are on the Tools tab, where the checksum a file should have now
+  shows in full.
 - **The window in Polish, and a Preferences tab.** The window now speaks the
   language your system is set to when it has that language, and English
   otherwise - so on a system set to Polish it opens in Polish. Preferences

README.md

@@ -387,6 +387,8 @@ tfg formats <id>         what a single format accepts
 tfg tool list [--json]                          the tools this build has
 tfg tool show <id> [--json]                     what one tool works on and takes
 tfg tool checksum <file> [--algorithm sha256] [--expected <checksum>] [--json]
+tfg tool checksum-write <folder> [--algorithm sha256] [--json]
+tfg tool checksum-check <checksum_file> [--json]
 ```
 
 Small things to do with files you already have, beside the generator. Every tool
@@ -396,6 +398,12 @@ unless you ask - and compares it with one you were given, telling the algorithm
 from its length. A checksum that does not match ends with code 7, the same as
 `tfg verify`. crc32 is the one ZIP and PNG use, not the one `cksum` prints.
 
+`checksum-write` writes the checksum of every file in a folder into SHA256SUMS
+beside them, the same bytes `sha256sum` writes, and never over one that is
+there. `checksum-check` checks every file a checksum file lists, in the folder
+the checksum file is in. Files it does not list are not looked at, the same as
+`sha256sum -c`, and a path that leaves that folder is refused rather than read.
+
 ### `tfg damage`
 
 ```

internal/audit/audit.go

@@ -15,7 +15,6 @@ import (
 	"encoding/hex"
 	"fmt"
 	"io"
-	"io/fs"
 	"os"
 	"path"
 	"path/filepath"
@@ -294,7 +293,7 @@ func Verify(ctx context.Context, dir string, m *manifest.Manifest, skip string)
 		return nil, err
 	}
 
-	found, stopped := inOrder(ctx, len(claimed), func(i int, scratch []byte) Difference {
+	found, stopped := InOrder(ctx, len(claimed), func(i int, scratch []byte) Difference {
 		return compare(claimed[i], full[i], scratch)
 	})
 	for _, d := range found {
@@ -428,50 +427,6 @@ func comparablePath(p string) string {
 	return path.Clean(p)
 }
 
-// walk lists every file under dir as a slash separated path relative to it.
-//
-// Recursive because the manifest carries a path rather than a bare name, and
-// a run that groups its output into folders has to verify the same way.
-//
-// It takes the context because this is the part with no upper bound: the loop
-// over a manifest is as long as the manifest, and this is as long as whatever
-// directory somebody pointed at. Until 2026-08-25 only the loop asked, so
-// Ctrl+C during the walk of a large tree did nothing until the walk was over.
-func walk(ctx context.Context, dir string) ([]string, error) {
-	// The root is resolved first, because WalkDir does not follow links and a
-	// directory that is itself one would be handed to the callback as a single
-	// entry that is not a directory. Found on 2026-08-03 by the guard for
-	// generating into a linked directory: verify reported "extra ." and called
-	// the whole run a mismatch. People keep fixtures on redirected paths, so
-	// this is an ordinary setup rather than a corner.
-	if resolved, err := filepath.EvalSymlinks(dir); err == nil {
-		dir = resolved
-	}
-
-	var out []string
-	err := filepath.WalkDir(dir, func(p string, d fs.DirEntry, err error) error {
-		if err != nil {
-			return err
-		}
-		if err := ctx.Err(); err != nil {
-			return err
-		}
-		if d.IsDir() {
-			return nil
-		}
-		rel, relErr := filepath.Rel(dir, p)
-		if relErr != nil {
-			return relErr
-		}
-		out = append(out, filepath.ToSlash(rel))
-		return nil
-	})
-	if err != nil {
-		return nil, err
-	}
-	return out, nil
-}
-
 // claimedPaths is where each claimed file sits on the disk, in the order the
 // manifest gives them, refusing on the first one that leaves the directory.
 //

internal/audit/cleanup.go

@@ -79,7 +79,7 @@ func Inspect(ctx context.Context, dir string, m *manifest.Manifest) ([]Candidate
 
 	// In order, because this list is what cleanup removes from and what it
 	// printed to a person beforehand.
-	return inOrder(ctx, len(claimed), func(i int, scratch []byte) Candidate {
+	return InOrder(ctx, len(claimed), func(i int, scratch []byte) Candidate {
 		return look(claimed[i], full[i], scratch)
 	})
 }

internal/audit/parallel.go

@@ -54,7 +54,7 @@ func widthFor(n int) int {
 	return w
 }
 
-// inOrder answers one question for each of n items, over several goroutines,
+// InOrder answers one question for each of n items, over several goroutines,
 // and hands the answers back in the order the items were given.
 //
 // Three properties, and each one is depended on by something else in this
@@ -75,7 +75,12 @@ func widthFor(n int) int {
 //     own sake: if a refusal could arrive here, stopping the other goroutines
 //     would mean a LOWER index never got asked, and the same manifest would
 //     name a different file on different days.
-func inOrder[T any](ctx context.Context, n int, one func(i int, scratch []byte) T) ([]T, error) {
+//
+// Exported since 2026-09-30 for the checksum tools, which hash a folder the
+// same way and are held to the same three properties: a file that cannot be
+// read is an answer of one, never a stop, and the tool decides afterwards
+// what the answers come to. The goroutines stay in this file.
+func InOrder[T any](ctx context.Context, n int, one func(i int, scratch []byte) T) ([]T, error) {
 	out := make([]T, n)
 	done := make([]bool, n)
 
@@ -138,6 +143,34 @@ func drain[T any](ctx context.Context, next *atomic.Int64, out []T, done []bool,
 	}
 }
 
+// Tally adds up what several goroutines have read and tells one listener the
+// running total, one call at a time.
+//
+// Here because this is the file where things run beside each other. A tool
+// hashing a folder counts bytes in every worker, and the listener at the other
+// end - a window's progress bar - is not written to be called from two
+// goroutines at once. So the calls are made one after another under a lock,
+// rather than every listener having to be written for it and every package
+// that counts having to be one the race detector is run for
+// (docs/NARZEDZIA-SUMY-2026-09-29.md §15.3).
+type Tally struct {
+	mu   sync.Mutex
+	done int64
+	tell func(done int64)
+}
+
+// NewTally is a tally that tells tell each new total.
+func NewTally(tell func(done int64)) *Tally { return &Tally{tell: tell} }
+
+// Add counts n more and tells the listener the total, before the next Add
+// from any goroutine can.
+func (t *Tally) Add(n int64) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	t.done += n
+	t.tell(t.done)
+}
+
 // finishedPrefix is how many items were answered before the first one that was
 // not - which on a cancelled pass is everything the caller may speak about.
 func finishedPrefix(done []bool) int {

internal/audit/walk.go

@@ -0,0 +1,136 @@
+package audit
+
+import (
+	"context"
+	"io/fs"
+	"path/filepath"
+)
+
+// EntryKind is what a name found under a directory is, told from the listing
+// of the directory rather than by opening the name.
+type EntryKind int
+
+// The three kinds. A file is the only one anything here reads.
+const (
+	// Regular is an ordinary file.
+	Regular EntryKind = iota + 1
+	// Link is a symbolic link. Never followed: a link can lead out of the
+	// directory, or back into it for ever.
+	Link
+	// Other is a pipe, a device, a socket, or a junction on Windows - which
+	// the listing reports as irregular rather than as a link or a directory,
+	// measured with go1.27.0 on 2026-09-30. Opening one for reading can wait
+	// for ever, so nothing here does.
+	Other
+)
+
+// Entry is one name found under a directory that is not a directory itself.
+type Entry struct {
+	// Path is relative to the directory walked and slash separated on every
+	// system, the way a manifest and a checksum file both write a path.
+	Path string
+	Kind EntryKind
+
+	found fs.DirEntry
+}
+
+// Info is what the system says about the entry, asked when somebody needs it
+// rather than during the walk. Verify never does, and on Linux and macOS each
+// answer is one more call to the system per file.
+func (e Entry) Info() (fs.FileInfo, error) { return e.found.Info() }
+
+// Found is what a walk of a directory came to.
+type Found struct {
+	Entries []Entry
+	// Unreadable is every directory under the one walked that could not be
+	// listed, in the order the walk met them, each error naming its path.
+	// The walk goes on past them, so a caller refusing the whole directory can
+	// name all of them at once rather than the first one on each try.
+	Unreadable []error
+}
+
+// Walk lists every name under dir that is not a directory, with what kind of
+// thing each one is.
+//
+// Recursive because the manifest carries a path rather than a bare name, and
+// a run that groups its output into folders has to verify the same way. Shared
+// by verify and the checksum tools, because "what is in this folder" is one
+// question and a checksum file and a manifest have to answer it alike
+// (docs/NARZEDZIA-SUMY-2026-09-29.md §3.3).
+//
+// It takes the context because this is the part with no upper bound: the loop
+// over a manifest is as long as the manifest, and this is as long as whatever
+// directory somebody pointed at. Until 2026-08-25 only the loop asked, so
+// Ctrl+C during the walk of a large tree did nothing until the walk was over.
+func Walk(ctx context.Context, dir string) (Found, error) {
+	// The root is resolved first, because WalkDir does not follow links and a
+	// directory that is itself one would be handed to the callback as a single
+	// entry that is not a directory. Found on 2026-08-03 by the guard for
+	// generating into a linked directory: verify reported "extra ." and called
+	// the whole run a mismatch. People keep fixtures on redirected paths, so
+	// this is an ordinary setup rather than a corner.
+	if resolved, err := filepath.EvalSymlinks(dir); err == nil {
+		dir = resolved
+	}
+
+	var found Found
+	err := filepath.WalkDir(dir, func(p string, d fs.DirEntry, err error) error {
+		if err != nil {
+			found.Unreadable = append(found.Unreadable, err)
+			return pastIt(d)
+		}
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+		if d.IsDir() {
+			return nil
+		}
+		rel, relErr := filepath.Rel(dir, p)
+		if relErr != nil {
+			return relErr
+		}
+		found.Entries = append(found.Entries, Entry{Path: filepath.ToSlash(rel), Kind: kindOf(d), found: d})
+		return nil
+	})
+	return found, err
+}
+
+// pastIt is how the walk carries on after a directory it could not list: it
+// leaves that directory and goes on with the rest. A root that could not be
+// looked at has no entry, and then there is nothing to go on with.
+func pastIt(d fs.DirEntry) error {
+	if d != nil && d.IsDir() {
+		return fs.SkipDir
+	}
+	return nil
+}
+
+// kindOf is what the listing says an entry is. Asked of the type bits the
+// listing already has, so nothing is opened and nothing is followed.
+func kindOf(d fs.DirEntry) EntryKind {
+	switch {
+	case d.Type().IsRegular():
+		return Regular
+	case d.Type()&fs.ModeSymlink != 0:
+		return Link
+	}
+	return Other
+}
+
+// walk is Walk for verify, which needs only the paths and refuses on the first
+// directory it could not list - the same error, in the same place, that it
+// gave before the walk learned to go past one.
+func walk(ctx context.Context, dir string) ([]string, error) {
+	found, err := Walk(ctx, dir)
+	if len(found.Unreadable) > 0 {
+		return nil, found.Unreadable[0]
+	}
+	if err != nil {
+		return nil, err
+	}
+	out := make([]string, 0, len(found.Entries))
+	for _, e := range found.Entries {
+		out = append(out, e.Path)
+	}
+	return out, nil
+}

internal/cli/errors.go

@@ -187,6 +187,8 @@ func classifyTool(err error) (int, bool) {
 		return ExitUsage, true
 	case tool.Reading:
 		return ExitIO, true
+	case tool.Room:
+		return ExitSpace, true
 	}
 	return 0, false
 }

internal/cli/toolcmd.go

@@ -8,6 +8,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/donislawdev/TestingFilesGenerator/internal/core"
 	"github.com/donislawdev/TestingFilesGenerator/internal/format"
 	"github.com/donislawdev/TestingFilesGenerator/internal/tool"
 )
@@ -93,7 +94,7 @@ func toolUsage(w io.Writer) {
 Usage:
   tfg tool list                    the tools this build has
   tfg tool show <id>               what one tool works on and takes
-  tfg tool <id> <file> [flags]     run it
+  tfg tool <id> <path> [flags]     run it
 
 Every tool is also on the Tools tab of the window, with the same settings.
 `)
@@ -310,7 +311,10 @@ func renderToolResult(d tool.Descriptor, r tool.Result, asJSON bool, out, errOut
 			return code
 		}
 	} else {
-		printToolTable(d.Columns, r.Rows, w)
+		if len(r.Rows) > 0 {
+			printToolTable(d.Columns, r.Rows, w)
+		}
+		printNotes(d, r.Notes, w)
 		if said := r.Verdict.Said(); said != "" {
 			fmt.Fprintf(w, "\n%s\n", said)
 		}
@@ -321,6 +325,27 @@ func renderToolResult(d tool.Descriptor, r tool.Result, asJSON bool, out, errOut
 	return ExitOK
 }
 
+// printNotes prints what a run noted, each as the sentence its tool declared
+// and its items: one item on the same line, several on lines of their own.
+//
+// Every item goes through core.Shown, because an item is usually a file name
+// and a name may hold a line break or an escape sequence - printed as it is, a
+// name could end the list early or rewrite the lines above it in a terminal.
+// The same reason verify shows its paths that way.
+func printNotes(d tool.Descriptor, notes []tool.Noted, w io.Writer) {
+	for _, n := range notes {
+		says := d.NoteSays(n.ID)
+		if len(n.Items) == 1 {
+			fmt.Fprintf(w, "%s %s\n", says, core.Shown(n.Items[0]))
+			continue
+		}
+		fmt.Fprintln(w, says)
+		for _, item := range n.Items {
+			fmt.Fprintf(w, "  %s\n", core.Shown(item))
+		}
+	}
+}
+
 // printToolTable prints a result as columns under their headings, each as wide
 // as its longest cell.
 func printToolTable(columns []string, rows [][]string, w io.Writer) {

internal/format/format.go

@@ -196,6 +196,17 @@ type Property struct {
 	// Declared here rather than known by the places that care, because a
 	// second secret property added later would otherwise have to find them.
 	Secret bool
+
+	// Long marks free text whose value is long by nature - a checksum of 64 or
+	// 128 digits - so a window gives its box the whole row, as it gives a path.
+	//
+	// It says something about the value rather than about pixels, and a
+	// terminal has nothing to do with it. Every other box of text is as wide
+	// as a short name (the owner's report of 2026-09-21), which is right for a
+	// name and showed about twenty of the sixty four digits a pasted sha256
+	// has (docs/NARZEDZIA-SUMY-2026-09-29.md §14, the owner's decision of
+	// 2026-09-30). Ignored by every kind but text.
+	Long bool
 }
 
 // JointLimit is a rule binding two settings that neither of them can state