doc

type CustomValidator func(node *JsonMLNode, attrs map[string]any, schema *TagSchema, emit func(Diagnostic))

type Diagnostic struct {
	Range      Range              // 源位置
	Severity   Severity           // 严重程度
	Code       string             // 错误码 (见 error code 常量)
	Source     string             // "json-syntax" | "jsonml-grammar" | "jsonml-schema"
	Message    string             // 人可读描述
	Suggestion string             // 可粘贴的最小合法片段 (可选)
	Context    *DiagnosticContext // schema 上下文 (可选, Layer 2 填充)
}

type DiagnosticContext struct {
	TagName         string    // 当前/期望 tag
	Description     string    // P1: tag description from schema
	AllowedChildren []string  // 父节点合法子节点全集
	AllValidTags    []string  // schema 全量 tag 列表（unknown tag 时填充）
	AllValidAttrs   []string  // 当前 tag 全量 attr 列表（unknown attr 时填充）
	AttrSpec        *TypeSpec // 当前属性的 schema 定义
}

type DiagnosticList []Diagnostic

type JsonMLDocument struct {
	Nodes       []*JsonMLNode  // 顶层节点列表
	Source      []byte         // 原始输入
	Diagnostics DiagnosticList // Layer 0 + Layer 1 诊断
}

type JsonMLNode struct {
	Tag      string         // tag 名称（IsText 时为空）
	Attrs    map[string]any // 属性 map（无 attrs 时为 nil）
	Children []*JsonMLNode  // 子节点列表
	Text     string         // 文本内容（仅 IsText == true 时有值）

	IsText  bool // true = 文本节点
	IsError bool // true = 错误占位节点 (error recovery 产生)

	Range    Range // 整个节点的源位置
	TagRange Range // tag string 的源位置
}

type JsonMLValidationResult struct {
	Errors   []string
	Warnings []string
}

type Lexer struct {
	// contains filtered or unexported fields
}

type Position struct {
	Line   int   // 1-based 行号
	Col    int   // 1-based 列号 (UTF-8 byte offset within line)
	Offset int64 // 0-based 字节偏移 (相对于整个输入)
}

type Range struct {
	Start Position
	End   Position
}

type SchemaV2 struct {
	Version     string                `json:"_version"`
	Description string                `json:"_description"`
	Tags        map[string]*TagSchema `json:"tags"`
	// contains filtered or unexported fields
}

type Severity int

type TagSchema struct {
	AllowedChildren []string            `json:"allowed_children"`
	Attrs           map[string]TypeSpec `json:"attrs"`
	Aliases         map[string]string   `json:"aliases,omitempty"`     // P1: aliasName → canonicalAttrName
	Description     string              `json:"description,omitempty"` // P1: tag description for diagnostics
	// contains filtered or unexported fields
}

type Token struct {
	Kind  TokenKind
	Value []byte // 原始字节（string 含引号, number 含原始文本）
	Range Range  // 精确源位置
}

type TokenKind int

type TypeSpec struct {
	Type      string              `json:"type"`                 // string|number|boolean|array|object|any|enum|union
	Min       *float64            `json:"min,omitempty"`        // for number
	Max       *float64            `json:"max,omitempty"`        // for number
	Values    []string            `json:"values,omitempty"`     // for enum
	Types     []string            `json:"types,omitempty"`      // for union: pass silently
	WarnTypes []string            `json:"warn_types,omitempty"` // for union: match → warning (not error)
	Fields    map[string]TypeSpec `json:"fields,omitempty"`     // for object (deep validation)
	// P1:
	Required   bool `json:"required,omitempty"`   // mandatory attribute marker
	Deprecated bool `json:"deprecated,omitempty"` // deprecated attribute marker
}