DEV Community

Muhammadh Ahzem
Muhammadh Ahzem

Posted on

Phantom Dependency 👻 — Local AI Codebase Auditor for Forgotten & Haunted Packages

#devchallenge #hf26challenge #opensource #ai

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

"Every project has a past. Discover the dependencies haunting yours."

In modern software development, every codebase inherits ghosts. We install packages for a sprint hack, abandon utility libraries when native JavaScript evolves, or maintain repositories where dependencies declared five years ago still sit silently in package.json — unreferenced, unmaintained, or quietly harboring severe security vulnerabilities.

Phantom Dependency is an open-source, local-first dependency investigation tool built for JavaScript and TypeScript codebases. It reframes the invisible technical debt and supply chain hazards in your repositories through a haunted codebase metaphor:

  • Dependencies are the spirits inhabiting your codebase.
  • Outdated & Inactive libraries are the forgotten residents who stopped talking.
  • Unused runtime declarations are whispering ghosts haunting your manifest.
  • The Dependency Graveyard is an actionable, forensic audit report.

🛡️ The "Fact Over Fear" Philosophy

Unlike conventional dependency scanners that trigger alarm fatigue by screaming about every package older than a year, Phantom Dependency adheres to a strict standard: Never label a package abandoned, malicious, or vulnerable without verifiable evidence. Every classification is backed by concrete lockfile versions, static AST import walks, and verified OSV/GHSA security advisory databases.

⚰️ The Graveyard Classifications

State Indicator Definition Example Trigger
Resting 🟢 Emerald Stable, up-to-date, actively imported in source code. Actively maintained & imported runtime package
Aging 🟡 Amber Behind major releases or >24 months without a release. lodash@3.10.1 when v4+ is released
Whispering 🟣 Amethyst Ghost package: declared in package.json, but 0 imports found anywhere in source files. moment declared in runtime deps with zero usage
Haunted 🔴 Crimson Confirmed security advisory (CVE / OSV.dev) or verified exploit vector. minimist@0.0.8 prototype pollution advisory

Demo

Watch the complete step-by-step walkthrough of Phantom Dependency in action, analyzing a haunted testbed codebase, classifying packages, and generating local AI forensic reports:

Video Link: Watch on YouTube

Code

The entire codebase is open source under the MIT License and organized as a clean monorepo:

GitHub logo Ahzem / phantom-dependency

Phantom Dependency 👻

"Every project has a past. Discover the dependencies haunting yours."

Phantom Dependency is an open-source, local-first AI dependency investigation tool for JavaScript and TypeScript codebases. Built for the Hacktoberfest Open-Source AI Challenge, Week 4: "Ghost in the Machine".

🌟 The Metaphor & The Tool

Beneath its spooky haunted codebase aesthetic lies a serious developer security and audit tool:

  • Dependencies are the spirits living in your codebase.
  • Outdated & Inactive packages are the forgotten residents who stopped talking.
  • The Dependency Graveyard is your actionable investigation report.

🛡️ Core Principles

  1. Fact over Fear: Never label a package abandoned, malicious, or vulnerable solely because it is old. Every finding is backed by explicit evidence.
  2. Local-First & Private: Source files are inspected statically on your machine. Code is never transmitted to an external service or cloud AI.
  3. Local AI Inference: Powered by Ollama and Google's lightweight gemma3:1b model.
  4. Resilient Offline…
View on GitHub

🏗️ Technical Architecture

  • Frontend (apps/web): Next.js 15 (App Router), React 19, Tailwind CSS, Lucide icons, Dark Spectral Ghost UI with live stepper progress and interactive Graveyard filters.
  • Backend API (apps/api): Python 3.12+ with FastAPI and Pydantic v2, featuring strict path safety traversal guards, static AST import inspection, multi-lockfile resolution (npm, pnpm, yarn), and local inference clients.
  • Test Suite: 17 comprehensive Pytest unit and integration tests covering manifest parsing, semver comparisons, lockfile resolution, and schema validation.

How I Built It

