government

commit 21ba553f2ac9aed7435e6a7744c2a33c37c9dec8

tree

parent:
9d8c149e89e015823df22a42b5d70029e7e44e25

nmyk <nick@nmyk.io>

2026-11-14T17:32:54-05:00

add tree and decompile

diff --git a/DESIGN.md b/DESIGN.md
index 0efe165ed484fceb1e177f358ed4c4100ad51666..ecfe9de98df81e1159695f16128b67f60c45f031 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -191,13 +191,19 @@ 6. Anything else is a decode error that names the offending OID and depth.
 
 ### Worked example: `(+ 1 (* 2 3))`
 
-The AST is 3 deep, so the file holds an anchor plus 3 certs. Pre-order ids; `′` marks a copy the validator makes:
+The AST is 3 deep, so the file holds an anchor plus 3 certs. Ids are given in pre-order. This is `government tree`'s output for it; a trailing `'` marks a copy the validator makes:
 
 ```
-depth 0   anyPolicy
-depth 1   └─ (…)#1
-depth 2      ├─ +#2          ├─ 1#3          └─ (…)#4
-depth 3      │  └─ +#2′      │  └─ 1#3′        ├─ *#5  ├─ 2#6  └─ 3#7
+depth 0  anyPolicy
+depth 1  `-- (...)#1       GOV.0.1.1
+depth 2      |-- +#2       GOV.0.2.21
+depth 3      |   `-- +#2'  copy
+depth 2      |-- 1#3       GOV.2.3.49
+depth 3      |   `-- 1#3'  copy
+depth 2      `-- (...)#4   GOV.0.4.1
+depth 3          |-- *#5   GOV.0.5.23
+depth 3          |-- 2#6   GOV.2.6.50
+depth 3          `-- 3#7   GOV.2.7.51
 ```
 
 | Cert | certificatePolicies | policyMappings |
