@birthday8/doc-mcp 1.0.2 → 1.0.4

package/python/html_rules.py

@@ -0,0 +1,652 @@
+"""
+HTML验证规则引擎
+面向对象的规则定义和验证系统
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Set, Optional, Any, Callable
+from enum import Enum
+
+
+class Severity(Enum):
+    """严重程度"""
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
+@dataclass
+class ValidationResult:
+    """验证结果"""
+
+    is_valid: bool
+    errors: List[Dict[str, Any]] = field(default_factory=list)
+    warnings: List[Dict[str, Any]] = field(default_factory=list)
+
+    def add_error(self, code: str, message: str, details: Optional[Dict] = None):
+        """添加错误"""
+        self.errors.append({"code": code, "message": message, "details": details or {}})
+        self.is_valid = False
+
+    def add_warning(self, code: str, message: str, details: Optional[Dict] = None):
+        """添加警告"""
+        self.warnings.append(
+            {"code": code, "message": message, "details": details or {}}
+        )
+
+    def to_json(self) -> Dict[str, Any]:
+        """转换为JSON格式"""
+        return {
+            "valid": self.is_valid,
+            "errors": self.errors,
+            "warnings": self.warnings,
+            "summary": {
+                "error_count": len(self.errors),
+                "warning_count": len(self.warnings),
+            },
+        }
+
+
+@dataclass
+class TagRule:
+    """标签规则"""
+
+    tag_name: str
+    allowed: bool
+    description: str = ""
+    required_attrs: Set[str] = field(default_factory=set)
+    optional_attrs: Set[str] = field(default_factory=set)
+    allowed_classes: Set[str] = field(default_factory=set)
+    must_be_self_closing: bool = False
+    allowed_parents: Set[str] = field(default_factory=set)
+    disallowed_parents: Set[str] = field(default_factory=set)
+    allowed_children: Set[str] = field(default_factory=set)
+    disallowed_children: Set[str] = field(default_factory=set)
+    is_block_level: bool = False
+
+    def can_be_child_of(self, parent_tag: str) -> bool:
+        """检查是否可以是某个标签的子元素"""
+        if self.disallowed_parents and parent_tag in self.disallowed_parents:
+            return False
+        if self.allowed_parents and parent_tag not in self.allowed_parents:
+            return False
+        return True
+
+    def can_contain(self, child_tag: str) -> bool:
+        """检查是否可以包含某个子元素"""
+        if self.disallowed_children and child_tag in self.disallowed_children:
+            return False
+        if self.allowed_children and child_tag not in self.allowed_children:
+            return False
+        return True
+
+
+@dataclass
+class AttributeRule:
+    """属性规则"""
+
+    attr_name: str
+    allowed: bool
+    applicable_tags: Set[str] = field(default_factory=set)
+    description: str = ""
+    required_for: Set[str] = field(default_factory=set)
+    validator: Optional[Callable[[str], bool]] = None
+    default_value: Optional[str] = None
+    enum_values: Optional[List[str]] = None
+
+    def is_applicable_to(self, tag: str) -> bool:
+        """检查属性是否适用于某个标签"""
+        return not self.applicable_tags or tag in self.applicable_tags
+
+
+@dataclass
+class StyleRule:
+    """样式规则"""
+
+    style_name: str
+    allowed: bool
+    applicable_tags: Set[str] = field(default_factory=set)
+    description: str = ""
+    validator: Optional[Callable[[str], bool]] = None
+    unit_required: Optional[str] = None
+    enum_values: Optional[List[str]] = None
+
+    def is_applicable_to(self, tag: str) -> bool:
+        """检查样式是否适用于某个标签"""
+        return not self.applicable_tags or tag in self.applicable_tags
+
+    def validate_value(self, value: str) -> tuple[bool, Optional[str]]:
+        """验证样式值"""
+        if self.validator:
+            try:
+                result = self.validator(value)
+                if isinstance(result, tuple):
+                    return result
+                elif isinstance(result, bool):
+                    return result, None
+                else:
+                    return False, f"验证失败: {result}"
+            except Exception as e:
+                return False, f"验证错误: {str(e)}"
+
+        if self.enum_values and value not in self.enum_values:
+            return False, f"必须是以下值之一: {', '.join(self.enum_values)}"
+
+        if self.unit_required and not value.endswith(self.unit_required):
+            return False, f"单位必须是 {self.unit_required}"
+
+        return True, None
+
+
+class RuleEngine:
+    """规则引擎"""
+
+    def __init__(self):
+        self.tag_rules: Dict[str, TagRule] = {}
+        self.attr_rules: Dict[str, AttributeRule] = {}
+        self.style_rules: Dict[str, StyleRule] = {}
+        self._initialize_rules()
+
+    def _initialize_rules(self):
+        """初始化所有规则"""
+        self._init_tag_rules()
+        self._init_attribute_rules()
+        self._init_style_rules()
+
+    def _init_tag_rules(self):
+        """初始化标签规则"""
+        # 结构标签（HTML文档结构）
+        structure_tags = {"html", "head", "body", "meta", "title", "style"}
+
+        # 块级元素
+        block_tags = {
+            "h1",
+            "h2",
+            "h3",
+            "h4",
+            "h5",
+            "h6",
+            "p",
+            "div",
+            "ul",
+            "ol",
+            "table",
+            "blockquote",
+            "pre",
+        }
+
+        # 表格相关
+        table_tags = {"thead", "tbody", "tfoot"}
+
+        # 行内元素
+        inline_tags = {"strong", "em", "u", "s", "sup", "sub", "code", "span"}
+
+        # 自闭合标签
+        self_closing_tags = {"img", "br", "hr", "meta"}
+
+        # 允许的标签列表
+        allowed_tags = (
+            structure_tags
+            | block_tags
+            | table_tags
+            | inline_tags
+            | self_closing_tags
+            | {"li", "tr", "td", "th", "math", "latex"}
+        )
+
+        # 创建标签规则
+        for tag in allowed_tags:
+            self.tag_rules[tag] = TagRule(
+                tag_name=tag,
+                allowed=True,
+                description=f"{tag} 标签",
+                must_be_self_closing=tag in self_closing_tags,
+                is_block_level=tag in block_tags,
+            )
+
+        # 特殊规则：段落不能包含块级元素
+        self.tag_rules["p"].disallowed_children = block_tags
+
+        # 特殊规则：table只能包含tr
+        self.tag_rules["table"].allowed_children = {"tr"}
+
+        # 特殊规则：tr只能包含td或th
+        self.tag_rules["tr"].allowed_children = {"td", "th"}
+
+        # 特殊规则：li可以包含ul或ol（嵌套列表）
+        self.tag_rules["li"].allowed_children = {"ul", "ol"}
+
+        # 特殊规则：blockquote可以嵌套
+        self.tag_rules["blockquote"].allowed_children = {
+            "blockquote",
+            "p",
+            "div",
+        } | inline_tags
+
+        # 特殊规则：table可以包含thead, tbody, tfoot
+        self.tag_rules["table"].allowed_children = {"thead", "tbody", "tfoot", "tr"}
+
+        # 特殊规则：thead, tbody, tfoot只能包含tr
+        for tag in ["thead", "tbody", "tfoot"]:
+            if tag in self.tag_rules:
+                self.tag_rules[tag].allowed_children = {"tr"}
+
+    def _init_attribute_rules(self):
+        """初始化属性规则"""
+        # 图片属性
+        self.attr_rules["src"] = AttributeRule(
+            attr_name="src",
+            allowed=True,
+            applicable_tags={"img"},
+            description="图片源路径",
+            required_for={"img"},
+        )
+
+        self.attr_rules["alt"] = AttributeRule(
+            attr_name="alt",
+            allowed=True,
+            applicable_tags={"img"},
+            description="图片替代文本",
+        )
+
+        self.attr_rules["width"] = AttributeRule(
+            attr_name="width",
+            allowed=True,
+            applicable_tags={"img", "td", "th"},
+            description="宽度（像素）",
+            validator=lambda x: x.lstrip("-").isdigit(),
+        )
+
+        self.attr_rules["height"] = AttributeRule(
+            attr_name="height",
+            allowed=True,
+            applicable_tags={"img", "td", "th"},
+            description="高度（像素）",
+            validator=lambda x: x.lstrip("-").isdigit(),
+        )
+
+        self.attr_rules["align"] = AttributeRule(
+            attr_name="align",
+            allowed=True,
+            applicable_tags={"img"},
+            description="对齐方式",
+            enum_values=["left", "center", "right"],
+        )
+
+        # 表格属性
+        self.attr_rules["colspan"] = AttributeRule(
+            attr_name="colspan",
+            allowed=True,
+            applicable_tags={"td", "th"},
+            description="跨列数",
+            validator=lambda x: x.lstrip("-").isdigit(),
+        )
+
+        self.attr_rules["rowspan"] = AttributeRule(
+            attr_name="rowspan",
+            allowed=True,
+            applicable_tags={"td", "th"},
+            description="跨行数",
+            validator=lambda x: x.lstrip("-").isdigit(),
+        )
+
+        # 多栏布局
+        self.attr_rules["data-cols"] = AttributeRule(
+            attr_name="data-cols",
+            allowed=True,
+            applicable_tags={"div"},
+            description="栏数",
+            validator=lambda x: x.lstrip("-").isdigit(),
+        )
+
+        # 缩进
+        self.attr_rules["data-indent"] = AttributeRule(
+            attr_name="data-indent",
+            allowed=True,
+            applicable_tags={"p", "div"},
+            description="缩进级别",
+            validator=lambda x: x.lstrip("-").isdigit(),
+        )
+
+        # HTML属性
+        self.attr_rules["lang"] = AttributeRule(
+            attr_name="lang",
+            allowed=True,
+            applicable_tags={"html"},
+            description="语言",
+            enum_values=["zh-CN", "en", "en-US"],
+        )
+
+        self.attr_rules["charset"] = AttributeRule(
+            attr_name="charset",
+            allowed=True,
+            applicable_tags={"meta"},
+            description="字符编码",
+            enum_values=["UTF-8", "utf-8"],
+        )
+
+        self.attr_rules["name"] = AttributeRule(
+            attr_name="name",
+            allowed=True,
+            applicable_tags={"meta"},
+            description="元数据名称",
+        )
+
+        self.attr_rules["content"] = AttributeRule(
+            attr_name="content",
+            allowed=True,
+            applicable_tags={"meta"},
+            description="元数据内容",
+        )
+
+        # 通用属性
+        self.attr_rules["class"] = AttributeRule(
+            attr_name="class",
+            allowed=True,
+            applicable_tags={
+                "p",
+                "div",
+                "span",
+                "table",
+                "td",
+                "th",
+                "ul",
+                "ol",
+                "li",
+                "h1",
+                "h2",
+                "h3",
+                "h4",
+                "h5",
+                "h6",
+            },
+            description="CSS类名",
+        )
+
+        self.attr_rules["style"] = AttributeRule(
+            attr_name="style",
+            allowed=True,
+            applicable_tags={
+                "h1",
+                "h2",
+                "h3",
+                "h4",
+                "h5",
+                "h6",
+                "p",
+                "div",
+                "span",
+                "strong",
+                "em",
+                "u",
+                "s",
+                "sup",
+                "sub",
+                "code",
+                "table",
+                "tr",
+                "td",
+                "th",
+                "ul",
+                "ol",
+                "li",
+                "blockquote",
+                "pre",
+            },
+            description="内联样式",
+        )
+
+    def _init_style_rules(self):
+        """初始化样式规则"""
+
+        # 颜色样式
+        def validate_color(value: str) -> tuple[bool, Optional[str]]:
+            """验证颜色格式"""
+            if not value.startswith("#"):
+                return False, "颜色必须使用十六进制格式 #RRGGBB"
+            if len(value) != 7:
+                return False, "颜色必须是6位十六进制 #RRGGBB"
+            try:
+                int(value[1:], 16)
+                return True, None
+            except ValueError:
+                return False, "无效的十六进制颜色"
+
+        self.style_rules["color"] = StyleRule(
+            style_name="color",
+            allowed=True,
+            description="文本颜色",
+            validator=validate_color,
+        )
+
+        self.style_rules["background-color"] = StyleRule(
+            style_name="background-color",
+            allowed=True,
+            description="背景颜色",
+            validator=validate_color,
+        )
+
+        # 字体样式
+        self.style_rules["font-family"] = StyleRule(
+            style_name="font-family",
+            allowed=True,
+            description="支持任意系统已安装的字体",
+        )
+
+        self.style_rules["font-size"] = StyleRule(
+            style_name="font-size",
+            allowed=True,
+            description="字体大小",
+            unit_required="pt",
+            validator=lambda x: x.endswith("pt") and x[:-2].lstrip("-").isdigit(),
+        )
+
+        self.style_rules["font-weight"] = StyleRule(
+            style_name="font-weight",
+            allowed=True,
+            description="字体粗细",
+            enum_values=[
+                "normal",
+                "bold",
+                "bolder",
+                "lighter",
+                "100",
+                "200",
+                "300",
+                "400",
+                "500",
+                "600",
+                "700",
+                "800",
+                "900",
+            ],
+        )
+
+        self.style_rules["font-style"] = StyleRule(
+            style_name="font-style",
+            allowed=True,
+            description="字体样式",
+            enum_values=["normal", "italic", "oblique"],
+        )
+
+        # 文本装饰
+        self.style_rules["text-decoration"] = StyleRule(
+            style_name="text-decoration",
+            allowed=True,
+            description="文本装饰",
+            enum_values=["none", "underline", "overline", "line-through", "blink"],
+        )
+
+        # 段落样式
+        self.style_rules["text-align"] = StyleRule(
+            style_name="text-align",
+            allowed=True,
+            description="文本对齐",
+            enum_values=["left", "center", "right", "justify"],
+        )
+
+        self.style_rules["line-height"] = StyleRule(
+            style_name="line-height",
+            allowed=True,
+            description="行高",
+            validator=lambda x: x.replace(".", "", 1).isdigit(),
+        )
+
+        # 边距
+        margin_padding_styles = [
+            "margin-top",
+            "margin-bottom",
+            "margin-left",
+            "margin-right",
+            "padding-top",
+            "padding-bottom",
+            "padding-left",
+            "padding-right",
+        ]
+
+        for style_name in margin_padding_styles:
+            self.style_rules[style_name] = StyleRule(
+                style_name=style_name,
+                allowed=True,
+                description=f"{style_name.replace('-', ' ')}",
+                unit_required="pt",
+                validator=lambda x: (x.endswith("pt") or x.endswith("px"))
+                and x[:-2].lstrip("-").isdigit(),
+            )
+
+        # 表格样式
+        table_styles = ["width", "border-collapse", "margin", "border", "padding"]
+        for style_name in table_styles:
+            self.style_rules[style_name] = StyleRule(
+                style_name=style_name,
+                allowed=True,
+                description=f"表格样式: {style_name}",
+            )
+
+    def get_tag_rule(self, tag_name: str) -> Optional[TagRule]:
+        """获取标签规则"""
+        return self.tag_rules.get(tag_name)
+
+    def get_attribute_rule(self, attr_name: str) -> Optional[AttributeRule]:
+        """获取属性规则"""
+        return self.attr_rules.get(attr_name)
+
+    def get_style_rule(self, style_name: str) -> Optional[StyleRule]:
+        """获取样式规则"""
+        return self.style_rules.get(style_name)
+
+    def is_tag_allowed(self, tag_name: str) -> bool:
+        """检查标签是否允许"""
+        rule = self.get_tag_rule(tag_name)
+        return rule is not None and rule.allowed
+
+    def is_attribute_allowed(self, attr_name: str, tag_name: str) -> bool:
+        """检查属性是否允许"""
+        rule = self.get_attribute_rule(attr_name)
+        if not rule or not rule.allowed:
+            return False
+        return rule.is_applicable_to(tag_name)
+
+    def is_style_allowed(self, style_name: str, tag_name: str) -> bool:
+        """检查样式是否允许"""
+        rule = self.get_style_rule(style_name)
+        if not rule or not rule.allowed:
+            return False
+        return rule.is_applicable_to(tag_name)
+
+    def is_nesting_allowed(self, parent_tag: str, child_tag: str) -> bool:
+        """检查嵌套是否允许"""
+        parent_rule = self.get_tag_rule(parent_tag)
+        child_rule = self.get_tag_rule(child_tag)
+
+        if not parent_rule or not child_rule:
+            return False
+
+        # 检查父标签是否允许包含子标签
+        if not parent_rule.can_contain(child_tag):
+            return False
+
+        # 检查子标签是否可以是父标签的子元素
+        if not child_rule.can_be_child_of(parent_tag):
+            return False
+
+        return True
+
+    def is_self_closing_tag(self, tag_name: str) -> bool:
+        """检查标签是否是自闭合标签"""
+        rule = self.get_tag_rule(tag_name)
+        if not rule:
+            return False
+        return rule.must_be_self_closing
+
+    def get_disallowed_tags(self) -> List[Dict[str, str]]:
+        """获取所有不允许的标签（用于文档说明）"""
+        return [
+            {"tag": tag, "reason": "不在允许列表中"}
+            for tag in [
+                "script",
+                "style",
+                "iframe",
+                "form",
+                "input",
+                "button",
+                "select",
+                "textarea",
+                "a",
+                "canvas",
+                "video",
+                "audio",
+            ]
+        ]
+
+    def get_disallowed_attributes(self) -> List[Dict[str, str]]:
+        """获取所有不允许的属性（用于文档说明）"""
+        return [
+            {"attr": attr, "reason": "不在允许列表中"}
+            for attr in [
+                "onclick",
+                "onload",
+                "onerror",
+                "class",
+                "id",
+                "style",
+                "loading",
+                "float",
+                "position",
+                "display",
+                "transform",
+            ]
+        ]
+
+    def get_disallowed_styles(self) -> List[Dict[str, str]]:
+        """获取所有不允许的样式（用于文档说明）"""
+        return [
+            {"style": style, "reason": "不在允许列表中"}
+            for style in [
+                "float",
+                "text-shadow",
+                "display",
+                "transform",
+                "position",
+                "opacity",
+                "overflow",
+                "visibility",
+                "z-index",
+            ]
+        ]
+
+
+# 延迟创建全局实例
+_rule_engine_instance = None
+
+
+def get_rule_engine():
+    """获取规则引擎单例"""
+    global _rule_engine_instance
+    if _rule_engine_instance is None:
+        _rule_engine_instance = RuleEngine()
+    return _rule_engine_instance
+
+
+# 向后兼容的全局实例
+rule_engine = get_rule_engine()