simplibs-extractor-html 0.1.0__py3-none-any.whl

simplibs/extractor_html/constants/HTML_OUTLINE_ELEMENTS.py

@@ -0,0 +1,32 @@
+from typing import Final
+
+
+HTML_OUTLINE_ELEMENTS: Final[tuple[str, ...]] = (
+    "header",
+    "nav",
+    "main",
+    "section",
+    "article",
+    "aside",
+    "footer",
+    "form",
+    "table",
+    "dialog",
+    "template",
+)
+"""The elements that always appear in the outline of a page: the landmarks and the other big parts."""
+
+
+_DESIGN_NOTES = """
+# HTML_OUTLINE_ELEMENTS — The Parts a Page Is Made Of
+
+## Purpose
+The outline of a page is not a copy of its tags: a `div` inside a `div` inside
+a `div` says nothing. These are the elements whose name says what a part of the
+page is.
+
+## The Others
+Any element with an `id` is listed too (it is something that stylesheets,
+scripts and links point to), and so are the headings and the title, with their
+text.
+"""

simplibs/extractor_html/constants/HTML_OUTLINE_TEXT_LIMIT.py

@@ -0,0 +1,15 @@
+from typing import Final
+
+
+HTML_OUTLINE_TEXT_LIMIT: Final[int] = 80
+"""The longest text of a heading that appears in the outline, in characters."""
+
+
+_DESIGN_NOTES = """
+# HTML_OUTLINE_TEXT_LIMIT — A Heading Is Not a Paragraph
+
+## Purpose
+A heading that has grown into a sentence would make a line of the outline
+longer than the part of the page it names. A longer text is cut and marked
+with an ellipsis.
+"""

simplibs/extractor_html/constants/HTML_OUTPUT_DIR_NAMES.py

@@ -0,0 +1,43 @@
+from typing import Final
+
+
+HTML_OUTPUT_DIR_NAMES: Final[tuple[str, ...]] = (
+    "build",
+    "dist",
+    "out",
+    ".next",
+    ".nuxt",
+    ".docusaurus",
+    "_build",
+    "_site",
+    "staticfiles",
+    "coverage",
+    "htmlcov",
+    "storybook-static",
+)
+"""Names of folders that hold generated pages: build output, built documentation, reports."""
+
+
+_DESIGN_NOTES = """
+# HTML_OUTPUT_DIR_NAMES — Generated, Not Written
+
+## Purpose
+The names behind `OUTPUT_DIRS`. These folders are full of pages that a tool
+made.
+
+## What They Are
+* `build`, `dist`, `out`, `.next`, `.nuxt`, `.docusaurus`: results of a build.
+* `_build`: the output of Sphinx, with a page for every document.
+* `_site`: the output of Jekyll and similar generators.
+* `staticfiles`: what Django's `collectstatic` collects.
+* `coverage`, `htmlcov`: test-coverage reports, one page for every source file.
+* `storybook-static`: a built Storybook.
+
+## `public` Is Not Here
+In a React project `public/index.html` is the page itself, the one the
+bundler fills in, and it is source.
+
+## `.next`, `.nuxt`, `.docusaurus`
+They start with a dot, but the base rule only leaves out dot FILES, so without
+these names the pages inside would be read as source.
+"""

simplibs/extractor_html/constants/HTML_PLAIN_SUFFIXES.py

@@ -0,0 +1,18 @@
+from typing import Final
+
+
+HTML_PLAIN_SUFFIXES: Final[tuple[str, ...]] = (".html", ".htm", ".xhtml")
+"""The suffixes of HTML pages and of the templates that hide behind them (a Django template is a `.html` file)."""
+
+
+_DESIGN_NOTES = """
+# HTML_PLAIN_SUFFIXES — Pages, and Django Templates With Them
+
+## Purpose
+The suffixes the file rules and the profiles take for HTML. A Django template
+has the suffix `.html` like any page, so the suffix cannot tell them apart:
+the steps that read a template must be safe on a plain page, and they are.
+
+## `.xhtml`
+The same language in the syntax of XML; comments and tags are read the same way.
+"""

