Crate deps_core 

Core abstractions for deps-lsp.

This crate provides the foundational traits and utilities used across all ecosystem-specific implementations (Cargo, npm, PyPI, etc.).

Architecture

deps-core defines:

• Traits: Registry, Version, Metadata, Ecosystem, ParseResult
• HTTP Cache: Shared caching layer with ETag/Last-Modified validation
• Error Types: Unified error handling across all ecosystems

API stability (issue #769)

Most public structs and enums here are #[non_exhaustive] so a new field or variant never breaks a downstream ecosystem crate’s exhaustive match or struct literal. This is a per-kind decision, not one policy for both: on a struct with no pub fields, #[non_exhaustive] is a semantic no-op (an external crate can’t literal-construct or destructure it either way), so such structs are deliberately left exhaustive instead. On an enum, #[non_exhaustive] always forces a downstream match to carry a wildcard arm, regardless of any variant’s field visibility — each enum opts in when that forced wildcard is wanted and stays exhaustive when a future variant should instead be a compile error downstream; see the individual enum’s own doc comment for which applies.

A few pre-1.0 dependency types remain visible in public signatures as a deliberate semver commitment rather than an oversight:

• error::SanitizedRegistryError implements From<reqwest::Error> — a reqwest major bump that reshapes Error is a breaking change for this crate too.
• parser::yaml_scalar_string takes &yaml_rust2::Yaml; yaml_rust2 is re-exported from the crate root so callers can name the type without their own direct dependency, and a yaml-rust2 major bump is likewise a breaking change here.
• deps-gitlab-ci’s gitlab_version_req (crates/deps-gitlab-ci/src/component.rs) returns semver::VersionReq directly — low risk since semver is unusually stable pre-1.0, but the same commitment applies.
• cache_policy takes/returns &dashmap::DashMap<K, V> in its public functions; this is not new coupling — registry::register_capped_with_occupied already exposes &DashMap publicly without a pub use dashmap — so a dashmap major bump is already a breaking change here regardless of this module’s visibility.

LSP type stability (issue #832, narrowed by #1071 and #1083)

tower-lsp-server is pinned pre-1.0, so a tower-lsp-server minor bump (e.g. 0.23 → 0.24) is not an implementation detail this crate can absorb silently — it forces a breaking release of deps-core: a minor version bump while deps-core itself remains pre-1.0, a major version bump once deps-core reaches 1.0. This section describes which parts of the public API still carry that coupling.

As of issue #1071, a dependency’s own domain data never carried it in the first place: ecosystem::Dependency’s range accessors return position::Range, and ecosystem::ParseResult::uri / ecosystem::Ecosystem::parse_manifest use url::Url — neither names a tower-lsp-server type.

As of issue #1083, the remaining response-shaped surface — generate_hover, generate_diagnostics (retyped to the protocol-agnostic diagnostic::Diagnostic, not merely gated), generate_code_actions, generate_code_lenses, generate_inlay_hints, generate_document_links, generate_completions/complete_version/ complete_package_name/complete_feature, and the [completion] module itself — is gated behind the lsp-responses Cargo feature, along with the tower-lsp-server dependency it requires. The feature is not part of this crate’s default set: Cargo does not allow a workspace = true dependency edge to turn off a feature that a crate defaults on, so making it default here would make it inescapable for deps-engine (see deps-engine/Cargo.toml’s own lsp-responses feature doc) — every consumer that wants it, including each of the 14 deps-<ecosystem> crates via their own identically-named feature, must request deps-core/lsp-responses explicitly (deps-lsp does, directly and via deps-engine; deps-cli never does). Under --no-default-features (or with lsp-responses otherwise off), deps-core links no tower-lsp-server code at all, [tower_lsp_server] is not re-exported, and an ecosystem crate’s Ecosystem impl simply doesn’t declare the gated trait methods (the trait itself omits them when the feature is off, so there is nothing to implement) — this is FR-001/SC-001’s mechanism for keeping deps-cli’s dependency tree free of tower-lsp-server entirely (verified by cargo tree -p deps-cli -e features,no-dev in CI).

Downstream consumers implementing ecosystem::Ecosystem with lsp-responses enabled should depend on the exact matching tower-lsp-server version through the [tower_lsp_server] re-export rather than adding their own separate direct dependency, which could otherwise drift out of sync with the version deps-core was built against. deps-core’s own lsp_helpers converts a position::Position/position::Range into its ls_types equivalent internally via their From impls wherever one must be embedded in a gated response.

Whether the rest of deps-core’s public API should stop naming third-party dependency types generally (reqwest::Error, yaml_rust2::Yaml, …) is issue #851’s broader, still- open question — out of scope for #1071/#1083.

Re-exports

pub use cache::BodyLimit;

pub use cache::CachedResponse;

pub use cache::HttpCache;

pub use dependency_cap::DependencyBudget;

pub use dependency_cap::MAX_DEPENDENCIES_PER_DOCUMENT;

pub use deps_dev::DepsDevClient;

pub use deps_dev::ProvenanceStatus;

pub use deps_dev::ScorecardSummary;

pub use deps_dev::SupplyChainTrustSignal;

pub use ecosystem::BlockedRegistryOccurrence;

pub use ecosystem::BlockedSourceClass;

pub use ecosystem::Dependency;

pub use ecosystem::Ecosystem;

pub use ecosystem::EcosystemConfig;

pub use ecosystem::EcosystemId;

pub use ecosystem::LicenseSource;

pub use ecosystem::ParseResult;

pub use ecosystem::parse_manifest_blocking;

pub use ecosystem_registry::EcosystemRegistry;

pub use error::DepsError;

pub use error::FetchFailure;

pub use error::Result;

pub use freshness::DEFAULT_COOLDOWN_SECS;

pub use freshness::FreshnessSettings;

pub use freshness::PublishTime;

pub use freshness::format_relative_age;

pub use freshness::is_within_cooldown;

pub use json_ast::JsonAst;

pub use json_ast::JsonSection;

pub use json_ast::find_last_prop;

pub use json_helpers::string_valued_entries;

pub use licenses::LicensePolicy;

pub use licenses::LicenseViolation;

pub use licenses::MAX_POM_LICENSE_NAME_RAW_CHARS;

pub use licenses::ViolationReason;

pub use licenses::evaluate as evaluate_license_policy;

pub use licenses::resolve_license_entries;

pub use lockfile::LockFileProvider;

pub use lockfile::ResolvedPackage;

pub use lockfile::ResolvedPackages;

pub use lockfile::ResolvedSource;

pub use lockfile::read_and_parse_lockfile;

pub use lockfile::read_lockfile_content;

pub use lsp_helpers::DependencyOutcome;

pub use lsp_helpers::DependencyOutcomes;

pub use lsp_helpers::DiagnosticMessages;

pub use lsp_helpers::DiagnosticPolicy;

pub use lsp_helpers::DiagnosticSeverities;

pub use lsp_helpers::EcosystemFormatter;

pub use lsp_helpers::HOVER_RECENT_VERSIONS;

pub use lsp_helpers::LICENSE_POLICY_VIOLATION_DIAGNOSTIC_CODE;

pub use lsp_helpers::LineOffsetTable;

pub use lsp_helpers::OsvNaming;

pub use lsp_helpers::PackageNaming;

pub use lsp_helpers::PackageRendering;

pub use lsp_helpers::PackageVersions;

pub use lsp_helpers::RequirementMatcher;

pub use lsp_helpers::RequirementResolution;

pub use lsp_helpers::RequirementStatus;

pub use lsp_helpers::SourcePolicy;

pub use lsp_helpers::UNSATISFIABLE_DIAGNOSTIC_CODE;

pub use lsp_helpers::VersionData;

pub use lsp_helpers::is_dot_segment;

pub use lsp_helpers::is_safe_maven_coordinate_segment;

pub use lsp_helpers::is_safe_package_name;

pub use lsp_helpers::is_safe_registry_url;

pub use lsp_helpers::is_safe_version_string;

pub use lsp_helpers::is_same_major_minor;

pub use lsp_helpers::maven_coordinate_path;

pub use lsp_helpers::position_in_range;

pub use lsp_helpers::requirement_is_unsatisfiable;

pub use lsp_helpers::warn_rejected_value;

pub use mtime_cache::DEFAULT_MAX_CACHED_FILES;

pub use mtime_cache::MAX_CACHED_FILE_BYTES;

pub use mtime_cache::MtimeFileCache;

pub use package::ConcreteVersion;

pub use package::InvalidPackageName;

pub use package::PackageName;

pub use package::VersionReq;

pub use parser::DependencySource;

pub use parser::LoadingState;

pub use parser::MAX_JSON_NESTING_DEPTH;

pub use parser::MAX_TOML_NESTING_DEPTH;

pub use parser::MAX_YAML_EXPANDED_BYTES;

pub use parser::MAX_YAML_NESTING_DEPTH;

pub use parser::check_json_nesting_depth;

pub use parser::check_toml_nesting_depth;

pub use parser::check_yaml_expansion;

pub use parser::check_yaml_nesting_depth;

pub use parser::json_depth_error_message;

pub use parser::parse_json_checked;

pub use parser::yaml_scalar_string;

pub use position::Position;

pub use position::Range;

pub use registry::Deprecation;

pub use registry::Metadata;

pub use registry::Registry;

pub use registry::RemovalStatus;

pub use registry::Version;

pub use registry::classify_default_registry_url;

pub use registry::existence_wildcard_req;

pub use registry::find_latest_stable;

pub use registry::has_default_prerelease_marker;

pub use registry::hash_routing_key;

pub use registry::is_existence_wildcard;

pub use registry::is_existence_wildcard_str;

pub use registry::not_found_or;

pub use registry::select_latest_for_existence;

pub use version_matcher::Pep440Matcher;

pub use version_matcher::SemverMatcher;

pub use version_matcher::VersionRequirementMatcher;

pub use version_matcher::extract_pypi_min_version;

pub use version_matcher::normalize_and_parse_version;

pub use version_matcher::normalize_operator_spacing;

pub use yaml_rust2;

pub use reqwest;

Modules

cache

HTTP response cache with ETag/Last-Modified conditional-request validation. HTTP response cache shared by every ecosystem’s registry client.

cache_policy

Bounded-DashMap capacity policies shared by cache, github, deps_dev, and osv.

dependency_cap

Per-document ceiling on tracked dependencies, enforced by ecosystem::parse_manifest_blocking for all 14 ecosystems (#796). Per-document ceiling on tracked dependencies (#796).

deps_dev

Supply-chain trust signal via deps.dev API v3.

diagnostic

Protocol-agnostic diagnostic::Diagnostic/diagnostic::Severity types (issue #1083).

ecosystem

The ecosystem::Ecosystem trait: the sealed extension point every package ecosystem crate implements to plug into the LSP server.

ecosystem_registry

Routes a manifest path to its owning ecosystem::Ecosystem implementation.

error

Unified error types (DepsError, FetchFailure) shared across ecosystems.

fallback_completion

Shared raw-text scanners for fallback (parse-failure) completion.

freshness

Release-freshness signal: publish-time tracking and cooldown-window checks.

fs_probe

Counted filesystem probe funnel, shared by every ecosystem crate’s config-file cache.

github

Shared GitHub tags-API client, used by every ecosystem that resolves package versions from GitHub repository tags rather than a dedicated package registry (deps-swift, deps-github-actions).

interval

Shared bracket-interval version-range grammar ([1.0,2.0)-shaped), used by deps-maven, deps-gradle, and deps-nuget (#821). Shared bracket-interval version-range grammar (#821).

json_ast

Shared JSONC-AST helpers for recovering exact dependency source positions (#613).

json_helpers

Shared serde_json-side helpers for leniently interpreting untrusted JSON value shapes from a manifest or registry response (#624, #662).

licenses

SPDX license-policy matching (issue #661, spec 010 Phase 2).

lockfile

Lock file parsing abstractions.

lsp_helpers

Shared LSP response builders.

macros

Macro utilities for reducing boilerplate in ecosystem implementations.

mtime_cache

Generic per-path, mtime-gated file cache shared by every ecosystem config-file cache (deps-cargo’s .cargo/config.toml/$CARGO_HOME/config.toml, deps-npm’s .npmrc).

net_policy

Reachability policy for registry index URLs declared by a workspace file.

osv

OSV.dev vulnerability scanning.

package

Newtypes distinguishing package names, version requirement strings, and concrete resolved versions.

pagination

Generic paginated-fetch loop for a git-tags-shaped REST API returning per_page=100 pages.

parser

Shared manifest-parsing helpers: bounded JSON/TOML/YAML nesting checks and depth-limited parsing used by every ecosystem’s manifest parser.

policy_config

The policy-relevant subset of deps-lsp’s configuration.

position

Protocol-agnostic position::Position/position::Range types (issue #1071).

quote_scan

Shared escape-aware string-literal and comment scanning.

rate_limit

Local, process-lifetime rate-limit short-circuiting.

registry

The registry::Registry trait: version lookup and search that every ecosystem’s registry client implements.

secret

Generic “never surfaced via Debug/Display” wrapper for in-memory secrets.

version_matcher

Version requirement matching abstractions.

xml_bounds

Shared scan-budget constants for a bounded quick-xml event loop over a remote, registry-generated XML response (#698).

yaml_anchor

Shared bounded scalar-anchor value table for yaml-rust2 MarkedEventReceiver-based parsers (deps-dart, deps-gitlab-ci).

yaml_walk

Generic frame-stack mechanics shared by every yaml-rust2 MarkedEventReceiver-based parser in this workspace (deps-dart, deps-github-actions, deps-gitlab-ci).

Macros

impl_dependency

Implement the Dependency trait for a struct.

impl_get_versions_with_passthrough

Generates a trivial inherent get_versions_with that ignores freshness.

impl_metadata

Implement Metadata trait for a struct.

impl_parse_result

Implement ParseResult trait for a struct.

impl_registry_versions_method

Generates one Registry trait-impl method that boxes an inherent method’s result.

impl_version

Implement Version trait for a struct.