fix: hint at correct attribute-level GRANT syntax in parse errors

When users write `GRANT ... (READ "Attr1", "Attr2")` with quoted strings
instead of `READ (Attr1, Attr2)`, the parse error now points at the
correct syntax. Fixes issue #203 where AI agents silently fell back to
`READ *` rather than using fine-grained attribute access.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ako

mdl/visitor/visitor.go

@@ -35,6 +35,16 @@ func (l *errorListener) SyntaxError(_ antlr.Recognizer, _ any, line, column int,
 // enhanceErrorMessage checks if an error message indicates a reserved keyword
 // was used as an identifier and provides a more helpful message.
 func enhanceErrorMessage(msg string) string {
+	// Check for quoted attribute names after READ/WRITE in a GRANT clause.
+	// Users often write `READ "Attr1", "Attr2"` instead of the correct
+	// `READ (Attr1, Attr2)` — the grammar expects unquoted identifiers in parens.
+	if looksLikeQuotedGrantAttribute(msg) {
+		return fmt.Sprintf("%s\n\n  Attribute-level GRANT uses unquoted identifiers inside parentheses,\n"+
+			"  not quoted strings. Comma-separate multiple attributes:\n"+
+			"    GRANT Mod.Role ON Mod.Entity (READ (Attr1, Attr2), WRITE (Attr1));  (correct)\n"+
+			"    GRANT Mod.Role ON Mod.Entity (READ \"Attr1\", \"Attr2\");            (wrong — causes parse error)", msg)
+	}
+
 	// Check for unescaped apostrophe in string literals first.
 	// When 'it's here' is parsed, ANTLR sees 'it' as a complete string, then
 	// the leftover characters (like "s", "ll", "t") appear as unexpected tokens.
@@ -86,6 +96,26 @@ func enhanceErrorMessage(msg string) string {
 	return msg
 }
 
+// looksLikeQuotedGrantAttribute detects ANTLR errors from `READ "Attr"` /
+// `WRITE "Attr"` — a common mistake where users quote attribute names instead
+// of using the correct `READ (Attr1, Attr2)` identifier list.
+//
+// Typical ANTLR shapes:
+//   - no viable alternative at input 'READ"Attr1"'
+//   - no viable alternative at input 'WRITE"Attr1"'
+//   - mismatched input '"Attr"' expecting {CREATE, DELETE, READ, WRITE}
+func looksLikeQuotedGrantAttribute(msg string) bool {
+	if strings.Contains(msg, `input 'READ"`) || strings.Contains(msg, `input 'WRITE"`) {
+		return true
+	}
+	// Quoted string appearing where a GRANT access right is expected.
+	if strings.Contains(msg, `expecting {CREATE, DELETE, READ, WRITE}`) &&
+		(strings.Contains(msg, `input '"`) || strings.Contains(msg, `input "`)) {
+		return true
+	}
+	return false
+}
+
 // looksLikeUnescapedApostrophe detects ANTLR errors that are likely caused by
 // unescaped apostrophes in string literals. When 'don't' is parsed, ANTLR sees
 // 'don' as a complete string, then 't' as an unexpected token, producing errors

mdl/visitor/visitor_test.go

@@ -1111,6 +1111,65 @@ END;`
 	}
 }
 
+func TestEnhanceErrorMessage_QuotedGrantAttribute(t *testing.T) {
+	tests := []struct {
+		name     string
+		msg      string
+		wantHint bool
+	}{
+		{
+			name:     "READ with quoted attribute",
+			msg:      `line 1:51 no viable alternative at input 'READ"Attr1"'`,
+			wantHint: true,
+		},
+		{
+			name:     "WRITE with quoted attribute",
+			msg:      `line 1:75 no viable alternative at input 'WRITE"Attr1"'`,
+			wantHint: true,
+		},
+		{
+			name:     "quoted string where access right expected",
+			msg:      `mismatched input '"Attr2"' expecting {CREATE, DELETE, READ, WRITE}`,
+			wantHint: true,
+		},
+		{
+			name:     "unrelated error does not trigger",
+			msg:      `no viable alternative at input 'CREATE PERSISTENT'`,
+			wantHint: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := enhanceErrorMessage(tt.msg)
+			hasHint := strings.Contains(result, "Attribute-level GRANT")
+			if hasHint != tt.wantHint {
+				t.Errorf("expected hint=%v\n  input:  %s\n  output: %s", tt.wantHint, tt.msg, result)
+			}
+		})
+	}
+}
+
+func TestParseError_QuotedGrantAttribute(t *testing.T) {
+	input := `GRANT Mod.Role ON Mod.Entity (READ "Attr1", "Attr2");`
+	_, errs := Build(input)
+	if len(errs) == 0 {
+		t.Fatal("expected parse errors for quoted GRANT attribute")
+	}
+	found := false
+	for _, err := range errs {
+		if strings.Contains(err.Error(), "Attribute-level GRANT") {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Errorf("expected GRANT-attribute hint in error messages, got:\n")
+		for _, err := range errs {
+			t.Errorf("  %v", err)
+		}
+	}
+}
+
 // TestEnumDefaultQuotedIdentifier verifies that quoted identifiers in enum
 // DEFAULT values are unquoted correctly (issue #11 / BUG-004).
 // e.g. DEFAULT MaisonElegance."FormSubmissionStatus".StatusNew should store