xactflow 0.1.0__tar.gz

xactflow-0.1.0/LICENSE

@@ -0,0 +1,164 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

xactflow-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: xactflow
+Version: 0.1.0
+Summary: Multi-file IP-XACT elaboration and semantic consistency checking on top of ipxact-compiler.
+Author: Maxime Travaillard
+License-Expression: LGPL-3.0-only
+Project-URL: Repository, https://github.com/IP-XACT/XactFlow
+Project-URL: Issues, https://github.com/IP-XACT/XactFlow/issues
+Keywords: IP-XACT,IEEE 1685,XML,Compiler,XactFlow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ipxact-compiler
+Requires-Dist: lxml
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# XactFlow
+
+Multi-file [IEEE 1685-2022](https://standards.ieee.org/ieee/1685/10307/) IP-XACT elaboration
+and semantic consistency checking, built on top of
+[`ipxact-compiler`](https://github.com/IP-XACT/ipxact-compiler) (a standalone single-file
+IP-XACT parser).
+
+`ipxact-compiler` parses one IP-XACT XML document into a Python object model and stops there,
+no cross-file resolution, no validation or further checking.
+XactFlow is what consumes those parsed objects to do the higher-level work: resolving a
+`Design` (and its component instances, bus interfaces, and interconnections) against a library
+of `Component`/`BusDefinition`/`AbstractionDefinition` files into one combined, navigable
+object graph, and checking that graph against IP-XACT Semantic Consistency Rules (SCRs).
+
+## Installation
+
+```bash
+pip install xactflow
+```
+
+For local development, `requirements-dev.txt` overrides ipxact-compiler to a local installation.
+It can be modified to adapt the path or to keep the version on PyPI.
+
+```bash
+pip install -r requirements-dev.txt -e .
+```
+
+Requires Python >= 3.9.
+
+## CLI
+
+```bash
+xactflow elaborate <design.xml> [--lib DIR ...] [--config <designConfig.xml>]
+xactflow check <file.xml>
+```
+
+`elaborate` scans every `--lib` directory into a library indexed by VLNV, resolves `<design.xml>`
+against it (component instances, bus interfaces, interconnections, monitor interconnections, ad
+hoc connections), runs SCR checks on the result, prints every diagnostic, and exits nonzero if
+any of them is an error.
+
+`check` runs only the SCR rules that are checkable on a single document (no library needed) and
+is useful for validating one file in isolation, e.g. as a pre-commit or CI step.
+
+Installed exporter and importer plugins each become their own top-level subcommand
+automatically, named after whatever entry point name they registered under
+(`xactflow.exporters` / `xactflow.importers`), e.g. `xactflow html design.xml -o docs/` once a
+package like that is installed. XactFlow itself ships no exporters or importers; see
+[Plugins](#plugins) below.
+
+## Library usage
+
+```python
+import ipxact
+from xactflow import Library, elaborate
+
+library = Library.scan("path/to/ip/library")
+design = ipxact.parse_file("path/to/top_design.xml")
+
+elaborated = elaborate(design, library)
+
+elaborated.instances          # dict[str, ElaboratedInstance], keyed by instance name
+elaborated.interconnections   # list[ElaboratedInterconnection], every endpoint resolved
+elaborated.diagnostics        # list[Diagnostic] from every applicable SCR rule
+```
+
+## Semantic Consistency Rules (SCR)
+
+IEEE 1685-2022's Annex B defines 281 SCRs across 15 tables, each independently tagged
+`single doc check` (checkable on one document alone) and `post config` (only applies once
+configuration has been completed). Every one of them is registered in `xactflow.SCR`, one module
+per table (`SCR/scr_01.py` through `SCR/scr_15.py`), so the full set is always discoverable:
+
+```python
+from xactflow import SCR
+
+len(SCR.all_rules())                                   # 281
+[r.id for r in SCR.all_rules() if r.implemented]        # currently implemented: SCR 1.2, 1.9, 2.1-2.5
+```
+
+A rule with `implemented=False` is registered (id, name, table, the two flags, and the rule text
+as its description) but its check always reports nothing; that's a deliberate placeholder, not a
+bug, tracking Annex B's full rule set ahead of writing the check logic for each one. Table B.14
+(expressions) and most of the overlap/alignment rules in Tables B.7-B.9 additionally need real
+IP-XACT expression evaluation, which neither `ipxact-compiler` nor XactFlow implements yet
+(`Expression` fields are unevaluated strings in the object model).
+
+`SCR.run_single_doc_checks(document)` and `SCR.run_post_config_checks(elaborated)` are public,
+standalone functions independent of the elaborator's internals, so any caller (including a
+future exporter that itself emits IP-XACT) should re-run SCR checking on IP-XACT it produced, not
+only on the input.
+
+## Plugins
+
+XactFlow defines two plugin interfaces, both discovered via
+[entry points](https://packaging.python.org/en/latest/specifications/entry-points/), neither
+implemented in this repository:
+
+- `xactflow.Exporter` (`xactflow.exporters` entry point group): turns some IP-XACT-flavored
+  Python object into an output artifact, e.g. RTL, documentation, or another IP-XACT file. Its
+  `export(subject, output_dir, **options)` method leaves `subject` deliberately untyped: it may
+  be an `ElaboratedDesign` (a fully resolved multi-instance design), a bare `ipxact.Component` or
+  `ipxact.Design`, or anything else a given exporter chooses to support.
+  Each exporter documents and checks what it actually accepts.
+- `xactflow.Importer` (`xactflow.importers` entry point group): reads a non-IP-XACT source (a
+  custom design description, an annotated SystemVerilog file, etc.) and produces an IP-XACT
+  object model instance from it.
+
+A package that generates IP-XACT itself (from a hand-built object model, or as an importer's
+downstream step) is still just an `Exporter` writing its own XML; that capability lives in its
+own package rather than in `ipxact-compiler` or XactFlow.
+
+A plugin package registers itself in its own `pyproject.toml`:
+
+```toml
+[project.entry-points."xactflow.exporters"]
+html = "xactflow_html:HtmlExporter"
+```
+
+## Known limitations
+
+- **No IP-XACT expression evaluation.** `addressOffset`, `size`, `range`, `width`, `bitOffset`,
+  and similar fields are unevaluated `str` in the object model (`ipxact-compiler`'s deliberate
+  choice, carried through here). This blocks most of the overlap/alignment/stride SCRs,
+  from having real check logic yet.
+- **No multi-level design hierarchy.** `elaborate()` resolves one `Design` flat, it does not
+  recurse into a design nested inside another design's hierarchy. It will be supported in the future.
+- **No `DesignConfiguration` application.** A `DesignConfiguration` can be passed to `elaborate()`
+  and its single-doc rules get checked, but nothing actually applies it yet.
+- **Monitor interconnections and ad hoc connections resolve but aren't checked.** `elaborate()`
+  resolves both into the graph, but no SCR rule (Table B.4, or the ad hoc rules in B.2/B.6) has
+  check logic yet, so a broken monitor or ad hoc reference is silently dropped rather than
+  reported.
+- **274 of 281 SCR rules have no check logic.** See [Semantic Consistency
+  Rules](#semantic-consistency-rules-scr) above. 
+
+## Ideas for later
+
+- Real IP-XACT expression evaluation.
+- Multi-level design hierarchy elaboration.
+- A better SCR coverage, especially for the single file and pre config ones.
+- The actual exporter and importer plugin packages (an elaborated design to RTL exporter, an IP-XACT-emitting
+  exporter (component & design), a SystemVerilog-with-metadata importer, etc.), each in its own repository per
+  [Plugins](#plugins) above.
+
+## License
+
+LGPL-3.0. See [LICENSE](LICENSE).

xactflow-0.1.0/README.md

@@ -0,0 +1,148 @@
+# XactFlow
+
+Multi-file [IEEE 1685-2022](https://standards.ieee.org/ieee/1685/10307/) IP-XACT elaboration
+and semantic consistency checking, built on top of
+[`ipxact-compiler`](https://github.com/IP-XACT/ipxact-compiler) (a standalone single-file
+IP-XACT parser).
+
+`ipxact-compiler` parses one IP-XACT XML document into a Python object model and stops there,
+no cross-file resolution, no validation or further checking.
+XactFlow is what consumes those parsed objects to do the higher-level work: resolving a
+`Design` (and its component instances, bus interfaces, and interconnections) against a library
+of `Component`/`BusDefinition`/`AbstractionDefinition` files into one combined, navigable
+object graph, and checking that graph against IP-XACT Semantic Consistency Rules (SCRs).
+
+## Installation
+
+```bash
+pip install xactflow
+```
+
+For local development, `requirements-dev.txt` overrides ipxact-compiler to a local installation.
+It can be modified to adapt the path or to keep the version on PyPI.
+
+```bash
+pip install -r requirements-dev.txt -e .
+```
+
+Requires Python >= 3.9.
+
+## CLI
+
+```bash
+xactflow elaborate <design.xml> [--lib DIR ...] [--config <designConfig.xml>]
+xactflow check <file.xml>
+```
+
+`elaborate` scans every `--lib` directory into a library indexed by VLNV, resolves `<design.xml>`
+against it (component instances, bus interfaces, interconnections, monitor interconnections, ad
+hoc connections), runs SCR checks on the result, prints every diagnostic, and exits nonzero if
+any of them is an error.
+
+`check` runs only the SCR rules that are checkable on a single document (no library needed) and
+is useful for validating one file in isolation, e.g. as a pre-commit or CI step.
+
+Installed exporter and importer plugins each become their own top-level subcommand
+automatically, named after whatever entry point name they registered under
+(`xactflow.exporters` / `xactflow.importers`), e.g. `xactflow html design.xml -o docs/` once a
+package like that is installed. XactFlow itself ships no exporters or importers; see
+[Plugins](#plugins) below.
+
+## Library usage
+
+```python
+import ipxact
+from xactflow import Library, elaborate
+
+library = Library.scan("path/to/ip/library")
+design = ipxact.parse_file("path/to/top_design.xml")
+
+elaborated = elaborate(design, library)
+
+elaborated.instances          # dict[str, ElaboratedInstance], keyed by instance name
+elaborated.interconnections   # list[ElaboratedInterconnection], every endpoint resolved
+elaborated.diagnostics        # list[Diagnostic] from every applicable SCR rule
+```
+
+## Semantic Consistency Rules (SCR)
+
+IEEE 1685-2022's Annex B defines 281 SCRs across 15 tables, each independently tagged
+`single doc check` (checkable on one document alone) and `post config` (only applies once
+configuration has been completed). Every one of them is registered in `xactflow.SCR`, one module
+per table (`SCR/scr_01.py` through `SCR/scr_15.py`), so the full set is always discoverable:
+
+```python
+from xactflow import SCR
+
+len(SCR.all_rules())                                   # 281
+[r.id for r in SCR.all_rules() if r.implemented]        # currently implemented: SCR 1.2, 1.9, 2.1-2.5
+```
+
+A rule with `implemented=False` is registered (id, name, table, the two flags, and the rule text
+as its description) but its check always reports nothing; that's a deliberate placeholder, not a
+bug, tracking Annex B's full rule set ahead of writing the check logic for each one. Table B.14
+(expressions) and most of the overlap/alignment rules in Tables B.7-B.9 additionally need real
+IP-XACT expression evaluation, which neither `ipxact-compiler` nor XactFlow implements yet
+(`Expression` fields are unevaluated strings in the object model).
+
+`SCR.run_single_doc_checks(document)` and `SCR.run_post_config_checks(elaborated)` are public,
+standalone functions independent of the elaborator's internals, so any caller (including a
+future exporter that itself emits IP-XACT) should re-run SCR checking on IP-XACT it produced, not
+only on the input.
+
+## Plugins
+
+XactFlow defines two plugin interfaces, both discovered via
+[entry points](https://packaging.python.org/en/latest/specifications/entry-points/), neither
+implemented in this repository:
+
+- `xactflow.Exporter` (`xactflow.exporters` entry point group): turns some IP-XACT-flavored
+  Python object into an output artifact, e.g. RTL, documentation, or another IP-XACT file. Its
+  `export(subject, output_dir, **options)` method leaves `subject` deliberately untyped: it may
+  be an `ElaboratedDesign` (a fully resolved multi-instance design), a bare `ipxact.Component` or
+  `ipxact.Design`, or anything else a given exporter chooses to support.
+  Each exporter documents and checks what it actually accepts.
+- `xactflow.Importer` (`xactflow.importers` entry point group): reads a non-IP-XACT source (a
+  custom design description, an annotated SystemVerilog file, etc.) and produces an IP-XACT
+  object model instance from it.
+
+A package that generates IP-XACT itself (from a hand-built object model, or as an importer's
+downstream step) is still just an `Exporter` writing its own XML; that capability lives in its
+own package rather than in `ipxact-compiler` or XactFlow.
+
+A plugin package registers itself in its own `pyproject.toml`:
+
+```toml
+[project.entry-points."xactflow.exporters"]
+html = "xactflow_html:HtmlExporter"
+```
+
+## Known limitations
+
+- **No IP-XACT expression evaluation.** `addressOffset`, `size`, `range`, `width`, `bitOffset`,
+  and similar fields are unevaluated `str` in the object model (`ipxact-compiler`'s deliberate
+  choice, carried through here). This blocks most of the overlap/alignment/stride SCRs,
+  from having real check logic yet.
+- **No multi-level design hierarchy.** `elaborate()` resolves one `Design` flat, it does not
+  recurse into a design nested inside another design's hierarchy. It will be supported in the future.
+- **No `DesignConfiguration` application.** A `DesignConfiguration` can be passed to `elaborate()`
+  and its single-doc rules get checked, but nothing actually applies it yet.
+- **Monitor interconnections and ad hoc connections resolve but aren't checked.** `elaborate()`
+  resolves both into the graph, but no SCR rule (Table B.4, or the ad hoc rules in B.2/B.6) has
+  check logic yet, so a broken monitor or ad hoc reference is silently dropped rather than
+  reported.
+- **274 of 281 SCR rules have no check logic.** See [Semantic Consistency
+  Rules](#semantic-consistency-rules-scr) above. 
+
+## Ideas for later
+
+- Real IP-XACT expression evaluation.
+- Multi-level design hierarchy elaboration.
+- A better SCR coverage, especially for the single file and pre config ones.
+- The actual exporter and importer plugin packages (an elaborated design to RTL exporter, an IP-XACT-emitting
+  exporter (component & design), a SystemVerilog-with-metadata importer, etc.), each in its own repository per
+  [Plugins](#plugins) above.
+
+## License
+
+LGPL-3.0. See [LICENSE](LICENSE).

xactflow-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xactflow"
+dynamic = ["version"]
+description = "Multi-file IP-XACT elaboration and semantic consistency checking on top of ipxact-compiler."
+readme = "README.md"
+license = "LGPL-3.0-only"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Maxime Travaillard"},
+]
+requires-python = ">=3.9"
+dependencies = [
+    "ipxact-compiler",
+    "lxml",
+]
+keywords = [
+    "IP-XACT", "IEEE 1685", "XML", "Compiler",
+    "XactFlow",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.urls]
+Repository = "https://github.com/IP-XACT/XactFlow"
+Issues = "https://github.com/IP-XACT/XactFlow/issues"
+
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+]
+
+[project.scripts]
+xactflow = "xactflow.cli:main"
+
+[tool.setuptools.dynamic]
+version = {attr = "xactflow.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+xactflow = ["py.typed"]

xactflow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xactflow-0.1.0/src/xactflow/SCR/__init__.py

@@ -0,0 +1,28 @@
+from . import (  # noqa: F401  (registers every Annex B rule as an import side effect)
+    scr_01,
+    scr_02,
+    scr_03,
+    scr_04,
+    scr_05,
+    scr_06,
+    scr_07,
+    scr_08,
+    scr_09,
+    scr_10,
+    scr_11,
+    scr_12,
+    scr_13,
+    scr_14,
+    scr_15,
+)
+from .registry import Rule, all_rules, rule, stub
+from .runner import run_post_config_checks, run_single_doc_checks
+
+__all__ = [
+    "Rule",
+    "all_rules",
+    "rule",
+    "stub",
+    "run_post_config_checks",
+    "run_single_doc_checks",
+]

xactflow-0.1.0/src/xactflow/SCR/registry.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Iterator, List
+
+from ..diagnostics import Diagnostic
+
+
+@dataclass(frozen=True)
+class Rule:
+    """One IEEE 1685-2022 Annex B semantic consistency rule (SCR)."""
+
+    id: str
+    table: str
+    name: str
+    single_doc_check: bool
+    post_config: bool
+    description: str
+    check: Callable[[object], Iterator[Diagnostic]]
+    implemented: bool
+
+
+_REGISTRY: List[Rule] = []
+
+
+def rule(
+    *,
+    id: str,
+    table: str,
+    name: str,
+    single_doc_check: bool,
+    post_config: bool,
+    description: str,
+) -> Callable[[Callable[[object], Iterator[Diagnostic]]], Callable[[object], Iterator[Diagnostic]]]:
+    """Decorator registering a check function as one working Annex B SCR rule."""
+
+    def decorator(
+        check: Callable[[object], Iterator[Diagnostic]]
+    ) -> Callable[[object], Iterator[Diagnostic]]:
+        _REGISTRY.append(
+            Rule(
+                id=id,
+                table=table,
+                name=name,
+                single_doc_check=single_doc_check,
+                post_config=post_config,
+                description=description,
+                check=check,
+                implemented=True,
+            )
+        )
+        return check
+
+    return decorator
+
+
+def _not_yet_implemented(_subject: object) -> Iterator[Diagnostic]:
+    return []
+
+
+def stub(
+    *,
+    id: str,
+    table: str,
+    name: str,
+    single_doc_check: bool,
+    post_config: bool,
+    description: str,
+) -> None:
+    """Register an Annex B rule that is tracked (discoverable via all_rules()) but has no check
+    logic implemented yet. Its check always reports nothing; `implemented` is False so callers
+    can tell it apart from a working rule registered through @rule.
+    """
+    _REGISTRY.append(
+        Rule(
+            id=id,
+            table=table,
+            name=name,
+            single_doc_check=single_doc_check,
+            post_config=post_config,
+            description=description,
+            check=_not_yet_implemented,
+            implemented=False,
+        )
+    )
+
+
+def all_rules() -> List[Rule]:
+    return list(_REGISTRY)