Phantom Dependency is architected around on-device, local-first open-source AI:

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Next.js 15 App Router)        │
│    - Spectral Dark Theme (Charcoal, Emerald, Amethyst)      │
│    - 5-Step Pipeline Stepper UI                             │
│    - Graveyard Visualizer with Filter Bar & Search          │
│    - Markdown & JSON Export Engine                          │
└──────────────────────────────▲──────────────────────────────┘
                               │ HTTP / JSON
┌──────────────────────────────▼──────────────────────────────┐
│                    Backend (FastAPI & Pydantic)             │
│    ├── Core: Path Sanitization, AST Walk, Lockfile Resolver │
│    ├── Heuristic Pipeline: OSV.dev Advisories + Registry    │
│    └── Local AI Service: Ollama Client + Structured Prompts │
└──────────────────────────────▲──────────────────────────────┘
                               │ Local HTTP (127.0.0.1:11434)
┌──────────────────────────────▼──────────────────────────────┐
│                    Ollama Inference Engine                  │
│    Model: Google Gemma 3 1B (Open-Weight)                   │
│    - Zero Telemetry • 100% On-Device • Deterministic Fallback│
└─────────────────────────────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode
  1. Local Open-Weight Model (Gemma 3 1B via Ollama): We selected Google's lightweight open-weight Gemma 3 1B model running locally via Ollama. It excels at fast, structured JSON output generation on standard developer hardware without requiring expensive GPUs.
  2. Safe Source Code AST Walk: Before querying the model, the backend statically parses .js, .jsx, .ts, .tsx, .vue, and .svelte files to build an exact inventory of ESM import and CommonJS require() references. It cross-checks build tools (like prettier, eslint, and tailwindcss) declared in package.json scripts and config files to avoid false positives.
  3. Structured Prompting & Guardrails: Evidence (declared ranges, locked versions, import frequencies, advisory titles) is passed into Gemma 3 using a strictly typed Pydantic schema. The AI is explicitly forbidden from hallucinating CVE numbers or release dates; if data is unverified, it flags the status as heuristic rather than fact.
  4. Resilient Offline Fallback: If Ollama is offline or uninstalled, the tool automatically degrades to deterministic, rule-based templates so developer workflows are never blocked.

Why Does Open Innovation Matter?

In developer tooling and application security, open innovation is the difference between an audit you can trust and one you cannot run.

  1. Zero Code Exposure (Codebases Stay On-Device): Enterprise and private open-source repositories cannot pipe internal codebases, import trees, or proprietary dependency manifests to closed third-party cloud APIs. Open-source local AI ensures that zero bytes of code or file paths ever leave 127.0.0.1.
  2. Deterministic, Offline-Ready Audits: Closed AI APIs suffer from rate limits, subscription paywalls, breaking prompt changes, and downtime. Running open-weight Gemma 3 locally over Ollama guarantees zero marginal cost per scan and total air-gapped readiness — whether you're coding on a flight, in a secure enclave, or with the lights off on Halloween night.
  3. No Vendor Lock-in & Full Auditability: Closed security scanners treat their risk scoring as proprietary black boxes. Because Phantom Dependency and its underlying AI harness are completely open source, developers can inspect the exact prompt templates, verify the AST walker logic, and fine-tune or swap models without asking permission.

The Spirit of It

The line between the living and the forgotten in software engineering is razor-thin.

When building Phantom Dependency against our sample haunted project, we targeted a repository that had declared moment.js three years ago alongside an unpinned minimist parser. Running the tool revealed the moment the theme truly landed:

moment sat quietly in package.json, inflating every Docker build and container image, while index.js hadn't called a single date method in over 700 commits. Meanwhile, minimist version 0.0.8 lingered like a poltergeist in the lockfile, silently exposing the CLI to prototype pollution.

Seeing Gemma 3 examine the cold, hard lockfile data and report back with empathy — "This package stopped speaking to your codebase years ago. It's time to let it rest" — proved that developer security doesn't have to be sterile and terrifying. It can be engaging, illuminating, and respectful of the code we leave behind.

Prize Categories

  • Overall Challenge Entry: Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

Top comments (0)