/// All known pip configuration keys with their documentation, types, defaults, and sections.
/// Based on pip documentation: https://pip.pypa.io/en/stable/topics/configuration/

#[derive(Debug, Clone)]
#[allow(dead_code)]
pub enum ValueType {
    String,
    Bool,
    Integer,
    Url,
    Path,
    List,     // newline or space separated
    Duration, // seconds or "none"
    ByteSize,
}

#[derive(Debug, Clone)]
pub struct KeySchema {
    pub section: &'static str,
    pub key: &'static str,
    pub value_type: ValueType,
    pub default: Option<&'static str>,
    pub description: &'static str,
    pub example: Option<&'static str>,
    pub env_var: Option<&'static str>,
    pub deprecated: bool,
    pub deprecated_msg: Option<&'static str>,
}

pub fn all_keys() -> Vec<KeySchema> {
    vec![
        // ─── [global] ───────────────────────────────────────────────────────────────
        KeySchema {
            section: "global",
            key: "index-url",
            value_type: ValueType::Url,
            default: Some("https://pypi.org/simple"),
            description: "Base URL of the Python Package Index. pip uses this to search for packages.",
            example: Some("https://pypi.org/simple"),
            env_var: Some("PIP_INDEX_URL"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "extra-index-url",
            value_type: ValueType::List,
            default: None,
            description: "Extra URLs to search for packages. Searched after index-url. One URL per line.",
            example: Some("https://my.internal.pypi/simple"),
            env_var: Some("PIP_EXTRA_INDEX_URL"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "no-index",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Ignore package index (only looking at --find-links URLs).",
            example: Some("true"),
            env_var: Some("PIP_NO_INDEX"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "find-links",
            value_type: ValueType::List,
            default: None,
            description: "URLs or paths to search for packages, in addition to index. Can be a local dir or http URL.",
            example: Some("/path/to/local/packages"),
            env_var: Some("PIP_FIND_LINKS"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "trusted-host",
            value_type: ValueType::List,
            default: None,
            description: "Mark this host or host:port as trusted, even if it has no valid HTTPS certificate.",
            example: Some("pypi.example.com"),
            env_var: Some("PIP_TRUSTED_HOST"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "cert",
            value_type: ValueType::Path,
            default: None,
            description: "Path to alternate CA bundle file. Can be a file or a directory with hashed certificate files.",
            example: Some("/etc/ssl/certs/ca-certificates.crt"),
            env_var: Some("PIP_CERT"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "client-cert",
            value_type: ValueType::Path,
            default: None,
            description: "Path to SSL client certificate, a single file containing the private key and certificate in PEM format.",
            example: Some("/path/to/client.pem"),
            env_var: Some("PIP_CLIENT_CERT"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "proxy",
            value_type: ValueType::Url,
            default: None,
            description: "Specify a proxy in the form scheme://[user:passwd@]proxy.server:port.",
            example: Some("http://user:pass@proxy.example.com:8080"),
            env_var: Some("PIP_PROXY"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "timeout",
            value_type: ValueType::Integer,
            default: Some("15"),
            description: "Set the socket timeout (default 15 seconds).",
            example: Some("60"),
            env_var: Some("PIP_TIMEOUT"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "retries",
            value_type: ValueType::Integer,
            default: Some("5"),
            description: "Maximum number of retries each connection should attempt.",
            example: Some("3"),
            env_var: Some("PIP_RETRIES"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "quiet",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Give less output. Can be specified multiple times.",
            example: Some("true"),
            env_var: Some("PIP_QUIET"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "verbose",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Give more output. Can be specified multiple times.",
            example: Some("true"),
            env_var: Some("PIP_VERBOSE"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "log",
            value_type: ValueType::Path,
            default: None,
            description: "Path to a verbose appending log file.",
            example: Some("/var/log/pip.log"),
            env_var: Some("PIP_LOG"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "no-cache-dir",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Disable the pip cache.",
            example: Some("true"),
            env_var: Some("PIP_NO_CACHE_DIR"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "cache-dir",
            value_type: ValueType::Path,
            default: None,
            description: "Store the cache data in this directory.",
            example: Some("/home/user/.cache/pip"),
            env_var: Some("PIP_CACHE_DIR"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "disable-pip-version-check",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Don't periodically check PyPI to determine whether a new version of pip is available.",
            example: Some("true"),
            env_var: Some("PIP_DISABLE_PIP_VERSION_CHECK"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "require-virtualenv",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Allow pip to only run in a virtual environment; exit with an error otherwise.",
            example: Some("true"),
            env_var: Some("PIP_REQUIRE_VIRTUALENV"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "no-python-version-warning",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Silence deprecation warnings for upcoming unsupported Pythons.",
            example: Some("true"),
            env_var: Some("PIP_NO_PYTHON_VERSION_WARNING"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "progress-bar",
            value_type: ValueType::String,
            default: Some("on"),
            description: "Specify whether the progress bar should be used [on, off, ascii, pretty, emoji].",
            example: Some("off"),
            env_var: Some("PIP_PROGRESS_BAR"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "use-feature",
            value_type: ValueType::List,
            default: None,
            description: "Enable new functionality that may be backward incompatible.",
            example: Some("fast-deps"),
            env_var: Some("PIP_USE_FEATURE"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "no-build-isolation",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Disable isolation when building a modern source distribution.",
            example: Some("true"),
            env_var: Some("PIP_NO_BUILD_ISOLATION"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "use-pep517",
            value_type: ValueType::Bool,
            default: Some("true"),
            description: "Use PEP 517 for building source distributions (use --no-use-pep517 to disable).",
            example: Some("false"),
            env_var: Some("PIP_USE_PEP517"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "global",
            key: "check-build-dependencies",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Check the build dependencies when PEP517 is used.",
            example: Some("true"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },

        // ─── [install] ──────────────────────────────────────────────────────────────
        KeySchema {
            section: "install",
            key: "user",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Install to the Python user install directory (~/.local).",
            example: Some("true"),
            env_var: Some("PIP_USER"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "root",
            value_type: ValueType::Path,
            default: None,
            description: "Install everything relative to this alternate root directory.",
            example: Some("/tmp/installroot"),
            env_var: Some("PIP_ROOT"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "prefix",
            value_type: ValueType::Path,
            default: None,
            description: "Installation prefix where lib, bin and other top-level folders are placed.",
            example: Some("/usr/local"),
            env_var: Some("PIP_PREFIX"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "target",
            value_type: ValueType::Path,
            default: None,
            description: "Install packages into this directory. Overrides --prefix and --root.",
            example: Some("/tmp/target"),
            env_var: Some("PIP_TARGET"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "src",
            value_type: ValueType::Path,
            default: None,
            description: "Directory to check out editable projects into. Default: <current dir>/src.",
            example: Some("~/src"),
            env_var: Some("PIP_SRC"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "upgrade",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Upgrade all specified packages to the newest available version.",
            example: Some("true"),
            env_var: Some("PIP_UPGRADE"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "upgrade-strategy",
            value_type: ValueType::String,
            default: Some("only-if-needed"),
            description: "Determines how dependency upgrading is handled [only-if-needed, eager].",
            example: Some("eager"),
            env_var: Some("PIP_UPGRADE_STRATEGY"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "force-reinstall",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Reinstall all packages even if they are already up-to-date.",
            example: Some("true"),
            env_var: Some("PIP_FORCE_REINSTALL"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "ignore-installed",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Ignore the installed packages, overwriting them.",
            example: Some("true"),
            env_var: Some("PIP_IGNORE_INSTALLED"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "ignore-requires-python",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Ignore the Requires-Python information.",
            example: Some("true"),
            env_var: Some("PIP_IGNORE_REQUIRES_PYTHON"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "no-deps",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Don't install package dependencies.",
            example: Some("true"),
            env_var: Some("PIP_NO_DEPS"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "pre",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Include pre-release and development versions.",
            example: Some("true"),
            env_var: Some("PIP_PRE"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "dry-run",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Don't actually install anything, just print what would be installed.",
            example: Some("true"),
            env_var: Some("PIP_DRY_RUN"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "compile",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Compile Python source files to bytecode.",
            example: Some("true"),
            env_var: Some("PIP_COMPILE"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "no-compile",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Do not compile Python source files to bytecode.",
            example: Some("true"),
            env_var: Some("PIP_NO_COMPILE"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "require-hashes",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Require a hash to check each requirement against, for repeatable installs.",
            example: Some("true"),
            env_var: Some("PIP_REQUIRE_HASHES"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "install",
            key: "report",
            value_type: ValueType::Path,
            default: None,
            description: "Generate a JSON file describing what pip did to install the provided requirements.",
            example: Some("install-report.json"),
            env_var: Some("PIP_REPORT"),
            deprecated: false,
            deprecated_msg: None,
        },

        // ─── [download] ─────────────────────────────────────────────────────────────
        KeySchema {
            section: "download",
            key: "dest",
            value_type: ValueType::Path,
            default: None,
            description: "Download packages into this directory.",
            example: Some("./downloads"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "download",
            key: "no-deps",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Don't download package dependencies.",
            example: Some("true"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },

        // ─── [freeze] ───────────────────────────────────────────────────────────────
        KeySchema {
            section: "freeze",
            key: "all",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Do not skip these packages in the output: setuptools, distribute, pip, wheel.",
            example: Some("true"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "freeze",
            key: "local",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "If in a virtualenv that has global access, do not output globally-installed packages.",
            example: Some("true"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "freeze",
            key: "exclude-editable",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Exclude editable package from output.",
            example: Some("true"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "freeze",
            key: "exclude",
            value_type: ValueType::List,
            default: None,
            description: "Exclude specified package from the output.",
            example: Some("setuptools\nwheels"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },

        // ─── [list] ─────────────────────────────────────────────────────────────────
        KeySchema {
            section: "list",
            key: "format",
            value_type: ValueType::String,
            default: Some("columns"),
            description: "Select the output format [columns, freeze, json].",
            example: Some("json"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "list",
            key: "outdated",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "List outdated packages.",
            example: Some("true"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "list",
            key: "uptodate",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "List up-to-date packages.",
            example: Some("true"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "list",
            key: "local",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "If in a virtualenv, do not output globally-installed packages.",
            example: Some("true"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "list",
            key: "user",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Only output packages installed in user-site.",
            example: Some("true"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "list",
            key: "exclude",
            value_type: ValueType::List,
            default: None,
            description: "Exclude specified package from the output.",
            example: Some("pip"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },

        // ─── [wheel] ────────────────────────────────────────────────────────────────
        KeySchema {
            section: "wheel",
            key: "wheel-dir",
            value_type: ValueType::Path,
            default: None,
            description: "Build wheels into this directory. Defaults to current directory.",
            example: Some("./wheels"),
            env_var: Some("PIP_WHEEL_DIR"),
            deprecated: false,
            deprecated_msg: None,
        },
        KeySchema {
            section: "wheel",
            key: "no-deps",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Don't build wheels for dependencies.",
            example: Some("true"),
            env_var: None,
            deprecated: false,
            deprecated_msg: None,
        },

        // ─── [uninstall] ────────────────────────────────────────────────────────────
        KeySchema {
            section: "uninstall",
            key: "yes",
            value_type: ValueType::Bool,
            default: Some("false"),
            description: "Don't ask for confirmation of uninstall deletions.",
            example: Some("true"),
            env_var: Some("PIP_YES"),
            deprecated: false,
            deprecated_msg: None,
        },

        // ─── [search] ───────────────────────────────────────────────────────────────
        KeySchema {
            section: "search",
            key: "index",
            value_type: ValueType::Url,
            default: Some("https://pypi.org/pypi"),
            description: "Base URL of the Python Package Index for 'pip search'.",
            example: Some("https://pypi.org/pypi"),
            env_var: Some("PIP_INDEX"),
            deprecated: false,
            deprecated_msg: None,
        },
    ]
}

/// Lookup schema for a key in a section
pub fn find_key(section: &str, key: &str) -> Option<KeySchema> {
    all_keys()
        .into_iter()
        .find(|k| k.section == section && k.key == key)
}

/// All valid sections
pub fn sections() -> Vec<&'static str> {
    vec![
        "global",
        "install",
        "download",
        "freeze",
        "list",
        "wheel",
        "uninstall",
        "search",
    ]
}

/// Known pip-related environment variables (beyond per-key vars)
pub fn pip_env_vars() -> Vec<(&'static str, &'static str)> {
    vec![
        ("PIP_CONFIG_FILE", "Override the config file path"),
        ("PIP_INDEX_URL", "Override index-url"),
        ("PIP_EXTRA_INDEX_URL", "Override extra-index-url"),
        ("PIP_TRUSTED_HOST", "Mark hosts as trusted"),
        ("PIP_PROXY", "HTTP proxy"),
        ("PIP_TIMEOUT", "Socket timeout"),
        ("PIP_RETRIES", "Retry count"),
        ("PIP_CERT", "CA bundle path"),
        ("PIP_CLIENT_CERT", "Client certificate"),
        ("PIP_CACHE_DIR", "Cache directory"),
        ("PIP_NO_CACHE_DIR", "Disable cache"),
        ("PIP_DISABLE_PIP_VERSION_CHECK", "Disable version check"),
        ("PIP_REQUIRE_VIRTUALENV", "Require virtualenv"),
        ("PIP_DEFAULT_TIMEOUT", "Default timeout (legacy alias)"),
        ("PIP_VERBOSE", "Verbosity level"),
        ("PIP_QUIET", "Quiet output"),
        ("PIP_LOG", "Log file path"),
        ("VIRTUAL_ENV", "Active virtual environment"),
        ("CONDA_PREFIX", "Active conda environment"),
        ("PIP_NO_INDEX", "Disable index"),
        ("PIP_FIND_LINKS", "Local/extra find-links path"),
        ("PIP_USE_FEATURE", "Enable experimental features"),
        ("PIP_UPGRADE_STRATEGY", "Upgrade strategy"),
        ("PIP_REQUIRE_HASHES", "Require package hashes"),
        ("PIP_PROGRESS_BAR", "Progress bar display mode"),
        ("PIP_SRC", "Source checkout directory"),
        ("PIP_REPORT", "Install report JSON path"),
        ("HTTPS_PROXY", "HTTPS proxy (system-level)"),
        ("HTTP_PROXY", "HTTP proxy (system-level)"),
        ("NO_PROXY", "No-proxy hosts"),
        ("SSL_CERT_FILE", "SSL certificate bundle (OpenSSL)"),
        ("REQUESTS_CA_BUNDLE", "CA bundle for requests library"),
    ]
}
