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)
+ }
+}