trlcdoc 0.3.0__py3-none-any.whl

trlcdoc/__init__.py

@@ -0,0 +1,37 @@
+"""trlcdoc - configurable documentation tooling for TRLC based projects.
+
+"""
+
+# trlcdoc - A utility for producing project documentation from TRLC and LOBSTER contents.
+# Copyright (c) 2026 - 2026 Norbert Schulz github@schulznorbert.de
+#
+# This file is part of trlcdoc program.
+#
+# The trlcdoc program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software Foundation,
+# either version 3 of the License, or (at your option) any later version.
+#
+# The trlcdoc program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with pyTRLCConverter.
+# If not, see <https://www.gnu.org/licenses/>.
+
+# Imports **********************************************************************
+
+from importlib.metadata import PackageNotFoundError, version
+
+# Variables ********************************************************************
+
+# Single source of truth is the version in pyproject.toml.
+try:
+    __version__ = version("trlcdoc")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree without install
+    __version__ = "0.0.0+unknown"
+
+# Classes **********************************************************************
+
+# Functions ********************************************************************
+
+# Main *************************************************************************

trlcdoc/__main__.py

@@ -0,0 +1,36 @@
+"""Entry point for 'python -m trlcdoc'.
+
+"""
+
+# trlcdoc - A utility for producing project documentation from TRLC and LOBSTER contents.
+# Copyright (c) 2026 - 2026 Norbert Schulz github@schulznorbert.de
+#
+# This file is part of trlcdoc program.
+#
+# The trlcdoc program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software Foundation,
+# either version 3 of the License, or (at your option) any later version.
+#
+# The trlcdoc program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with pyTRLCConverter.
+# If not, see <https://www.gnu.org/licenses/>.
+
+# Imports **********************************************************************
+
+import sys
+
+from .cli import main
+
+# Variables ********************************************************************
+
+# Classes **********************************************************************
+
+# Functions ********************************************************************
+
+# Main *************************************************************************
+
+if __name__ == "__main__":
+    sys.exit(main())

trlcdoc/cli.py

