mesh-catalog/checks/paths/main.go

// Command paths holds the catalogue's modules to talking over the bus (novox/hq ADR 0260): no module
// names a path that another module's manifest places under /run, /var/lib, /usr/local/lib or /etc.
// Such a path is that module's state or configuration on its machine, and a second module reading or
// writing it is two modules talking through a file, which the bus exists to replace.
//
// A module owns every `path` of its resources under those roots. Every other module's manifest, and
// every file of its own but its documentation, its tests and its binaries, is searched for each as a
// whole path: followed by nothing, a slash, or a character no path takes. A path a container sees
// inside itself (the target of a `volumes` entry) is the container's, and is not searched.
//
// Two lists beside this file narrow it, each line a path or a finding and its reason after a `#`:
//
//   - shared: paths every program on a machine reads as the machine's, not as a message from their
//     owner — /etc/hosts, which every resolver reads.
//   - known: the findings standing on the day the roots were widened (2026-10-08). The check fails on a
//     finding not listed, and on a listed one that no longer occurs, so the list only shrinks.
//
// **What it cannot see:** a path built in code from pieces (`filepath.Join("/etc", name)`), one read
// from the environment or a setting, and one reached through a shell the module runs. It reads text,
// not what a program does; review and the runtime's grants cover the rest.
//
//	go run . <catalogue root>
//
// Exits 1 on a finding.
package main

import (
	"bufio"
	"bytes"
	"encoding/json"
	"fmt"
	"io/fs"
	"os"
	"path/filepath"
	"regexp"
	"sort"
	"strings"
)

// stateRoots are where a machine keeps a module's state and configuration.
var stateRoots = []string{"/run/", "/var/lib/", "/usr/local/lib/", "/etc/"}

// Finding is one module naming another's path.
type Finding struct {
	Module, File, Path, Owner string
}

func (f Finding) String() string {
	return fmt.Sprintf("%s names %s in %s, and the path is %s's; modules talk over the bus (novox/hq ADR 0260)",
		f.Module, f.Path, f.File, f.Owner)
}

// Key is how a finding is listed in `known`: the module, the path and the file.
func (f Finding) Key() string { return f.Module + " " + f.Path + " " + f.File }

// containerTargets drops what a container sees inside itself from a manifest before it is searched:
// the target half of every `volumes` entry of a container resource.
func containerTargets(m map[string]any) {
	resources, _ := m["resources"].([]any)
	for _, raw := range resources {
		r, ok := raw.(map[string]any)
		if !ok || r["type"] != "container" {
			continue
		}
		volumes, _ := r["volumes"].([]any)
		for i, v := range volumes {
			if s, ok := v.(string); ok {
				if src, _, two := strings.Cut(s, ":"); two {
					volumes[i] = src
				}
			}
			if o, ok := v.(map[string]any); ok {
				delete(o, "target")
				delete(o, "container")
			}
		}
	}
}

// Check is every finding in the catalogue at root, before the lists narrow it.
func Check(root string) ([]Finding, error) {
	files, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
	if err != nil {
		return nil, err
	}
	owner := map[string]string{}
	modules := map[string]string{}
	for _, f := range files {
		raw, err := os.ReadFile(f)
		if err != nil {
			return nil, err
		}
		var m struct {
			Module    string           `json:"module"`
			Resources []map[string]any `json:"resources"`
		}
		if err := json.Unmarshal(raw, &m); err != nil {
			return nil, fmt.Errorf("%s: %w", f, err)
		}
		modules[m.Module] = filepath.Dir(f)
		for _, r := range m.Resources {
			p, _ := r["path"].(string)
			for _, root := range stateRoots {
				if strings.HasPrefix(p, root) && len(p) > len(root) {
					owner[strings.TrimRight(p, "/")] = m.Module
				}
			}
		}
	}
	paths := make([]string, 0, len(owner))
	for p := range owner {
		paths = append(paths, p)
	}
	sort.Strings(paths)
	patterns := map[string]*regexp.Regexp{}
	for _, p := range paths {
		patterns[p] = regexp.MustCompile(regexp.QuoteMeta(p) + `(?:$|[^A-Za-z0-9._-])`)
	}
	names := make([]string, 0, len(modules))
	for n := range modules {
		names = append(names, n)
	}
	sort.Strings(names)
	var out []Finding
	for _, module := range names {
		err := filepath.WalkDir(modules[module], func(path string, d fs.DirEntry, err error) error {
			if err != nil || d.IsDir() {
				return err
			}
			name := d.Name()
			if strings.HasSuffix(name, ".md") || strings.HasSuffix(name, "_test.go") ||
				name == "go.sum" || name == "package-lock.json" {
				return nil
			}
			raw, err := os.ReadFile(path)
			if err != nil {
				return err
			}
			if bytes.IndexByte(raw, 0) >= 0 {
				return nil // a binary: what it says is in its source
			}
			if name == "module.json" {
				var m map[string]any
				if json.Unmarshal(raw, &m) == nil {
					containerTargets(m)
					raw, _ = json.Marshal(m)
				}
			}
			text := string(raw)
			for _, p := range paths {
				if owner[p] != module && patterns[p].MatchString(text) {
					rel, _ := filepath.Rel(root, path)
					out = append(out, Finding{Module: module, File: rel, Path: p, Owner: owner[p]})
				}
			}
			return nil
		})
		if err != nil {
			return nil, err
		}
	}
	return out, nil
}

// list reads one of the lists beside this check: each line's text before a `#`, trimmed.
func list(path string) (map[string]bool, error) {
	out := map[string]bool{}
	f, err := os.Open(path)
	if err != nil {
		return nil, err
	}
	defer f.Close()
	s := bufio.NewScanner(f)
	for s.Scan() {
		line, _, _ := strings.Cut(s.Text(), "#")
		if line = strings.TrimSpace(line); line != "" {
			out[line] = true
		}
	}
	return out, s.Err()
}

// Judge narrows the findings by the lists: what is left to refuse, and the known findings that no
// longer occur, which must leave the list.
func Judge(found []Finding, shared, known map[string]bool) (refused []Finding, gone []string) {
	seen := map[string]bool{}
	for _, f := range found {
		if shared[f.Path] {
			continue
		}
		seen[f.Key()] = true
		if !known[f.Key()] {
			refused = append(refused, f)
		}
	}
	for k := range known {
		if !seen[k] {
			gone = append(gone, k)
		}
	}
	sort.Strings(gone)
	return refused, gone
}

func main() {
	root := "."
	if len(os.Args) > 1 {
		root = os.Args[1]
	}
	found, err := Check(root)
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(2)
	}
	here := filepath.Join(root, "checks", "paths")
	shared, err1 := list(filepath.Join(here, "shared"))
	known, err2 := list(filepath.Join(here, "known"))
	if err1 != nil || err2 != nil {
		fmt.Fprintln(os.Stderr, "the lists beside the check cannot be read:", err1, err2)
		os.Exit(2)
	}
	refused, gone := Judge(found, shared, known)
	for _, f := range refused {
		fmt.Println(f)
	}
	for _, k := range gone {
		fmt.Printf("%q is in checks/paths/known and no longer occurs: take it out, so it cannot come back\n", k)
	}
	if len(refused) > 0 || len(gone) > 0 {
		os.Exit(1)
	}
	fmt.Printf("paths: no module names another's state on its machine (%d known, listed to go)\n", len(known))
}