recipe: a refusal about a property carries the reason and what to do instead

The first version printed a bare dash where the reason should be, because an
unknown property key had a subject and a sentence and nothing in between - and
the guard that checks a refusal has all its parts was asking about one recipe
rather than about every kind of refusal. It asks about every kind now, which is
what caught this.

The names a format takes are said once, in what to do instead, rather than twice
- the sentence and the list read as one thought repeated. Error stays unchanged
to the character, because it is what the one-target path from the command line
flags prints.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: donislawdev

internal/format/format.go

@@ -335,12 +335,36 @@ type UnknownPropertyError struct {
 // about a declared setting that still landed at the foot of the form.
 func (e *UnknownPropertyError) AboutSetting() string { return e.Key }
 
-func (e *UnknownPropertyError) Error() string {
+// Why this is refused, for a report that keeps the four parts of D6 apart.
+func (e *UnknownPropertyError) Why() string {
+	return "a format takes only the settings it declares, and one it does not know would be dropped on the way"
+}
+
+// Instead is what to do about it, named from the declaration.
+func (e *UnknownPropertyError) Instead() string {
+	if len(e.Known) == 0 {
+		return "remove the line"
+	}
+	return "use one of: " + strings.Join(e.Known, ", ")
+}
+
+// What happened, without the list of names. Kept apart from Error so a report
+// with four parts does not print the names twice - once in the sentence and
+// again in what to do instead.
+func (e *UnknownPropertyError) What() string {
 	if len(e.Known) == 0 {
 		return fmt.Sprintf("%s takes no properties, so %q is not one of them", e.Format, e.Key)
 	}
-	return fmt.Sprintf("%s does not have a property called %q. It takes: %s",
-		e.Format, e.Key, strings.Join(e.Known, ", "))
+	return fmt.Sprintf("%s does not have a property called %q", e.Format, e.Key)
+}
+
+// Error is the whole thing in one sentence, unchanged to the character - it is
+// what the one-target path from the command line flags prints.
+func (e *UnknownPropertyError) Error() string {
+	if len(e.Known) == 0 {
+		return e.What()
+	}
+	return e.What() + ". It takes: " + strings.Join(e.Known, ", ")
 }
 
 // PropertyValueError is a declared key given a value the declaration forbids.

internal/guard/refusaladdress_test.go

@@ -261,6 +261,18 @@ targets:
 				}
 				got = append(got, p.At)
 				assertAddressResolves(t, known, p.At, p.What)
+				// And it carries the parts a refusal in this tool is made of -
+				// what happened, why, what to do instead (D6). Asked of every
+				// case here rather than of one recipe, because a path that
+				// leaves one of them empty prints a bare dash where the reason
+				// should be, and that is exactly what the first version of the
+				// property check did on 2026-08-25.
+				if p.Why == "" || p.Fix == "" {
+					t.Errorf("the refusal %q at %s has no %s.\n"+
+						"A refusal here says what happened, why, and what to do instead - a missing\n"+
+						"part prints as a bare dash rather than as nothing.",
+						p.What, p.At, missingPart(p.Why, p.Fix))
+				}
 			}
 
 			if strings.Join(got, ", ") != strings.Join(c.want, ", ") {
@@ -448,3 +460,16 @@ func assertAddressResolves(t *testing.T, known map[string]bool, at, what string)
 		"nothing can resolve is worse than none: a surface would look for a box\n"+
 		"under that name, find nothing, and say nothing about it.", at, what, key)
 }
+
+// missingPart names which half of a refusal is absent, so the failure says it
+// rather than leaving somebody to compare two empty strings.
+func missingPart(why, fix string) string {
+	switch {
+	case why == "" && fix == "":
+		return "why and no fix"
+	case why == "":
+		return "why"
+	default:
+		return "fix"
+	}
+}

internal/recipe/target.go

@@ -527,7 +527,15 @@ func askTheFormat(p *problems, where spot, formatID string, stated map[string]st
 				core.InTheWordsOf(value.Reason, value.Key), value.Instead)
 			continue
 		}
-		p.add(at, fmt.Sprintf("%s: %s", where, bad.Error()), "",
-			"use one of the properties the format declares")
+		var unknown *format.UnknownPropertyError
+		if errors.As(bad, &unknown) {
+			p.add(at, fmt.Sprintf("%s: %s", where, unknown.What()),
+				unknown.Why(), unknown.Instead())
+			continue
+		}
+		// A kind of problem this does not know the shape of. It still names its
+		// box, and the sentence still arrives whole - an empty why would print
+		// as a bare dash, which is what the first version of this did.
+		p.add(at, fmt.Sprintf("%s: %s", where, bad.Error()), "", "")
 	}
 }