Add guide for adding a new language or ecosystem#243
Add guide for adding a new language or ecosystem#243Ashusf90 wants to merge 1 commit intompiton:mainfrom
Conversation
This guide outlines the steps to add support for a new language or package ecosystem, including defining data structures, implementing a parser and registry, and adding tests.
github-actions
Bot
added
documentation
|
Welcome to Dependi, @Ashusf90! 🎉 Thank you for your first contribution to this project! We really appreciate you taking the time to help improve Dependi. A maintainer will review your PR soon. In the meantime, please make sure:
If you have any questions, feel free to ask here. Happy coding! 🚀 |
📝 WalkthroughWalkthroughA new documentation file Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Greptile SummaryThis PR adds Confidence Score: 4/5Documentation-only PR, but the new guide is missing Jekyll front matter (breaking docs-site rendering) and is unreachable from any nav page — both should be fixed before merging. Two P1 findings: missing front matter prevents the page from rendering correctly in the Jekyll docs site, and the file is orphaned with no inbound links. The content quality issues are P2. The P1s are straightforward fixes but need to land before the guide is useful. docs/adding-a-language.md — missing front matter and nav linkage; also consider updating docs/contributing.md or docs/languages/index.md to point to this new page. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Start: New Language] --> B[Define Data Structures\ndependi-lsp/src/parsers/]
B --> C[Implement Parser\ndependi-lsp/src/parsers/mylang.rs]
C --> D[Implement Registry Client\ndependi-lsp/src/registries/myregistry.rs]
D --> E[Register Language\nlib.rs + backend.rs]
E --> F[Add Tests\ntests/integration_test.rs]
F --> G[Update Docs & extension.toml\nREADME.md + extension.toml]
G --> H[Open Pull Request]
Reviews (1): Last reviewed commit: "Add guide for adding a new language or e..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| @@ -0,0 +1,94 @@ | |||
| # Adding a New Language / Ecosystem | |||
There was a problem hiding this comment.
Every other file under docs/ includes a YAML front matter block (e.g. docs/contributing.md, docs/languages/index.md). Without it, the docs site won't render a title, set a nav order, or display the layout correctly, effectively making this page invisible in the generated site.
| # Adding a New Language / Ecosystem | |
| --- | |
| title: Adding a Language | |
| layout: default | |
| nav_order: 10 | |
| description: "Guide for adding support for a new language or ecosystem" | |
| --- | |
| # Adding a New Language / Ecosystem |
| # Adding a New Language / Ecosystem | ||
|
|
||
| This guide explains how to add support for a new language or package ecosystem. | ||
|
|
||
| --- | ||
|
|
||
| ## 🧩 Overview | ||
|
|
||
| To support a new ecosystem, you need to: | ||
|
|
||
| 1. Define dependency data structures | ||
| 2. Implement a parser | ||
| 3. Implement a registry | ||
| 4. Integrate with the backend | ||
| 5. Add tests | ||
|
|
||
| --- | ||
|
|
||
| ## 📦 Step 1: Define Data Structures | ||
|
|
||
| Create structures to represent dependencies such as: | ||
|
|
||
| * Package name | ||
| * Version | ||
| * Source | ||
|
|
||
| --- | ||
|
|
||
| ## 🔍 Step 2: Implement Parser | ||
|
|
||
| Create a parser to read dependency files (e.g. `pom.xml`, `package.json`). | ||
|
|
||
| The parser should: | ||
|
|
||
| * Extract dependencies | ||
| * Convert them into the standard format | ||
|
|
||
| --- | ||
|
|
||
| ## 🌐 Step 3: Implement Registry | ||
|
|
||
| The registry is responsible for: | ||
|
|
||
| * Fetching package metadata | ||
| * Resolving versions | ||
|
|
||
| --- | ||
|
|
||
| ## 🔗 Step 4: Integration | ||
|
|
||
| Connect your parser and registry to the system: | ||
|
|
||
| * Register parser | ||
| * Register registry client | ||
|
|
||
| --- | ||
|
|
||
| ## 🧪 Step 5: Add Tests | ||
|
|
||
| Ensure correctness by adding: | ||
|
|
||
| * Unit tests for parser | ||
| * Integration tests | ||
|
|
||
| --- | ||
|
|
||
| ## ✅ Final Checklist | ||
|
|
||
| * Parser works correctly | ||
| * Registry returns valid data | ||
| * Tests are passing | ||
|
|
||
| --- | ||
|
|
||
| ## 🚀 Example | ||
|
|
||
| For example: | ||
|
|
||
| * Maven → Java | ||
| * npm → JavaScript | ||
|
|
||
| Use existing implementations as reference. | ||
|
|
||
| --- | ||
|
|
||
| ## 🤝 Contribution Tips | ||
|
|
||
| * Follow project structure | ||
| * Keep code clean | ||
| * Write tests | ||
|
|
||
| --- | ||
|
|
||
| Happy contributing! 🎉 |
There was a problem hiding this comment.
docs/contributing.md and docs/languages/index.md both direct contributors to CONTRIBUTING.md#adding-support-for-new-languages for this topic, but neither references the new file. Unless this page is added to at least one nav entry, contributors will never find it. Consider adding a link in docs/contributing.md or docs/languages/index.md, or replacing the existing CONTRIBUTING.md pointer with a link here.
|
|
||
| ## 🔍 Step 2: Implement Parser | ||
|
|
||
| Create a parser to read dependency files (e.g. `pom.xml`, `package.json`). | ||
|
|
||
| The parser should: | ||
|
|
||
| * Extract dependencies | ||
| * Convert them into the standard format | ||
|
|
||
| --- | ||
|
|
||
| ## 🌐 Step 3: Implement Registry | ||
|
|
||
| The registry is responsible for: | ||
|
|
||
| * Fetching package metadata | ||
| * Resolving versions | ||
|
|
||
| --- | ||
|
|
||
| ## 🔗 Step 4: Integration | ||
|
|
||
| Connect your parser and registry to the system: | ||
|
|
||
| * Register parser | ||
| * Register registry client | ||
|
|
||
| --- | ||
|
|
||
| ## 🧪 Step 5: Add Tests | ||
|
|
||
| Ensure correctness by adding: | ||
|
|
||
| * Unit tests for parser | ||
| * Integration tests | ||
|
|
||
| --- | ||
|
|
||
| ## ✅ Final Checklist | ||
|
|
||
| * Parser works correctly | ||
| * Registry returns valid data | ||
| * Tests are passing | ||
|
|
||
| --- | ||
|
|
||
| ## 🚀 Example | ||
|
|
||
| For example: | ||
|
|
||
| * Maven → Java | ||
| * npm → JavaScript | ||
|
|
||
| Use existing implementations as reference. | ||
|
|
||
| --- | ||
|
|
||
| ## 🤝 Contribution Tips | ||
|
|
||
| * Follow project structure | ||
| * Keep code clean | ||
| * Write tests | ||
|
|
||
| --- | ||
|
|
||
| Happy contributing! 🎉 |
There was a problem hiding this comment.
CONTRIBUTING.md (lines 135–191) already covers the same topic with concrete Rust code templates, exact file paths (dependi-lsp/src/parsers/, dependi-lsp/src/registries/), the specific files to update (lib.rs, backend.rs, tests/integration_test.rs), and a Step 5 reminding contributors to update README.md and extension.toml. This new doc omits all of that, making it less useful than what already exists. Consider embedding or cross-referencing those specifics so a contributor can act on this guide without also needing to read CONTRIBUTING.md.
| ## 🚀 Example | ||
|
|
||
| For example: | ||
|
|
||
| * Maven → Java | ||
| * npm → JavaScript | ||
|
|
||
| Use existing implementations as reference. |
There was a problem hiding this comment.
"Use existing implementations as reference" gives no concrete pointer. The project has eight parsers (parsers/cargo.rs, parsers/npm.rs, etc.) and eight registry clients. Linking directly to those — e.g. "see dependi-lsp/src/parsers/cargo.rs for a well-documented example" — would make this section actionable rather than a placeholder.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
docs/adding-a-language.md (1)
49-64: Consider making integration/testing steps concrete with exact touchpoints.This section is a bit abstract. Pointing to
Backend::new()registration and expected unit/integration test targets would make contributor onboarding faster and less error-prone.📌 Suggested doc patch
Connect your parser and registry to the system: -* Register parser -* Register registry client +* Register parser in backend initialization (`dependi-lsp/src/backend.rs`) using `Arc::new(...)` +* Register registry client in backend initialization, reusing the shared HTTP client +* Add/extend routing so the new ecosystem maps to the correct parser + registry @@ Ensure correctness by adding: * Unit tests for parser -* Integration tests +* Unit tests for registry response mapping (`VersionInfo`) +* Integration tests covering end-to-end parsing + version lookup🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/adding-a-language.md` around lines 49 - 64, Make the Integration and Testing steps concrete by showing the exact touchpoints: instruct contributors to call Backend::new() and pass the parser and registry client instances (e.g., register via Backend::new(...).register_parser(...) or Backend::new(...).with_registry_client(...)), name the functions used to wire things together (e.g., register_parser, register_registry_client or Backend::with_parser/with_registry), and list concrete test targets—unit tests for Parser::parse (and the Parser type) and RegistryClient implementations, plus an integration test that constructs Backend via Backend::new with a test parser/registry and asserts end-to-end behavior (e.g., integration test target integration::language_integration or tests/integration/language_integration.rs).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/adding-a-language.md`:
- Around line 21-26: The docs currently list only name/version/source for the
Dependency type; update the Dependency contract in docs/adding-a-language.md to
enumerate and describe all required fields (e.g., name, version, source,
resolvedVersion, positions (start/end or range), and flags such as
dev/prod/optional) and how parsers must populate them; include the expected
types/formats for positions and flags and a note about optional vs required
fields so new parser implementations know to emit positions, flags, and optional
resolvedVersion in addition to package identity.
- Around line 29-37: Docs are missing the exact Parser trait signature which can
cause interface drift; add the concrete trait definition that contributors must
implement: declare a public trait named Parser with Send + Sync bounds and a
parse method signature fn parse(&self, content: &str) -> Vec<Dependency>; and
state that implementations should read ecosystem files (e.g. pom.xml,
package.json) and return normalized Dependency entries so implementers know the
required trait and return type (refer to Parser, parse, and Dependency).
- Around line 40-46: Update the "Implement Registry" section to explicitly
document the Registry trait from dependi-lsp/src/registries/mod.rs: list the
exact method signatures and contracts for the two required methods
(fetch_package_metadata and resolve_versions), their expected inputs, return
types (Result/Err behavior) and error semantics, and examples of expected
behavior for edge cases (missing package, network errors, version resolution).
Also document the shared-client pattern: explain that registry implementations
should reuse a clonable HTTP client (e.g., a reqwest::Client wrapped in Arc or a
SharedClient type), show where to accept or inject that client
(constructor/struct field) and that the client must be reused across calls for
connection pooling and timeouts. Ensure the docs reference the Registry trait
and the two methods so implementers can find the exact code to implement.
---
Nitpick comments:
In `@docs/adding-a-language.md`:
- Around line 49-64: Make the Integration and Testing steps concrete by showing
the exact touchpoints: instruct contributors to call Backend::new() and pass the
parser and registry client instances (e.g., register via
Backend::new(...).register_parser(...) or
Backend::new(...).with_registry_client(...)), name the functions used to wire
things together (e.g., register_parser, register_registry_client or
Backend::with_parser/with_registry), and list concrete test targets—unit tests
for Parser::parse (and the Parser type) and RegistryClient implementations, plus
an integration test that constructs Backend via Backend::new with a test
parser/registry and asserts end-to-end behavior (e.g., integration test target
integration::language_integration or tests/integration/language_integration.rs).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 117a4cc1-e1eb-43ff-b65f-80c90ced6cdf
📒 Files selected for processing (1)
docs/adding-a-language.md
| Create structures to represent dependencies such as: | ||
|
|
||
| * Package name | ||
| * Version | ||
| * Source | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the canonical Dependency contract in source.
rg -n -A40 -B2 'pub struct Dependency' dependi-lsp/src/parsers/mod.rsRepository: mpiton/zed-dependi
Length of output: 1638
Document the full Dependency contract, not just name/version/source.
This section currently under-specifies the required parser output shape. New parser implementations must populate fields used by editor features (positions, flags, and optional resolved version), not only basic package identity.
📌 Suggested doc patch
-Create structures to represent dependencies such as:
-
-* Package name
-* Version
-* Source
+Use the existing `Dependency` model from `dependi-lsp/src/parsers/mod.rs`.
+At minimum, parser output must include:
+
+* `name`, `version`
+* source location fields: `line`, `name_start`, `name_end`, `version_start`, `version_end`
+* flags/metadata: `dev`, `optional`, `registry`, `resolved_version` (when available)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/adding-a-language.md` around lines 21 - 26, The docs currently list only
name/version/source for the Dependency type; update the Dependency contract in
docs/adding-a-language.md to enumerate and describe all required fields (e.g.,
name, version, source, resolvedVersion, positions (start/end or range), and
flags such as dev/prod/optional) and how parsers must populate them; include the
expected types/formats for positions and flags and a note about optional vs
required fields so new parser implementations know to emit positions, flags, and
optional resolvedVersion in addition to package identity.
| ## 🔍 Step 2: Implement Parser | ||
|
|
||
| Create a parser to read dependency files (e.g. `pom.xml`, `package.json`). | ||
|
|
||
| The parser should: | ||
|
|
||
| * Extract dependencies | ||
| * Convert them into the standard format | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify parser trait signature.
rg -n -A8 -B3 'pub trait Parser' dependi-lsp/src/parsers/mod.rsRepository: mpiton/zed-dependi
Length of output: 365
🏁 Script executed:
cat -n docs/adding-a-language.md | sed -n '20,45p'Repository: mpiton/zed-dependi
Length of output: 652
Include the exact Parser trait signature to prevent interface drift.
The documentation at lines 29-37 is too vague. Contributors should explicitly implement the Parser trait with the correct method signature and trait bounds.
📌 Suggested doc patch
-Create a parser to read dependency files (e.g. `pom.xml`, `package.json`).
+Implement the `Parser` trait in `dependi-lsp/src/parsers/mod.rs`:
+
+```rust
+pub trait Parser: Send + Sync {
+ fn parse(&self, content: &str) -> Vec<Dependency>;
+}
+```
+
+Your parser should read ecosystem files (e.g. `pom.xml`, `package.json`)
+and return normalized `Dependency` entries.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/adding-a-language.md` around lines 29 - 37, Docs are missing the exact
Parser trait signature which can cause interface drift; add the concrete trait
definition that contributors must implement: declare a public trait named Parser
with Send + Sync bounds and a parse method signature fn parse(&self, content:
&str) -> Vec<Dependency>; and state that implementations should read ecosystem
files (e.g. pom.xml, package.json) and return normalized Dependency entries so
implementers know the required trait and return type (refer to Parser, parse,
and Dependency).
| ## 🌐 Step 3: Implement Registry | ||
|
|
||
| The registry is responsible for: | ||
|
|
||
| * Fetching package metadata | ||
| * Resolving versions | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify registry trait contract and shared-client docs.
rg -n -A20 -B5 'pub trait Registry' dependi-lsp/src/registries/mod.rs
rg -n -A12 -B4 'Shared HTTP Client|create_shared_client' dependi-lsp/src/registries/mod.rsRepository: mpiton/zed-dependi
Length of output: 2692
🏁 Script executed:
cd / && find . -name "adding-a-language.md" -type f 2>/dev/null | head -5Repository: mpiton/zed-dependi
Length of output: 107
🏁 Script executed:
cat -n docs/adding-a-language.md | sed -n '35,55p'Repository: mpiton/zed-dependi
Length of output: 522
🏁 Script executed:
cat -n docs/adding-a-language.md | sed -n '1,70p'Repository: mpiton/zed-dependi
Length of output: 1626
🏁 Script executed:
grep -r "Registry" docs/adding-a-language.mdRepository: mpiton/zed-dependi
Length of output: 124
🏁 Script executed:
grep -r "trait Registry\|get_version_info\|http_client" docs/Repository: mpiton/zed-dependi
Length of output: 44
Registry section must document the trait contract and shared-client pattern.
Step 3 is too vague for developers implementing a new registry. They need explicit guidance on the Registry trait from dependi-lsp/src/registries/mod.rs, including the two required methods and the shared HTTP client pattern.
📌 Suggested doc patch
-The registry is responsible for:
-
-* Fetching package metadata
-* Resolving versions
+Implement the `Registry` trait from `dependi-lsp/src/registries/mod.rs`:
+
+* `async fn get_version_info(&self, package_name: &str) -> anyhow::Result<VersionInfo>`
+* `fn http_client(&self) -> Arc<Client>`
+
+Use the shared HTTP client pattern via `http_client::create_shared_client` for consistency with existing registries.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ## 🌐 Step 3: Implement Registry | |
| The registry is responsible for: | |
| * Fetching package metadata | |
| * Resolving versions | |
| ## 🌐 Step 3: Implement Registry | |
| Implement the `Registry` trait from `dependi-lsp/src/registries/mod.rs`: | |
| * `async fn get_version_info(&self, package_name: &str) -> anyhow::Result<VersionInfo>` | |
| * `fn http_client(&self) -> Arc<Client>` | |
| Use the shared HTTP client pattern via `http_client::create_shared_client` for consistency with existing registries. | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/adding-a-language.md` around lines 40 - 46, Update the "Implement
Registry" section to explicitly document the Registry trait from
dependi-lsp/src/registries/mod.rs: list the exact method signatures and
contracts for the two required methods (fetch_package_metadata and
resolve_versions), their expected inputs, return types (Result/Err behavior) and
error semantics, and examples of expected behavior for edge cases (missing
package, network errors, version resolution). Also document the shared-client
pattern: explain that registry implementations should reuse a clonable HTTP
client (e.g., a reqwest::Client wrapped in Arc or a SharedClient type), show
where to accept or inject that client (constructor/struct field) and that the
client must be reused across calls for connection pooling and timeouts. Ensure
the docs reference the Registry trait and the two methods so implementers can
find the exact code to implement.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 1 file
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/adding-a-language.md">
<violation number="1" location="docs/adding-a-language.md:1">
P2: Add YAML front matter at the top of this docs page so the site can apply layout/title/nav metadata correctly.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| @@ -0,0 +1,94 @@ | |||
| # Adding a New Language / Ecosystem | |||
There was a problem hiding this comment.
P2: Add YAML front matter at the top of this docs page so the site can apply layout/title/nav metadata correctly.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/adding-a-language.md, line 1:
<comment>Add YAML front matter at the top of this docs page so the site can apply layout/title/nav metadata correctly.</comment>
<file context>
@@ -0,0 +1,94 @@
+# Adding a New Language / Ecosystem
+
+This guide explains how to add support for a new language or package ecosystem.
</file context>
mpiton
left a comment
mpiton
left a comment
There was a problem hiding this comment.
Hey, thanks for picking this up.
A couple things need fixing before this can merge.
First, the file needs Jekyll front matter. Without it the docs site won't render the page. Every other file under docs/ has one, look at docs/contributing.md for the format:
---
title: Adding a Language
layout: default
nav_order: 6
description: "How to add a new language or ecosystem to Dependi"
---Second, the page isn't linked from anywhere. Add a reference in docs/contributing.md and docs/languages/index.md, otherwise nobody will find it.
On the content itself: the guide is currently thinner than what we already have in CONTRIBUTING.md (L135-191). That section already has Rust code templates and exact file paths. This dedicated page needs to go further, not repeat a subset. Specifically:
-
The
Dependencystruct has ~10 fields (line positions, dev/optional flags, registry, resolved_version...), not just name/version/source. Parsers need to populate all of them for diagnostics and inlay hints to work. -
Include the actual trait signatures. Contributors need to see what they're implementing:
pub trait Parser: Send + Sync { fn parse(&self, content: &str) -> Vec<Dependency>; }
pub trait Registry: Send + Sync { async fn get_version_info(&self, package_name: &str) -> anyhow::Result<VersionInfo>; fn http_client(&self) -> Arc<Client>; }
-
FileTypeenum infile_types.rsis missing from the guide entirely. That's what routes files to the right parser/registry. You need to add a variant there and wire it inbackend.rs. Most people won't figure that out without being told. -
extension.tomlalso needs updating if the new language has file patterns Zed doesn't know about yet. -
The "Examples" section says "use existing implementations as reference" but doesn't point to anything. Link to
dependi-lsp/src/parsers/cargo.rsanddependi-lsp/src/registries/crates_io.rs.
Also, please go through all the comments from Greptile, CodeRabbit, and Cubic on this PR and resolve them. They've flagged the points above plus a few more (shared HTTP client pattern, VersionInfo struct docs, concrete test targets). All of that needs to be addressed.
|
I'll close soon if there is no response. |
2 participants
Closes #233
Summary by cubic
Add a guide for adding a new language or package ecosystem. It covers data structures, parser and registry, backend integration, tests, and a checklist with examples to help contributors ship new integrations faster (addresses #233).
Written for commit afed4c1. Summary will update on new commits.
Summary by CodeRabbit