DEV Community

Cover image for Dependency Undertaker: Scan for dependency rot locally
Creta
Creta

Posted on

Dependency Undertaker: Scan for dependency rot locally

#devchallenge #hf26challenge

Hacktoberfest Open-Source AI Challenge: Ghost in the Machine Submission 👻🌼

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

What I Built

Dependency rot can hide in plain sight: packages that are deprecated, inactive, or affected by known advisories. I built Dependency Undertaker, a small local CLI that checks direct npm or Python dependencies and turns findings into a Markdown report and GitHub issue drafts.

What it does

Run it against a project folder and it:

  1. Reads direct dependencies from package.json or requirements.txt.
  2. Checks package metadata from the public npm or PyPI registry and deps.dev.
  3. Applies deterministic rules to rate risk. The optional local AI model writes explanations and issue drafts; it does not decide the risk rating.
  4. Writes undertaker-report.md and, when there are medium or high findings, issues/upgrade-dependencies.md.

The tool does not read source code or lockfiles, and it does not resolve transitive dependencies. Without a lockfile, a version range cannot tell the tool exactly which version is installed. For ranges, the current implementation checks the registry's latest version for advisory metadata.

Terminal

Install

Requirements: Python 3.10 or newer and internet access for public package metadata. Ollama is optional.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
Enter fullscreen mode Exit fullscreen mode

Run the commands from the Dependency Undertaker repository root. In Command Prompt, activate with .venv\Scripts\activate instead.

Scan the included demo 

python -m undertaker.cli scan .\demo\stale-npm-app --no-llm
Enter fullscreen mode Exit fullscreen mode

Scan your own local project

Pass the path to the project folder containing package.json or requirements.txt:

python -m undertaker.cli scan "C:\path\to\your-project" --no-llm
Enter fullscreen mode Exit fullscreen mode

To put the generated files in a separate folder:

python -m undertaker.cli scan "C:\path\to\your-project" --no-llm --output-dir .\scan-results
Enter fullscreen mode Exit fullscreen mode

Scan a GitHub repository

The current version accepts a local folder, not a GitHub URL. Clone the repository first, then scan the clone:

git clone https://github.com/OWNER/REPOSITORY.git
python -m undertaker.cli scan .\REPOSITORY --no-llm
Enter fullscreen mode Exit fullscreen mode

You can also scan an existing local clone by passing its full path. The target must contain one supported manifest. If both package.json and requirements.txt are present, scan an ecosystem-specific subfolder separately.

Optional local AI

For local Gemma generated wording, install and start Ollama, then download the model:

ollama pull gemma4:e2b
Enter fullscreen mode Exit fullscreen mode

Run without --no-llm:

python -m undertaker.cli scan .\demo\stale-npm-app
Enter fullscreen mode Exit fullscreen mode

When Ollama is unavailable, the CLI falls back to deterministic draft templates. --no-llm skips the model request entirely.

Privacy and limitations

Package names and version information are sent to public registry metadata services. Source files, lockfiles, environment variables, and API keys are not sent. With the optional LLM, only compact package metadata goes to the configured Ollama endpoint, which defaults to localhost.

This is an early MVP. Registry coverage and risk signals can be incomplete; a missing advisory is not proof that a dependency is safe. Always review suggested upgrades and issue drafts before acting.

Try it 

python -m undertaker.cli scan .\demo\stale-npm-app --no-llm
Enter fullscreen mode Exit fullscreen mode

Feedback and contributions are welcome.

Top comments (0)