config¶

def resolve_base_css(css_path: Path | None, project_root: Path) -> str:
    """Return the base stylesheet compiled into the ODD's generated CSS.

    ``[transform] css`` / ``--css`` replaces the packaged default wholesale — it
    is an override for the rules the runtime's markup needs, not an extra layer.
    Project design CSS belongs in ``[transform.web] assets`` instead, where it can
    sit beside the images and fonts it references.
    """
    from opm.odd_compiler.css_generator import default_base_css

    if css_path is not None:
        path = css_path if css_path.is_absolute() else project_root / css_path
        if not path.is_file():
            # Silently returning '' here would drop every base rule — the
            # popover and column-break styles included — for a typo.
            raise FileNotFoundError(f'Stylesheet not found: {path}')
        return path.read_text(encoding='utf-8')

    local = project_root / 'styles' / 'default-styles.css'
    if local.is_file():
        return local.read_text(encoding='utf-8')

    return default_base_css()

def load_project_config(path: Path | None = None) -> ProjectConfig:
    """Load ``opm.toml`` from *path* or CWD; return defaults if absent."""
    config_path = path if path is not None else Path(CONFIG_FILENAME)
    if not config_path.is_file():
        return ProjectConfig()

    with config_path.open('rb') as f:
        data = tomllib.load(f)

    transform = _section_table(data.get('transform'))
    chunking_tables = _chunking_tables(data.get('chunking'))
    index_data = _section_table(data.get('index'))
    project_data = _section_table(data.get('project'))
    document_data = data.get('document')

    # Per-type tables: prefer [transform.<type>], accept legacy top-level [<type>].
    type_sections = {
        type_name: _resolve_type_section(transform, data, type_name)
        for type_name in CONFIG_SECTIONS
    }
    docx_data = type_sections['docx']
    typst_data = type_sections['typst']
    print_data = type_sections['print']
    epub_data = type_sections['epub']
    web_data = type_sections['web']
    webcomponents_enabled = web_data.get('webcomponents')
    if webcomponents_enabled is not None and not isinstance(webcomponents_enabled, bool):
        raise ValueError('opm.toml: transform.web.webcomponents must be a boolean')

    raw_context = data.get('context', {})
    if not isinstance(raw_context, dict):
        raise ValueError('opm.toml: [context] must be a table')
    # Values are handed to Jinja2 untouched: whatever TOML can express, a
    # template can read. No coercion, no key whitelist.
    template_context = dict(raw_context)
    template_context_by_type = {
        type_name: dict(_section_table(section.get('context')))
        for type_name, section in type_sections.items()
        if _section_table(section.get('context'))
    }

    # The HTML shell only wraps web output, so it lives with the other per-type
    # templates; the base CSS is compiled into every type's ODD stylesheet, so
    # it is shared.
    template = web_data.get('template')
    document_template = config_path.parent / str(template) if template else None
    web_pages = web_data.get('pages')
    if web_pages is not None and not isinstance(web_pages, str):
        raise ValueError('opm.toml: transform.web.pages must be a dotted Python path')
    web_assets = tuple(
        config_path.parent / str(asset) for asset in (web_data.get('assets') or ())
    )
    css_file = transform.get('css')
    if css_file is not None and not isinstance(css_file, str):
        raise ValueError('opm.toml: transform.css must be a path string')
    docx_template_file = docx_data.get('template')
    typst_template_file = typst_data.get('template')
    print_template_file = print_data.get('template')
    epub_css_file = epub_data.get('css')
    raw_xpath_extensions = transform.get('xpath_extensions')
    xpath_extensions: tuple[str, ...]
    if raw_xpath_extensions is None:
        xpath_extensions = ()
    elif isinstance(raw_xpath_extensions, str):
        xpath_extensions = (raw_xpath_extensions,)
    elif isinstance(raw_xpath_extensions, list):
        xpath_extensions = tuple(str(item) for item in raw_xpath_extensions)
    else:
        raise ValueError(
            'opm.toml: transform.xpath_extensions must be a string or list of strings',
        )

    footnote_order = transform.get('footnote_order')
    if footnote_order is not None and not isinstance(footnote_order, str):
        raise ValueError(
            'opm.toml: transform.footnote_order must be the dotted path of a callable, '
            'e.g. "opm.runtime.footnote_order.labelled_first"',
        )

    raw_xpath_documents = transform.get('documents', [])
    if isinstance(raw_xpath_documents, str):
        raw_xpath_documents = [raw_xpath_documents]
    elif not isinstance(raw_xpath_documents, list):
        raise ValueError(
            'opm.toml: transform.documents must be a string or list of strings',
        )
    xpath_documents = tuple(config_path.parent / str(path) for path in raw_xpath_documents)

    raw_collections = transform.get('collections', [])
    if isinstance(raw_collections, dict):
        raw_collections = [raw_collections]
    elif not isinstance(raw_collections, list):
        raise ValueError(
            'opm.toml: transform.collections must be an array of tables',
        )
    collections: list[CollectionConfig] = []
    for entry in raw_collections:
        if not isinstance(entry, dict):
            raise ValueError('opm.toml: each transform.collections entry must be a table')
        uri = str(entry.get('uri', '')).strip()
        if not uri:
            raise ValueError('opm.toml: transform.collections entry is missing "uri"')
        parts = urlsplit(uri)
        if not parts.scheme and not parts.netloc and not parts.path.startswith('/'):
            raise ValueError(
                f'opm.toml: transform.collections uri {uri!r} must be absolute — a relative '
                'URI resolves against each source document, so it would not match reliably',
            )
        raw_members = entry.get('documents', [])
        if isinstance(raw_members, str):
            raw_members = [raw_members]
        elif not isinstance(raw_members, list):
            raise ValueError(
                f'opm.toml: transform.collections["{uri}"].documents must be a string or list',
            )
        collections.append(
            CollectionConfig(
                uri=uri,
                documents=tuple(config_path.parent / str(p) for p in raw_members),
            ),
        )

    raw_namespaces = transform.get('namespaces', {})
    if not isinstance(raw_namespaces, dict):
        raise ValueError('opm.toml: transform.namespaces must be a table of prefix = uri')
    xpath_namespaces: dict[str, str] = {}
    for prefix, uri in raw_namespaces.items():
        if not isinstance(uri, str):
            raise ValueError(
                f'opm.toml: transform.namespaces["{prefix}"] must be a namespace URI string',
            )
        xpath_namespaces[str(prefix)] = uri

    raw_variables = transform.get('variables', {})
    if not isinstance(raw_variables, dict):
        raise ValueError('opm.toml: transform.variables must be a table')
    xpath_variables: dict[str, Any] = {}

    def _scalar(value: Any, where: str) -> Any:
        # Keep TOML scalars typed. Stringifying a boolean is actively wrong:
        # ``str(False)`` is 'False', a non-empty string, whose effective boolean
        # value in XPath is *true* — so ``if ($global:address-by-id)`` would take
        # the wrong branch for ``address-by-id = false``.
        if isinstance(value, (bool, int, float, str)):
            return value
        raise ValueError(f'opm.toml: {where} must be a string, number or boolean')

    for key, entries in raw_variables.items():
        if not isinstance(entries, dict):
            # A scalar straight under [transform.variables] is a variable in no
            # namespace, referenced as ``$name``.
            xpath_variables[str(key)] = _scalar(entries, f'transform.variables.{key}')
            continue
        # A sub-table groups variables by the namespace *prefix* declared in
        # [transform.namespaces], so the URI is written once. A key that is
        # itself a URI is still accepted, for a namespace used only here.
        if ':' in key or '/' in key:
            namespace = str(key)
        else:
            namespace = xpath_namespaces.get(str(key), '')
            if not namespace:
                known = ', '.join(sorted(xpath_namespaces)) or '(none declared)'
                raise ValueError(
                    f'opm.toml: transform.variables.{key} — prefix "{key}" is not declared in '
                    f'[transform.namespaces]. Declared prefixes: {known}',
                )
        for local_name, value in entries.items():
            where = f'transform.variables.{key}.{local_name}'
            # Clark notation: elementpath accepts it directly as a variable key.
            clark = f'{{{namespace}}}{local_name}' if namespace else str(local_name)
            xpath_variables[clark] = _scalar(value, where)

    raw_parameters = transform.get('parameters', {})
    if not isinstance(raw_parameters, dict):
        raise ValueError('opm.toml: transform.parameters must be a table')
    # Nested [transform.<type>] tables are also dict values; only keep scalar params.
    parameters = {
        str(key): str(value)
        for key, value in raw_parameters.items()
        if not isinstance(value, dict)
    }

    chunking_runs = [
        _parse_chunking(table, config_path) for table in chunking_tables
    ]
    _check_run_output_dirs(chunking_runs, chunking_tables)

    raw_pythonpath = project_data.get('pythonpath', [])
    if isinstance(raw_pythonpath, str):
        raw_pythonpath = [raw_pythonpath]
    pythonpath = tuple(config_path.parent / p for p in raw_pythonpath)

    raw_default_odd = transform.get('odd')
    transform_odd = (
        config_path.parent / str(raw_default_odd) if raw_default_odd else None
    )

    transform_odds: dict[str, Path] = {}
    for type_name, section in type_sections.items():
        raw_type_odd = section.get('odd')
        if raw_type_odd:
            transform_odds[type_name] = config_path.parent / str(raw_type_odd)

    # Legacy convenience: [transform.web].odd alone still acts as the default
    # when [transform].odd is omitted (keeps transform_odd / chunking fallbacks).
    if transform_odd is None:
        transform_odd = transform_odds.get('web')

    # Chunking inherits the shared transform ODD when [chunking].odd is omitted.
    if transform_odd is not None:
        chunking_runs = [
            replace(run, odd=transform_odd) if run.odd is None else run
            for run in chunking_runs
        ]
    # Chunk pages are web pages: a run without its own template or assets
    # uses the [transform.web] ones.
    chunking_runs = [
        replace(
            run,
            template=run.template or document_template,
            assets=run.assets if 'assets' in table else web_assets,
        )
        for run, table in zip(chunking_runs, chunking_tables)
    ]
    chunking = chunking_runs[0] if chunking_runs else None

    index_fields = _index_fields(index_data)
    _check_index_fragment_fields(index_fields, chunking_runs)

    return ProjectConfig(
        webcomponents_enabled=webcomponents_enabled,
        template_context=template_context,
        template_context_by_type=template_context_by_type,
        document_template=document_template,
        web_assets=web_assets,
        web_pages=web_pages,
        document_css=config_path.parent / str(css_file) if css_file else None,
        document_docx_template=config_path.parent / docx_template_file if docx_template_file else None,
        typst_template=config_path.parent / typst_template_file if typst_template_file else None,
        print_template=(
            config_path.parent / str(print_template_file) if print_template_file else None
        ),
        epub_css=config_path.parent / str(epub_css_file) if epub_css_file else None,
        epub_skip_title=bool(epub_data.get('skip_title', False)),
        epub_chunk_overrides={
            key: epub_data[key]
            for key in ('xpath', 'selector', 'depth')
            if key in epub_data
        },
        xpath_extensions=xpath_extensions,
        footnote_order=footnote_order,
        xpath_documents=xpath_documents,
        xpath_collections=tuple(collections),
        xpath_variables=xpath_variables,
        xpath_namespaces=xpath_namespaces,
        parameters=parameters,
        chunking=chunking,
        chunking_runs=tuple(chunking_runs),
        document=_document_config(document_data, config_path),
        index_max_chars=int(index_data.get('max_chars', 1500)),
        index_min_chars=int(index_data.get('min_chars', 40)),
        index_overlap=int(index_data.get('overlap', 1)),
        index_fields=index_fields,
        index_units=_index_units(index_data),
        pythonpath=pythonpath,
        transform_odd=transform_odd,
        transform_odds=transform_odds,
    )