OVAPortableText 0.1.0__py3-none-any.whl

ova_portable_text/validator.py

@@ -0,0 +1,511 @@
+from __future__ import annotations
+
+"""
+Document validation for OVAPortableText.
+OVAPortableText 的文档校验器。
+
+This validator intentionally stays close to the protocol's v1 guidance:
+本校验器刻意贴近协议 v1 的建议：
+- schemaVersion must exist / `schemaVersion` 必填
+- sections/body structure must be valid / `sections` 与 `body` 结构必须合法
+- top-level registries should exist / 顶层 registry 应存在
+- section nesting levels should be self-consistent / section 层级应自洽
+- all references should resolve / 所有引用应能解析
+- formal heading styles should not appear inside content.blocks
+  `content.blocks` 中不应出现正式标题样式
+
+Step 8 improves the *quality* of validation output:
+第 8 步重点提升的是校验输出质量：
+- richer issue context / 更丰富的 issue 上下文
+- better maintenance hints / 更明确的维护提示
+- readable report summaries / 更易读的报告摘要
+"""
+
+from .block_objects import CalloutBlock, ChartBlock, ImageBlock, TableBlock
+from .content import ALLOWED_TEXT_STYLES, ContentItem, Span, TextBlock
+from .document import Document
+from .exceptions import ValidationReport
+from .inline import CitationRef, FootnoteRef, GlossaryTerm, XRef
+from .registry import BibliographyEntry, FootnoteEntry, GlossaryEntry
+from .resolver import DocumentResolver, ResolvedTarget
+from .section import Section, SubsectionItem
+
+ALLOWED_DECORATOR_MARKS = {"strong", "em", "underline", "code"}
+
+
+def validate_document(document: Document) -> ValidationReport:
+    """
+    Validate the whole document and return a structured report.
+    校验整份文档，并返回结构化报告。
+    """
+    report = ValidationReport()
+
+    if not document.schemaVersion:
+        report.add_issue(
+            code="missing_schema_version",
+            message="`schemaVersion` is required.",
+            path="schemaVersion",
+            contextType="document",
+            suggestion="Set `schemaVersion` to `report.v1` unless you intentionally target another protocol version.",
+        )
+
+    if not isinstance(document.sections, list):
+        report.add_issue(
+            code="invalid_sections",
+            message="`sections` must be a list.",
+            path="sections",
+            contextType="document",
+            suggestion="Top-level `sections` should always be present, even when empty.",
+        )
+        return report
+
+    for index, section in enumerate(document.sections):
+        _validate_section(section, path=f"sections[{index}]", parent_level=None, report=report)
+
+    _validate_bibliography(document.bibliography, report=report)
+    _validate_footnotes(document.footnotes, report=report)
+    _validate_glossary(document.glossary, report=report)
+
+    resolver = document.build_resolver()
+
+    for duplicate_id, targets in resolver.duplicates.items():
+        locations = ", ".join(target.location for target in targets)
+        first = targets[0]
+        report.add_issue(
+            code="duplicate_id",
+            message=f"Duplicate global id detected: {duplicate_id!r}. Locations: {locations}",
+            contextType="global_id",
+            contextId=duplicate_id,
+            sectionId=first.sectionId,
+            sectionTitle=first.sectionTitle,
+            suggestion="Keep each globally resolvable object's `id` unique across the whole document.",
+        )
+
+    for anchor, targets in resolver.duplicateAnchors.items():
+        locations = ", ".join(target.location for target in targets)
+        first = targets[0]
+        report.add_issue(
+            code="duplicate_anchor",
+            message=f"Duplicate anchor detected: {anchor!r}. Locations: {locations}",
+            severity="warning",
+            contextType="anchor",
+            contextAnchor=anchor,
+            sectionId=first.sectionId,
+            sectionTitle=first.sectionTitle,
+            suggestion="Prefer globally unique anchors if the renderer will support page jumps or bookmarks.",
+        )
+
+    for index, section in enumerate(document.sections):
+        _validate_section_references(section, path=f"sections[{index}]", resolver=resolver, report=report)
+
+    return report
+
+
+def assert_valid_document(document: Document) -> Document:
+    """
+    Validate and raise on errors.
+    校验文档；若存在 error 则抛错。
+    """
+    validate_document(document).raise_for_errors()
+    return document
+
+
+def _ctx(
+    *,
+    section: Section | None = None,
+    context_type: str | None = None,
+    context_id: str | None = None,
+    context_anchor: str | None = None,
+    suggestion: str | None = None,
+    location: str | None = None,
+) -> dict[str, str | None]:
+    """
+    Build common context kwargs for `ValidationReport.add_issue()`.
+    为 `ValidationReport.add_issue()` 构建通用上下文参数。
+
+    This helper keeps the validator code readable while still attaching
+    rich issue context.
+    这个 helper 的意义是：
+    既让校验器代码保持可读，又能给 issue 挂上较丰富的上下文信息。
+    """
+    return {
+        "location": location,
+        "contextType": context_type,
+        "contextId": context_id,
+        "contextAnchor": context_anchor,
+        "sectionId": section.id if section else None,
+        "sectionTitle": section.title if section else None,
+        "suggestion": suggestion,
+    }
+
+
+def _ctx_from_target(target: ResolvedTarget, *, suggestion: str | None = None) -> dict[str, str | None]:
+    """
+    Build context kwargs from a resolved target.
+    根据 resolver target 构建上下文参数。
+    """
+    return {
+        "location": target.location,
+        "contextType": target.targetType,
+        "contextId": target.id,
+        "contextAnchor": target.anchor,
+        "sectionId": target.sectionId,
+        "sectionTitle": target.sectionTitle,
+        "suggestion": suggestion,
+    }
+
+
+def _validate_section(section: Section, *, path: str, parent_level: int | None, report: ValidationReport) -> None:
+    if not isinstance(section.body, list):
+        report.add_issue(
+            code="invalid_section_body",
+            message="Section `body` must be a list.",
+            path=f"{path}.body",
+            **_ctx(section=section, context_type="section", context_id=section.id, context_anchor=section.anchor, location=f"{path}.body", suggestion="Set `body` to an array of `content` / `subsection` items."),
+        )
+        return
+
+    if parent_level is None:
+        if section.level < 1:
+            report.add_issue(
+                code="invalid_top_section_level",
+                message=f"Top-level section level should be >= 1. Got {section.level}.",
+                path=f"{path}.level",
+                **_ctx(section=section, context_type="section", context_id=section.id, context_anchor=section.anchor, location=f"{path}.level", suggestion="Top-level sections are normally level 1."),
+            )
+    elif section.level != parent_level + 1:
+        report.add_issue(
+            code="invalid_section_level",
+            message=f"Child section level should be parent level + 1. Got parent={parent_level}, child={section.level}.",
+            path=f"{path}.level",
+            **_ctx(section=section, context_type="section", context_id=section.id, context_anchor=section.anchor, location=f"{path}.level", suggestion="Keep formal subsections strictly aligned with the section tree, instead of using heading-like text styles."),
+        )
+
+    for body_index, item in enumerate(section.body):
+        item_path = f"{path}.body[{body_index}]"
+        if item.itemType not in {"content", "subsection"}:
+            report.add_issue(
+                code="invalid_body_item_type",
+                message=f"Unsupported body itemType: {item.itemType!r}",
+                path=f"{item_path}.itemType",
+                **_ctx(section=section, context_type="body_item", location=f"{item_path}.itemType", suggestion="Use `itemType = \"content\"` or `itemType = \"subsection\"`."),
+            )
+
+        if isinstance(item, ContentItem):
+            if not isinstance(item.blocks, list):
+                report.add_issue(
+                    code="invalid_content_blocks",
+                    message="`content.blocks` must be a list.",
+                    path=f"{item_path}.blocks",
+                    **_ctx(section=section, context_type="content", location=f"{item_path}.blocks", suggestion="Wrap consecutive content blocks in an array."),
+                )
+                continue
+            for block_index, block in enumerate(item.blocks):
+                block_path = f"{item_path}.blocks[{block_index}]"
+                if isinstance(block, TextBlock):
+                    _validate_text_block_structure(block, path=block_path, section=section, report=report)
+        elif isinstance(item, SubsectionItem):
+            _validate_section(item.section, path=f"{item_path}.section", parent_level=section.level, report=report)
+
+
+def _validate_text_block_structure(block: TextBlock, *, path: str, section: Section | None, report: ValidationReport) -> None:
+    if block.style not in ALLOWED_TEXT_STYLES:
+        report.add_issue(
+            code="invalid_text_style",
+            message=f"Unsupported text block style: {block.style!r}",
+            path=f"{path}.style",
+            **_ctx(section=section, context_type="text_block", location=f"{path}.style", suggestion="Use one of the protocol-approved text styles only."),
+        )
+
+    if block.style in {"h1", "h2", "h3", "h4"}:
+        report.add_issue(
+            code="forbidden_heading_style",
+            message="Formal heading styles h1/h2/h3/h4 must not appear in `content.blocks`.",
+            path=f"{path}.style",
+            **_ctx(section=section, context_type="text_block", location=f"{path}.style", suggestion="Use formal `Section` / `subsection` nodes for document structure, and reserve text styles like `subheading` for in-body visual grouping."),
+        )
+
+    if block.listItem is None and block.level is not None:
+        report.add_issue(
+            code="invalid_list_level_without_list_item",
+            message="`level` must not appear without `listItem`.",
+            path=f"{path}.level",
+            **_ctx(section=section, context_type="text_block", location=f"{path}.level", suggestion="Set both `listItem` and `level`, or remove `level`."),
+        )
+
+    if block.level is not None and block.level < 1:
+        report.add_issue(
+            code="invalid_list_level",
+            message="Text block list level must be >= 1.",
+            path=f"{path}.level",
+            **_ctx(section=section, context_type="text_block", location=f"{path}.level", suggestion="List nesting is 1-based in this package."),
+        )
+
+    mark_def_keys: set[str] = set()
+    for mark_def_index, mark_def in enumerate(block.markDefs):
+        if mark_def.key in mark_def_keys:
+            report.add_issue(
+                code="duplicate_mark_def_key",
+                message=f"Duplicate markDef key in the same block: {mark_def.key!r}",
+                path=f"{path}.markDefs[{mark_def_index}]._key",
+                **_ctx(section=section, context_type="text_block", location=f"{path}.markDefs[{mark_def_index}]", suggestion="Keep each markDef key unique within one text block."),
+            )
+        mark_def_keys.add(mark_def.key)
+
+    for child_index, child in enumerate(block.children):
+        if not isinstance(child, Span):
+            continue
+        for mark_index, mark in enumerate(child.marks):
+            if mark not in ALLOWED_DECORATOR_MARKS and mark not in mark_def_keys:
+                report.add_issue(
+                    code="unresolved_mark_reference",
+                    message=f"Span mark {mark!r} is neither a known decorator mark nor a key present in `markDefs[]`.",
+                    path=f"{path}.children[{child_index}].marks[{mark_index}]",
+                    **_ctx(section=section, context_type="span", location=f"{path}.children[{child_index}]", suggestion="Either use a built-in decorator mark or define the key in `markDefs[]` of the same block."),
+                )
+
+
+def _validate_bibliography(entries: list[BibliographyEntry], *, report: ValidationReport) -> None:
+    for index, entry in enumerate(entries):
+        path = f"bibliography[{index}]"
+        if not entry.type:
+            report.add_issue(
+                code="invalid_bibliography_type",
+                message="`type` is required.",
+                path=f"{path}.type",
+                contextType="bibliography_item",
+                contextId=entry.id,
+                contextAnchor=entry.anchor,
+                location=f"{path}.type",
+                suggestion="Set a normalized bibliography type such as `article`, `book`, or `misc`.",
+            )
+        if not entry.title:
+            report.add_issue(
+                code="invalid_bibliography_title",
+                message="`title` is required.",
+                path=f"{path}.title",
+                contextType="bibliography_item",
+                contextId=entry.id,
+                contextAnchor=entry.anchor,
+                location=f"{path}.title",
+                suggestion="Provide a stable human-readable title for bibliography entries.",
+            )
+        if not isinstance(entry.authors, list):
+            report.add_issue(
+                code="invalid_bibliography_authors",
+                message="`authors` must be a list.",
+                path=f"{path}.authors",
+                contextType="bibliography_item",
+                contextId=entry.id,
+                contextAnchor=entry.anchor,
+                location=f"{path}.authors",
+                suggestion="Use a string array, even if there is only one author.",
+            )
+        elif len(entry.authors) == 0:
+            report.add_issue(
+                code="empty_bibliography_authors",
+                message="`authors` should not be empty according to the current protocol guidance.",
+                path=f"{path}.authors",
+                severity="warning",
+                contextType="bibliography_item",
+                contextId=entry.id,
+                contextAnchor=entry.anchor,
+                location=f"{path}.authors",
+                suggestion="Prefer a non-empty author list for better citation quality.",
+            )
+        if entry.year is None:
+            report.add_issue(
+                code="missing_bibliography_year",
+                message="`year` is recommended for bibliography entries.",
+                path=f"{path}.year",
+                severity="warning",
+                contextType="bibliography_item",
+                contextId=entry.id,
+                contextAnchor=entry.anchor,
+                location=f"{path}.year",
+                suggestion="Add `year` if known; it helps later rendering and citation styling.",
+            )
+
+
+def _validate_footnotes(entries: list[FootnoteEntry], *, report: ValidationReport) -> None:
+    for index, entry in enumerate(entries):
+        path = f"footnotes[{index}]"
+        if not isinstance(entry.blocks, list):
+            report.add_issue(
+                code="invalid_footnote_blocks",
+                message="`blocks` must be a list.",
+                path=f"{path}.blocks",
+                contextType="footnote",
+                contextId=entry.id,
+                contextAnchor=entry.anchor,
+                location=f"{path}.blocks",
+                suggestion="Store footnote content as a Portable Text block array.",
+            )
+            continue
+        if len(entry.blocks) == 0:
+            report.add_issue(
+                code="empty_footnote_blocks",
+                message="`footnotes[].blocks` should not be empty.",
+                path=f"{path}.blocks",
+                contextType="footnote",
+                contextId=entry.id,
+                contextAnchor=entry.anchor,
+                location=f"{path}.blocks",
+                suggestion="Provide at least one text block for each footnote entry.",
+            )
+            continue
+        for block_index, block in enumerate(entry.blocks):
+            _validate_text_block_structure(block, path=f"{path}.blocks[{block_index}]", section=None, report=report)
+
+
+def _validate_glossary(entries: list[GlossaryEntry], *, report: ValidationReport) -> None:
+    for index, entry in enumerate(entries):
+        path = f"glossary[{index}]"
+        if not entry.term:
+            report.add_issue(
+                code="invalid_glossary_term",
+                message="`term` is required.",
+                path=f"{path}.term",
+                contextType="glossary_term",
+                contextId=entry.id,
+                contextAnchor=entry.anchor,
+                location=f"{path}.term",
+                suggestion="Glossary entries should have a stable visible term string.",
+            )
+        if not entry.definition:
+            report.add_issue(
+                code="invalid_glossary_definition",
+                message="`definition` is required.",
+                path=f"{path}.definition",
+                contextType="glossary_term",
+                contextId=entry.id,
+                contextAnchor=entry.anchor,
+                location=f"{path}.definition",
+                suggestion="Provide a non-empty definition for glossary links to resolve meaningfully.",
+            )
+        if entry.aliases is not None:
+            if not isinstance(entry.aliases, list):
+                report.add_issue(
+                    code="invalid_glossary_aliases",
+                    message="`aliases` must be a list.",
+                    path=f"{path}.aliases",
+                    contextType="glossary_term",
+                    contextId=entry.id,
+                    contextAnchor=entry.anchor,
+                    location=f"{path}.aliases",
+                    suggestion="Use a string array for aliases.",
+                )
+            elif len(set(entry.aliases)) != len(entry.aliases):
+                report.add_issue(
+                    code="duplicate_glossary_alias",
+                    message="Duplicate alias strings found in one glossary entry.",
+                    path=f"{path}.aliases",
+                    severity="warning",
+                    contextType="glossary_term",
+                    contextId=entry.id,
+                    contextAnchor=entry.anchor,
+                    location=f"{path}.aliases",
+                    suggestion="Remove repeated alias strings inside the same glossary entry.",
+                )
+
+
+def _validate_section_references(section: Section, *, path: str, resolver: DocumentResolver, report: ValidationReport) -> None:
+    for body_index, item in enumerate(section.body):
+        item_path = f"{path}.body[{body_index}]"
+        if isinstance(item, ContentItem):
+            for block_index, block in enumerate(item.blocks):
+                block_path = f"{item_path}.blocks[{block_index}]"
+                if isinstance(block, TextBlock):
+                    _validate_text_block_inline_references(block, path=block_path, section=section, resolver=resolver, report=report)
+                elif isinstance(block, ImageBlock):
+                    if resolver.resolve_xref(target_type="image_asset", target_id=block.imageRef) is None:
+                        report.add_issue(
+                            code="unresolved_image_ref",
+                            message=f"`imageRef` cannot be resolved: {block.imageRef!r}",
+                            path=f"{block_path}.imageRef",
+                            **_ctx(section=section, context_type="image", context_id=block.id, context_anchor=block.anchor, location=f"{block_path}.imageRef", suggestion="Add the corresponding entry to `assets.images`, or fix the referenced id."),
+                        )
+                elif isinstance(block, ChartBlock):
+                    if resolver.resolve_xref(target_type="chart_dataset", target_id=block.chartRef) is None:
+                        report.add_issue(
+                            code="unresolved_chart_ref",
+                            message=f"`chartRef` cannot be resolved: {block.chartRef!r}",
+                            path=f"{block_path}.chartRef",
+                            **_ctx(section=section, context_type="chart", context_id=block.id, context_anchor=block.anchor, location=f"{block_path}.chartRef", suggestion="Add the corresponding entry to `datasets.charts`, or fix the referenced id."),
+                        )
+                elif isinstance(block, TableBlock):
+                    if resolver.resolve_xref(target_type="table_dataset", target_id=block.tableRef) is None:
+                        report.add_issue(
+                            code="unresolved_table_ref",
+                            message=f"`tableRef` cannot be resolved: {block.tableRef!r}",
+                            path=f"{block_path}.tableRef",
+                            **_ctx(section=section, context_type="table", context_id=block.id, context_anchor=block.anchor, location=f"{block_path}.tableRef", suggestion="Add the corresponding entry to `datasets.tables`, or fix the referenced id."),
+                        )
+                elif isinstance(block, CalloutBlock):
+                    for sub_index, sub_block in enumerate(block.blocks):
+                        _validate_text_block_structure(sub_block, path=f"{block_path}.blocks[{sub_index}]", section=section, report=report)
+                        _validate_text_block_inline_references(sub_block, path=f"{block_path}.blocks[{sub_index}]", section=section, resolver=resolver, report=report)
+        elif isinstance(item, SubsectionItem):
+            _validate_section_references(item.section, path=f"{item_path}.section", resolver=resolver, report=report)
+
+
+def _validate_text_block_inline_references(block: TextBlock, *, path: str, section: Section, resolver: DocumentResolver, report: ValidationReport) -> None:
+    for child_index, child in enumerate(block.children):
+        child_path = f"{path}.children[{child_index}]"
+        if isinstance(child, XRef):
+            if not resolver.is_supported_target_type(child.targetType):
+                report.add_issue(
+                    code="unsupported_xref_target_type",
+                    message=f"Unsupported `xref.targetType`: {child.targetType!r}. Supported values include: {sorted(resolver.supported_target_types())}",
+                    path=f"{child_path}.targetType",
+                    **_ctx(section=section, context_type="xref", location=f"{child_path}.targetType", suggestion="Use one of the resolver-supported semantic types, such as `section`, `figure`, `table`, `equation`, `footnote`, or `bibliography`."),
+                )
+                continue
+            target = resolver.resolve_xref(target_type=child.targetType, target_id=child.targetId)
+            if target is None:
+                report.add_issue(
+                    code="unresolved_xref",
+                    message=f"`xref` target cannot be resolved: targetType={child.targetType!r}, targetId={child.targetId!r}",
+                    path=child_path,
+                    **_ctx(section=section, context_type="xref", location=child_path, suggestion="Check both `targetType` and `targetId`, and confirm that the target object exists exactly once in the document."),
+                )
+        elif isinstance(child, CitationRef):
+            if len(child.refIds) == 0:
+                report.add_issue(
+                    code="empty_citation_ref",
+                    message="`citation_ref.refIds` must not be empty.",
+                    path=f"{child_path}.refIds",
+                    **_ctx(section=section, context_type="citation_ref", location=f"{child_path}.refIds", suggestion="Provide at least one bibliography id."),
+                )
+                continue
+            for ref_index, ref_id in enumerate(child.refIds):
+                target = resolver.resolve_xref(target_type="bibliography_item", target_id=ref_id)
+                if target is None:
+                    report.add_issue(
+                        code="unresolved_citation_ref",
+                        message=f"`citation_ref` target cannot be resolved: {ref_id!r}",
+                        path=f"{child_path}.refIds[{ref_index}]",
+                        **_ctx(section=section, context_type="citation_ref", location=f"{child_path}.refIds[{ref_index}]", suggestion="Create a matching bibliography entry under the top-level `bibliography` registry."),
+                    )
+                else:
+                    # Optional future hook: successful resolution context is now available if needed.
+                    # 这里保留成功解析的 target 上下文，方便未来继续扩展校验逻辑。
+                    _ = _ctx_from_target(target)
+        elif isinstance(child, FootnoteRef):
+            target = resolver.resolve_xref(target_type="footnote", target_id=child.refId)
+            if target is None:
+                report.add_issue(
+                    code="unresolved_footnote_ref",
+                    message=f"`footnote_ref` target cannot be resolved: {child.refId!r}",
+                    path=f"{child_path}.refId",
+                    **_ctx(section=section, context_type="footnote_ref", location=f"{child_path}.refId", suggestion="Create a matching top-level footnote entry."),
+                )
+        elif isinstance(child, GlossaryTerm):
+            target = resolver.resolve_xref(target_type="glossary_term", target_id=child.termId)
+            if target is None:
+                report.add_issue(
+                    code="unresolved_glossary_term",
+                    message=f"`glossary_term` target cannot be resolved: {child.termId!r}",
+                    path=f"{child_path}.termId",
+                    **_ctx(section=section, context_type="glossary_term_ref", location=f"{child_path}.termId", suggestion="Create a matching top-level glossary entry."),
+                )

ova_portable_text/version.py

@@ -0,0 +1,9 @@
+"""
+Package version information for OVAPortableText.
+OVAPortableText 的包版本信息。
+
+This module provides a single source of truth for the runtime package version.
+本模块提供运行时版本号的单一事实来源。
+"""
+
+__version__ = "0.1.1"