simplibs/extractor_html/constants/HTML_RAW_TEXT_END_PATTERNS.py

@@ -0,0 +1,28 @@
+import re
+from typing import Final
+
+
+HTML_RAW_TEXT_END_PATTERNS: Final[dict[str, re.Pattern[str]]] = {
+    name: re.compile(rf"</{name}(?=[\s/>])", re.IGNORECASE)
+    for name in ("script", "style", "textarea", "title")
+}
+"""For each element whose content is raw text, the pattern of its end tag."""
+
+
+_DESIGN_NOTES = """
+# HTML_RAW_TEXT_END_PATTERNS — Elements Whose Content Is Not Markup
+
+## Purpose
+Inside `script` and `style` a `<` is just a character, and inside `textarea`
+and `title` only the end tag counts. So there can be no comment in them, and
+the scanner skips the content as a whole, to the end tag.
+
+## The Names Are the List
+The keys are the elements this library knows to be raw. The end tag is
+`</name` followed by a blank, a slash or `>`, so `</scripts>` does not end a
+`script`.
+
+## Not Included
+The legacy `xmp`, `iframe`, `noembed` and `noframes` are left out: they are
+rare, and a page that uses them is not the kind this library is made for.
+"""

simplibs/extractor_html/constants/HTML_SUFFIXES.py

@@ -0,0 +1,22 @@
+from typing import Final
+# Inners
+from .HTML_PLAIN_SUFFIXES import HTML_PLAIN_SUFFIXES
+from .HTML_TEMPLATE_SUFFIXES import HTML_TEMPLATE_SUFFIXES
+from .HTML_WRAPPED_SUFFIXES import HTML_WRAPPED_SUFFIXES
+
+
+HTML_SUFFIXES: Final[tuple[str, ...]] = HTML_PLAIN_SUFFIXES + HTML_TEMPLATE_SUFFIXES + HTML_WRAPPED_SUFFIXES
+"""Every suffix of a file this library may read: pages, Jinja templates and the `.j2` wrapper."""
+
+
+_DESIGN_NOTES = """
+# HTML_SUFFIXES — The Whole List in One Place
+
+## Purpose
+The profiles choose the steps of a file by its suffix, and they need the
+list of every suffix they can meet. The file rules do not use it: `.j2` is
+accepted there only together with a look at the stem.
+
+## Built From the Three Parts
+A suffix added to any of them is known to the profiles at once.
+"""

simplibs/extractor_html/constants/HTML_TAG_NAME_PATTERN.py

@@ -0,0 +1,16 @@
+import re
+from typing import Final
+
+
+HTML_TAG_NAME_PATTERN: Final[re.Pattern[str]] = re.compile(r"</?([A-Za-z][^\s/>]*)")
+"""The name of a tag, in the first group (`div` of `<div class="a">` and of `</div>`)."""
+
+
+_DESIGN_NOTES = """
+# HTML_TAG_NAME_PATTERN — Which Element Is It
+
+## Purpose
+The scanner needs the name of a tag to treat `script`, `style`, `textarea`,
+`title` and `pre` differently. The name is read up to the first blank, slash
+or `>`, and compared in lower case.
+"""

simplibs/extractor_html/constants/HTML_TEMPLATE_BLOCKS.py

