# Layering contracts for mgf.common — enforces the dependency
# direction documented in docs/standards/DESIGN_PRINCIPLES.md
# (rule DP-01) and the lift-readiness rule (LIFT-1) from
# docs/STANDARD_GAP.md.
#
# Run locally:      lint-imports
# Run in CI:        see .woodpecker.yml lint step
#
# Adding contracts? Each contract is phrased as a hard MUST NOT —
# import-linter fails the CI build on any violation. When adding a
# new rule, add a ``reason = ...`` comment so a future engineer
# (or AI) knows why it exists before deciding to relax it.

[importlinter]
root_packages =
    mgf.common
# Required because the contracts below name external packages
# (vmanager, mgf-* siblings, future consumer namespaces) as
# forbidden — without this flag, import-linter refuses to start.
include_external_packages = True

# ---------------------------------------------------------------------------
# Contract 1 — mgf.common is the federation leaf.
#
# Reason: mgf.common is the SHARED library that every consumer
# project depends on. The dependency direction MUST be one-way:
# consumers (vmanager, future siblings, future projects) depend
# on mgf.common, NEVER the reverse. Without this contract, a
# casual ``import vmanager.X`` inside mgf.common would create a
# cycle that breaks every other consumer.
#
# Federation policy (v0.4 Phase G1):
# Every consumer or sibling package gets a row below — independent
# downstream projects (vmanager and future open-source consumers)
# AND future siblings under the mgf.* PEP 420 namespace
# (mgf.qt / mgf.providers / mgf.cli when they materialize). The
# import direction always points OUT OF mgf.common; this contract
# forbids the reverse.
#
# Adding a new consumer? Add a row to ``forbidden_modules`` AND
# update docs/standards/DESIGN_PRINCIPLES.md to mention it as a
# known consumer of mgf.common.
#
# Why not a wildcard "deny all imports except deps"? import-linter
# doesn't support that directly. The pragmatic shape: enumerate
# known consumers + siblings. False negatives (a brand-new
# consumer not in this list) are caught by code review +
# integration testing on the consumer side.
# ---------------------------------------------------------------------------

[importlinter:contract:mgf-common-is-the-federation-leaf]
name = mgf.common does not import any consumer or sibling project
type = forbidden
source_modules =
    mgf.common
forbidden_modules =
    # Known consumer projects (top-level names)
    vmanager
    # Reserved sibling slots under the mgf.* namespace.
    # NOTE: import-linter rejects "subpackages of external
    # packages" in forbidden_modules. Future siblings register
    # themselves as top-level packages on PyPI (mgf-qt, mgf-cli,
    # mgf-providers); the importable name (mgf.qt / mgf.cli /
    # mgf.providers) is what we forbid here. When a sibling
    # actually ships, uncomment its line + add a row to
    # docs/CLAUDE.md "Federation siblings" + open a CONSUMERS
    # entry referencing it.
    # mgf.cli
    # mgf.qt
    # mgf.providers
    # mgf.gui
