"""Deferred physical resource type definitions for the Resource Registry.

Contains the built-in deferred physical type entries (git object taxonomy
and filesystem link types) that are appended to ``BUILTIN_TYPES`` in
``_resource_registry_data``.  Extracted to keep each module under the
500-line CONTRIBUTING limit.

.. note::

    This is an **internal** module (``_``-prefixed).  External code
    should import ``BUILTIN_TYPES`` from ``_resource_registry_data``
    instead.
"""

from __future__ import annotations

from typing import Any

__all__ = ["DEFERRED_PHYSICAL_TYPES"]

# === Deferred Physical Resource Types (#330) ===
#
# Git object taxonomy (9 types) and filesystem link types (2 types).
# Auto-discovery rules use bounded scan_depth (1-3) to prevent
# unbounded traversal.  Types without discovery are leaf nodes.

DEFERRED_PHYSICAL_TYPES: list[dict[str, Any]] = [
    {
        "name": "git",
        "description": (
            "A git repository \u2014 the object database, refs, and full history."
        ),
        "resource_kind": "physical",
        "sandbox_strategy": "none",
        "user_addable": True,
        "built_in": True,
        "cli_args": [
            {
                "name": "path",
                "type": "path",
                "required": False,
                "description": "Path to the local .git directory.",
                "default": None,
            },
            {
                "name": "url",
                "type": "string",
                "required": False,
                "description": "Remote URL of the git repository.",
                "default": None,
            },
        ],
        "parent_types": ["git-checkout"],
        "child_types": [
            "git-remote",
            "git-branch",
            "git-tag",
            "git-commit",
            "git-stash",
            "git-submodule",
        ],
        "auto_discovery": {
            "enabled": True,
            "scan_depth": 1,
            "rules": [
                {"type": "git-remote", "pattern": "refs/remotes/*"},
                {"type": "git-branch", "pattern": "refs/heads/*"},
                {"type": "git-tag", "pattern": "refs/tags/*"},
                {"type": "git-stash", "pattern": "refs/stash"},
                {"type": "git-submodule", "pattern": ".gitmodules"},
            ],
        },
        "handler": "cleveragents.resource.handlers.git:GitHandler",
        "capabilities": {
            "read": True,
            "write": False,
            "sandbox": False,
            "checkpoint": False,
        },
    },
    {
        "name": "git-remote",
        "description": (
            "A remote URL configured on a git repo "
            "(e.g., origin \u2192 https://github.com/org/repo)."
        ),
        "resource_kind": "physical",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": ["git"],
        "child_types": [],
        "handler": "cleveragents.resource.handlers.git:GitConfigHandler",
        "capabilities": {
            "read": True,
            "write": False,
            "sandbox": False,
            "checkpoint": False,
        },
    },
    {
        "name": "git-branch",
        "description": "A named branch ref (e.g., main, feature/auth).",
        "resource_kind": "physical",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": ["git"],
        "child_types": ["git-commit"],
        "auto_discovery": {
            "enabled": True,
            "scan_depth": 1,
            "rules": [
                {"type": "git-commit", "pattern": "HEAD"},
            ],
        },
        "handler": "cleveragents.resource.handlers.git:GitRefHandler",
        "capabilities": {
            "read": True,
            "write": True,
            "sandbox": False,
            "checkpoint": False,
        },
    },
    {
        # NOTE: git-tag has no auto_discovery (unlike git-branch) because
        # tags are passive refs — they point to a commit but don't "own"
        # children that need discovery.  The tag→commit relationship is
        # expressed via child_types only.
        "name": "git-tag",
        "description": "A tag ref \u2014 lightweight or annotated (e.g., v1.0.0).",
        "resource_kind": "physical",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": ["git"],
        # Spec S23518 omits git-commit as child of git-tag, but annotated tags
        # target commits directly.  Added for DAG consistency with git-commit
        # listing git-tag as a parent.
        # NOTE: This is NOT a cycle — git-tag is a parent of git-commit
        # (tag -> commit), and git-commit lists git-tag as parent (commit
        # can be reached FROM a tag).  The DAG remains acyclic.
        "child_types": ["git-commit"],
        "handler": "cleveragents.resource.handlers.git:GitRefHandler",
        "capabilities": {
            "read": True,
            "write": True,
            "sandbox": False,
            "checkpoint": False,
        },
    },
    {
        "name": "git-commit",
        "description": "A specific commit object.",
        "resource_kind": "physical",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        # Spec S23518 omits git-tag as parent; added because annotated tags
        # target commits directly, so the relationship is semantically correct.
        "parent_types": ["git-branch", "git-tag", "git"],
        "child_types": ["git-tree"],
        "auto_discovery": {
            "enabled": True,
            "scan_depth": 1,
            "rules": [
                {"type": "git-tree", "pattern": "tree"},
            ],
        },
        "handler": "cleveragents.resource.handlers.git:GitObjectHandler",
        "capabilities": {
            "read": True,
            "write": False,
            "sandbox": False,
            "checkpoint": False,
        },
    },
    {
        "name": "git-tree",
        "description": "A tree object \u2014 a directory listing at a specific commit.",
        "resource_kind": "physical",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": ["git-commit", "git-tree"],
        "child_types": ["git-tree-entry", "git-tree"],
        # WARNING: git-tree is a recursive type (tree -> subtree -> ...).
        # scan_depth is capped at 2 to prevent expensive traversal on
        # large repositories (e.g. Linux kernel ~70k tree entries).
        # The discovery engine MUST enforce a global max_depth cap.
        "auto_discovery": {
            "enabled": True,
            "scan_depth": 2,
            "rules": [
                {"type": "git-tree-entry", "pattern": "blob *"},
                {"type": "git-tree", "pattern": "tree *"},
            ],
        },
        "handler": "cleveragents.resource.handlers.git:GitObjectHandler",
        "capabilities": {
            "read": True,
            "write": False,
            "sandbox": False,
            "checkpoint": False,
        },
    },
    {
        "name": "git-tree-entry",
        "description": (
            "A blob entry in a tree \u2014 a specific file's content "
            "at a specific path and mode."
        ),
        "resource_kind": "physical",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": ["git-tree"],
        "child_types": [],
        "handler": "cleveragents.resource.handlers.git:GitObjectHandler",
        "capabilities": {
            "read": True,
            "write": False,
            "sandbox": False,
            "checkpoint": False,
        },
    },
    {
        "name": "git-stash",
        "description": "A stash entry (e.g., stash@{0}).",
        "resource_kind": "physical",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": ["git"],
        "child_types": [],
        "handler": "cleveragents.resource.handlers.git:GitRefHandler",
        "capabilities": {
            "read": True,
            "write": True,
            "sandbox": False,
            "checkpoint": False,
        },
    },
    {
        "name": "git-submodule",
        "description": (
            "A submodule reference \u2014 a pointer to another git "
            "repository at a specific commit and path."
        ),
        "resource_kind": "physical",
        "sandbox_strategy": "none",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": ["git"],
        "child_types": [],
        "handler": "cleveragents.resource.handlers.git:GitConfigHandler",
        "capabilities": {
            "read": True,
            "write": False,
            "sandbox": False,
            "checkpoint": False,
        },
    },
    {
        "name": "fs-symlink",
        "description": "A symbolic link on the local filesystem.",
        "resource_kind": "physical",
        "sandbox_strategy": "copy_on_write",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": ["fs-directory"],
        "child_types": [],
        "handler": "cleveragents.resource.handlers.fs_file:FilesystemHandler",
        "capabilities": {
            "read": True,
            "write": False,
            "sandbox": False,
            "checkpoint": False,
        },
    },
    {
        "name": "fs-hardlink",
        "description": (
            "A hard link on the local filesystem \u2014 a file with link count > 1."
        ),
        "resource_kind": "physical",
        "sandbox_strategy": "copy_on_write",
        "user_addable": False,
        "built_in": True,
        "cli_args": [],
        "parent_types": ["fs-directory"],
        "child_types": [],
        "handler": "cleveragents.resource.handlers.fs_file:FilesystemHandler",
        "capabilities": {
            "read": True,
            "write": True,
            "sandbox": False,
            "checkpoint": False,
        },
    },
]