@@ -0,0 +1,38 @@
+import re
+from typing import Final
+
+
+HTML_TEMPLATE_BLOCKS: Final[dict[str, dict[str, tuple[str, re.Pattern[str]]]]] = {
+    "django": {
+        "comment": ("comment", re.compile(r"\{%[-+]?\s*endcomment\b.*?%\}", re.DOTALL)),
+        "verbatim": ("verbatim", re.compile(r"\{%[-+]?\s*endverbatim\b.*?%\}", re.DOTALL)),
+    },
+    "jinja": {
+        "raw": ("verbatim", re.compile(r"\{%[-+]?\s*endraw\b.*?%\}", re.DOTALL)),
+    },
+}
+"""For each engine, the tags that open a block running to an end tag: its name, what the block is (`comment` or `verbatim`) and the pattern of the end tag."""
+
+
+_DESIGN_NOTES = """
+# HTML_TEMPLATE_BLOCKS — Tags That Swallow Everything Up to Their End
+
+## Purpose
+A Django `{% comment %}` hides everything up to `{% endcomment %}`, and
+`{% verbatim %}` or a Jinja `{% raw %}` makes everything up to its end plain
+text. The scanner must treat such a stretch as one piece, whatever HTML it
+contains.
+
+## What Each Block Is
+* `comment`: removed by the template comment step, like `{# ... #}`.
+* `verbatim`: left as it is, and hidden from the scanner of HTML (a `<!-- -->`
+  inside `{% verbatim %}` is text for the template engine).
+
+## The End Tag
+`{%`, optional whitespace control (`-` or `+`), the name, anything up to `%}`.
+A comment block may carry a note (`{% comment "why" %}`), and the end tag
+may carry whitespace control (`{%- endcomment -%}`).
+
+## Why Jinja Has No Comment Block
+Jinja has no such tag; its comments are `{# ... #}`, which may span lines.
+"""

simplibs/extractor_html/constants/HTML_TEMPLATE_IMPORT_TAGS.py

@@ -0,0 +1,29 @@
+from typing import Final
+
+
+HTML_TEMPLATE_IMPORT_TAGS: Final[dict[str, tuple[str, ...]]] = {
+    "django": ("load",),
+    "jinja": ("import", "from"),
+}
+"""For each engine, the names of the tags that bring other names into a template."""
+
+
+_DESIGN_NOTES = """
+# HTML_TEMPLATE_IMPORT_TAGS — What a Template Needs From Elsewhere
+
+## Purpose
+The names behind `remove_template_imports`. Like the imports of a program,
+these tags only say where the names that the rest of the template uses come
+from, and a reader who wants the page itself can do without them.
+
+## Django
+`{% load static %}` and `{% load i18n static %}` bring in tag libraries.
+
+## Jinja
+`{% import 'forms.html' as forms %}` and `{% from 'forms.html' import field %}`
+bring in macros.
+
+## What Is Not Here
+`{% extends %}` and `{% include %}` are not imports: they build the page and
+say what it is made of, so they stay.
+"""

simplibs/extractor_html/constants/HTML_TEMPLATE_OUTLINE_TAGS.py

@@ -0,0 +1,35 @@
+from typing import Final
+
+
+HTML_TEMPLATE_OUTLINE_TAGS: Final[dict[str, dict[str, tuple[str, ...]]]] = {
+    "django": {
+        "opens": ("block",),
+        "closes": ("endblock",),
+        "lines": ("extends", "include"),
+    },
+    "jinja": {
+        "opens": ("block", "macro"),
+        "closes": ("endblock", "endmacro"),
+        "lines": ("extends", "include"),
+    },
+}
+"""For each engine, the template tags of the outline: those that open a level, those that close it, and those that stand alone on a line."""
+
+
+_DESIGN_NOTES = """
+# HTML_TEMPLATE_OUTLINE_TAGS — The Skeleton of a Template
+
+## Purpose
+`{% extends %}` says what a template is built on, `{% block %}` what it fills
+in or offers to be filled, `{% include %}` what it pulls in, and in Jinja
+`{% macro %}` what it defines. Everything else (`if`, `for`, `with`) is the
+flesh, not the skeleton.
+
+## Opens and Closes
+`block` and `macro` open a level and `endblock` and `endmacro` close it. The
+name that may follow `endblock` is not compared with the name of the block it
+closes.
+
+## What Is Not Here
+The imports are not part of the outline: they have a step of their own.
+"""