@@ -0,0 +1,186 @@
+"""Command line interface of trlcdoc.
+
+"""
+
+# trlcdoc - A utility for producing project documentation from TRLC and LOBSTER contents.
+# Copyright (c) 2026 - 2026 Norbert Schulz github@schulznorbert.de
+#
+# This file is part of trlcdoc program.
+#
+# The trlcdoc program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software Foundation,
+# either version 3 of the License, or (at your option) any later version.
+#
+# The trlcdoc program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with pyTRLCConverter.
+# If not, see <https://www.gnu.org/licenses/>.
+
+# Imports **********************************************************************
+
+import argparse
+from pathlib import Path
+from typing import List, Optional
+
+from . import __version__
+from .config import Config, find_config, load_config
+from .convert import convert_documents
+from .html import build_html
+from .plantuml import provide_plantuml
+from .testrun import run_tests
+from .trace import build_trace_report
+from .util import TrlcdocError, remove_output
+
+# Variables ********************************************************************
+
+# Steps in execution order. 'all' runs every step the configuration needs, except clean.
+STEPS = ["clean", "check", "plantuml", "tests", "convert", "trace", "html"]
+
+COPYRIGHT = "Copyright (c) 2026 Norbert Schulz"
+REPOSITORY = "https://github.com/nhjschulz/trlc-doc"
+DESCRIPTION = """Build project documentation for TRLC/LOBSTER based projects: requirements, architecture,
+tests, test results, tracing report and HTML site."""
+
+# Classes **********************************************************************
+
+# Functions ********************************************************************
+
+
+def _parse_args(argv: Optional[List[str]]) -> argparse.Namespace:
+    # lobster-trace: SwRequirements.sw_req_cli
+    # lobster-trace: SwRequirements.sw_req_cli_help
+    # lobster-trace: SwRequirements.sw_req_cli_version
+    # lobster-trace: SwRequirements.sw_req_steps
+    # lobster-trace: SwRequirements.sw_req_config_file
+    """Parse the command line arguments.
+
+    Args:
+        argv (Optional[List[str]]): Arguments, defaults to sys.argv[1:].
+
+    Returns:
+        argparse.Namespace: The parsed arguments.
+    """
+    parser = argparse.ArgumentParser(
+        prog="trlcdoc",
+        description=DESCRIPTION,
+        epilog=f"Version {__version__} - {COPYRIGHT} - GPL-3.0-or-later - see {REPOSITORY} for further information.",
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
+    parser.add_argument("steps", nargs="*", metavar="step",
+                        help=f"steps to run: {', '.join(STEPS)} or all (default: all)")
+    parser.add_argument("-v", "--version", action="version", version=f"%(prog)s {__version__}",
+                        help="show the trlcdoc version and exit")
+    parser.add_argument("-c", "--config", type=Path,
+                        help="project configuration (default: trlcdoc.yaml in the current folder or a parent)")
+    parser.add_argument("--online", action="store_true",
+                        help="link the tracing report to the repository instead of local files")
+    parser.add_argument("--format", choices=["rst", "markdown"], default="rst",
+                        help="output format of the convert step (default: rst, needed for html)")
+    args = parser.parse_args(argv)
+
+    args.steps = args.steps or ["all"]
+    unknown = [step for step in args.steps if step not in (*STEPS, "all")]
+    if unknown:
+        parser.error(f"unknown step(s) {', '.join(unknown)}, choose from {', '.join(STEPS)}, all")
+    return args
+
+
+def _selected_steps(cfg: Config, requested: List[str]) -> List[str]:
+    # lobster-trace: SwRequirements.sw_req_steps
+    # lobster-trace: SwRequirements.sw_req_step_order
+    """Determine the steps to run, in execution order.
+
+    Args:
+        cfg (Config): Project configuration.
+        requested (List[str]): Steps from the command line.
+
+    Returns:
+        List[str]: The steps to run.
+    """
+    selected = {step for step in STEPS if step in requested}
+    if "all" in requested:
+        selected.update(step for step in STEPS
+                        if step != "clean"
+                        and not (step == "tests" and cfg.tests is None)
+                        and not (step == "trace" and cfg.trace is None))
+    # Converting and rendering need the PlantUML jar.
+    if selected & {"convert", "html"}:
+        selected.add("plantuml")
+    return [step for step in STEPS if step in selected]
+
+
+def _run_step(step: str, cfg: Config, args: argparse.Namespace) -> bool:
+    # lobster-trace: SwRequirements.sw_req_steps
+    # lobster-trace: SwRequirements.sw_req_clean
+    # lobster-trace: SwRequirements.sw_req_exit_code
+    """Run one step.
+
+    Args:
+        step (str): Step name.
+        cfg (Config): Project configuration.
+        args (argparse.Namespace): Command line arguments.
+
+    Returns:
+        bool: True if the step found no problems in the project content
+        (failed tests, missing trace links). Build errors raise TrlcdocError.
+
+    Raises:
+        TrlcdocError: If the step cannot be completed.
+    """
+    ok = True
+    print(f"\n===== trlcdoc {step} =====", flush=True)
+    if step == "clean":
+        print(f"Removing {cfg.output}" if remove_output(cfg.output) else f"Nothing to clean in {cfg.output}")
+    elif step == "check":
+        print(f"Configuration {cfg.config_file} is valid, output: {cfg.output}")
+    elif step == "plantuml":
+        provide_plantuml(cfg)
+    elif step == "tests":
+        if cfg.tests is None:
+            raise TrlcdocError("The configuration has no 'tests' section.")
+        ok = run_tests(cfg)
+    elif step == "convert":
+        convert_documents(cfg, args.format)
+    elif step == "trace":
+        if cfg.trace is None:
+            raise TrlcdocError("The configuration has no 'trace' section.")
+        ok = build_trace_report(cfg, args.online) == 0
+    else:
+        build_html(cfg)
+    return ok
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    # lobster-trace: SwRequirements.sw_req_cli
+    # lobster-trace: SwRequirements.sw_req_config_validation
+    # lobster-trace: SwRequirements.sw_req_exit_code
+    """Run the requested trlcdoc steps.
+
+    Args:
+        argv (Optional[List[str]]): Arguments, defaults to sys.argv[1:].
+
+    Returns:
+        int: 0 if all steps succeeded and the content has no findings,
+        1 on findings (failed tests, missing trace links), 2 on build errors.
+    """
+    args = _parse_args(argv)
+    exit_code = 0
+    try:
+        cfg = load_config(args.config if args.config is not None else find_config(Path.cwd()))
+        findings: List[str] = []
+        for step in _selected_steps(cfg, args.steps):
+            if not _run_step(step, cfg, args):
+                findings.append(step)
+        if findings:
+            print(f"\ntrlcdoc finished with findings in: {', '.join(findings)}")
+            exit_code = 1
+        else:
+            print("\ntrlcdoc finished successfully.")
+    except TrlcdocError as err:
+        print(f"\ntrlcdoc error: {err}")
+        exit_code = 2
+    return exit_code
+
+# Main *************************************************************************

trlcdoc/config.py

@@ -0,0 +1,433 @@
+"""Loading, validation and path resolution of the trlcdoc project configuration.
+
+"""
+
+# trlcdoc - A utility for producing project documentation from TRLC and LOBSTER contents.
+# Copyright (c) 2026 - 2026 Norbert Schulz github@schulznorbert.de
+#
+# This file is part of trlcdoc program.
+#
+# The trlcdoc program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software Foundation,
+# either version 3 of the License, or (at your option) any later version.
+#
+# The trlcdoc program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with pyTRLCConverter.
+# If not, see <https://www.gnu.org/licenses/>.
+
+# Imports **********************************************************************
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import jsonschema
+import yaml
+
+from .util import TrlcdocError
+
+# Variables ********************************************************************
+
+PACKAGE_DIR = Path(__file__).resolve().parent
+SCHEMA_FILE = PACKAGE_DIR / "schema" / "trlcdoc.schema.json"
+BUILTIN_DIR = PACKAGE_DIR / "converters"
+BUILTIN_PREFIX = "builtin:"
+TESTS_COVERAGE = "tests:coverage"
+
+# Document types whose content are TRLC records.
+TRLC_DOCUMENT_TYPES = ("trlc", "test_results")
+
+# Classes **********************************************************************
+
+
+class Config:
+    """Validated project configuration with resolved paths."""
+
+    def __init__(self, data: Dict[str, Any], config_file: Path) -> None:
+        # lobster-trace: SwRequirements.sw_req_project_settings
+        # lobster-trace: SwRequirements.sw_req_documents
+        """Construct the configuration.
+
+        Args:
+            data (Dict[str, Any]): Schema validated configuration data.
+            config_file (Path): The configuration file. Its folder is the project root.
+        """
+        self.data = data
+        self.config_file = config_file.resolve()
+        self.root = self.config_file.parent
+        self.documents: List[Dict[str, Any]] = data["documents"]
+        self.tests: Optional[Dict[str, Any]] = data.get("tests")
+        self.trace: Optional[Dict[str, Any]] = data.get("trace")
+        self.project: Dict[str, Any] = data["project"]
+        self.html: Dict[str, Any] = data.get("html", {})
+        self.plantuml: Dict[str, Any] = data.get("plantuml", {})
+
+    # Paths ********************************************************************
+
+    def path(self, value: str) -> Path:
+        # lobster-trace: SwRequirements.sw_req_config_file
+        """Resolve a configured path against the project root.
+
+        Args:
+            value (str): Absolute path or path relative to the project root.
+
+        Returns:
+            Path: The absolute path.
+        """
+        return (self.root / value).resolve()
+
+    @property
+    def output(self) -> Path:
+        # lobster-trace: SwRequirements.sw_req_output_folder
+        """Folder for all generated files."""
+        return self.path(self.data["paths"].get("output", "build/trlcdoc"))
+
+    @property
+    def trlc_model(self) -> Path:
+        # lobster-trace: SwRequirements.sw_req_trlc_conversion
+        """Folder with the TRLC model files."""
+        return self.path(self.data["paths"]["trlc_model"])
+
+    @property
+    def plantuml_dir(self) -> Path:
+        # lobster-trace: SwRequirements.sw_req_plantuml
+        # lobster-trace: SwRequirements.sw_req_output_folder
+        """Folder for the downloaded PlantUML jar."""
+        return self.output / "plantuml"
+
+    def convert_dir(self, fmt: str, doc_id: str) -> Path:
+        # lobster-trace: SwRequirements.sw_req_trlc_conversion
+        # lobster-trace: SwRequirements.sw_req_output_folder
+        """Output folder of a converted document.
+
+        Args:
+            fmt (str): Output format, rst or markdown.
+            doc_id (str): Document id.
+
+        Returns:
+            Path: The output folder.
+        """
+        return self.output / "convert" / fmt / doc_id
+
+    @property
+    def tests_dir(self) -> Path:
+        # lobster-trace: SwRequirements.sw_req_test_run
+        # lobster-trace: SwRequirements.sw_req_output_folder
+        """Output folder of the tests step."""
+        return self.output / "tests"
+
+    @property
+    def junit_file(self) -> Path:
+        # lobster-trace: SwRequirements.sw_req_test_run
+        """JUnit XML file with the test results."""
+        result = self.tests_dir / "junit.xml"
+        if self.tests is not None and self.tests["runner"] == "command":
+            result = self.path(self.tests["junit"])
+        return result
+
+    @property
+    def coverage_dir(self) -> Path:
+        # lobster-trace: SwRequirements.sw_req_test_run
+        """HTML coverage report folder."""
+        result = self.tests_dir / "coverage"
+        if self.tests is not None and "coverage" in self.tests:
+            result = self.path(self.tests["coverage"])
+        return result
+
+    @property
+    def test_results_dir(self) -> Path:
+        # lobster-trace: SwRequirements.sw_req_test_results
+        """Folder with the TRLC test result records generated from the JUnit XML."""
+        return self.tests_dir / "results"
+
+    @property
+    def trace_dir(self) -> Path:
+        # lobster-trace: SwRequirements.sw_req_trace_report
+        # lobster-trace: SwRequirements.sw_req_output_folder
+        """Output folder of the trace step."""
+        return self.output / "trace"
+
+    @property
+    def trace_report_html(self) -> Path:
+        # lobster-trace: SwRequirements.sw_req_trace_report
+        """The HTML tracing report."""
+        return self.trace_dir / "tracing_report.html"
+
+    @property
+    def sphinx_dir(self) -> Path:
+        # lobster-trace: SwRequirements.sw_req_html_site
+        # lobster-trace: SwRequirements.sw_req_output_folder
+        """Generated Sphinx source folder."""
+        return self.output / "sphinx"
+
+    @property
+    def html_dir(self) -> Path:
+        # lobster-trace: SwRequirements.sw_req_html_site
+        # lobster-trace: SwRequirements.sw_req_output_folder
+        """Generated HTML site."""
+        return self.output / "html"
+
+    # Documents ****************************************************************
+
+    def document(self, doc_id: str) -> Dict[str, Any]:
+        # lobster-trace: SwRequirements.sw_req_documents
+        """Get a document by its id.
+
+        Args:
+            doc_id (str): Document id.
+
+        Returns:
+            Dict[str, Any]: The document configuration.
+        """
+        return next(doc for doc in self.documents if doc["id"] == doc_id)
+
+    def trlc_sources(self, doc: Dict[str, Any]) -> List[Path]:
+        # lobster-trace: SwRequirements.sw_req_trlc_conversion
+        """Get the TRLC source folders of a TRLC document.
+
+        Args:
+            doc (Dict[str, Any]): Document of type trlc or test_results.
+
+        Returns:
+            List[Path]: The source folders.
+        """
+        result = [self.test_results_dir]
+        if doc["type"] == "trlc":
+            result = [self.path(doc["source"])]
+        return result
+
+    def included_documents(self, doc: Dict[str, Any]) -> List[Dict[str, Any]]:
+        # lobster-trace: SwRequirements.sw_req_trlc_conversion
+        """Get all documents included by a document, transitively.
+
+        Args:
+            doc (Dict[str, Any]): The including document.
+
+        Returns:
+            List[Dict[str, Any]]: Included documents, without the document itself.
+        """
+        result: List[Dict[str, Any]] = []
+        pending = list(doc.get("include", []))
+        while pending:
+            doc_id = pending.pop(0)
+            if doc_id != doc["id"] and all(inc["id"] != doc_id for inc in result):
+                included = self.document(doc_id)
+                result.append(included)
+                pending.extend(included.get("include", []))
+        return result
+
+    def included_sources(self, doc: Dict[str, Any]) -> List[Path]:
+        # lobster-trace: SwRequirements.sw_req_trlc_conversion
+        """Get the TRLC source folders of all documents included by a document.
+
+        Args:
+            doc (Dict[str, Any]): The including document.
+
+        Returns:
+            List[Path]: The source folders.
+        """
+        result: List[Path] = []
+        for included in self.included_documents(doc):
+            result.extend(self.trlc_sources(included))
+        return result
+
+    def file_reference(self, value: str) -> Path:
+        # lobster-trace: SwRequirements.sw_req_trlc_conversion
+        # lobster-trace: SwRequirements.sw_req_builtin_converters
+        """Resolve a converter, translation or render configuration file reference.
+
+        Args:
+            value (str): 'builtin:<file>' or a path relative to the project root.
+
+        Returns:
+            Path: The absolute file path.
+        """
+        result = self.path(value)
+        if value.startswith(BUILTIN_PREFIX):
+            result = BUILTIN_DIR / value[len(BUILTIN_PREFIX):]
+        return result
+
+    def html_source(self, doc: Dict[str, Any]) -> Path:
+        # lobster-trace: SwRequirements.sw_req_document_types
+        """Resolve the HTML folder of a document of type html or command.
+
+        Args:
+            doc (Dict[str, Any]): Document of type html or command.
+
+        Returns:
+            Path: The HTML folder.
+        """
+        result = self.coverage_dir
+        if doc["type"] == "command":
+            result = self.path(doc["output"])
+        elif doc["source"] != TESTS_COVERAGE:
+            result = self.path(doc["source"])
+        return result
+
+    # Project ******************************************************************
+
+    @property
+    def repository(self) -> str:
+        # lobster-trace: SwRequirements.sw_req_project_settings
+        # lobster-trace: SwRequirements.sw_req_trace_report
+        """Configured repository URL or 'auto'."""
+        return self.project.get("repository", "auto")
+
+# Functions ********************************************************************
+
+
+def _check_references(cfg: Config) -> List[str]:
+    # lobster-trace: SwRequirements.sw_req_config_validation
+    # lobster-trace: SwRequirements.sw_req_output_folder
+    """Check the cross references, which the JSON schema cannot express.
+
+    Args:
+        cfg (Config): Schema validated configuration.
+
+    Returns:
+        List[str]: Error messages, empty if all references are valid.
+    """
+    errors: List[str] = []
+    doc_ids = [doc["id"] for doc in cfg.documents]
+    doc_types = {doc["id"]: doc["type"] for doc in cfg.documents}
+
+    for doc_id in sorted({doc_id for doc_id in doc_ids if doc_ids.count(doc_id) > 1}):
+        errors.append(f"documents: id '{doc_id}' is used more than once.")
+
+    for doc in cfg.documents:
+        errors.extend(_check_document(cfg, doc, doc_types))
+
+    if cfg.trace is not None:
+        errors.extend(_check_levels(cfg.trace["levels"], doc_types))
+
+    for key in ("conf", "index", "page_header"):
+        if key in cfg.html and not cfg.path(cfg.html[key]).is_file():
+            errors.append(f"html.{key}: file '{cfg.html[key]}' not found.")
+
+    if cfg.output.is_relative_to(PACKAGE_DIR):
+        errors.append("paths.output: must not be inside the trlcdoc package folder.")
+    # The clean step removes the output folder, so it must never contain the project.
+    if cfg.root.is_relative_to(cfg.output):
+        errors.append("paths.output: must not be the project root or one of its parents.")
+
+    return errors
+
+
+def _check_document(cfg: Config, doc: Dict[str, Any], doc_types: Dict[str, str]) -> List[str]:
+    # lobster-trace: SwRequirements.sw_req_config_validation
+    """Check the references of one document.
+
+    Args:
+        cfg (Config): Schema validated configuration.
+        doc (Dict[str, Any]): The document.
+        doc_types (Dict[str, str]): Document type per document id.
+
+    Returns:
+        List[str]: Error messages, empty if all references are valid.
+    """
+    errors: List[str] = []
+    where = f"documents[{doc['id']}]"
+
+    for inc in doc.get("include", []):
+        if doc_types.get(inc) not in TRLC_DOCUMENT_TYPES:
+            errors.append(f"{where}.include: '{inc}' is no document of type trlc or test_results.")
+
+    options = doc.get("pytrlcconverter", {})
+    files = {f"pytrlcconverter.converter.{fmt}": value for fmt, value in options.get("converter", {}).items()}
+    files.update({f"pytrlcconverter.{key}": options[key] for key in ("translation", "render_cfg") if key in options})
+    for key, value in files.items():
+        if not cfg.file_reference(value).is_file():
+            errors.append(f"{where}.{key}: file '{value}' not found.")
+
+    needs_tests = doc["type"] == "test_results" or doc.get("source") == TESTS_COVERAGE
+    if needs_tests and cfg.tests is None:
+        errors.append(f"{where}: needs a 'tests' section.")
+    if doc["type"] == "trace_report" and cfg.trace is None:
+        errors.append(f"{where}: type trace_report needs a 'trace' section.")
+    return errors
+
+
+def _check_levels(levels: List[Dict[str, Any]], doc_types: Dict[str, str]) -> List[str]:
+    # lobster-trace: SwRequirements.sw_req_config_validation
+    # lobster-trace: SwRequirements.sw_req_trace_levels
+    """Check the trace level references.
+
+    Args:
+        levels (List[Dict[str, Any]]): Configured trace levels.
+        doc_types (Dict[str, str]): Document type per document id.
+
+    Returns:
+        List[str]: Error messages, empty if all references are valid.
+    """
+    errors: List[str] = []
+    names = [level["name"] for level in levels]
+
+    for name in sorted({name for name in names if names.count(name) > 1}):
+        errors.append(f"trace.levels: name '{name}' is used more than once.")
+
+    for level in levels:
+        where = f"trace.levels[{level['name']}]"
+        if "document" in level and doc_types.get(level["document"]) not in TRLC_DOCUMENT_TYPES:
+            errors.append(f"{where}.document: '{level['document']}' is no document of type trlc or test_results.")
+        for key in ("trace_to", "requires"):
+            for target in level.get(key, []):
+                if target not in names:
+                    errors.append(f"{where}.{key}: level '{target}' is not defined.")
+    return errors
+
+
+def load_config(config_file: Path) -> Config:
+    # lobster-trace: SwRequirements.sw_req_config_file
+    # lobster-trace: SwRequirements.sw_req_config_validation
+    """Load and validate the project configuration.
+
+    Args:
+        config_file (Path): The trlcdoc YAML configuration file.
+
+    Returns:
+        Config: The validated configuration.
+
+    Raises:
+        TrlcdocError: If the file is missing or invalid.
+    """
+    if not config_file.is_file():
+        raise TrlcdocError(f"Configuration file {config_file} not found.")
+
+    with open(config_file, encoding="utf-8") as file:
+        data = yaml.safe_load(file)
+
+    with open(SCHEMA_FILE, encoding="utf-8") as file:
+        schema = json.load(file)
+
+    validator = jsonschema.Draft202012Validator(schema)
+    schema_errors = sorted(validator.iter_errors(data), key=lambda err: list(err.absolute_path))
+    if schema_errors:
+        messages = [f"{'/'.join(str(p) for p in err.absolute_path) or '<root>'}: {err.message}"
+                    for err in schema_errors]
+        raise TrlcdocError(f"{config_file} does not match the schema:\n  " + "\n  ".join(messages))
+
+    cfg = Config(data, config_file)
+    reference_errors = _check_references(cfg)
+    if reference_errors:
+        raise TrlcdocError(f"{config_file} has invalid settings:\n  " + "\n  ".join(reference_errors))
+
+    return cfg
+
+
+def find_config(start: Path) -> Path:
+    # lobster-trace: SwRequirements.sw_req_config_file
+    """Find the default configuration file trlcdoc.yaml in a folder or its parents.
+
+    Args:
+        start (Path): Folder to start the search in.
+
+    Returns:
+        Path: The configuration file, or start/trlcdoc.yaml if none was found.
+    """
+    candidates = [folder / "trlcdoc.yaml" for folder in (start, *start.parents)]
+    return next((file for file in candidates if file.is_file()), start / "trlcdoc.yaml")
+
+# Main *************************************************************************