Implement proper flag support (close #8)

object-Object · object-Object · commit 91c7f713ab0b · 2025-10-11T00:15:19.000-04:00
diff --git a/noxfile.py b/noxfile.py
@@ -299,12 +299,20 @@ def dummy_setup(session: nox.Session):
                                 "icon": "minecraft:amethyst_shard",
                                 "description": "Foo bar baz qux$(br)$(li)quux$(br)$(li2)corge$(br)$(li3)grault$(br)$(li4)garply$(li)waldo$(br)fred plugh xyzzy thud",
                                 "sortnum": 0,
+                                "flag": "foo:bar",
+                            },
+                            "categories/disabled.json": {
+                                "name": "Disabled",
+                                "icon": "minecraft:bedrock",
+                                "description": "Disabled",
+                                "flag": "foo:baz",
                             },
                             "entries/bar.json": {
                                 "name": "Dummy Entry",
                                 "category": "dummy:foo",
                                 "icon": "minecraft:textures/mob_effect/nausea.png",
                                 "sortnum": 0,
+                                "flag": "foo:bar",
                                 "pages": [
                                     {
                                         "type": "patchouli:text",
@@ -471,6 +479,77 @@ def dummy_setup(session: nox.Session):
                                     },
                                 ],
                             },
+                            "entries/flags.json": {
+                                "name": "Flags",
+                                "category": "dummy:foo",
+                                "icon": "minecraft:paper",
+                                "pages": [
+                                    {
+                                        "type": "patchouli:text",
+                                        "text": "enabled 1",
+                                        "flag": "does not exist",
+                                    },
+                                    {
+                                        "type": "patchouli:text",
+                                        "text": "enabled 2",
+                                        "flag": "foo:bar",
+                                    },
+                                    {
+                                        "type": "patchouli:text",
+                                        "text": "enabled 3",
+                                        "flag": "advancements_disabled_foo",
+                                    },
+                                    {
+                                        "type": "patchouli:text",
+                                        "text": "enabled 4",
+                                        "flag": "mod:aaaaaaaaa",
+                                    },
+                                    {
+                                        "type": "patchouli:text",
+                                        "text": "enabled 5",
+                                        "flag": "mod:minecraft",
+                                    },
+                                    {
+                                        "type": "patchouli:text",
+                                        "text": "disabled 1",
+                                        "flag": "foo:baz",
+                                    },
+                                    {
+                                        "type": "patchouli:text",
+                                        "text": "disabled 2",
+                                        "flag": "mod:foo",
+                                    },
+                                    {
+                                        "type": "patchouli:text",
+                                        "text": "disabled 3",
+                                        "flag": "advancements_disabled_bar",
+                                    },
+                                    {
+                                        "type": "patchouli:text",
+                                        "text": "disabled 4",
+                                        "flag": "debug",
+                                    },
+                                    {
+                                        "type": "patchouli:text",
+                                        "text": "web only",
+                                        "flag": "mod:hexdoc:web_only",
+                                    },
+                                    {
+                                        "type": "patchouli:text",
+                                        "text": "ingame only",
+                                        "flag": "!mod:hexdoc:web_only",
+                                    },
+                                ],
+                            },
+                            "entries/disabled.json": {
+                                "name": "Disabled",
+                                "category": "dummy:foo",
+                                "icon": "minecraft:bedrock",
+                                "flag": "foo:baz",
+                                "pages": [
+                                    "disabled",
+                                ],
+                            },
                         },
                     },
                     "data/dummy": {
@@ -553,6 +632,12 @@ def dummy_setup(session: nox.Session):
                     ]
                     export_dir = "src/hexdoc_dummy/_export/generated"
 
+                    [flags]
+                    "foo:bar" = true
+                    advancements_disabled_foo = true
+                    "foo:baz" = false
+                    "mod:foo" = false
+
                     [template]
                     icon = "icon.png"
                     include = [
diff --git a/src/hexdoc/cli/utils/load.py b/src/hexdoc/cli/utils/load.py
@@ -146,6 +146,7 @@ def init_context(
                 loader
             ).value_ids_set,
             all_metadata=all_metadata,
+            flags=pm.load_flags(),
         ),
     ]:
         item.add_to_context(context)
diff --git a/src/hexdoc/core/properties.py b/src/hexdoc/core/properties.py
@@ -241,6 +241,12 @@ class Properties(BaseProperties):
 
     textures: TexturesProps = Field(default_factory=TexturesProps)
 