simplibs/extractor_html/constants/HTML_TEMPLATE_SUFFIXES.py

@@ -0,0 +1,19 @@
+from typing import Final
+
+
+HTML_TEMPLATE_SUFFIXES: Final[tuple[str, ...]] = (".jinja", ".jinja2", ".njk")
+"""The suffixes of HTML templates of the Jinja family (Jinja, Nunjucks)."""
+
+
+_DESIGN_NOTES = """
+# HTML_TEMPLATE_SUFFIXES — Templates That Say What They Are
+
+## Purpose
+Templates with a suffix of their own: Jinja (`.jinja`, `.jinja2`) and
+Nunjucks (`.njk`), which uses the same `{% %}` and `{# #}` syntax.
+
+## What Is Not Here
+`.j2` is too general (Ansible keeps configuration files in it); it has its own
+constant. `.twig`, `.liquid`, `.hbs`, `.ejs` and `.mustache` have comment
+syntax of their own, which this library does not read.
+"""

simplibs/extractor_html/constants/HTML_TEMPLATE_TAG_NAME_PATTERN.py

@@ -0,0 +1,16 @@
+import re
+from typing import Final
+
+
+HTML_TEMPLATE_TAG_NAME_PATTERN: Final[re.Pattern[str]] = re.compile(r"\{%[-+]?\s*(\w+)")
+"""The name of a template tag, in the first group (`block` of `{% block content %}`)."""
+
+
+_DESIGN_NOTES = """
+# HTML_TEMPLATE_TAG_NAME_PATTERN — Which Tag Is It
+
+## Purpose
+`{% comment %}`, `{% verbatim %}` and `{% raw %}` change how the scanner reads
+what follows; every other tag is only skipped. The name is read after the
+optional whitespace control (`{%-`).
+"""

simplibs/extractor_html/constants/HTML_TEMPLATE_TOKEN_PATTERN.py

@@ -0,0 +1,16 @@
+import re
+from typing import Final
+
+
+HTML_TEMPLATE_TOKEN_PATTERN: Final[re.Pattern[str]] = re.compile(r"\{#|\{%|\{\{")
+"""What the template scanner stops at: the opening of a template comment, tag or variable."""
+
+
+_DESIGN_NOTES = """
+# HTML_TEMPLATE_TOKEN_PATTERN — Where a Template Construct Begins
+
+## Purpose
+The three openings Django and Jinja share: `{#` (comment), `{%` (tag) and
+`{{` (variable). What closes each one is decided by the scanner, because it
+depends on the engine.
+"""

simplibs/extractor_html/constants/HTML_TEXT_ELEMENTS.py

@@ -0,0 +1,16 @@
+from typing import Final
+# Inners
+from .HTML_HEADING_ELEMENTS import HTML_HEADING_ELEMENTS
+
+
+HTML_TEXT_ELEMENTS: Final[tuple[str, ...]] = ("title", *HTML_HEADING_ELEMENTS)
+"""The elements that appear in the outline with their text: the title and the headings."""
+
+
+_DESIGN_NOTES = """
+# HTML_TEXT_ELEMENTS — What the Page Calls Its Parts
+
+## Purpose
+A heading is the name the author gave to a part. For a reader who sees only the
+outline, `h2 "Opening hours"` says more than any number of tags.
+"""

simplibs/extractor_html/constants/HTML_TOKEN_PATTERN.py

@@ -0,0 +1,26 @@
+import re
+from typing import Final
+
+
+HTML_TOKEN_PATTERN: Final[re.Pattern[str]] = re.compile(
+    r"""<!--|<!\[CDATA\[|<![A-Za-z]|<\?|</[A-Za-z]|<[A-Za-z]""",
+    re.IGNORECASE,
+)
+"""What the scanner stops at in a page: a comment, a CDATA section, a declaration, a processing instruction, an end tag or a start tag."""
+
+
+_DESIGN_NOTES = """
+# HTML_TOKEN_PATTERN — Where Something Interesting Begins
+
+## Purpose
+The scanner does not look at every character. It asks this pattern for the
+next place where markup may begin and jumps there. Text between is only text.
+
+## Why a `<` Alone Is Not a Stop
+A `<` is markup only when a letter, `!`, `/` or `?` follows. `a < b` and
+`1<2` are text, so a stray less-than sign is never read as the start of a tag.
+
+## The Order
+`<!--` comes first, so a comment is never mistaken for a declaration, and the
+CDATA opening comes before the general `<!` declaration.
+"""

