Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

refactor(advisor/tidb): migrate charset/collation/comment family to omni AST (Phase 1.5 §1.5.3 batch 6) (#20217)

Vincent Huang687d723be26e
diff --git a/backend/plugin/advisor/tidb/advisor_charset_allowlist.go b/backend/plugin/advisor/tidb/advisor_charset_allowlist.go
index accdc504b8..9f14166587 100644
--- a/backend/plugin/advisor/tidb/advisor_charset_allowlist.go
+++ b/backend/plugin/advisor/tidb/advisor_charset_allowlist.go
@@ -1,13 +1,11 @@
package tidb
-// Framework code is generated by the generator.
-
import (
"context"
"fmt"
"strings"
- "github.com/pingcap/tidb/pkg/parser/ast"
+ "github.com/bytebase/omni/tidb/ast"
"github.com/bytebase/bytebase/backend/common"
storepb "github.com/bytebase/bytebase/backend/generated-go/store"
@@ -17,21 +15,22 @@ import (
var (
_ advisor.Advisor = (*CharsetAllowlistAdvisor)(nil)
- _ ast.Visitor = (*charsetAllowlistChecker)(nil)
)
func init() {
advisor.Register(storepb.Engine_TIDB, storepb.SQLReviewRule_SYSTEM_CHARSET_ALLOWLIST, &CharsetAllowlistAdvisor{})
}
-// CharsetAllowlistAdvisor is the advisor checking for charset allowlist.
+// CharsetAllowlistAdvisor checks for charset allowlist.
type CharsetAllowlistAdvisor struct {
}
-// Check checks for charset allowlist.
+// Check is Recipe A. Empirically verified safe: EXPLAIN doesn't accept
+// DDL in either pingcap or omni grammar (parse-error before reaching the
+// advisor), and CreateDatabase/CreateTable/AlterDatabase/AlterTable
+// can't nest themselves. No wrapper-statement risk.
func (*CharsetAllowlistAdvisor) Check(_ context.Context, checkCtx advisor.Context) ([]*storepb.Advice, error) {
- stmtList, err := getTiDBNodes(checkCtx)
-
+ stmts, err := getTiDBOmniNodes(checkCtx)
if err != nil {
return nil, err
}
@@ -39,139 +38,142 @@ func (*CharsetAllowlistAdvisor) Check(_ context.Context, checkCtx advisor.Contex
if err != nil {
return nil, err
}
+
stringArrayPayload := checkCtx.Rule.GetStringArrayPayload()
- checker := &charsetAllowlistChecker{
- level: level,
- title: checkCtx.Rule.Type.String(),
- allowlist: make(map[string]bool),
- }
+ allowlist := make(map[string]bool)
for _, charset := range stringArrayPayload.List {
- checker.allowlist[strings.ToLower(charset)] = true
+ allowlist[strings.ToLower(charset)] = true
}
- for _, stmt := range stmtList {
- checker.text = stmt.Text()
- checker.line = stmt.OriginTextPosition()
- (stmt).Accept(checker)
- }
-
- return checker.adviceList, nil
-}
+ title := checkCtx.Rule.Type.String()
+ var adviceList []*storepb.Advice
-type charsetAllowlistChecker struct {
- adviceList []*storepb.Advice
- level storepb.Advice_Status
- title string
- text string
- line int
- allowlist map[string]bool
-}
+ emit := func(text, charset string, line int) {
+ adviceList = append(adviceList, &storepb.Advice{
+ Status: level,
+ Code: advisorcode.DisabledCharset.Int32(),
+ Title: title,
+ Content: fmt.Sprintf("\"%s\" used disabled charset '%s'", text, charset),
+ StartPosition: common.ConvertANTLRLineToPosition(line),
+ })
+ }
-// Enter implements the ast.Visitor interface.
-func (checker *charsetAllowlistChecker) Enter(in ast.Node) (ast.Node, bool) {
- code := advisorcode.Ok
- var disabledCharset string
- line := checker.line
- switch node := in.(type) {
- case *ast.CreateDatabaseStmt:
- charset := getDatabaseCharset(node.Options)
- if _, exist := checker.allowlist[charset]; charset != "" && !exist {
- code = advisorcode.DisabledCharset
- disabledCharset = charset
- }
- case *ast.CreateTableStmt:
- charset := getTableCharset(node.Options)
- if _, exist := checker.allowlist[charset]; charset != "" && !exist {
- code = advisorcode.DisabledCharset
- disabledCharset = charset
- break
- }
- for _, column := range node.Cols {
- charset := getColumnCharset(column)
- if _, exist := checker.allowlist[charset]; charset != "" && !exist {
- code = advisorcode.DisabledCharset
- disabledCharset = charset
- line = column.OriginTextPosition()
- break
+ for _, ostmt := range stmts {
+ text := ostmt.TrimmedText()
+ stmtLine := ostmt.FirstTokenLine()
+ switch n := ostmt.Node.(type) {
+ case *ast.CreateDatabaseStmt:
+ if cs := omniDatabaseOption(n.Options, omniOptionNamesCharset); cs != "" {
+ if _, ok := allowlist[cs]; !ok {
+ emit(text, cs, stmtLine)
+ }
}
- }
- case *ast.AlterDatabaseStmt:
- charset := getDatabaseCharset(node.Options)
- if _, exist := checker.allowlist[charset]; charset != "" && !exist {
- code = advisorcode.DisabledCharset
- disabledCharset = charset
- }
- case *ast.AlterTableStmt:
- for _, spec := range node.Specs {
- switch spec.Tp {
- case ast.AlterTableOption:
- charset := getTableCharset(spec.Options)
- if _, exist := checker.allowlist[charset]; charset != "" && !exist {
- code = advisorcode.DisabledCharset
- disabledCharset = charset
+ case *ast.AlterDatabaseStmt:
+ if cs := omniDatabaseOption(n.Options, omniOptionNamesCharset); cs != "" {
+ if _, ok := allowlist[cs]; !ok {
+ emit(text, cs, stmtLine)
}
- case ast.AlterTableAddColumns:
- for _, column := range spec.NewColumns {
- charset := getColumnCharset(column)
- if _, exist := checker.allowlist[charset]; charset != "" && !exist {
- code = advisorcode.DisabledCharset
- disabledCharset = charset
- break
- }
+ }
+ case *ast.CreateTableStmt:
+ // Table-level charset first; pingcap parity stops at the first
+ // violation per top-level statement (table-level OR column-level,
+ // not both).
+ if cs := omniTableOption(n.Options, omniOptionNamesCharset); cs != "" {
+ if _, ok := allowlist[cs]; !ok {
+ emit(text, cs, stmtLine)
+ continue
+ }
+ }
+ for _, col := range n.Columns {
+ if col == nil {
+ continue
}
- case ast.AlterTableChangeColumn, ast.AlterTableModifyColumn:
- charset := getColumnCharset(spec.NewColumns[0])
- if _, exist := checker.allowlist[charset]; charset != "" && !exist {
- code = advisorcode.DisabledCharset
- disabledCharset = charset
+ cs := omniColumnCharset(col)
+ if cs == "" {
+ continue
+ }
+ if _, ok := allowlist[cs]; !ok {
+ emit(text, cs, ostmt.AbsoluteLine(col.Loc.Start))
+ break
}
- default:
}
- }
- default:
- }
-
- if code != advisorcode.Ok {
- checker.adviceList = append(checker.adviceList, &storepb.Advice{
- Status: checker.level,
- Code: code.Int32(),
- Title: checker.title,
- Content: fmt.Sprintf("\"%s\" used disabled charset '%s'", checker.text, disabledCharset),
- StartPosition: common.ConvertANTLRLineToPosition(line),
- })
- }
-
- return in, false
-}
-
-// Leave implements the ast.Visitor interface.
-func (*charsetAllowlistChecker) Leave(in ast.Node) (ast.Node, bool) {
- return in, true
-}
-
-func getDatabaseCharset(optionList []*ast.DatabaseOption) string {
- for _, option := range optionList {
- if option.Tp == ast.DatabaseOptionCharset {
- return strings.ToLower(option.Value)
- }
- }
-
- return ""
-}
-
-func getTableCharset(optionList []*ast.TableOption) string {
- for _, option := range optionList {
- if option.Tp == ast.TableOptionCharset {
- if option.Default {
- return ""
+ case *ast.AlterTableStmt:
+ // Pingcap parity: a single ALTER TABLE statement emits AT MOST
+ // ONE advice regardless of how many commands violate. Pingcap's
+ // pattern set `code`/`disabledCharset` inside the spec loop
+ // without break, with one append after the loop — multiple
+ // violations overwrite, last violation wins. Mirroring exactly
+ // (Codex P2 round-1 catch on PR #20217).
+ var lastViolation string
+ for _, cmd := range n.Commands {
+ if cmd == nil {
+ continue
+ }
+ switch cmd.Type {
+ case ast.ATTableOption:
+ if cmd.Option == nil {
+ continue
+ }
+ if !omniOptionNameMatches(cmd.Option.Name, omniOptionNamesCharset) {
+ continue
+ }
+ cs := strings.ToLower(cmd.Option.Value)
+ if cs == "" {
+ continue
+ }
+ if _, ok := allowlist[cs]; !ok {
+ lastViolation = cs
+ }
+ case ast.ATConvertCharset:
+ // `ALTER TABLE t CONVERT TO CHARACTER SET cs [COLLATE c]`.
+ // Pingcap parses this as AlterTableOption with the
+ // charset in spec.Options (Tp=TableOptionCharset), so the
+ // pingcap-typed advisor flagged it. Omni splits into
+ // ATConvertCharset with charset on cmd.Name (and optional
+ // collation on cmd.NewName); cmd.Option is nil. Without
+ // this case, mechanical migration silently misses the
+ // CONVERT form (Codex P2 round-2 catch on PR #20217).
+ cs := strings.ToLower(cmd.Name)
+ if cs == "" {
+ continue
+ }
+ if _, ok := allowlist[cs]; !ok {
+ lastViolation = cs
+ }
+ case ast.ATAddColumn:
+ for _, col := range addColumnTargets(cmd) {
+ if col == nil {
+ continue
+ }
+ cs := omniColumnCharset(col)
+ if cs == "" {
+ continue
+ }
+ if _, ok := allowlist[cs]; !ok {
+ lastViolation = cs
+ break // pingcap parity: only first violating column per spec
+ }
+ }
+ case ast.ATChangeColumn, ast.ATModifyColumn:
+ if cmd.Column == nil {
+ continue
+ }
+ cs := omniColumnCharset(cmd.Column)
+ if cs == "" {
+ continue
+ }
+ if _, ok := allowlist[cs]; !ok {
+ lastViolation = cs
+ }
+ default:
+ }
}
- return strings.ToLower(option.StrValue)
+ if lastViolation != "" {
+ emit(text, lastViolation, stmtLine)
+ }
+ default:
}
}
- return ""
-}
-
-func getColumnCharset(column *ast.ColumnDef) string {
- return strings.ToLower(column.Tp.GetCharset())
+ return adviceList, nil
}
diff --git a/backend/plugin/advisor/tidb/advisor_collation_allowlist.go b/backend/plugin/advisor/tidb/advisor_collation_allowlist.go
index 84496dc273..4710be67bd 100644
--- a/backend/plugin/advisor/tidb/advisor_collation_allowlist.go
+++ b/backend/plugin/advisor/tidb/advisor_collation_allowlist.go
@@ -1,13 +1,11 @@
package tidb
-// Framework code is generated by the generator.
-
import (
"context"
"fmt"
"strings"
- "github.com/pingcap/tidb/pkg/parser/ast"
+ "github.com/bytebase/omni/tidb/ast"
"github.com/bytebase/bytebase/backend/common"
storepb "github.com/bytebase/bytebase/backend/generated-go/store"
@@ -17,163 +15,158 @@ import (
var (
_ advisor.Advisor = (*CollationAllowlistAdvisor)(nil)
- _ ast.Visitor = (*collationAllowlistChecker)(nil)
)
func init() {
advisor.Register(storepb.Engine_TIDB, storepb.SQLReviewRule_SYSTEM_COLLATION_ALLOWLIST, &CollationAllowlistAdvisor{})
}
-// CollationAllowlistAdvisor is the advisor checking for collation allowlist.
+// CollationAllowlistAdvisor checks for collation allowlist.
type CollationAllowlistAdvisor struct {
}
-// Check checks for collation allowlist.
+// Check is Recipe A. Same wrapper-safety rationale as
+// CharsetAllowlistAdvisor: EXPLAIN-DDL doesn't parse, the matched stmt
+// types can't nest themselves.
func (*CollationAllowlistAdvisor) Check(_ context.Context, checkCtx advisor.Context) ([]*storepb.Advice, error) {
- stmtList, err := getTiDBNodes(checkCtx)
-
+ stmts, err := getTiDBOmniNodes(checkCtx)
if err != nil {
return nil, err
}
-
level, err := advisor.NewStatusBySQLReviewRuleLevel(checkCtx.Rule.Level)
if err != nil {
return nil, err
}
+
stringArrayPayload := checkCtx.Rule.GetStringArrayPayload()
- checker := &collationAllowlistChecker{
- level: level,
- title: checkCtx.Rule.Type.String(),
- allowlist: make(map[string]bool),
- }
+ allowlist := make(map[string]bool)
for _, collation := range stringArrayPayload.List {
- checker.allowlist[strings.ToLower(collation)] = true
- }
-
- for _, stmt := range stmtList {
- checker.text = stmt.Text()
- checker.line = stmt.OriginTextPosition()
- (stmt).Accept(checker)
+ allowlist[strings.ToLower(collation)] = true
}
- return checker.adviceList, nil
-}
+ title := checkCtx.Rule.Type.String()
+ var adviceList []*storepb.Advice
-type collationAllowlistChecker struct {
- adviceList []*storepb.Advice
- level storepb.Advice_Status
- title string
- text string
- line int
- allowlist map[string]bool
-}
+ emit := func(text, collation string, line int) {
+ adviceList = append(adviceList, &storepb.Advice{
+ Status: level,
+ Code: advisorcode.DisabledCollation.Int32(),
+ Title: title,
+ Content: fmt.Sprintf("\"%s\" used disabled collation '%s'", text, collation),
+ StartPosition: common.ConvertANTLRLineToPosition(line),
+ })
+ }
-// Enter implements the ast.Visitor interface.
-func (checker *collationAllowlistChecker) Enter(in ast.Node) (ast.Node, bool) {
- code := advisorcode.Ok
- var disabledCollation string
- line := checker.line
- switch node := in.(type) {
- case *ast.CreateDatabaseStmt:
- collation := getDatabaseCollation(node.Options)
- if _, exists := checker.allowlist[collation]; collation != "" && !exists {
- code = advisorcode.DisabledCollation
- disabledCollation = collation
- }
- case *ast.CreateTableStmt:
- collation := getTableCollation(node.Options)
- if _, exist := checker.allowlist[collation]; collation != "" && !exist {
- code = advisorcode.DisabledCollation
- disabledCollation = collation
- break
- }
- for _, column := range node.Cols {
- collation := getColumnCollation(column)
- if _, exist := checker.allowlist[collation]; collation != "" && !exist {
- code = advisorcode.DisabledCollation
- disabledCollation = collation
- line = column.OriginTextPosition()
- break
+ for _, ostmt := range stmts {
+ text := ostmt.TrimmedText()
+ stmtLine := ostmt.FirstTokenLine()
+ switch n := ostmt.Node.(type) {
+ case *ast.CreateDatabaseStmt:
+ if c := omniDatabaseOption(n.Options, omniOptionNamesCollate); c != "" {
+ if _, ok := allowlist[c]; !ok {
+ emit(text, c, stmtLine)
+ }
}
- }
- case *ast.AlterDatabaseStmt:
- collation := getDatabaseCollation(node.Options)
- if _, exist := checker.allowlist[collation]; collation != "" && !exist {
- code = advisorcode.DisabledCollation
- disabledCollation = collation
- }
- case *ast.AlterTableStmt:
- for _, spec := range node.Specs {
- switch spec.Tp {
- case ast.AlterTableOption:
- collation := getTableCollation(spec.Options)
- if _, exist := checker.allowlist[collation]; collation != "" && !exist {
- code = advisorcode.DisabledCollation
- disabledCollation = collation
+ case *ast.AlterDatabaseStmt:
+ if c := omniDatabaseOption(n.Options, omniOptionNamesCollate); c != "" {
+ if _, ok := allowlist[c]; !ok {
+ emit(text, c, stmtLine)
}
- case ast.AlterTableAddColumns:
- for _, column := range spec.NewColumns {
- collation := getColumnCollation(column)
- if _, exist := checker.allowlist[collation]; collation != "" && !exist {
- code = advisorcode.DisabledCollation
- disabledCollation = collation
- break
- }
+ }
+ case *ast.CreateTableStmt:
+ if c := omniTableOption(n.Options, omniOptionNamesCollate); c != "" {
+ if _, ok := allowlist[c]; !ok {
+ emit(text, c, stmtLine)
+ continue
+ }
+ }
+ for _, col := range n.Columns {
+ if col == nil {
+ continue
}
- case ast.AlterTableChangeColumn, ast.AlterTableModifyColumn:
- collation := getColumnCollation(spec.NewColumns[0])
- if _, exist := checker.allowlist[collation]; collation != "" && !exist {
- code = advisorcode.DisabledCollation
- disabledCollation = collation
+ c := omniColumnCollate(col)
+ if c == "" {
+ continue
+ }
+ if _, ok := allowlist[c]; !ok {
+ emit(text, c, ostmt.AbsoluteLine(col.Loc.Start))
+ break
}
- default:
- // Other alter table types
}
- }
- default:
- }
-
- if code != advisorcode.Ok {
- checker.adviceList = append(checker.adviceList, &storepb.Advice{
- Status: checker.level,
- Code: code.Int32(),
- Title: checker.title,
- Content: fmt.Sprintf("\"%s\" used disabled collation '%s'", checker.text, disabledCollation),
- StartPosition: common.ConvertANTLRLineToPosition(line),
- })
- }
-
- return in, false
-}
-
-// Leave implements the ast.Visitor interface.
-func (*collationAllowlistChecker) Leave(in ast.Node) (ast.Node, bool) {
- return in, true
-}
-
-func getDatabaseCollation(optionList []*ast.DatabaseOption) string {
- for _, option := range optionList {
- if option.Tp == ast.DatabaseOptionCollate {
- return strings.ToLower(option.Value)
- }
- }
- return ""
-}
-
-func getTableCollation(optionList []*ast.TableOption) string {
- for _, option := range optionList {
- if option.Tp == ast.TableOptionCollate {
- return strings.ToLower(option.StrValue)
+ case *ast.AlterTableStmt:
+ // Pingcap parity: single ALTER TABLE → at most ONE advice. See
+ // the matching comment in advisor_charset_allowlist.go for the
+ // rationale (Codex P2 round-1 catch on PR #20217).
+ var lastViolation string
+ for _, cmd := range n.Commands {
+ if cmd == nil {
+ continue
+ }
+ switch cmd.Type {
+ case ast.ATTableOption:
+ if cmd.Option == nil {
+ continue
+ }
+ if !omniOptionNameMatches(cmd.Option.Name, omniOptionNamesCollate) {
+ continue
+ }
+ c := strings.ToLower(cmd.Option.Value)
+ if c == "" {
+ continue
+ }
+ if _, ok := allowlist[c]; !ok {
+ lastViolation = c
+ }
+ case ast.ATConvertCharset:
+ // `ALTER TABLE t CONVERT TO CHARACTER SET cs COLLATE col`.
+ // Pingcap parses both charset and collation into
+ // spec.Options (Tp=TableOptionCharset / Tp=TableOptionCollate).
+ // Omni splits: charset on cmd.Name, collation on cmd.NewName
+ // (empty if no COLLATE clause). cmd.Option is nil. Without
+ // this case, mechanical migration silently misses the
+ // COLLATE-on-CONVERT form (Codex P2 round-2 catch on
+ // PR #20217).
+ c := strings.ToLower(cmd.NewName)
+ if c == "" {
+ continue
+ }
+ if _, ok := allowlist[c]; !ok {
+ lastViolation = c
+ }
+ case ast.ATAddColumn:
+ for _, col := range addColumnTargets(cmd) {
+ if col == nil {
+ continue
+ }
+ c := omniColumnCollate(col)
+ if c == "" {
+ continue
+ }
+ if _, ok := allowlist[c]; !ok {
+ lastViolation = c
+ break // pingcap parity: only first violating column per spec
+ }
+ }
+ case ast.ATChangeColumn, ast.ATModifyColumn:
+ if cmd.Column == nil {
+ continue
+ }
+ c := omniColumnCollate(cmd.Column)
+ if c == "" {
+ continue
+ }
+ if _, ok := allowlist[c]; !ok {
+ lastViolation = c
+ }
+ default:
+ }
+ }
+ if lastViolation != "" {
+ emit(text, lastViolation, stmtLine)
+ }
+ default:
}
}
- return ""
-}
-func getColumnCollation(column *ast.ColumnDef) string {
- for _, option := range column.Options {
- if option.Tp == ast.ColumnOptionCollate {
- return strings.ToLower(option.StrValue)
- }
- }
- return ""
+ return adviceList, nil
}
diff --git a/backend/plugin/advisor/tidb/advisor_column_comment_convention.go b/backend/plugin/advisor/tidb/advisor_column_comment_convention.go
index 3823b3d399..3f2a22ed24 100644
--- a/backend/plugin/advisor/tidb/advisor_column_comment_convention.go
+++ b/backend/plugin/advisor/tidb/advisor_column_comment_convention.go
@@ -1,13 +1,10 @@
package tidb
-// Framework code is generated by the generator.
-
import (
"context"
"fmt"
- "github.com/pingcap/tidb/pkg/parser/ast"
- "github.com/pingcap/tidb/pkg/parser/format"
+ "github.com/bytebase/omni/tidb/ast"
"github.com/bytebase/bytebase/backend/common"
storepb "github.com/bytebase/bytebase/backend/generated-go/store"
@@ -17,152 +14,130 @@ import (
var (
_ advisor.Advisor = (*ColumnCommentConventionAdvisor)(nil)
- _ ast.Visitor = (*columnCommentConventionChecker)(nil)
)
func init() {
advisor.Register(storepb.Engine_TIDB, storepb.SQLReviewRule_COLUMN_COMMENT, &ColumnCommentConventionAdvisor{})
}
-// ColumnCommentConventionAdvisor is the advisor checking for column comment convention.
+// ColumnCommentConventionAdvisor checks the comment convention for columns.
type ColumnCommentConventionAdvisor struct {
}
-// Check checks for column comment convention.
+// Check is Recipe A. Matches *ast.CreateTableStmt and *ast.AlterTableStmt
+// at top level; neither nests. EXPLAIN-DDL is invalid grammar in both
+// pingcap and omni.
+//
+// Cumulative shape divergence #14: column comment in omni lives in the
+// direct field ColumnDef.Comment (a normalized string), not in
+// column.Options[].Expr as in pingcap. The pingcap-typed advisor needed a
+// fallible restoreNode call (and an internal-error advice path on
+// failure); omni's direct field eliminates both. The internal-error
+// advice path is intentionally removed in this migration — there's no
+// fallible op left to wrap.
func (*ColumnCommentConventionAdvisor) Check(_ context.Context, checkCtx advisor.Context) ([]*storepb.Advice, error) {
- stmtList, err := getTiDBNodes(checkCtx)
-
+ stmts, err := getTiDBOmniNodes(checkCtx)
if err != nil {
return nil, err
}
-
level, err := advisor.NewStatusBySQLReviewRuleLevel(checkCtx.Rule.Level)
if err != nil {
return nil, err
}
- commentPayload := checkCtx.Rule.GetCommentConventionPayload()
- checker := &columnCommentConventionChecker{
- level: level,
- title: checkCtx.Rule.Type.String(),
- payload: commentPayload,
- }
-
- for _, stmt := range stmtList {
- checker.text = stmt.Text()
- checker.line = stmt.OriginTextPosition()
- (stmt).Accept(checker)
- }
-
- return checker.adviceList, nil
-}
-
-type columnCommentConventionChecker struct {
- adviceList []*storepb.Advice
- level storepb.Advice_Status
- title string
- text string
- line int
- payload *storepb.SQLReviewRule_CommentConventionRulePayload
-}
-
-type columnCommentData struct {
- exist bool
- comment string
- table string
- column string
- line int
-}
-
-// Enter implements the ast.Visitor interface.
-func (checker *columnCommentConventionChecker) Enter(in ast.Node) (ast.Node, bool) {
- var columnList []columnCommentData
- switch node := in.(type) {
- case *ast.CreateTableStmt:
- for _, column := range node.Cols {
- exist, comment := checker.columnComment(column)
- columnList = append(columnList, columnCommentData{
- exist: exist,
- comment: comment,
- table: node.Table.Name.O,
- column: column.Name.Name.O,
- line: column.OriginTextPosition(),
- })
- }
- case *ast.AlterTableStmt:
- table := node.Table.Name.O
- for _, spec := range node.Specs {
- switch spec.Tp {
- case ast.AlterTableAddColumns:
- for _, column := range spec.NewColumns {
- exist, comment := checker.columnComment(column)
- columnList = append(columnList, columnCommentData{
- exist: exist,
- comment: comment,
- table: table,
- column: column.Name.Name.O,
- line: checker.line,
- })
+ payload := checkCtx.Rule.GetCommentConventionPayload()
+ title := checkCtx.Rule.Type.String()
+
+ var adviceList []*storepb.Advice
+ for _, ostmt := range stmts {
+ var rows []columnCommentRow
+ switch n := ostmt.Node.(type) {
+ case *ast.CreateTableStmt:
+ if n.Table == nil {
+ continue
+ }
+ tableName := n.Table.Name
+ for _, col := range n.Columns {
+ if col == nil {
+ continue
}
- case ast.AlterTableChangeColumn, ast.AlterTableModifyColumn:
- exist, comment := checker.columnComment(spec.NewColumns[0])
- columnList = append(columnList, columnCommentData{
- exist: exist,
- comment: comment,
- table: table,
- column: spec.NewColumns[0].Name.Name.O,
- line: checker.line,
+ rows = append(rows, columnCommentRow{
+ table: tableName,
+ column: col.Name,
+ exists: omniColumnHasComment(col),
+ comment: col.Comment,
+ line: ostmt.AbsoluteLine(col.Loc.Start),
})
- default:
}
+ case *ast.AlterTableStmt:
+ if n.Table == nil {
+ continue
+ }
+ tableName := n.Table.Name
+ stmtLine := ostmt.FirstTokenLine()
+ for _, cmd := range n.Commands {
+ if cmd == nil {
+ continue
+ }
+ switch cmd.Type {
+ case ast.ATAddColumn:
+ for _, col := range addColumnTargets(cmd) {
+ if col == nil {
+ continue
+ }
+ rows = append(rows, columnCommentRow{
+ table: tableName,
+ column: col.Name,
+ exists: omniColumnHasComment(col),
+ comment: col.Comment,
+ line: stmtLine,
+ })
+ }
+ case ast.ATChangeColumn, ast.ATModifyColumn:
+ if cmd.Column == nil {
+ continue
+ }
+ rows = append(rows, columnCommentRow{
+ table: tableName,
+ column: cmd.Column.Name,
+ exists: omniColumnHasComment(cmd.Column),
+ comment: cmd.Column.Comment,
+ line: stmtLine,
+ })
+ default:
+ }
+ }
+ default:
+ continue
}
- default:
- }
-
- for _, column := range columnList {
- if checker.payload.Required && !column.exist {
- checker.adviceList = append(checker.adviceList, &storepb.Advice{
- Status: checker.level,
- Code: code.CommentEmpty.Int32(),
- Title: checker.title,
- Content: fmt.Sprintf("Column `%s`.`%s` requires comments", column.table, column.column),
- StartPosition: common.ConvertANTLRLineToPosition(column.line),
- })
- }
- if checker.payload.MaxLength >= 0 && int32(len(column.comment)) > checker.payload.MaxLength {
- checker.adviceList = append(checker.adviceList, &storepb.Advice{
- Status: checker.level,
- Code: code.CommentTooLong.Int32(),
- Title: checker.title,
- Content: fmt.Sprintf("The length of column `%s`.`%s` comment should be within %d characters", column.table, column.column, checker.payload.MaxLength),
- StartPosition: common.ConvertANTLRLineToPosition(column.line),
- })
- }
- }
-
- return in, false
-}
-
-// Leave implements the ast.Visitor interface.
-func (*columnCommentConventionChecker) Leave(in ast.Node) (ast.Node, bool) {
- return in, true
-}
-func (checker *columnCommentConventionChecker) columnComment(column *ast.ColumnDef) (bool, string) {
- for _, option := range column.Options {
- if option.Tp == ast.ColumnOptionComment {
- comment, err := restoreNode(option.Expr, format.RestoreStringWithoutCharset)
- if err != nil {
- comment = ""
- checker.adviceList = append(checker.adviceList, &storepb.Advice{
- Status: checker.level,
- Code: code.Internal.Int32(),
- Title: "Internal error for parsing column comment",
- Content: fmt.Sprintf("\"%q\" meet internal error %s", checker.text, err),
+ for _, r := range rows {
+ if payload.Required && !r.exists {
+ adviceList = append(adviceList, &storepb.Advice{
+ Status: level,
+ Code: code.CommentEmpty.Int32(),
+ Title: title,
+ Content: fmt.Sprintf("Column `%s`.`%s` requires comments", r.table, r.column),
+ StartPosition: common.ConvertANTLRLineToPosition(r.line),
+ })
+ }
+ if payload.MaxLength >= 0 && int32(len(r.comment)) > payload.MaxLength {
+ adviceList = append(adviceList, &storepb.Advice{
+ Status: level,
+ Code: code.CommentTooLong.Int32(),
+ Title: title,
+ Content: fmt.Sprintf("The length of column `%s`.`%s` comment should be within %d characters", r.table, r.column, payload.MaxLength),
+ StartPosition: common.ConvertANTLRLineToPosition(r.line),
})
}
- return true, comment
}
}
+ return adviceList, nil
+}
- return false, ""
+type columnCommentRow struct {
+ table string
+ column string
+ exists bool
+ comment string
+ line int
}
diff --git a/backend/plugin/advisor/tidb/advisor_table_comment_convention.go b/backend/plugin/advisor/tidb/advisor_table_comment_convention.go
index e164088838..e1d8c36baa 100644
--- a/backend/plugin/advisor/tidb/advisor_table_comment_convention.go
+++ b/backend/plugin/advisor/tidb/advisor_table_comment_convention.go
@@ -1,12 +1,10 @@
package tidb
-// Framework code is generated by the generator.
-
import (
"context"
"fmt"
- "github.com/pingcap/tidb/pkg/parser/ast"
+ "github.com/bytebase/omni/tidb/ast"
"github.com/bytebase/bytebase/backend/common"
storepb "github.com/bytebase/bytebase/backend/generated-go/store"
@@ -16,92 +14,61 @@ import (
var (
_ advisor.Advisor = (*TableCommentConventionAdvisor)(nil)
- _ ast.Visitor = (*tableCommentConventionChecker)(nil)
)
func init() {
advisor.Register(storepb.Engine_TIDB, storepb.SQLReviewRule_TABLE_COMMENT, &TableCommentConventionAdvisor{})
}
-// TableCommentConventionAdvisor is the advisor checking for table comment convention.
+// TableCommentConventionAdvisor checks the comment convention for tables.
type TableCommentConventionAdvisor struct {
}
-// Check checks for table comment convention.
+// Check is Recipe A. Only matches *ast.CreateTableStmt at top level —
+// CREATE TABLE doesn't nest, and EXPLAIN-DDL is invalid grammar in both
+// pingcap and omni.
func (*TableCommentConventionAdvisor) Check(_ context.Context, checkCtx advisor.Context) ([]*storepb.Advice, error) {
- stmtList, err := getTiDBNodes(checkCtx)
-
+ stmts, err := getTiDBOmniNodes(checkCtx)
if err != nil {
return nil, err
}
-
level, err := advisor.NewStatusBySQLReviewRuleLevel(checkCtx.Rule.Level)
if err != nil {
return nil, err
}
- commentPayload := checkCtx.Rule.GetCommentConventionPayload()
- checker := &tableCommentConventionChecker{
- level: level,
- title: checkCtx.Rule.Type.String(),
- payload: commentPayload,
- }
-
- for _, stmt := range stmtList {
- checker.text = stmt.Text()
- checker.line = stmt.OriginTextPosition()
- (stmt).Accept(checker)
- }
-
- return checker.adviceList, nil
-}
-
-type tableCommentConventionChecker struct {
- adviceList []*storepb.Advice
- level storepb.Advice_Status
- title string
- text string
- line int
- payload *storepb.SQLReviewRule_CommentConventionRulePayload
-}
-
-// Enter implements the ast.Visitor interface.
-func (checker *tableCommentConventionChecker) Enter(in ast.Node) (ast.Node, bool) {
- if node, ok := in.(*ast.CreateTableStmt); ok {
- exist, comment := tableComment(node.Options)
- if checker.payload.Required && !exist {
- checker.adviceList = append(checker.adviceList, &storepb.Advice{
- Status: checker.level,
+ payload := checkCtx.Rule.GetCommentConventionPayload()
+ title := checkCtx.Rule.Type.String()
+
+ var adviceList []*storepb.Advice
+ for _, ostmt := range stmts {
+ n, ok := ostmt.Node.(*ast.CreateTableStmt)
+ if !ok || n.Table == nil {
+ continue
+ }
+ // omni TableOption.Value is the literal comment string (no quotes,
+ // no ESCAPE wrapper); pingcap stored it the same way after restore.
+ // The "exists" signal is the option's presence in the slice, not a
+ // non-empty value (a deliberate empty COMMENT '' is still present).
+ comment, exists := omniTableOptionPresent(n.Options, omniOptionNamesComment)
+ line := ostmt.FirstTokenLine()
+ if payload.Required && !exists {
+ adviceList = append(adviceList, &storepb.Advice{
+ Status: level,
Code: code.CommentEmpty.Int32(),
- Title: checker.title,
- Content: fmt.Sprintf("Table `%s` requires comments", node.Table.Name.O),
- StartPosition: common.ConvertANTLRLineToPosition(checker.line),
+ Title: title,
+ Content: fmt.Sprintf("Table `%s` requires comments", n.Table.Name),
+ StartPosition: common.ConvertANTLRLineToPosition(line),
})
}
- if checker.payload.MaxLength >= 0 && int32(len(comment)) > checker.payload.MaxLength {
- checker.adviceList = append(checker.adviceList, &storepb.Advice{
- Status: checker.level,
+ if payload.MaxLength >= 0 && int32(len(comment)) > payload.MaxLength {
+ adviceList = append(adviceList, &storepb.Advice{
+ Status: level,
Code: code.CommentTooLong.Int32(),
- Title: checker.title,
- Content: fmt.Sprintf("The length of table `%s` comment should be within %d characters", node.Table.Name.O, checker.payload.MaxLength),
- StartPosition: common.ConvertANTLRLineToPosition(checker.line),
+ Title: title,
+ Content: fmt.Sprintf("The length of table `%s` comment should be within %d characters", n.Table.Name, payload.MaxLength),
+ StartPosition: common.ConvertANTLRLineToPosition(line),
})
}
}
-
- return in, false
-}
-
-// Leave implements the ast.Visitor interface.
-func (*tableCommentConventionChecker) Leave(in ast.Node) (ast.Node, bool) {
- return in, true
-}
-
-func tableComment(options []*ast.TableOption) (bool, string) {
- for _, option := range options {
- if option.Tp == ast.TableOptionComment {
- return true, option.StrValue
- }
- }
-
- return false, ""
+ return adviceList, nil
}
diff --git a/backend/plugin/advisor/tidb/test/system_charset_allowlist.yaml b/backend/plugin/advisor/tidb/test/system_charset_allowlist.yaml
index 449633a547..19fd499419 100644
--- a/backend/plugin/advisor/tidb/test/system_charset_allowlist.yaml
+++ b/backend/plugin/advisor/tidb/test/system_charset_allowlist.yaml
@@ -89,3 +89,106 @@
endposition: null
- statement: /* this is a comment */
changeType: 1
+# Cumulative shape divergence #14 pin: omni preserves the user's keyword
+# form on TableOption.Name — `CHARSET ascii` produces Name="CHARSET" and
+# `CHARACTER SET ascii` produces Name="CHARACTER SET" (no canonicalization).
+# Pingcap canonicalized at the enum level (both produced TableOptionCharset).
+# The advisor's accessor matches both forms; this fixture pins the long
+# form (existing fixtures all use CHARSET shorthand).
+- statement: CREATE TABLE t(a int) CHARACTER SET ascii
+ changeType: 1
+ want:
+ - status: 2
+ code: 1001
+ title: SYSTEM_CHARSET_ALLOWLIST
+ content: '"CREATE TABLE t(a int) CHARACTER SET ascii" used disabled charset ''ascii'''
+ startposition:
+ line: 1
+ column: 0
+ endposition: null
+# Pin: column-level scan runs when table-level is in the allowlist.
+# Pingcap parity: if table-level is disabled, "break before column scan"
+# (only one violation reported per top-level stmt). If table-level is OK,
+# column scan must run to find the column-level violation.
+- statement: CREATE TABLE t(a varchar(255) CHARSET ascii) CHARSET utf8mb4
+ changeType: 1
+ want:
+ - status: 2
+ code: 1001
+ title: SYSTEM_CHARSET_ALLOWLIST
+ content: '"CREATE TABLE t(a varchar(255) CHARSET ascii) CHARSET utf8mb4" used disabled charset ''ascii'''
+ startposition:
+ line: 1
+ column: 0
+ endposition: null
+# Cardinality pin (Codex P2 round-1 catch on PR #20217): a single
+# ALTER TABLE statement emits AT MOST ONE advice regardless of how many
+# commands violate. Pingcap's pattern set state inside the spec loop
+# without break, with one append after — multiple violations overwrite,
+# last violation wins. Mirroring exactly. Without this fixture, a future
+# refactor that emits per-command would silently regress.
+- statement: |-
+ CREATE TABLE t(a int);
+ ALTER TABLE t CHARSET ascii, MODIFY COLUMN a VARCHAR(10) CHARSET latin1
+ changeType: 1
+ want:
+ - status: 2
+ code: 1001
+ title: SYSTEM_CHARSET_ALLOWLIST
+ content: '"ALTER TABLE t CHARSET ascii, MODIFY COLUMN a VARCHAR(10) CHARSET latin1" used disabled charset ''latin1'''
+ startposition:
+ line: 2
+ column: 0
+ endposition: null
+# CONVERT TO CHARACTER SET pin (Codex P2 round-2 catch on PR #20217):
+# pingcap parsed `ALTER TABLE t CONVERT TO CHARACTER SET ascii` as
+# AlterTableOption (Tp=1) with the charset in spec.Options, so the
+# pingcap-typed advisor flagged it via its `case ast.AlterTableOption:`.
+# Omni splits this into ATConvertCharset (Type=17), with charset on
+# cmd.Name (and collation on cmd.NewName if specified). cmd.Option is nil.
+# Mechanical migration matching only ATTableOption silently misses the
+# CONVERT form.
+- statement: |-
+ CREATE TABLE t(a int);
+ ALTER TABLE t CONVERT TO CHARACTER SET ascii
+ changeType: 1
+ want:
+ - status: 2
+ code: 1001
+ title: SYSTEM_CHARSET_ALLOWLIST
+ content: '"ALTER TABLE t CONVERT TO CHARACTER SET ascii" used disabled charset ''ascii'''
+ startposition:
+ line: 2
+ column: 0
+ endposition: null
+# DEFAULT-prefix normalization pin (peer review on PR #20217). The
+# DEFAULT keyword in `DEFAULT CHARSET <name>` / `DEFAULT CHARACTER SET
+# <name>` is consumed by omni's parser without affecting the TableOption
+# shape — the resulting Name/Value matches the bare `CHARSET <name>` /
+# `CHARACTER SET <name>` form. The three syntactic variants below
+# produce identical advisor output, locking in the normalization claim
+# that the advisor's name-set (CHARACTER SET / CHARSET) catches all
+# DEFAULT-prefixed forms identically. Pingcap-typed and omni-typed
+# advisors agree: all three flag `ascii`.
+- statement: CREATE TABLE t(a int) DEFAULT CHARSET ascii
+ changeType: 1
+ want:
+ - status: 2
+ code: 1001
+ title: SYSTEM_CHARSET_ALLOWLIST
+ content: '"CREATE TABLE t(a int) DEFAULT CHARSET ascii" used disabled charset ''ascii'''
+ startposition:
+ line: 1
+ column: 0
+ endposition: null
+- statement: CREATE TABLE t(a int) DEFAULT CHARACTER SET ascii
+ changeType: 1
+ want:
+ - status: 2
+ code: 1001
+ title: SYSTEM_CHARSET_ALLOWLIST
+ content: '"CREATE TABLE t(a int) DEFAULT CHARACTER SET ascii" used disabled charset ''ascii'''
+ startposition:
+ line: 1
+ column: 0
+ endposition: null
diff --git a/backend/plugin/advisor/tidb/test/system_collation_allowlist.yaml b/backend/plugin/advisor/tidb/test/system_collation_allowlist.yaml
index a2bd9e7e7d..101190b599 100644
--- a/backend/plugin/advisor/tidb/test/system_collation_allowlist.yaml
+++ b/backend/plugin/advisor/tidb/test/system_collation_allowlist.yaml
@@ -96,3 +96,39 @@
line: 2
column: 0
endposition: null
+# Cardinality pin (Codex P2 round-1 catch on PR #20217): single
+# ALTER TABLE → at most ONE advice. See the matching fixture in
+# system_charset_allowlist.yaml for rationale.
+- statement: |-
+ CREATE TABLE t(a int);
+ ALTER TABLE t COLLATE utf8mb4_polish_ci, MODIFY COLUMN a VARCHAR(10) COLLATE latin1_bin
+ changeType: 1
+ want:
+ - status: 2
+ code: 1201
+ title: SYSTEM_COLLATION_ALLOWLIST
+ content: '"ALTER TABLE t COLLATE utf8mb4_polish_ci, MODIFY COLUMN a VARCHAR(10) COLLATE latin1_bin" used disabled collation ''latin1_bin'''
+ startposition:
+ line: 2
+ column: 0
+ endposition: null
+# CONVERT TO CHARACTER SET pin (Codex P2 round-2 catch on PR #20217):
+# pingcap parsed the COLLATE clause into spec.Options as
+# Tp=TableOptionCollate; pingcap-typed advisor flagged it via
+# `case ast.AlterTableOption:`. Omni splits ATConvertCharset (Type=17)
+# from ATTableOption, with collation on cmd.NewName (charset on cmd.Name).
+# Mechanical migration matching only ATTableOption silently misses the
+# CONVERT form's collation.
+- statement: |-
+ CREATE TABLE t(a int);
+ ALTER TABLE t CONVERT TO CHARACTER SET utf8mb4 COLLATE latin1_bin
+ changeType: 1
+ want:
+ - status: 2
+ code: 1201
+ title: SYSTEM_COLLATION_ALLOWLIST
+ content: '"ALTER TABLE t CONVERT TO CHARACTER SET utf8mb4 COLLATE latin1_bin" used disabled collation ''latin1_bin'''
+ startposition:
+ line: 2
+ column: 0
+ endposition: null
diff --git a/backend/plugin/advisor/tidb/utils.go b/backend/plugin/advisor/tidb/utils.go
index 746572075c..d5409f4491 100644
--- a/backend/plugin/advisor/tidb/utils.go
+++ b/backend/plugin/advisor/tidb/utils.go
@@ -184,6 +184,139 @@ func (s OmniStmt) FirstTokenLine() int {
return s.AbsoluteLine(0)
}
+// AST-shape accessors for omni TableOption / DatabaseOption / ColumnDef.
+//
+// Cumulative shape divergence #14: omni replaces pingcap's
+// `{Tp: enum, StrValue}` model with `{Name: "CANONICAL KEYWORD", Value}`
+// for both Table and Database options. omni normalizes Name to uppercase
+// regardless of user case, but EqualFold is used here for safety. These
+// accessors centralize the lookup so future advisors don't repeat the
+// shape-aware logic.
+
+// omni preserves the user's keyword form on TableOption.Name and
+// DatabaseOption.Name — CHARSET and CHARACTER SET are NOT canonicalized
+// to a single form. Pingcap canonicalized at the enum level (both
+// produced TableOptionCharset / DatabaseOptionCharset). Accessors below
+// take a name-set and match any of them, EqualFold-style. Helps batch
+// authors avoid the silent-regression failure mode where mechanically
+// using only the canonical name misses the shorthand form.
+var (
+ omniOptionNamesCharset = []string{"CHARACTER SET", "CHARSET"}
+ omniOptionNamesCollate = []string{"COLLATE"}
+ omniOptionNamesComment = []string{"COMMENT"}
+)
+
+// omniDatabaseOption returns the lowercased value of the first option
+// whose Name matches any in `names` (case-insensitive), or "" if none
+// match. For case-insensitive identifiers (charset/collation names);
+// user-content values like COMMENT should use *Present variants.
+func omniDatabaseOption(opts []*omniast.DatabaseOption, names []string) string {
+ for _, opt := range opts {
+ if opt == nil {
+ continue
+ }
+ for _, name := range names {
+ if strings.EqualFold(opt.Name, name) {
+ return strings.ToLower(opt.Value)
+ }
+ }
+ }
+ return ""
+}
+
+// omniTableOption returns the lowercased value of the first option whose
+// Name matches any in `names` (case-insensitive), or "" if none match.
+// Case-insensitive-identifier semantics (see omniDatabaseOption).
+func omniTableOption(opts []*omniast.TableOption, names []string) string {
+ for _, opt := range opts {
+ if opt == nil {
+ continue
+ }
+ for _, name := range names {
+ if strings.EqualFold(opt.Name, name) {
+ return strings.ToLower(opt.Value)
+ }
+ }
+ }
+ return ""
+}
+
+// omniTableOptionPresent reports whether any option whose Name matches
+// any in `names` is in the slice; returns its raw value (case preserved —
+// user content). Distinguishes "no clause" from "clause with empty value"
+// (e.g. COMMENT ”).
+func omniTableOptionPresent(opts []*omniast.TableOption, names []string) (string, bool) {
+ for _, opt := range opts {
+ if opt == nil {
+ continue
+ }
+ for _, name := range names {
+ if strings.EqualFold(opt.Name, name) {
+ return opt.Value, true
+ }
+ }
+ }
+ return "", false
+}
+
+// omniOptionNameMatches reports whether `optName` (case-insensitively)
+// matches any name in `names`. Used for single-option checks where the
+// option is already plucked from a slice (e.g. AlterTableCmd.Option).
+func omniOptionNameMatches(optName string, names []string) bool {
+ for _, n := range names {
+ if strings.EqualFold(optName, n) {
+ return true
+ }
+ }
+ return false
+}
+
+// omniColumnCharset returns the column-level CHARACTER SET (lowercased)
+// from ColumnDef.TypeName.Charset. Empty if no clause.
+func omniColumnCharset(col *omniast.ColumnDef) string {
+ if col == nil || col.TypeName == nil {
+ return ""
+ }
+ return strings.ToLower(col.TypeName.Charset)
+}
+
+// omniColumnCollate returns the column-level COLLATE (lowercased) from
+// ColumnDef.TypeName.Collate. Empty if no clause. Note: omni stores
+// column-level COLLATE on the DataType, NOT in Constraints[] — the
+// ColConstrCollate enum value exists but isn't populated by the parser
+// for this form.
+func omniColumnCollate(col *omniast.ColumnDef) string {
+ if col == nil || col.TypeName == nil {
+ return ""
+ }
+ return strings.ToLower(col.TypeName.Collate)
+}
+
+// omniColumnHasComment reports whether the column has a COMMENT clause.
+// The value is in col.Comment, but the "clause was written" signal lives
+// in Constraints[] as ColConstrComment — needed to distinguish
+// "COMMENT ”" (present, empty) from no COMMENT clause at all.
+func omniColumnHasComment(col *omniast.ColumnDef) bool {
+ if col == nil {
+ return false
+ }
+ for _, c := range col.Constraints {
+ if c != nil && c.Type == omniast.ColConstrComment {
+ return true
+ }
+ }
+ return false
+}
+
+// getColumnCharset returns lowercased CHARACTER SET of a pingcap-AST
+// column. Moved here from advisor_charset_allowlist.go during its omni
+// migration; still consumed by advisor_column_disallow_set_charset.go
+// (un-migrated). Delete when that advisor migrates.
+// Tracked: https://linear.app/bytebase/issue/BYT-9412
+func getColumnCharset(column *ast.ColumnDef) string {
+ return strings.ToLower(column.Tp.GetCharset())
+}
+
// addColumnTargets returns the column definitions added by an ATAddColumn
// cmd. omni populates either cmd.Columns (multi-column ADD COLUMN (...))
// or cmd.Column (single ADD COLUMN); read both defensively.
diff --git a/backend/plugin/advisor/tidb/utils_test.go b/backend/plugin/advisor/tidb/utils_test.go
index 701358d587..d667b3e365 100644
--- a/backend/plugin/advisor/tidb/utils_test.go
+++ b/backend/plugin/advisor/tidb/utils_test.go
@@ -246,3 +246,48 @@ func TestRunNamingConventionRuleEmitsInternalErrorAdvice(t *testing.T) {
require.Contains(t, advices[0].Content, "meet internal error",
"content shape preserved from pre-extraction inline form")
}
+
+// TestOmniColumnHasComment_PresentAbsentDistinction pins the structural
+// contract that omniColumnHasComment uses to distinguish "no COMMENT
+// clause" from `COMMENT ”` (deliberately empty). Both produce
+// `ColumnDef.Comment == ""`, so the value field alone is ambiguous; the
+// signal lives in `Constraints[ColConstrComment]`. If a future omni
+// parser change stops emitting the marker for the empty-explicit form,
+// the column-comment-required check would silently treat
+// deliberately-empty comments as missing. This test catches that.
+//
+// Per peer review on PR #20217 — "the structural-marker contract is
+// plausible but unverified for COMMENT ” specifically". Pin it.
+func TestOmniColumnHasComment_PresentAbsentDistinction(t *testing.T) {
+ // Case 1: no COMMENT clause at all → omniColumnHasComment returns false.
+ noCommentCol := &omniast.ColumnDef{
+ Name: "c",
+ Comment: "",
+ Constraints: nil,
+ }
+ require.False(t, omniColumnHasComment(noCommentCol),
+ "absent COMMENT clause: no ColConstrComment marker, omniColumnHasComment must return false")
+
+ // Case 2: explicit COMMENT '' (deliberately empty) → marker present,
+ // value empty. omniColumnHasComment returns true.
+ emptyCommentCol := &omniast.ColumnDef{
+ Name: "c",
+ Comment: "",
+ Constraints: []*omniast.ColumnConstraint{
+ {Type: omniast.ColConstrComment},
+ },
+ }
+ require.True(t, omniColumnHasComment(emptyCommentCol),
+ "explicit COMMENT '' (empty value, marker present): omniColumnHasComment must return true")
+
+ // Case 3: explicit COMMENT 'something' → marker present, value populated.
+ regularCommentCol := &omniast.ColumnDef{
+ Name: "c",
+ Comment: "hello",
+ Constraints: []*omniast.ColumnConstraint{
+ {Type: omniast.ColConstrComment},
+ },
+ }
+ require.True(t, omniColumnHasComment(regularCommentCol),
+ "explicit COMMENT with value: omniColumnHasComment must return true")
+}