diff --git a/cmd/government/inspect.go b/cmd/government/inspect.go
new file mode 100644
index 0000000000000000000000000000000000000000..cdf9968159407b5dfbd966800904c9d0ecbdd9b7
--- /dev/null
+++ b/cmd/government/inspect.go
@@ -0,0 +1,63 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"io"
+
+	"government/gov2lisp"
+	"government/policy"
+	"government/program"
+	"government/ratify"
+)
+
+// tree stops after policy processing, without decoding, so it can still
+// show a graph whose shape the decoder would reject. That makes it the
+// tool for looking at a broken program.
+func tree(args []string, stdout, stderr io.Writer) int {
+	fs := flag.NewFlagSet("tree", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	lf := addLoadFlags(fs)
+	fs.Usage = func() {
+		fmt.Fprintln(stderr, "usage: government tree prog.gov [-at time] [-anchor file] [-max-nodes n]")
+		fs.PrintDefaults()
+	}
+	path, data, ok := oneFile(fs, args, stderr)
+	if !ok {
+		return exitInvalid
+	}
+	opts := lf.programOptions()
+	certs, err := ratify.Ratify(data, ratify.Options{At: opts.At, Pin: opts.Pin})
+	if err != nil {
+		fmt.Fprintf(stderr, "%s: %v\n", path, err)
+		return exitInvalid
+	}
+	g, err := policy.Program(certs, policy.Options{MaxNodes: opts.MaxNodes})
+	if err != nil {
+		fmt.Fprintf(stderr, "%s: %v\n", path, err)
+		return exitInvalid
+	}
+	fmt.Fprint(stdout, g.Draw())
+	return exitOK
+}
+
+func decompile(args []string, stdout, stderr io.Writer) int {
+	fs := flag.NewFlagSet("decompile", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	lf := addLoadFlags(fs)
+	fs.Usage = func() {
+		fmt.Fprintln(stderr, "usage: government decompile prog.gov [-at time] [-anchor file] [-max-nodes n]")
+		fs.PrintDefaults()
+	}
+	path, data, ok := oneFile(fs, args, stderr)
+	if !ok {
+		return exitInvalid
+	}
+	p, err := program.Load(data, lf.programOptions())
+	if err != nil {
+		fmt.Fprintf(stderr, "%s: %v\n", path, err)
+		return exitInvalid
+	}
+	fmt.Fprint(stdout, gov2lisp.Decompile(p.Forms))
+	return exitOK
+}
diff --git a/cmd/government/inspect_test.go b/cmd/government/inspect_test.go
new file mode 100644
index 0000000000000000000000000000000000000000..31e5db5279573ed545365925930d272cf9d4ac9e
--- /dev/null
+++ b/cmd/government/inspect_test.go
@@ -0,0 +1,39 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestTreeCommand(t *testing.T) {
+	gov := compileTo(t, t.TempDir(), "worked", "(+ 1 (* 2 3))")
+	code, stdout, stderr := runCmd("tree", gov)
+	if code != exitOK {
+		t.Fatalf("exit %d: %s", code, stderr)
+	}
+	for _, want := range []string{"depth 0  anyPolicy\n", "`-- (...)#1", "+#2'  copy", "`-- 3#7   GOV.2.7.51\n"} {
+		if !strings.Contains(stdout, want) {
+			t.Errorf("missing %q in\n%s", want, stdout)
+		}
+	}
+}
+
+func TestDecompileCommand(t *testing.T) {
+	gov := compileTo(t, t.TempDir(), "sq", sqSource)
+	code, stdout, stderr := runCmd("decompile", gov)
+	if code != exitOK || stdout != "(define sq (lambda (x) (* x x)))\n(sq 12)\n" {
+		t.Errorf("exit %d, stdout %q, stderr %s", code, stdout, stderr)
+	}
+}
+
+func TestInspectRefusals(t *testing.T) {
+	gov := compileTo(t, t.TempDir(), "p", "(+ 1 2)")
+	for _, cmd := range []string{"tree", "decompile"} {
+		if code, _, stderr := runCmd(cmd, gov, "-at", "1999-01-01T00:00:00Z"); code != exitInvalid || !strings.Contains(stderr, "E-NOT-IN-FORCE") {
+			t.Errorf("%s before the window: exit %d, %s", cmd, code, stderr)
+		}
+		if code, _, stderr := runCmd(cmd); code != exitInvalid || !strings.Contains(stderr, "usage") {
+			t.Errorf("%s with no file: exit %d, %s", cmd, code, stderr)
+		}
+	}
+}
diff --git a/cmd/government/load.go b/cmd/government/load.go
new file mode 100644
index 0000000000000000000000000000000000000000..1bef4e13ee9adeffa4a09ed6c6b662188e477234
--- /dev/null
+++ b/cmd/government/load.go
@@ -0,0 +1,50 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"os"
+
+	"government/policy"
+	"government/program"
+)
+
+// loadFlags are the flags every command that reads a .gov file shares.
+type loadFlags struct {
+	at       *atFlag
+	anchor   *anchorFlag
+	maxNodes *int
+}
+
+func addLoadFlags(fs *flag.FlagSet) loadFlags {
+	return loadFlags{
+		at:       addAtFlag(fs),
+		anchor:   addAnchorFlag(fs),
+		maxNodes: fs.Int("max-nodes", policy.DefaultMaxNodes, "refuse programs whose policy graph needs more than `n` nodes"),
+	}
+}
+
+func (lf loadFlags) programOptions() program.Options {
+	return program.Options{At: lf.at.Time(), Pin: lf.anchor.Pin(), MaxNodes: *lf.maxNodes}
+}
+
+// oneFile parses a command's arguments, which must name exactly one .gov
+// file, and reads it. It prints its own errors.
+func oneFile(fs *flag.FlagSet, args []string, stderr io.Writer) (path string, data []byte, ok bool) {
+	positional, err := parseInterspersed(fs, args)
+	if err != nil {
+		return "", nil, false
+	}
+	if len(positional) != 1 {
+		fs.Usage()
+		return "", nil, false
+	}
+	path = positional[0]
+	data, err = os.ReadFile(path)
+	if err != nil {
+		fmt.Fprintln(stderr, err)
+		return "", nil, false
+	}
+	return path, data, true
+}
diff --git a/cmd/government/main.go b/cmd/government/main.go
index f9c7b6bcc7106d10c10075fede0f63fff380c0d2..cb9a709144b5d5e109ce15b20199f4ddfa92a9a0 100644
--- a/cmd/government/main.go
+++ b/cmd/government/main.go
@@ -1,6 +1,6 @@
 // Command government runs GOVERNMENT programs.
 //
-// Only compile and run exist so far. The other subcommands arrive in later steps
+// verify and repeal arrive in later steps of PLAN.md. The other subcommands arrive in later steps
 // of PLAN.md.
 package main
 
@@ -23,11 +23,11 @@
 commands:
   compile    transpile Lisp source to .gov
   run        ratify, decode and evaluate a .gov program
+  tree       print the policy tree
+  decompile  print equivalent Lisp source
 
 not yet implemented:
   verify     ratify and decode only
-  tree       print the policy tree
-  decompile  print equivalent Lisp source
   repeal     write a CRL repealing one depth of a program
 `
 
@@ -45,6 +45,10 @@ 	case "compile":
 		return compile(args[1:], stdout, stderr)
 	case "run":
 		return runProgram(args[1:], stdout, stderr)
+	case "tree":
+		return tree(args[1:], stdout, stderr)
+	case "decompile":
+		return decompile(args[1:], stdout, stderr)
 	case "help", "-h", "-help", "--help":
 		fmt.Fprint(stdout, usage)
 		return exitOK
diff --git a/cmd/government/run.go b/cmd/government/run.go
index 843c10bc83e4e3f0d2f24a37e535c411306384df..4750a5dbc1c7612519f09f6b54c894bcf42a99ff 100644
--- a/cmd/government/run.go
+++ b/cmd/government/run.go
@@ -4,38 +4,23 @@ import (
 	"flag"
 	"fmt"
 	"io"
-	"os"
 
-	"government/policy"
 	"government/program"
 )
 
 func runProgram(args []string, stdout, stderr io.Writer) int {
 	fs := flag.NewFlagSet("run", flag.ContinueOnError)
 	fs.SetOutput(stderr)
-	at := addAtFlag(fs)
-	anchor := addAnchorFlag(fs)
-	maxNodes := fs.Int("max-nodes", policy.DefaultMaxNodes, "refuse programs whose policy graph needs more than `n` nodes")
+	lf := addLoadFlags(fs)
 	fs.Usage = func() {
 		fmt.Fprintln(stderr, "usage: government run prog.gov [-at time] [-anchor file] [-max-nodes n]")
 		fs.PrintDefaults()
 	}
-	positional, err := parseInterspersed(fs, args)
-	if err != nil {
+	path, data, ok := oneFile(fs, args, stderr)
+	if !ok {
 		return exitInvalid
 	}
-	if len(positional) != 1 {
-		fs.Usage()
-		return exitInvalid
-	}
-	path := positional[0]
-
-	data, err := os.ReadFile(path)
-	if err != nil {
-		fmt.Fprintln(stderr, err)
-		return exitInvalid
-	}
-	p, err := program.Load(data, program.Options{At: at.Time(), Pin: anchor.Pin(), MaxNodes: *maxNodes})
+	p, err := program.Load(data, lf.programOptions())
 	if err != nil {
 		fmt.Fprintf(stderr, "%s: %v\n", path, err)
 		return exitInvalid
diff --git a/gov2lisp/gov2lisp.go b/gov2lisp/gov2lisp.go
new file mode 100644
index 0000000000000000000000000000000000000000..e4f88a182691e363f89ed49fc17206a3c14a5a1c
--- /dev/null
+++ b/gov2lisp/gov2lisp.go
@@ -0,0 +1,21 @@
+// Package gov2lisp turns a decoded program back into Lisp source text.
+package gov2lisp
+
+import (
+	"strings"
+
+	"government/sexpr"
+)
+
+// Decompile prints one top-level form per line. The output is source in
+// normal form: the printer's spelling, so 'x comes back as (quote x),
+// 3.10 as 3.1, and comments are gone until notes carry them (Phase 7).
+// Reading it gives exactly the forms that were decoded.
+func Decompile(forms []sexpr.Value) string {
+	var b strings.Builder
+	for _, f := range forms {
+		b.WriteString(sexpr.Print(f))
+		b.WriteByte('\n')
+	}
+	return b.String()
+}
diff --git a/gov2lisp/gov2lisp_test.go b/gov2lisp/gov2lisp_test.go
new file mode 100644
index 0000000000000000000000000000000000000000..64e2c1a5d63b954b37578c59162b977eaf32e8bc
--- /dev/null
+++ b/gov2lisp/gov2lisp_test.go
@@ -0,0 +1,63 @@
+package gov2lisp
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+	"time"
+
+	"government/lisp2gov"
+	"government/program"
+	"government/sexpr"
+)
+
+// TestRoundTrip compiles each testdata file, decodes the .gov and
+// decompiles it. The text must equal the source in normal form, and read
+// back to the source's forms. A bug anywhere between reading the source
+// and printing the decoded program shows up here, in either direction.
+func TestRoundTrip(t *testing.T) {
+	files, _ := filepath.Glob("../testdata/*.gov.lisp")
+	examples, _ := filepath.Glob("../examples/*.gov.lisp")
+	files = append(files, examples...)
+	if len(files) == 0 {
+		t.Fatal("no programs found")
+	}
+	for _, file := range files {
+		src, err := os.ReadFile(file)
+		if err != nil {
+			t.Fatal(err)
+		}
+		want, err := sexpr.ReadAll(string(src))
+		if err != nil {
+			t.Fatal(err)
+		}
+		data, err := lisp2gov.Compile(string(src), lisp2gov.Options{})
+		if err != nil {
+			t.Fatal(err)
+		}
+		p, err := program.Load(data, program.Options{At: time.Now()})
+		if err != nil {
+			t.Fatalf("%s: %v", file, err)
+		}
+		got := Decompile(p.Forms)
+		if normal := Decompile(want); got != normal {
+			t.Errorf("%s: decompiled text differs from the source in normal form", file)
+		}
+		back, err := sexpr.ReadAll(got)
+		if err != nil {
+			t.Errorf("%s: decompiled text does not read: %v", file, err)
+			continue
+		}
+		if !reflect.DeepEqual(back, want) {
+			t.Errorf("%s: decompiled text reads as different forms", file)
+		}
+	}
+}
+
+func TestDecompileNormalForm(t *testing.T) {
+	forms, _ := sexpr.ReadAll("'x   ( + 1    3.10 )\n; gone\n\"a\\tb\"")
+	if got, want := Decompile(forms), "(quote x)\n(+ 1 3.1)\n\"a\\tb\"\n"; got != want {
+		t.Errorf("got %q, want %q", got, want)
+	}
+}
diff --git a/policy/draw.go b/policy/draw.go
new file mode 100644
index 0000000000000000000000000000000000000000..64934752029d2130a647ff3c8efd57fae9abac55
--- /dev/null
+++ b/policy/draw.go
@@ -0,0 +1,110 @@
+package policy
+
+import (
+	"cmp"
+	"fmt"
+	"slices"
+	"strconv"
+	"strings"
+
+	"government/ast"
+	"government/sexpr"
+)
+
+// Draw prints the graph as a tree, one node per line, with each node's
+// depth, its decoded label and its OID:
+//
+//	depth 1  `-- (...)#1     GOV.0.1.1
+//	depth 2      |-- +#2     GOV.0.2.21
+//	depth 3      |   `-- +#2'  copy
+//
+// A trailing ' marks a copy the validator made, which carries an atom down
+// to the bottom; a chain of copies is one line giving the depths it spans.
+// A node with several parents is drawn in full under the first and named
+// again, without its children, under the others.
+func (g *Graph) Draw() string {
+	type line struct {
+		depth       int
+		tree, where string
+	}
+	var lines []line
+	drawn := map[*Node]bool{}
+
+	var walk func(n *Node, parent *Node, prefix, branch string)
+	walk = func(n *Node, parent *Node, prefix, branch string) {
+		label, where := describe(n, parent)
+		if drawn[n] {
+			lines = append(lines, line{n.Depth, prefix + branch + label, where + "  (shared, drawn above)"})
+			return
+		}
+		drawn[n] = true
+		if where == "copy" {
+			// A copy can only have more copies of itself below it, down to
+			// the bottom; one line says how far the chain goes.
+			last := n
+			for len(last.Children) == 1 && last.Children[0].Policy.Equal(n.Policy) {
+				last = last.Children[0]
+			}
+			if last != n {
+				where = fmt.Sprintf("copy, depths %d-%d", n.Depth, last.Depth)
+			}
+			lines = append(lines, line{n.Depth, prefix + branch + label, where})
+			return
+		}
+		lines = append(lines, line{n.Depth, prefix + branch + label, where})
+		children := slices.Clone(n.Children)
+		slices.SortStableFunc(children, func(a, b *Node) int { return cmp.Compare(nodeID(a), nodeID(b)) })
+		childPrefix := prefix
+		switch branch {
+		case "|-- ":
+			childPrefix += "|   "
+		case "`-- ":
+			childPrefix += "    "
+		}
+		for i, c := range children {
+			b := "|-- "
+			if i == len(children)-1 {
+				b = "`-- "
+			}
+			walk(c, n, childPrefix, b)
+		}
+	}
+	walk(g.Levels[0][0], nil, "", "")
+
+	width := 0
+	for _, l := range lines {
+		width = max(width, len(l.tree))
+	}
+	var b strings.Builder
+	for _, l := range lines {
+		row := fmt.Sprintf("depth %d  %-*s  %s", l.depth, width, l.tree, l.where)
+		b.WriteString(strings.TrimRight(row, " "))
+		b.WriteByte('\n')
+	}
+	return b.String()
+}
+
+// describe gives a node's label, e.g. +#2 or "hi"#11, and what to show
+// beside it: its OID, or "copy" for a copy of its parent.
+func describe(n, parent *Node) (label, where string) {
+	if n.Policy.Equal(AnyPolicy) {
+		return "anyPolicy", ""
+	}
+	ns, id, text, err := ast.DecodeOID(n.Policy)
+	if err != nil {
+		return n.Policy.String(), "(not a GOVERNMENT node)"
+	}
+	if ns == ast.NSString {
+		text = sexpr.Print(sexpr.String(text))
+	}
+	label = text + "#" + strconv.FormatUint(id, 10)
+	if parent != nil && parent.Policy.Equal(n.Policy) {
+		return label + "'", "copy"
+	}
+	return label, short(n.Policy)
+}
+
+func nodeID(n *Node) uint64 {
+	_, id, _, _ := ast.DecodeOID(n.Policy)
+	return id
+}
diff --git a/policy/draw_test.go b/policy/draw_test.go
new file mode 100644
index 0000000000000000000000000000000000000000..a042e05fcf519b6503c79a1d750a103c8115ea20
--- /dev/null
+++ b/policy/draw_test.go
@@ -0,0 +1,53 @@
+package policy
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestDrawWorkedExample is the design doc's drawing of (+ 1 (* 2 3)).
+func TestDrawWorkedExample(t *testing.T) {
+	got := compiledGraph(t, "(+ 1 (* 2 3))").Draw()
+	want := strings.Join([]string{
+		"depth 0  anyPolicy",
+		"depth 1  `-- (...)#1       GOV.0.1.1",
+		"depth 2      |-- +#2       GOV.0.2.21",
+		"depth 3      |   `-- +#2'  copy",
+		"depth 2      |-- 1#3       GOV.2.3.49",
+		"depth 3      |   `-- 1#3'  copy",
+		"depth 2      `-- (...)#4   GOV.0.4.1",
+		"depth 3          |-- *#5   GOV.0.5.23",
+		"depth 3          |-- 2#6   GOV.2.6.50",
+		"depth 3          `-- 3#7   GOV.2.7.51",
+		"",
+	}, "\n")
+	if got != want {
+		t.Errorf("got\n%s\nwant\n%s", got, want)
+	}
+}
+
+func TestDrawLabelsAndSharing(t *testing.T) {
+	got := compiledGraph(t, `(f "hi" 2.5 'x)`).Draw()
+	for _, want := range []string{`"hi"#3`, "2.5#4", "quote#6", "x#7"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("missing %s in\n%s", want, got)
+		}
+	}
+	shared := mustProcess(t, path(
+		mapping(fakeCert("1.2.3", "1.2.4"), "1.2.3>1.2.5", "1.2.4>1.2.5"),
+		fakeCert("any"),
+	)).Draw()
+	if strings.Count(shared, "1.2.5") != 2 || !strings.Contains(shared, "(shared, drawn above)") {
+		t.Errorf("shared node:\n%s", shared)
+	}
+}
+
+func TestDrawFoldsCopyChains(t *testing.T) {
+	got := compiledGraph(t, "1 (a (b (c)))").Draw()
+	if !strings.Contains(got, "`-- 1#1'") || !strings.Contains(got, "copy, depths 2-4") {
+		t.Errorf("chain of copies not folded:\n%s", got)
+	}
+	if n := strings.Count(got, "\n"); n != 11 {
+		t.Errorf("%d lines, want 11:\n%s", n, got)
+	}
+}