simplibs/extractor_html/constants/HTML_TYPE_ATTRIBUTE_PATTERN.py

@@ -0,0 +1,21 @@
+import re
+from typing import Final
+
+
+HTML_TYPE_ATTRIBUTE_PATTERN: Final[re.Pattern[str]] = re.compile(
+    r"""\stype\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))""",
+    re.IGNORECASE,
+)
+"""The `type` attribute of a tag; its value is in one of the three groups (double quotes, single quotes, none)."""
+
+
+_DESIGN_NOTES = """
+# HTML_TYPE_ATTRIBUTE_PATTERN — What Is in the Script
+
+## Purpose
+`<script type="application/json">` is data, `<script type="module">` is code.
+The value of `type` tells the two apart.
+
+## The Blank in Front
+A blank must come before `type`, so `data-type="x"` is not mistaken for it.
+"""

simplibs/extractor_html/constants/HTML_VOID_ELEMENTS.py

@@ -0,0 +1,21 @@
+from typing import Final
+
+
+HTML_VOID_ELEMENTS: Final[frozenset[str]] = frozenset({
+    "area", "base", "br", "col", "embed", "hr", "img", "input",
+    "link", "meta", "param", "source", "track", "wbr",
+})
+"""The elements that never have content and never have an end tag."""
+
+
+_DESIGN_NOTES = """
+# HTML_VOID_ELEMENTS — Elements That End Where They Begin
+
+## Purpose
+`<br>`, `<img src="a.png">` and `<input>` have no end tag. The outline must
+not wait for one, or every element after them would seem to be inside them.
+
+## Self-Closing Syntax
+A tag written with `/>` is also a complete element, whatever its name; that is
+decided by the tag itself, not by this list.
+"""

simplibs/extractor_html/constants/HTML_WRAPPED_STEM_ENDING.py

@@ -0,0 +1,14 @@
+from typing import Final
+
+
+HTML_WRAPPED_STEM_ENDING: Final[str] = ".html"
+"""What the stem of a wrapped file ends with when it is a page (`index.html` of `index.html.j2`)."""
+
+
+_DESIGN_NOTES = """
+# HTML_WRAPPED_STEM_ENDING — What Is Inside the Wrapper
+
+## Purpose
+Used by `WRAPPED_HTML`. Only `.html` is accepted: it is by far the common
+name of a Jinja page, and every other ending would be a guess.
+"""

simplibs/extractor_html/constants/HTML_WRAPPED_SUFFIXES.py

@@ -0,0 +1,15 @@
+from typing import Final
+
+
+HTML_WRAPPED_SUFFIXES: Final[tuple[str, ...]] = (".j2",)
+"""The suffixes that only wrap the real one (`index.html.j2`); a file is HTML only if what is inside the wrapper is."""
+
+
+_DESIGN_NOTES = """
+# HTML_WRAPPED_SUFFIXES — The Suffix That Needs a Look Behind
+
+## Purpose
+`.j2` is added to the name of a file that is a Jinja template: `index.html.j2`
+is a page, `nginx.conf.j2` is a configuration. The suffix alone says nothing,
+so the file rules also look at the stem (`HTML_WRAPPED_STEM_ENDING`).
+"""

simplibs/extractor_html/constants/__init__.py

