devrites 3.2.28 → 4.0.0

package/engine/internal/doctor/doctor.go

@@ -1,306 +0,0 @@
-// Package doctor compares the engine, installed pack, and workspace schema
-// versions. It also reports root and installation problems without changing
-// workspace state.
-package doctor
-
-import (
-	"crypto/sha256"
-	"fmt"
-	"io/fs"
-	"os"
-	"path/filepath"
-	"strings"
-
-	"github.com/devrites/devrites/internal/devritespaths"
-	"github.com/devrites/devrites/internal/rootfacts"
-	"github.com/devrites/devrites/internal/state"
-	"github.com/devrites/devrites/internal/version"
-)
-
-// Unknown is reported when the installed pack version cannot be found. Doctor
-// does not report version skew against this value.
-const Unknown = "unknown"
-
-// Report is the resolved version triangle plus its verdict.
-type Report struct {
-	Binary       string   // the engine binary version
-	Pack         string   // the installed pack version, or Unknown
-	StateSchema  int      // the highest schemaVersion declared on disk
-	BinarySchema int      // the schema version this binary understands
-	Verdict      string   // one-line human summary
-	Checks       []string // advisory install/host-artifact drift checks
-	Refuse       bool     // true when topology or state schema makes action unsafe
-	Root         rootfacts.Facts
-}
-
-// Diagnose compares versions for projectDir and its .devrites root.
-//
-//   - A state schema newer than the binary causes a refusal because the binary
-//     cannot safely parse it.
-//   - A binary older than the pack produces a warning but does not block.
-//   - All other comparable versions are compatible. A newer binary can read
-//     older state because schema changes are additive.
-func Diagnose(projectDir, root string) (*Report, error) {
-	return DiagnoseFacts(rootfacts.Facts{
-		LexicalProject:  projectDir,
-		PhysicalProject: projectDir,
-		LexicalRoot:     root,
-		PhysicalRoot:    root,
-		SelectionReason: "provided",
-		Hazards:         []rootfacts.Hazard{},
-	})
-}
-
-// DiagnoseFacts reports the same canonical root facts used by state selection
-// and context show.
-func DiagnoseFacts(facts rootfacts.Facts) (*Report, error) {
-	stateSchema := state.SchemaVersion
-	if facts.PhysicalRoot != "" {
-		var err error
-		stateSchema, err = state.MaxDeclaredSchemaVersion(facts.PhysicalRoot)
-		if err != nil {
-			return nil, fmt.Errorf("read state schema: %w", err)
-		}
-		if stateSchema == 0 {
-			// Nothing on disk declares a version: treat it as the current schema;
-			// undeclared state is read as the engine's own version.
-			stateSchema = state.SchemaVersion
-		}
-	}
-	projectDir := facts.PhysicalProject
-
-	r := &Report{
-		Binary:       version.Version,
-		Pack:         packVersion(projectDir),
-		StateSchema:  stateSchema,
-		BinarySchema: state.SchemaVersion,
-		Checks:       driftChecks(projectDir),
-		Root:         facts,
-	}
-
-	switch {
-	case facts.Refuses():
-		r.Refuse = true
-		r.Verdict = "REFUSE: root or workspace selection is unsafe; apply the reported remediation"
-	case r.StateSchema > r.BinarySchema:
-		r.Refuse = true
-		r.Verdict = fmt.Sprintf("REFUSE: state schema v%d is newer than this binary supports (v%d): update devrites",
-			r.StateSchema, r.BinarySchema)
-	case r.packSkew():
-		r.Verdict = fmt.Sprintf("WARN: binary %s is older than the installed pack %s: update the devrites-engine binary",
-			r.Binary, r.Pack)
-	case len(facts.Hazards) > 0:
-		r.Verdict = "WARN: workspace or repository hazards need attention"
-	default:
-		r.Verdict = "ok: binary, pack, and state schema are compatible"
-	}
-	return r, nil
-}
-
-// packSkew reports whether the binary is comparably older than the pack.
-func (r *Report) packSkew() bool {
-	if r.Pack == Unknown {
-		return false
-	}
-	cmp, ok := version.Compare(r.Binary, r.Pack)
-	return ok && cmp < 0
-}
-
-// Render produces the deterministic doctor report with a trailing newline.
-func (r *Report) Render() string {
-	var b strings.Builder
-	physicalRoot := r.Root.PhysicalRoot
-	if physicalRoot == "" {
-		physicalRoot = "none"
-	}
-	physicalProject := r.Root.PhysicalProject
-	if physicalProject == "" {
-		physicalProject = "unknown"
-	}
-	fmt.Fprintf(&b, "project: %s\n", physicalProject)
-	fmt.Fprintf(&b, "root: %s\n", physicalRoot)
-	fmt.Fprintf(&b, "root-selection: %s\n", r.Root.SelectionReason)
-	if r.Root.LexicalProject != "" && r.Root.LexicalProject != r.Root.PhysicalProject {
-		fmt.Fprintf(&b, "project-lexical: %s\n", r.Root.LexicalProject)
-	}
-	if r.Root.LexicalRoot != "" && r.Root.LexicalRoot != r.Root.PhysicalRoot {
-		fmt.Fprintf(&b, "root-lexical: %s\n", r.Root.LexicalRoot)
-	}
-	if r.Root.Git.TopLevel == "" {
-		fmt.Fprintln(&b, "git: none")
-	} else {
-		fmt.Fprintf(&b, "git: top=%s dir=%s common=%s linked-worktree=%t submodule=%t\n",
-			r.Root.Git.TopLevel, r.Root.Git.Dir, r.Root.Git.CommonDir,
-			r.Root.Git.LinkedWorktree, r.Root.Git.Submodule)
-		if r.Root.Git.Superproject != "" {
-			fmt.Fprintf(&b, "git-superproject: %s\n", r.Root.Git.Superproject)
-		}
-	}
-	fmt.Fprintf(&b, "binary: %s\n", r.Binary)
-	fmt.Fprintf(&b, "pack: %s\n", r.Pack)
-	fmt.Fprintf(&b, "state-schema: v%d (binary supports v%d)\n", r.StateSchema, r.BinarySchema)
-	fmt.Fprintf(&b, "verdict: %s\n", r.Verdict)
-	if len(r.Root.Hazards) == 0 {
-		fmt.Fprintln(&b, "hazards: ok")
-	} else {
-		fmt.Fprintln(&b, "hazards:")
-		for _, hazard := range r.Root.Hazards {
-			fmt.Fprintf(&b, "  - [%s] %s: %s\n", hazard.ID, strings.ToUpper(hazard.Severity), hazard.Message)
-			fmt.Fprintf(&b, "    fix: %s\n", hazard.Remediation)
-		}
-	}
-	if len(r.Checks) == 0 {
-		fmt.Fprintln(&b, "checks: ok")
-	} else {
-		fmt.Fprintln(&b, "checks:")
-		for _, check := range r.Checks {
-			fmt.Fprintf(&b, "  - %s\n", check)
-		}
-	}
-	return b.String()
-}
-
-// packVersion discovers the installed DevRites pack version from the install
-// manifest. The old standalone marker remains readable for compatibility.
-func packVersion(projectDir string) string {
-	if v := manifestVersion(filepath.Join(projectDir, filepath.FromSlash(devritespaths.ManifestName))); v != "" {
-		return v
-	}
-	if v := firstLine(filepath.Join(projectDir, ".claude", "devrites.version")); v != "" {
-		return v
-	}
-	return Unknown
-}
-
-func manifestVersion(path string) string {
-	raw, err := os.ReadFile(path)
-	if err != nil {
-		return ""
-	}
-	const prefix = "# devrites-version:"
-	for _, line := range strings.Split(string(raw), "\n") {
-		if strings.HasPrefix(line, prefix) {
-			return strings.TrimSpace(strings.TrimPrefix(line, prefix))
-		}
-	}
-	return ""
-}
-
-func firstLine(path string) string {
-	raw, err := os.ReadFile(path)
-	if err != nil {
-		return ""
-	}
-	line, _, _ := strings.Cut(string(raw), "\n")
-	return strings.TrimSpace(line)
-}
-
-func driftChecks(projectDir string) []string {
-	var checks []string
-	settings := filepath.Join(projectDir, ".claude", "settings.json")
-	if isFile(settings) {
-		body := readString(settings)
-		if !strings.Contains(body, "devrites-engine hook") {
-			checks = append(checks, "WARN: .claude/settings.json exists but does not reference devrites-engine hooks")
-		}
-	} else if isDir(filepath.Join(projectDir, ".claude")) {
-		checks = append(checks, "WARN: .claude/settings.json missing: Claude hooks/statusline may be absent")
-	}
-	if isDir(filepath.Join(projectDir, ".claude", "skills")) && !isDir(filepath.Join(projectDir, ".agents", "skills")) {
-		checks = append(checks, "WARN: Claude skills installed but Codex skill mirror .agents/skills is missing")
-	}
-	if isDir(filepath.Join(projectDir, ".claude", "agents")) && !isDir(filepath.Join(projectDir, ".codex", "agents")) {
-		checks = append(checks, "WARN: Claude agents installed but Codex agent mirror .codex/agents is missing")
-	}
-	if packVersion(projectDir) == Unknown && isDir(filepath.Join(projectDir, ".claude", "skills")) {
-		checks = append(checks, "WARN: installed skills have no versioned .claude/devrites.manifest provenance")
-	}
-	if generatedClaudeDrift(projectDir) {
-		checks = append(checks, "[DRV-GENERATED-DRIFT] WARN: pack/generated/claude differs from canonical pack/.claude; run `bash scripts/build-host-artifacts.sh`")
-	}
-	return checks
-}
-
-func generatedClaudeDrift(projectDir string) bool {
-	canonical := filepath.Join(projectDir, "pack", ".claude")
-	generated := filepath.Join(projectDir, "pack", "generated", "claude")
-	if !isDir(canonical) {
-		return false
-	}
-	want, err := fileDigests(canonical, func(rel string) bool {
-		return rel == filepath.Join("agents", ".impeccable") ||
-			strings.HasPrefix(rel, filepath.Join("agents", ".impeccable")+string(filepath.Separator))
-	})
-	if err != nil {
-		return true
-	}
-	got, err := fileDigests(generated, nil)
-	if err != nil || len(want) != len(got) {
-		return true
-	}
-	for path, digest := range want {
-		if got[path] != digest {
-			return true
-		}
-	}
-	return false
-}
-
-func fileDigests(root string, skip func(string) bool) (map[string][sha256.Size]byte, error) {
-	rootDir, err := os.OpenRoot(root)
-	if err != nil {
-		return nil, err
-	}
-	defer func() { _ = rootDir.Close() }()
-
-	files := map[string][sha256.Size]byte{}
-	err = filepath.WalkDir(root, func(path string, entry fs.DirEntry, err error) error {
-		if err != nil {
-			return err
-		}
-		rel, err := filepath.Rel(root, path)
-		if err != nil {
-			return err
-		}
-		if rel == "." {
-			return nil
-		}
-		if skip != nil && skip(rel) {
-			if entry.IsDir() {
-				return filepath.SkipDir
-			}
-			return nil
-		}
-		if entry.IsDir() {
-			return nil
-		}
-		if entry.Type()&os.ModeSymlink != 0 || !entry.Type().IsRegular() {
-			return fmt.Errorf("generated tree contains non-regular file %s", rel)
-		}
-		body, err := rootDir.ReadFile(rel)
-		if err != nil {
-			return err
-		}
-		files[filepath.ToSlash(rel)] = sha256.Sum256(body)
-		return nil
-	})
-	return files, err
-}
-
-func readString(path string) string {
-	raw, err := os.ReadFile(path)
-	if err != nil {
-		return ""
-	}
-	return string(raw)
-}
-
-func isFile(path string) bool {
-	info, err := os.Stat(path)
-	return err == nil && !info.IsDir()
-}
-
-func isDir(path string) bool {
-	info, err := os.Stat(path)
-	return err == nil && info.IsDir()
-}

