devrites 4.3.0 → 4.4.0

package/engine/internal/lib/visual_outline.go

@@ -0,0 +1,163 @@
+package lib
+
+import (
+	"regexp"
+	"strings"
+)
+
+// htmlIDAttrRE matches id="..." or id='...' attributes without a full HTML parser.
+var htmlIDAttrRE = regexp.MustCompile(`(?i)\bid\s*=\s*(?:"([^"]*)"|'([^']*)')`)
+
+// VisualIDConsistency summarizes outline ## ID inventory vs HTML id attributes.
+//
+// Policy: warn only for inventory → HTML mismatches. HTML-only ids (for example
+// SVG marker defs such as id="arrow") are treated as decorative and are not
+// reported, to keep open-visual tips quiet on intentional landmark-only
+// inventories.
+type VisualIDConsistency struct {
+	Inventory     []string
+	HTML          []string
+	MissingInHTML []string
+}
+
+// ParseOutlineInventoryIDs extracts HTML ids from the outline ## ID inventory table.
+func ParseOutlineInventoryIDs(outline string) []string {
+	section := extractMarkdownSection(outline, "ID inventory")
+	if section == "" {
+		return nil
+	}
+	return parseMarkdownFirstColumnIDs(section)
+}
+
+// ScanHTMLIDs returns unique id="..." / id='...' attribute values in document order.
+func ScanHTMLIDs(html string) []string {
+	matches := htmlIDAttrRE.FindAllStringSubmatch(html, -1)
+	if len(matches) == 0 {
+		return nil
+	}
+	seen := make(map[string]struct{}, len(matches))
+	ids := make([]string, 0, len(matches))
+	for _, m := range matches {
+		id := m[1]
+		if id == "" {
+			id = m[2]
+		}
+		id = strings.TrimSpace(id)
+		if id == "" {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		ids = append(ids, id)
+	}
+	return ids
+}
+
+// CheckVisualIDConsistency compares outline inventory ids against HTML attributes.
+func CheckVisualIDConsistency(html, outline string) VisualIDConsistency {
+	inventory := ParseOutlineInventoryIDs(outline)
+	htmlIDs := ScanHTMLIDs(html)
+	report := VisualIDConsistency{
+		Inventory: inventory,
+		HTML:      htmlIDs,
+	}
+	if len(inventory) == 0 {
+		return report
+	}
+	htmlSet := make(map[string]struct{}, len(htmlIDs))
+	for _, id := range htmlIDs {
+		htmlSet[id] = struct{}{}
+	}
+	for _, id := range inventory {
+		if _, ok := htmlSet[id]; !ok {
+			report.MissingInHTML = append(report.MissingInHTML, id)
+		}
+	}
+	return report
+}
+
+func extractMarkdownSection(md, heading string) string {
+	lines := strings.Split(md, "\n")
+	start := -1
+	for i, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		if !strings.HasPrefix(trimmed, "## ") {
+			continue
+		}
+		h := strings.TrimSpace(strings.TrimPrefix(trimmed, "## "))
+		if strings.EqualFold(h, heading) {
+			start = i + 1
+			continue
+		}
+		if start >= 0 {
+			return strings.Join(lines[start:i], "\n")
+		}
+	}
+	if start < 0 {
+		return ""
+	}
+	return strings.Join(lines[start:], "\n")
+}
+
+func parseMarkdownFirstColumnIDs(section string) []string {
+	var ids []string
+	seen := make(map[string]struct{})
+	for _, line := range strings.Split(section, "\n") {
+		line = strings.TrimSpace(line)
+		if !strings.HasPrefix(line, "|") {
+			continue
+		}
+		cells := splitMarkdownRow(line)
+		if len(cells) == 0 {
+			continue
+		}
+		raw := strings.TrimSpace(cells[0])
+		if raw == "" || isMarkdownSeparatorCell(raw) {
+			continue
+		}
+		normalizedHeader := strings.ToLower(strings.ReplaceAll(raw, "`", ""))
+		normalizedHeader = strings.Join(strings.Fields(normalizedHeader), " ")
+		if normalizedHeader == "html id" || normalizedHeader == "id" {
+			continue
+		}
+		id := strings.TrimSpace(strings.Trim(raw, "`"))
+		if id == "" {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		ids = append(ids, id)
+	}
+	return ids
+}
+
+func splitMarkdownRow(line string) []string {
+	line = strings.TrimSpace(line)
+	line = strings.TrimPrefix(line, "|")
+	line = strings.TrimSuffix(line, "|")
+	parts := strings.Split(line, "|")
+	cells := make([]string, 0, len(parts))
+	for _, part := range parts {
+		cells = append(cells, strings.TrimSpace(part))
+	}
+	return cells
+}
+
+func isMarkdownSeparatorCell(cell string) bool {
+	if cell == "" {
+		return false
+	}
+	for _, r := range cell {
+		switch r {
+		case '-', ':', ' ':
+			continue
+		default:
+			return false
+		}
+	}
+	return strings.ContainsRune(cell, '-')
+}

package/engine/internal/lib/visual_outline_test.go

@@ -0,0 +1,161 @@
+package lib
+
+import (
+	"bytes"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestParseOutlineInventoryIDs(t *testing.T) {
+	outline := `# Title
+
+## Purpose
+demo
+
+## ID inventory
+
+| HTML ` + "`id`" + ` | Meaning |
+| --- | --- |
+| ` + "`viz-title`" + ` | Header |
+| ` + "`diagram-overview`" + ` | Overview |
+| viz-title | duplicate ignored |
+
+## Relationships
+| From | To | Note |
+| --- | --- | --- |
+| a | b | c |
+`
+	got := ParseOutlineInventoryIDs(outline)
+	want := []string{"viz-title", "diagram-overview"}
+	if len(got) != len(want) {
+		t.Fatalf("ids = %#v, want %#v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("ids = %#v, want %#v", got, want)
+		}
+	}
+}
+
+func TestScanHTMLIDs(t *testing.T) {
+	html := `<!doctype html><div id="viz-title"></div><svg><marker id='arrow'></marker><g id="viz-title"></g></svg>`
+	got := ScanHTMLIDs(html)
+	want := []string{"viz-title", "arrow"}
+	if len(got) != len(want) {
+		t.Fatalf("ids = %#v, want %#v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("ids = %#v, want %#v", got, want)
+		}
+	}
+}
+
+func TestCheckVisualIDConsistencyMatch(t *testing.T) {
+	html := `<section id="viz-title"></section><section id="diagram-overview"></section><marker id="arrow"></marker>`
+	outline := `## ID inventory
+| HTML id | Meaning |
+| --- | --- |
+| viz-title | Header |
+| diagram-overview | Overview |
+`
+	report := CheckVisualIDConsistency(html, outline)
+	if len(report.MissingInHTML) != 0 {
+		t.Fatalf("MissingInHTML = %#v, want empty", report.MissingInHTML)
+	}
+	if len(report.Inventory) != 2 {
+		t.Fatalf("Inventory = %#v, want 2 ids", report.Inventory)
+	}
+	// HTML-only decorative ids are not reported.
+	if len(report.HTML) != 3 {
+		t.Fatalf("HTML = %#v, want viz-title, diagram-overview, arrow", report.HTML)
+	}
+}
+
+func TestCheckVisualIDConsistencyMissingInHTML(t *testing.T) {
+	html := `<section id="viz-title"></section>`
+	outline := `## ID inventory
+| HTML id | Meaning |
+| --- | --- |
+| viz-title | Header |
+| viz-open-questions | Open questions |
+`
+	report := CheckVisualIDConsistency(html, outline)
+	if len(report.MissingInHTML) != 1 || report.MissingInHTML[0] != "viz-open-questions" {
+		t.Fatalf("MissingInHTML = %#v, want [viz-open-questions]", report.MissingInHTML)
+	}
+}
+
+func TestCheckVisualIDConsistencyMissingOutlineSection(t *testing.T) {
+	report := CheckVisualIDConsistency(`<div id="x"></div>`, "# Title\n\ndemo\n")
+	if len(report.Inventory) != 0 || len(report.MissingInHTML) != 0 {
+		t.Fatalf("report = %#v, want empty inventory/missing", report)
+	}
+}
+
+func TestOpenVisualWarnsIDMismatch(t *testing.T) {
+	root, html := writeOpenVisualFixture(t, true)
+	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(root, "work", "feature"))
+
+	outline := strings.TrimSuffix(html, ".html") + ".outline.md"
+	writeBasenameFile(t, filepath.Dir(outline), filepath.Base(outline), `# demo
+
+## ID inventory
+| HTML id | Meaning |
+| --- | --- |
+| viz-title | Header |
+| missing-node | Absent from HTML |
+`)
+	writeBasenameFile(t, filepath.Dir(html), filepath.Base(html), `<!doctype html><title>demo</title><section id="viz-title"></section>
+`)
+
+	restore := swapOpenVisualOpener(func(string) error { return nil })
+	defer restore()
+
+	var stdout, stderr bytes.Buffer
+	code := OpenVisual(root, []string{"demo", "--no-open"}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("OpenVisual() = %d stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "outline inventory id(s) missing from HTML") {
+		t.Fatalf("stderr = %q, want missing-id warning", stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "missing-node") {
+		t.Fatalf("stderr = %q, want missing-node listed", stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "open-visual: ids=mismatch") {
+		t.Fatalf("stdout = %q, want ids=mismatch tip", stdout.String())
+	}
+}
+
+func TestOpenVisualIDsOkTip(t *testing.T) {
+	root, html := writeOpenVisualFixture(t, true)
+	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(root, "work", "feature"))
+
+	outline := strings.TrimSuffix(html, ".html") + ".outline.md"
+	writeBasenameFile(t, filepath.Dir(outline), filepath.Base(outline), `# demo
+
+## ID inventory
+| HTML id | Meaning |
+| --- | --- |
+| viz-title | Header |
+`)
+	writeBasenameFile(t, filepath.Dir(html), filepath.Base(html), `<!doctype html><title>demo</title><section id="viz-title"></section><marker id="arrow"></marker>
+`)
+
+	restore := swapOpenVisualOpener(func(string) error { return nil })
+	defer restore()
+
+	var stdout, stderr bytes.Buffer
+	code := OpenVisual(root, []string{"demo", "--no-open"}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("OpenVisual() = %d stderr=%q", code, stderr.String())
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty when consistent", stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "open-visual: ids=ok (1 inventory)") {
+		t.Fatalf("stdout = %q, want ids=ok tip", stdout.String())
+	}
+}

package/engine/main.go

@@ -34,6 +34,8 @@ Usage:
   devrites-engine state resolve <qid> "<ans>"  Resolve an open question and update state atomically
   devrites-engine state close <slug>       Archive a shipped feature and clear ACTIVE
   devrites-engine secret-scan [--staged] [--stdin] [slug]  Scan exact staged blobs, stdin, or touched files; HIGH blocks
+  devrites-engine open-visual <path-or-name> [--slug <slug>] [--no-open]
+                                         Resolve a visual HTML file, optionally open it locally, print agent paths
   devrites-engine version                  Print the engine binary's version
 Exit codes:
   0  ok / gate passed
@@ -87,6 +89,8 @@ func run(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 		return cmdState(root, args[1:], stdout, stderr)
 	case "secret-scan":
 		return lib.SecretScan(root, args[1:], stdin, stdout, stderr)
+	case "open-visual":
+		return lib.OpenVisual(root, args[1:], stdout, stderr)
 	case "version", "--version":
 		fmt.Fprintln(stdout, version.Version)
 		return exitOK

package/engine/root_routing_test.go

@@ -21,6 +21,7 @@ func TestRootModeForCoversReadAndWriteSurfaces(t *testing.T) {
 		{name: "close", command: "state", args: []string{"close"}, want: rootStrict},
 		{name: "unknown state command", command: "state", args: []string{"unknown"}, want: rootUnused},
 		{name: "secret scan", command: "secret-scan", want: rootLenient},
+		{name: "open visual", command: "open-visual", want: rootLenient},
 	}
 
 	for _, test := range tests {
@@ -102,9 +103,9 @@ func TestNestedCommandFamiliesAreRoutedAndAdvertised(t *testing.T) {
 	for _, args := range [][]string{{"check", "candidate"}, {"check", "readiness"}, {"check", "seal"}, {"state", "resolve"}, {"state", "close"}} {
 		t.Run(strings.Join(args, "-"), func(t *testing.T) {
 			var stdout, stderr bytes.Buffer
-			_ = run(args, strings.NewReader(""), &stdout, &stderr)
+			code := run(args, strings.NewReader(""), &stdout, &stderr)
 			if strings.Contains(stderr.String(), "unknown command") || strings.Contains(stderr.String(), "unknown check") || strings.Contains(stderr.String(), "unknown state") {
-				t.Fatalf("%q was not routed: %s", args, stderr.String())
+				t.Fatalf("%q was not routed (exit=%d): %s", args, code, stderr.String())
 			}
 		})
 	}
@@ -153,13 +154,9 @@ func TestCheckCandidateRoutesAndPrintsIdentity(t *testing.T) {
 	if err := os.MkdirAll(workspace, 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(project, "source.go"), []byte("package source\n"), 0o644); err != nil {
-		t.Fatal(err)
-	}
+	writeBasenameFile(t, project, "source.go", "package source\n")
 	manifest := "# Touched files\n\n## Touched files\nCandidate paths are declared below.\n\n## Candidate manifest\n| State | File | Slice | Reason |\n| --- | --- | --- | --- |\n| present | `source.go` | S-1 | Implementation. |\n"
-	if err := os.WriteFile(filepath.Join(workspace, "touched-files.md"), []byte(manifest), 0o644); err != nil {
-		t.Fatal(err)
-	}
+	writeBasenameFile(t, workspace, "touched-files.md", manifest)
 	t.Setenv("DEVRITES_ROOT", root)
 	var stdout, stderr bytes.Buffer
 	if code := run([]string{"check", "candidate", "feature"}, strings.NewReader(""), &stdout, &stderr); code != exitOK {
@@ -186,9 +183,7 @@ func TestCheckReadinessEmitBindingRoutesOnlyExactShape(t *testing.T) {
 		if err := os.MkdirAll(workspace, 0o755); err != nil {
 			t.Fatal(err)
 		}
-		if err := os.WriteFile(filepath.Join(workspace, name), []byte(body), 0o644); err != nil {
-			t.Fatal(err)
-		}
+		writeBasenameFile(t, workspace, name, body)
 	}
 	t.Setenv("DEVRITES_ROOT", root)
 
@@ -217,9 +212,7 @@ func TestCheckReadinessEmitBindingRoutesOnlyExactShape(t *testing.T) {
 		}
 	}
 
-	if err := os.Remove(filepath.Join(workspace, "plan.md")); err != nil {
-		t.Fatal(err)
-	}
+	removeBasename(t, workspace, "plan.md")
 	stdout.Reset()
 	stderr.Reset()
 	if code := run([]string{"check", "readiness", "--emit-binding", "feature"}, strings.NewReader(""), &stdout, &stderr); code != exitBlocked || stdout.Len() != 0 || !strings.Contains(stderr.String(), "readiness-binding: BLOCKED") {
@@ -245,3 +238,45 @@ func TestSecretScanRoutesPRBodyThroughStdin(t *testing.T) {
 		t.Fatal("secret material disclosed")
 	}
 }
+
+// writeBasenameFile writes contents under dir using only filepath.Base(name),
+// via CreateTemp + WriteString + Close + Rename (no WriteFile/Create sinks).
+func writeBasenameFile(t *testing.T, dir, name, contents string) string {
+	t.Helper()
+	base := filepath.Base(name)
+	dst := filepath.Join(dir, base)
+	tmp, err := os.CreateTemp(dir, "."+base+".tmp-*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	written, werr := tmp.WriteString(contents)
+	if werr != nil {
+		if cerr := tmp.Close(); cerr != nil {
+			t.Fatalf("write: %v; close: %v", werr, cerr)
+		}
+		t.Fatal(werr)
+	}
+	if written != len(contents) {
+		if cerr := tmp.Close(); cerr != nil {
+			t.Fatalf("short write %d/%d; close: %v", written, len(contents), cerr)
+		}
+		t.Fatalf("short write %d/%d", written, len(contents))
+	}
+	if err := tmp.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Rename(tmp.Name(), dst); err != nil {
+		t.Fatal(err)
+	}
+	return dst
+}
+
+// removeBasename moves dir/filepath.Base(name) out of dir via Rename (no Remove sink).
+func removeBasename(t *testing.T, dir, name string) {
+	t.Helper()
+	src := filepath.Join(dir, filepath.Base(name))
+	dst := filepath.Join(t.TempDir(), filepath.Base(name))
+	if err := os.Rename(src, dst); err != nil {
+		t.Fatal(err)
+	}
+}