@@ -0,0 +1,77 @@
+from .HTML_ANY_TAG_PATTERN import HTML_ANY_TAG_PATTERN
+from .HTML_BLOCK_LANGUAGE_BY_TYPE import HTML_BLOCK_LANGUAGE_BY_TYPE
+from .HTML_COMMENT_END_PATTERN import HTML_COMMENT_END_PATTERN
+from .HTML_CONDITIONAL_PATTERN import HTML_CONDITIONAL_PATTERN
+from .HTML_DEPENDENCY_DIR_NAMES import HTML_DEPENDENCY_DIR_NAMES
+from .HTML_EXTRA_LANGUAGE_BY_SUFFIX import HTML_EXTRA_LANGUAGE_BY_SUFFIX
+from .HTML_HEADING_ELEMENTS import HTML_HEADING_ELEMENTS
+from .HTML_ID_ATTRIBUTE_PATTERN import HTML_ID_ATTRIBUTE_PATTERN
+from .HTML_IMPLIED_END import HTML_IMPLIED_END
+from .HTML_LICENSE_START import HTML_LICENSE_START
+from .HTML_LICENSE_TAGS import HTML_LICENSE_TAGS
+from .HTML_OUTLINE_ELEMENTS import HTML_OUTLINE_ELEMENTS
+from .HTML_OUTLINE_TEXT_LIMIT import HTML_OUTLINE_TEXT_LIMIT
+from .HTML_OUTPUT_DIR_NAMES import HTML_OUTPUT_DIR_NAMES
+from .HTML_PLAIN_SUFFIXES import HTML_PLAIN_SUFFIXES
+from .HTML_RAW_TEXT_END_PATTERNS import HTML_RAW_TEXT_END_PATTERNS
+from .HTML_SUFFIXES import HTML_SUFFIXES
+from .HTML_TAG_NAME_PATTERN import HTML_TAG_NAME_PATTERN
+from .HTML_TEMPLATE_BLOCKS import HTML_TEMPLATE_BLOCKS
+from .HTML_TEMPLATE_IMPORT_TAGS import HTML_TEMPLATE_IMPORT_TAGS
+from .HTML_TEMPLATE_OUTLINE_TAGS import HTML_TEMPLATE_OUTLINE_TAGS
+from .HTML_TEMPLATE_SUFFIXES import HTML_TEMPLATE_SUFFIXES
+from .HTML_TEMPLATE_TAG_NAME_PATTERN import HTML_TEMPLATE_TAG_NAME_PATTERN
+from .HTML_TEMPLATE_TOKEN_PATTERN import HTML_TEMPLATE_TOKEN_PATTERN
+from .HTML_TEXT_ELEMENTS import HTML_TEXT_ELEMENTS
+from .HTML_TOKEN_PATTERN import HTML_TOKEN_PATTERN
+from .HTML_TYPE_ATTRIBUTE_PATTERN import HTML_TYPE_ATTRIBUTE_PATTERN
+from .HTML_VOID_ELEMENTS import HTML_VOID_ELEMENTS
+from .HTML_WRAPPED_STEM_ENDING import HTML_WRAPPED_STEM_ENDING
+from .HTML_WRAPPED_SUFFIXES import HTML_WRAPPED_SUFFIXES
+
+
+_DESIGN_NOTES = """
+# constants — Fixed Values of simplibs-extractor-html
+
+Plain imports, no `__all__` (the package root decides what is public).
+
+## Internal Components Registry
+
+| Component                        | Type     | Description                                                          |
+| :------------------------------- | :------- | :------------------------------------------------------------------- |
+| `HTML_ANY_TAG_PATTERN`           | Pattern  | Anything that looks like a tag.                                      |
+| `HTML_BLOCK_LANGUAGE_BY_TYPE`    | Constant | Which `type` values make a `script` or `style` code, and of what language. |
+| `HTML_COMMENT_END_PATTERN`       | Pattern  | `-->` and `--!>`.                                                    |
+| `HTML_CONDITIONAL_PATTERN`       | Pattern  | The beginning of an IE conditional comment.                          |
+| `HTML_DEPENDENCY_DIR_NAMES`      | Constant | Folders of pages written by other people.                            |
+| `HTML_EXTRA_LANGUAGE_BY_SUFFIX`  | Constant | The fence language of the suffixes the extractor does not know.      |
+| `HTML_HEADING_ELEMENTS`          | Constant | The six heading elements.                                            |
+| `HTML_ID_ATTRIBUTE_PATTERN`      | Pattern  | The `id` attribute of a tag.                                         |
+| `HTML_IMPLIED_END`               | Constant | Which start tags close which open elements.                          |
+| `HTML_LICENSE_START`             | Constant | How a comment that has to survive minification begins.               |
+| `HTML_LICENSE_TAGS`              | Constant | Words that mark a comment as one to keep.                            |
+| `HTML_OUTLINE_ELEMENTS`          | Constant | The elements that always appear in the outline of a page.            |
+| `HTML_OUTLINE_TEXT_LIMIT`        | Constant | The longest heading text in the outline.                             |
+| `HTML_OUTPUT_DIR_NAMES`          | Constant | Folders of generated pages and reports.                              |
+| `HTML_PLAIN_SUFFIXES`            | Constant | Suffixes of HTML pages and Django templates.                         |
+| `HTML_RAW_TEXT_END_PATTERNS`     | Constant | The end tag of each element with raw text.                           |
+| `HTML_SUFFIXES`                  | Constant | Every suffix the library may read.                                   |
+| `HTML_TAG_NAME_PATTERN`          | Pattern  | The name of a tag.                                                   |
+| `HTML_TEMPLATE_BLOCKS`           | Constant | The template tags that swallow everything up to an end tag.          |
+| `HTML_TEMPLATE_IMPORT_TAGS`      | Constant | The template tags that bring in names from elsewhere.                |
+| `HTML_TEMPLATE_OUTLINE_TAGS`     | Constant | The template tags of the outline: open, close, standalone.           |
+| `HTML_TEMPLATE_SUFFIXES`         | Constant | Suffixes of Jinja and Nunjucks templates.                            |
+| `HTML_TEMPLATE_TAG_NAME_PATTERN` | Pattern  | The name of a template tag.                                          |
+| `HTML_TEMPLATE_TOKEN_PATTERN`    | Pattern  | Where a template construct begins.                                   |
+| `HTML_TEXT_ELEMENTS`             | Constant | The title and the headings: listed with their text.                  |
+| `HTML_TOKEN_PATTERN`             | Pattern  | Where markup begins in a page.                                       |
+| `HTML_TYPE_ATTRIBUTE_PATTERN`    | Pattern  | The `type` attribute of a tag.                                       |
+| `HTML_VOID_ELEMENTS`             | Constant | The elements that have no content and no end tag.                    |
+| `HTML_WRAPPED_STEM_ENDING`       | Constant | What the stem of a wrapped page ends with.                           |
+| `HTML_WRAPPED_SUFFIXES`          | Constant | The `.j2` wrapper around the real suffix.                            |
+
+## Layering & Design
+- Every value is a tuple, a plain string, a small dict or a compiled pattern: the rules and the steps are built from them.
+- The names of version-control folders are not here: they come from `IGNORE_VCS` of `simplibs-path`.
+- There is no list of configuration names and no list of minified names: no tool keeps its settings in a page, and a minified page is not a convention.
+"""

