flex-auth/tools/survey_layer_declarations.go

//go:build ignore

// Command survey_layer_declarations runs the §11 mechanical check across the
// estate rather than against flex-auth alone.
//
// Why this exists: §11 calls the layer declaration mechanically checkable, but
// every checker in the estate reads only its own file. A check that cannot
// disagree with anyone has not been run. FLEX-WP-0030 B1 was found by an ad-hoc
// shell survey, which is the same defect in a different costume — a finding
// nobody can reproduce is an assertion. This makes it a command.
//
// It checks ONE property: whether each layer: value sits in the §3 vocabulary
// as written, case-sensitively. It does not apply flex-auth's own declaration
// rules to any other repository, and it does not grade anyone: §11 is explicit
// that a layer stated about a repository by another repository is not a
// declaration.
//
//	go run tools/survey_layer_declarations.go --root ~ [--json out.json]
package main

import (
	"encoding/json"
	"flag"
	"fmt"
	"os"
	"os/user"
	"path/filepath"
	"sort"
	"strings"

	"github.com/netkingdom/flex-auth/internal/layer"
)

// Security-relevant counterparts from docs/conformance/boundaries-review.md.
var counterparts = []string{
	"approval-engine", "audit-core", "flex-auth", "gate-house", "key-cape",
	"kings-guard", "maturity-engine", "net-kingdom", "ops-mason", "ops-warden",
	"secrets-engine", "tenant-engine", "user-engine", "zone-engine",
}

func main() {
	root := flag.String("root", "", "directory holding the repositories (default: home)")
	jsonOut := flag.String("json", "", "write a receipt to this path")
	flag.Parse()

	dir := *root
	if dir == "" {
		u, err := user.Current()
		if err != nil {
			fail(err)
		}
		dir = u.HomeDir
	}

	rows, err := layer.SurveyDeclarations(dir, counterparts)
	if err != nil {
		fail(err)
	}

	fmt.Print(layer.FormatSurvey(rows))

	spellings := layer.Spellings(rows)
	undeclared := layer.Undeclared(rows)

	fmt.Printf("\n%d counterparts surveyed, %d declared, %d undeclared.\n",
		len(rows), len(rows)-len(undeclared), len(undeclared))

	keys := make([]string, 0, len(spellings))
	for k := range spellings {
		keys = append(keys, k)
	}
	sort.Strings(keys)

	fmt.Printf("\nSpellings of layer: (%d distinct)\n", len(keys))
	for _, k := range keys {
		fmt.Printf("  %-10s %s\n", k, strings.Join(spellings[k], ", "))
	}

	if len(undeclared) > 0 {
		fmt.Printf("\nNo machine-readable declaration (§11 B2): %s\n", strings.Join(undeclared, ", "))
	}

	disagree := layer.SelfDisagreeing(rows)
	if len(disagree) > 0 {
		fmt.Printf("\nRepositories whose two §11 forms disagree (§11 B1): %d\n", len(disagree))
		for _, r := range disagree {
			fmt.Printf("  %-18s INTENT.md=%-8q %s=%q\n", r.Repo, r.Intent.Layer, r.File.Source, r.File.Layer)
		}
		fmt.Println("\n§11 accepts \"a layer: key in INTENT.md frontmatter, OR an equivalent")
		fmt.Println("declaration file\" and does not say which governs when both exist and")
		fmt.Println("disagree. This is the open question, not a verdict.")
	}

	var offVocab []string
	for _, r := range rows {
		for _, f := range []layer.Form{r.Intent, r.File} {
			if f.Found && !f.InVocabulary {
				offVocab = append(offVocab, fmt.Sprintf("%s=%q", f.Source, f.Layer))
			}
		}
	}
	if len(offVocab) > 0 {
		fmt.Printf("\nOutside the §3 vocabulary as written: %s\n", strings.Join(offVocab, ", "))
	}

	if *jsonOut != "" {
		receipt := map[string]any{
			"derived_at":  "run time",
			"root":        dir,
			"rows":        rows,
			"spellings":   spellings,
			"undeclared":  undeclared,
			"off_vocab":   offVocab,
			"self_disagreeing": disagree,
			"checks_only": "§3 vocabulary as written; no flex-auth house rules applied to peers",
		}
		b, err := json.MarshalIndent(receipt, "", "  ")
		if err != nil {
			fail(err)
		}
		if err := os.WriteFile(filepath.Clean(*jsonOut), append(b, '\n'), 0o644); err != nil {
			fail(err)
		}
		fmt.Printf("\nReceipt: %s\n", *jsonOut)
	}
}

func fail(err error) {
	fmt.Fprintln(os.Stderr, "survey:", err)
	os.Exit(1)
}