+    flags: dict[str, bool] = Field(default_factory=dict)
+    """Local Patchouli flag overrides.
+
+    This has the final say over built-in defaults and flags exported by other mods.
+    """
+
     template: TemplateProps | None = None
 
     lang: defaultdict[
diff --git a/src/hexdoc/patchouli/book.py b/src/hexdoc/patchouli/book.py
@@ -1,3 +1,4 @@
+import logging
 from collections import defaultdict
 from typing import Any, Literal
 
@@ -19,6 +20,8 @@
 from .entry import Entry
 from .text import FormattingContext, FormatTree
 
+logger = logging.getLogger(__name__)
+
 
 class Book(HexdocModel):
     """Main Patchouli book class.
@@ -120,6 +123,9 @@ def _load_entries(
             use_resource_pack=self.use_resource_pack,
         ):
             entry = Entry.load(resource_dir, id, data, cast_context(context))
+            if not entry.is_flag_enabled:
+                logger.info(f"Skipping entry {id} due to disabled flag {entry.flag}")
+                continue
 
             spoilered_categories[entry.category_id] = (
                 entry.is_spoiler and spoilered_categories.get(entry.category_id, True)
diff --git a/src/hexdoc/patchouli/book_context.py b/src/hexdoc/patchouli/book_context.py
@@ -14,6 +14,7 @@ class BookContext(ValidationContextModel):
     book_links: BookLinks = Field(default_factory=dict)
     spoilered_advancements: set[ResourceLocation]
     all_metadata: dict[str, HexdocMetadata]
+    flags: dict[str, bool]
 
     def get_link_base(self, resource_dir: PathResourceDir) -> URL:
         modid = resource_dir.modid
diff --git a/src/hexdoc/patchouli/category.py b/src/hexdoc/patchouli/category.py
@@ -1,3 +1,4 @@
+import logging
 from typing import Any, Self
 
 from pydantic import Field
@@ -13,9 +14,12 @@
 
 from .entry import Entry
 from .text import FormatTree
+from .utils import Flagged
 
+logger = logging.getLogger(__name__)
 
-class Category(IDModel, Sortable):
+
+class Category(IDModel, Sortable, Flagged):
     """Category with pages and localizations.
 
     See: https://vazkiimods.github.io/Patchouli/docs/reference/category-json
@@ -32,7 +36,6 @@ class Category(IDModel, Sortable):
     # optional
     parent_id: ResourceLocation | None = Field(default=None, alias="parent")
     _parent_cmp_key: tuple[int, ...] | None = None
-    flag: str | None = None
     sortnum: int = 0
     secret: bool = False
 
@@ -54,7 +57,16 @@ def load_all(
             "categories",
             use_resource_pack,
         ):
-            category = categories[id] = cls.load(resource_dir, id, data, context)
+            # Patchouli checks flags before resolving category parents
+            # https://github.com/VazkiiMods/Patchouli/blob/abd6d03a08c37bcf116730021fda9f477412b31f/Xplat/src/main/java/vazkii/patchouli/client/book/BookContentsBuilder.java#L151
+            category = cls.load(resource_dir, id, data, context)
+            if not category.is_flag_enabled:
+                logger.info(
+                    f"Skipping category {id} due to disabled flag {category.flag}"
+                )
+                continue
+
+            categories[id] = category
             if category.parent_id:
                 G.add_edge(category.parent_id, category.id)
 
@@ -68,7 +80,13 @@ def load_all(
 
         # late-init _parent_cmp_key
         for parent_id in G.topological_sort():
-            parent = categories[parent_id]
+            parent = categories.get(parent_id)
+            if parent is None:
+                children = ", ".join(str(v) for _, v in G.iter_out_edges(parent_id))
+                raise ValueError(
+                    f"Parent category {parent_id} required by {children} does not exist"
+                )
+
             for _, child_id in G.iter_out_edges(parent_id):
                 categories[child_id]._parent_cmp_key = parent._cmp_key
 
diff --git a/src/hexdoc/patchouli/entry.py b/src/hexdoc/patchouli/entry.py
@@ -1,6 +1,7 @@
+import logging
 from typing import Iterable, Iterator
 
-from pydantic import Field
+from pydantic import Field, model_validator
 
 from hexdoc.core import ItemStack, ResourceLocation
 from hexdoc.minecraft import LocalizedStr
@@ -11,10 +12,12 @@
 
 from .page import CraftingPage, Page, PageWithTitle
 from .text import FormatTree
-from .utils import AdvancementSpoilered
+from .utils import AdvancementSpoilered, Flagged
 
+logger = logging.getLogger(__name__)
 
-class Entry(IDModel, Sortable, AdvancementSpoilered):
+
+class Entry(IDModel, Sortable, AdvancementSpoilered, Flagged):
     """Entry json file, with pages and localizations.
 
     See: https://vazkiimods.github.io/Patchouli/docs/reference/entry-json
@@ -28,7 +31,6 @@ class Entry(IDModel, Sortable, AdvancementSpoilered):
 
     # optional (entry.json)
     advancement: ResourceLocation | None = None
-    flag: str | None = None
     priority: bool = False
     secret: bool = False
     read_by_default: bool = False
@@ -118,6 +120,19 @@ def _get_advancement(self):
         # implements AdvancementSpoilered
         return self.advancement
 
+    @model_validator(mode="after")
+    def _skip_disabled_pages(self):
+        new_pages = list[Page]()
+        for i, page in enumerate(self.pages):
+            if not page.is_flag_enabled:
+                logger.info(
+                    f"Skipping page {i} of entry {self.id} due to disabled flag {page.flag}"
+                )
+                continue
+            new_pages.append(page)
+        self.pages = new_pages
+        return self
+
 
 class _CraftingPageAccumulator(PageWithTitle, template_type="patchouli:crafting"):
     recipes: list[CraftingRecipe] = Field(default_factory=list)
diff --git a/src/hexdoc/patchouli/page/abstract_pages.py b/src/hexdoc/patchouli/page/abstract_pages.py
@@ -10,19 +10,18 @@
 from hexdoc.utils import Inherit, InheritType, NoValue, classproperty
 
 from ..text import FormatTree
-from ..utils import AdvancementSpoilered
+from ..utils import AdvancementSpoilered, Flagged
 
 _T_Recipe = TypeVar("_T_Recipe", bound=Recipe)
 
 
-class Page(TypeTaggedTemplate, AdvancementSpoilered, type=None):
+class Page(TypeTaggedTemplate, AdvancementSpoilered, Flagged, type=None):
     """Base class for Patchouli page types.
 
     See: https://vazkiimods.github.io/Patchouli/docs/patchouli-basics/page-types
     """
 
     advancement: ResourceLocation | None = None
-    flag: str | None = None
     anchor: str | None = None
 
     def __init_subclass__(
diff --git a/src/hexdoc/patchouli/utils.py b/src/hexdoc/patchouli/utils.py
@@ -1,4 +1,6 @@
+import logging
 from abc import ABC, abstractmethod
+from typing import Iterator
 
 from pydantic import PrivateAttr, ValidationInfo, model_validator
 
@@ -7,6 +9,8 @@
 
 from .book_context import BookContext
 
+logger = logging.getLogger(__name__)
+
 
 class AdvancementSpoilered(HexdocModel, ABC):
     _is_spoiler: bool = PrivateAttr(False)
@@ -30,3 +34,58 @@ def _check_is_spoiler(self, info: ValidationInfo):
             )
 
         return self
+
+
+class Flagged(HexdocModel):
+    """Mixin model for categories, entries, and pages to implement flags."""
+
+    flag: str | None = None
+
+    _is_flag_enabled: bool = PrivateAttr(True)
+
+    @property
+    def is_flag_enabled(self) -> bool:
+        return self._is_flag_enabled
+
+    @model_validator(mode="after")
+    def _evaluate_flag(self, info: ValidationInfo):
+        ctx = BookContext.of(info)
+        self._is_flag_enabled = (
+            _evaluate_flag(self.flag, ctx.flags) if self.flag else True
+        )
+        return self
+
+
+# https://github.com/VazkiiMods/Patchouli/blob/abd6d03a08c37bcf116730021fda9f477412b31f/Xplat/src/main/java/vazkii/patchouli/common/base/PatchouliConfig.java#L42
+def _evaluate_flag(flag: str, flags: dict[str, bool]) -> bool:
+    # this SHOULD never be called with an empty string
+    match flag[0]:
+        case "&":
+            return all(_split_and_evaluate_flag(flag, flags))
+        case "|":
+            return any(_split_and_evaluate_flag(flag, flags))
+        case "!":
+            flag = flag[1:]
+            target = False
+        case _:
+            target = True
+
+    flag = flag.strip().lower()
+
+    b = flags.get(flag)
+    if b is None:
+        if flag.startswith("advancements_disabled_"):
+            b = False
+        else:
+            if not flag.startswith("mod:"):
+                logger.warning(f"Unknown config flag defaulting to True: {flag}")
+            b = True
+        # speed up subsequent checks a bit and avoid logging unnecessary warnings
+        flags[flag] = b
+
+    return b == target
+
+
+def _split_and_evaluate_flag(flag: str, flags: dict[str, bool]) -> Iterator[bool]:
+    for inner in flag.replace("&", "").replace("|", "").split(","):
+        yield _evaluate_flag(inner, flags)
diff --git a/src/hexdoc/plugin/manager.py b/src/hexdoc/plugin/manager.py
diff --git a/src/hexdoc/plugin/mod_plugin.py b/src/hexdoc/plugin/mod_plugin.py