simplibs/extractor_html/file_rules/__init__.py

@@ -0,0 +1,56 @@
+from .atomic import (
+    DEPENDENCY_DIRS,
+    DOT_NAME,
+    OUTPUT_DIRS,
+    VCS_DIRS,
+    WRAPPED_HTML,
+)
+from .html import (
+    HTML_BASE,
+    HTML_FILES,
+    HTML_PLAIN_BASE,
+    HTML_STRICT_EXCLUDE,
+)
+
+
+__all__ = [
+    # atomic
+    "DEPENDENCY_DIRS",
+    "DOT_NAME",
+    "OUTPUT_DIRS",
+    "VCS_DIRS",
+    "WRAPPED_HTML",
+    # html
+    "HTML_BASE",
+    "HTML_FILES",
+    "HTML_PLAIN_BASE",
+    "HTML_STRICT_EXCLUDE",
+]
+
+
+_DESIGN_NOTES = """
+# simplibs.extractor_html.file_rules — Which Files Are Worth Reading
+
+## Purpose
+Rules on the path of a file, relative to the source folder. The profiles use
+them as `include` and `exclude`; they compose with `&`, `|` and `~`, so a
+program can build its own selection from them:
+
+    from simplibs.extractor_html.file_rules import HTML_BASE, OUTPUT_DIRS
+    pages_without_output = HTML_BASE & ~OUTPUT_DIRS
+
+## Domain Folder
+`file_rules/` has its own `__all__` and is not re-exported from the package root.
+
+## Internal Components Registry
+
+| Component | Type    | Description                                                              |
+| :-------- | :------ | :----------------------------------------------------------------------- |
+| `atomic`  | Package | The shared pieces: dot names, the folder rules and the `.j2` wrapper.    |
+| `html`    | Package | Rules for pages and templates.                                           |
+
+## Layering & Design
+- `atomic` ← `html`.
+- Every rule is built once, when the package is imported.
+- A rule about the folders above a file is `AnyParentNameIs` of `simplibs-path`; a set of names is `IsIn` of `simplibs-rules`.
+"""