package/engine/internal/doctor/doctor_test.go

@@ -1,252 +0,0 @@
-package doctor
-
-import (
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/devrites/devrites/internal/rootfacts"
-	"github.com/devrites/devrites/internal/version"
-)
-
-// withBinaryVersion temporarily overrides the compiled-in binary version so skew
-// verdicts can be exercised deterministically.
-func withBinaryVersion(t *testing.T, v string) {
-	t.Helper()
-	prev := version.Version
-	version.Version = v
-	t.Cleanup(func() { version.Version = prev })
-}
-
-// writeFeature creates a minimal feature.md declaring a schemaVersion under root.
-func writeFeature(t *testing.T, root, slug string, schema int) {
-	t.Helper()
-	dir := filepath.Join(root, "features", slug)
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		t.Fatal(err)
-	}
-	content := "---\nslug: " + slug + "\nphase: build\nschemaVersion: " +
-		itoa(schema) + "\n---\n\nx\n"
-	if err := os.WriteFile(filepath.Join(dir, "feature.md"), []byte(content), 0o644); err != nil {
-		t.Fatal(err)
-	}
-}
-
-func itoa(n int) string {
-	if n == 0 {
-		return "0"
-	}
-	var b []byte
-	for n > 0 {
-		b = append([]byte{byte('0' + n%10)}, b...)
-		n /= 10
-	}
-	return string(b)
-}
-
-func TestDiagnoseOKWhenAligned(t *testing.T) {
-	withBinaryVersion(t, "2.6.1")
-	root := t.TempDir()
-	writeFeature(t, root, "f", 1) // state v1, binary supports v1
-	r, err := Diagnose(t.TempDir(), root)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if r.Refuse {
-		t.Errorf("Refuse = true, want false when aligned")
-	}
-	if got := r.Verdict; got == "" || got[:2] != "ok" {
-		t.Errorf("verdict = %q, want an ok verdict", got)
-	}
-}
-
-func TestDiagnoseWarnsWhenBinaryOlderThanPack(t *testing.T) {
-	withBinaryVersion(t, "1.0.0")
-	projectDir := t.TempDir()
-	// Installed pack newer than the binary → warn, not refuse.
-	claude := filepath.Join(projectDir, ".claude")
-	if err := os.MkdirAll(claude, 0o755); err != nil {
-		t.Fatal(err)
-	}
-	manifest := "# devrites-version: 2.0.0\n.claude/skills/rite/SKILL.md\tabc\n"
-	if err := os.WriteFile(filepath.Join(claude, "devrites.manifest"), []byte(manifest), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	root := t.TempDir()
-	writeFeature(t, root, "f", 1)
-
-	r, err := Diagnose(projectDir, root)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if r.Refuse {
-		t.Errorf("a pack-vs-binary skew must warn, not refuse")
-	}
-	if r.Pack != "2.0.0" {
-		t.Errorf("pack = %q, want 2.0.0", r.Pack)
-	}
-	if want := "WARN"; len(r.Verdict) < 4 || r.Verdict[:4] != want {
-		t.Errorf("verdict = %q, want a WARN verdict", r.Verdict)
-	}
-}
-
-func TestPackVersionUsesManifestBeforeLegacyMarker(t *testing.T) {
-	projectDir := t.TempDir()
-	claude := filepath.Join(projectDir, ".claude")
-	if err := os.MkdirAll(claude, 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(claude, "devrites.manifest"), []byte("# devrites-version: 3.2.0\n"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(claude, "devrites.version"), []byte("2.9.0\n"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	if got := packVersion(projectDir); got != "3.2.0" {
-		t.Fatalf("packVersion() = %q, want installer manifest version 3.2.0", got)
-	}
-}
-
-func TestPackVersionIgnoresProjectPackageJSON(t *testing.T) {
-	projectDir := t.TempDir()
-	if err := os.WriteFile(filepath.Join(projectDir, "package.json"), []byte(`{"version":"99.0.0"}`), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	if got := packVersion(projectDir); got != Unknown {
-		t.Fatalf("packVersion() = %q, want %q without DevRites install provenance", got, Unknown)
-	}
-}
-
-func TestDiagnoseRefusesNewerStateSchema(t *testing.T) {
-	withBinaryVersion(t, "2.6.1")
-	root := t.TempDir()
-	writeFeature(t, root, "f", 99) // far newer than the binary supports
-	r, err := Diagnose(t.TempDir(), root)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !r.Refuse {
-		t.Errorf("Refuse = false, want true for a newer-major state schema")
-	}
-	if len(r.Verdict) < 6 || r.Verdict[:6] != "REFUSE" {
-		t.Errorf("verdict = %q, want a REFUSE verdict", r.Verdict)
-	}
-}
-
-func TestDiagnoseDevBinaryNeverFalseWarns(t *testing.T) {
-	withBinaryVersion(t, "dev") // incomparable
-	projectDir := t.TempDir()
-	claude := filepath.Join(projectDir, ".claude")
-	_ = os.MkdirAll(claude, 0o755)
-	_ = os.WriteFile(filepath.Join(claude, "devrites.version"), []byte("9.9.9\n"), 0o644)
-	root := t.TempDir()
-	writeFeature(t, root, "f", 1)
-
-	r, err := Diagnose(projectDir, root)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if r.Refuse || (len(r.Verdict) >= 4 && r.Verdict[:4] == "WARN") {
-		t.Errorf("a dev (incomparable) binary must not warn on skew; verdict=%q", r.Verdict)
-	}
-}
-
-func TestDiagnoseReportsHostArtifactDrift(t *testing.T) {
-	projectDir := t.TempDir()
-	if err := os.MkdirAll(filepath.Join(projectDir, ".claude", "skills", "rite-build"), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(projectDir, ".claude", "settings.json"), []byte(`{"hooks":{}}`), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	root := t.TempDir()
-	writeFeature(t, root, "f", 1)
-
-	r, err := Diagnose(projectDir, root)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(r.Checks) == 0 {
-		t.Fatal("expected drift checks")
-	}
-	out := r.Render()
-	for _, want := range []string{"devrites-engine hooks", "Codex skill mirror", "devrites.manifest provenance"} {
-		if !strings.Contains(out, want) {
-			t.Fatalf("doctor output missing %q:\n%s", want, out)
-		}
-	}
-}
-
-func TestDiagnoseFactsReportsCanonicalRootAndStaleActive(t *testing.T) {
-	projectDir := t.TempDir()
-	root := filepath.Join(projectDir, ".devrites")
-	if err := os.MkdirAll(root, 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(root, "ACTIVE"), []byte("ghost\n"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	facts, err := rootfacts.ResolveFrom(projectDir, projectDir)
-	if err != nil {
-		t.Fatal(err)
-	}
-	r, err := DiagnoseFacts(facts)
-	if err != nil {
-		t.Fatal(err)
-	}
-	out := r.Render()
-	for _, want := range []string{
-		"root: " + facts.PhysicalRoot,
-		"root-selection: DEVRITES_ROOT",
-		"[DRV-ACTIVE-STALE]",
-		"fix: rm -f",
-	} {
-		if !strings.Contains(out, want) {
-			t.Fatalf("doctor output missing %q:\n%s", want, out)
-		}
-	}
-	if r.Refuse {
-		t.Fatal("stale ACTIVE should warn, not turn a read-only doctor run into a refusal")
-	}
-}
-
-func TestDiagnoseReportsCanonicalGeneratedResidue(t *testing.T) {
-	projectDir := t.TempDir()
-	canonical := filepath.Join(projectDir, "pack", ".claude")
-	generated := filepath.Join(projectDir, "pack", "generated", "claude")
-	for _, dir := range []string{canonical, generated} {
-		if err := os.MkdirAll(dir, 0o755); err != nil {
-			t.Fatal(err)
-		}
-	}
-	for _, path := range []string{
-		filepath.Join(canonical, "settings.json"),
-		filepath.Join(generated, "settings.json"),
-	} {
-		if err := os.WriteFile(path, []byte(`{"hooks":{}}`), 0o644); err != nil {
-			t.Fatal(err)
-		}
-	}
-	root := t.TempDir()
-	writeFeature(t, root, "f", 1)
-	aligned, err := Diagnose(projectDir, root)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if strings.Contains(aligned.Render(), "DRV-GENERATED-DRIFT") {
-		t.Fatalf("aligned generated tree reported drift:\n%s", aligned.Render())
-	}
-
-	if err := os.WriteFile(filepath.Join(generated, "legacy.json"), []byte("{}"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	drifted, err := Diagnose(projectDir, root)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !strings.Contains(drifted.Render(), "[DRV-GENERATED-DRIFT]") ||
-		!strings.Contains(drifted.Render(), "bash scripts/build-host-artifacts.sh") {
-		t.Fatalf("generated residue not diagnosed:\n%s", drifted.Render())
-	}
-}