loomctl orient: one table of contents, restating no rule

Generates .loom/orientation.md — what this repository depends on, where each copy came from, and which facets sit beside it — for whoever arrives next, of any make. One file rather than two, decided by loom's own rule. Generate what varies, adopt what does not: the publishing half varies not at all and is already adopted, so publication.md appears in the index like any other adopted document, in exactly the repositories that adopted it. A second command would emit a file whose whole content is a pointer to a file already in the tree, and would revive a noun declined when published check went. Restates no rule. The three moves are phrased as operations — what to run, what to write, where — and every rule stays in the document that owns it. The .usages.md is pointed at rather than summarised, because what depends on a document is free prose and anything extracting a claim from prose eventually extracts it wrong. It says nothing recorded when a document has no usages file, which is a finding rather than an omission and is currently true of six of nine. Byte-deterministic, pinned by a test that inserts records out of order and generates three times. Written to .loom/orientation.md rather than inside .loom/externals/, where check would report it as an unlocked external in every repository using the feature. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018UTxuSizozEA8yDitPuris
2026-09-08 09:11:04 -04:00
parent 1cc528c8aa
commit da6e8b9b51
4 changed files with 263 additions and 0 deletions
@@ -0,0 +1,109 @@
+// Package orient generates a table of contents over what a repository depends
+// on, for whoever arrives next — a person, or an agent of any make.
+//
+// It restates no rule. Every rule it might repeat is owned by a document already
+// in the working tree, and a copy of a rule is a copy that goes stale: this file
+// says only what is here, where it came from, and where the rules live.
+//
+// The output is byte-deterministic. A generated file that churns produces diffs
+// nobody reads, and the diff is most of the value — it is how somebody sees that
+// their dependencies moved.
+package orient
+
+import (
+	"fmt"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+
+	"git.hypertheory-labs.dev/loom/loom-cli/internal/lock"
+)
+
+// File is where the orientation lives, relative to the repository root.
+//
+// Beside .loom/event-log.md rather than inside .loom/externals/, because
+// everything in that directory is somebody else's document — which is what makes
+// "do not edit these" a rule you can state in four words — and because `check`
+// walks it and would report a generated file as an unlocked external forever.
+const File = ".loom/orientation.md"
+
+const preamble = `<!-- Generated by ` + "`loomctl orient`" + `. Safe to overwrite; nobody typed it.
+     Regenerate after adopting a document or reconciling a change. -->
+
+# What this repository depends on
+
+Copies of other people's documents are kept under ` + "`.loom/externals/`" + `, at a path
+that says where each came from. **They are copies: do not edit them.** Anything
+you want to say about one goes in a file *beside* it, never into it.
+
+Three moves, and each has a document that owns the rule:
+
+- **A copy is wrong, or you needed something it does not say** — write it in
+  ` + "`<name>.gaps.md`" + ` beside the copy.
+- **What of ours depends on a copy** — write it in ` + "`<name>.usages.md`" + ` beside it.
+- **A source changed** — ` + "`loomctl external check`" + ` says so and stages the new copy;
+  ` + "`loomctl external apply`" + ` takes it. Neither edits anything on its own.
+`
+
+// Generate writes the orientation for the repository at root.
+func Generate(root, out string) (string, error) {
+	locks, err := lock.Load(root)
+	if err != nil {
+		return "", err
+	}
+	var b strings.Builder
+	b.WriteString(preamble)
+
+	recs := locks.All() // already ordered by path
+	if len(recs) == 0 {
+		b.WriteString("\nThis repository adopts nothing yet.\n")
+	}
+	for _, r := range recs {
+		fmt.Fprintf(&b, "\n## `%s`\n\n", r.Path)
+		fmt.Fprintf(&b, "- source: %s\n", r.URL)
+		facets := facetsFor(root, r.Path)
+		if u, ok := facets["usages"]; ok {
+			fmt.Fprintf(&b, "- what of ours depends on it: `%s`\n", u)
+		} else {
+			fmt.Fprintf(&b, "- what of ours depends on it: **nothing recorded** — no `.usages.md`\n")
+		}
+		if g, ok := facets["gaps"]; ok {
+			fmt.Fprintf(&b, "- what we expected and did not find: `%s`\n", g)
+		}
+	}
+
+	if dir := filepath.Join(root, ".loom", "published"); isDir(dir) {
+		b.WriteString("\n## This repository publishes\n\n")
+		b.WriteString("See `.loom/published/`. What is handed over for others to depend on is\n")
+		b.WriteString("there; the rest of the repository is not hidden, it is simply not what\n")
+		b.WriteString("anybody depends on.\n")
+	}
+
+	dest := out
+	if dest == "" {
+		dest = filepath.Join(root, filepath.FromSlash(File))
+	}
+	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+		return "", err
+	}
+	return dest, os.WriteFile(dest, []byte(b.String()), 0o644)
+}
+
+// facetsFor finds the files written beside an adopted document.
+func facetsFor(root, rel string) map[string]string {
+	found := map[string]string{}
+	stem := strings.TrimSuffix(rel, path.Ext(rel))
+	for _, kind := range []string{"usages", "gaps"} {
+		p := stem + "." + kind + ".md"
+		if _, err := os.Stat(filepath.Join(root, lock.Dir, filepath.FromSlash(p))); err == nil {
+			found[kind] = lock.Dir + "/" + p
+		}
+	}
+	return found
+}
+
+func isDir(p string) bool {
+	fi, err := os.Stat(p)
+	return err == nil && fi.IsDir()
+}
@@ -0,0 +1,73 @@
+package orient
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.hypertheory-labs.dev/loom/loom-cli/internal/lock"
+)
+
+// A generated file that churns produces diffs nobody reads, and the diff is most
+// of the value.
+func TestGenerateIsDeterministic(t *testing.T) {
+	root := t.TempDir()
+	locks, err := lock.LoadFile(lock.Path(root))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Inserted out of order on purpose: the output must not depend on it.
+	for _, r := range []lock.Record{
+		{Path: "h/o/zeta/z.md", URL: "https://h/z", ETag: `"3"`},
+		{Path: "h/o/alpha/a.md", URL: "https://h/a", ETag: `"1"`},
+		{Path: "h/o/mid/m.md", URL: "https://h/m", ETag: `"2"`},
+	} {
+		locks.Put(r)
+	}
+	if err := locks.Save(); err != nil {
+		t.Fatal(err)
+	}
+
+	var first string
+	for i := 0; i < 3; i++ {
+		dest, err := Generate(root, filepath.Join(root, "out.md"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		b, err := os.ReadFile(dest)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if i == 0 {
+			first = string(b)
+			continue
+		}
+		if string(b) != first {
+			t.Fatal("output changed between runs")
+		}
+	}
+	if a, z := strings.Index(first, "alpha"), strings.Index(first, "zeta"); a > z {
+		t.Error("entries are not ordered by path")
+	}
+	if strings.Contains(first, "publishes") {
+		t.Error("claimed the repository publishes with no .loom/published")
+	}
+}
+
+func TestSaysWhenNothingRecordsADependency(t *testing.T) {
+	root := t.TempDir()
+	locks, _ := lock.LoadFile(lock.Path(root))
+	locks.Put(lock.Record{Path: "h/o/r/doc.md", URL: "https://h/doc", ETag: `"1"`})
+	if err := locks.Save(); err != nil {
+		t.Fatal(err)
+	}
+	dest, err := Generate(root, filepath.Join(root, "out.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	b, _ := os.ReadFile(dest)
+	if !strings.Contains(string(b), "nothing recorded") {
+		t.Error("a document with no .usages.md should say so — it is a finding, not an omission")
+	}
+}