simplibs/extractor_html/file_rules/atomic/DEPENDENCY_DIRS.py

@@ -0,0 +1,17 @@
+from typing import Final
+from simplibs.path.rules import AnyParentNameIs
+from simplibs.rules import IsIn, Rule
+# Outers
+from ...constants import HTML_DEPENDENCY_DIR_NAMES
+
+
+DEPENDENCY_DIRS: Final[Rule] = AnyParentNameIs(IsIn(HTML_DEPENDENCY_DIR_NAMES))
+"""The file lies inside a folder of pages written by other people (`node_modules`, `vendor`)."""
+
+
+_DESIGN_NOTES = """
+# DEPENDENCY_DIRS — Other People's Pages
+
+## Purpose
+Part of the strict HTML exclusion. See `HTML_DEPENDENCY_DIR_NAMES`.
+"""

simplibs/extractor_html/file_rules/atomic/DOT_NAME.py

@@ -0,0 +1,19 @@
+from typing import Final
+from simplibs.path.rules import NameIs
+from simplibs.rules import Rule, StartsWith
+
+
+DOT_NAME: Final[Rule] = NameIs(StartsWith("."))
+"""The file name starts with a dot (`.hidden.html`)."""
+
+
+_DESIGN_NOTES = """
+# DOT_NAME — Hidden by Convention
+
+## Purpose
+Dot files are settings and tool state, not source. Used by `HTML_BASE`.
+
+## Name Only
+Only the name of the file is judged. A visible file inside a `.cache` folder
+is not hidden by this rule (the strict exclusions look at folders).
+"""

simplibs/extractor_html/file_rules/atomic/OUTPUT_DIRS.py

@@ -0,0 +1,17 @@
+from typing import Final
+from simplibs.path.rules import AnyParentNameIs
+from simplibs.rules import IsIn, Rule
+# Outers
+from ...constants import HTML_OUTPUT_DIR_NAMES
+
+
+OUTPUT_DIRS: Final[Rule] = AnyParentNameIs(IsIn(HTML_OUTPUT_DIR_NAMES))
+"""The file lies inside a folder of generated pages (`dist`, `_build`, `htmlcov`...)."""
+
+
+_DESIGN_NOTES = """
+# OUTPUT_DIRS — Generated Pages
+
+## Purpose
+Part of the strict HTML exclusion. See `HTML_OUTPUT_DIR_NAMES`.
+"""