pkg_seer

PkgSeer

This repository contains Elixir/Phoenix service PkgSeer.

Intent for the service is to provide easy and fast access to package informatino including it's dependencies. Service can be used to see how many transitive dependencies package has, what kind of vulnerabilities it has had and make it easier to determine whether package is trustworthy.

Currently we support NPM and PyPI package registries

Development

🚀 Quick Start: For automated environment setup (especially for AI agents and Factory.ai), see DEVELOPMENT_SETUP.md

Database Setup

This project uses PostgreSQL with Docker Compose for local development:

• Start PostgreSQL: docker-compose up -d postgres (or use ./scripts/db.sh start)
• Create database: mix ecto.create
• Run migrations: mix ecto.migrate

The PostgreSQL container runs on port 5532 to avoid conflicts with system installations.

Database Management Scripts

Use the provided database management script:

./scripts/db.sh start    # Start PostgreSQL
./scripts/db.sh stop     # Stop PostgreSQL
./scripts/db.sh restart  # Restart PostgreSQL
./scripts/db.sh logs     # View logs
./scripts/db.sh shell    # Connect to database
./scripts/db.sh reset    # Reset database (WARNING: deletes all data)

You can use --test or --both to start test or both databases.

Starting the Application

To start your Phoenix server:

• Run mix setup to install and setup dependencies
• Start PostgreSQL: docker-compose up -d postgres
• Start Phoenix endpoint with mix phx.server or inside IEx with iex -S mix phx.server

Now you can visit localhost:4000 from your browser.

GitHub OAuth Setup

PkgSeer supports signing in with GitHub via Ueberauth. The existing package browsing experience remains public—GitHub accounts are only needed for upcoming user-specific features. To configure the integration locally:

• Create a GitHub OAuth App under https://github.com/settings/developers.
  • Set the authorization callback URL to http://localhost:4000/auth/github/callback.
• Export credentials (or place them in your preferred env manager):

  export GITHUB_CLIENT_ID="your-client-id"
  export GITHUB_CLIENT_SECRET="your-client-secret"
  

• Start Phoenix with the variables in scope so Ueberauth can read them from config/runtime.exs:

  mix phx.server
  

• Test the OAuth flow by visiting http://localhost:4000/auth/github. GitHub should prompt for authorization and redirect back to PkgSeer on success.

Automated coverage for the login flow lives in test/pkg_seer_web/controllers/auth_controller_test.exs and test/pkg_seer_web/plugs/require_user_test.exs. Run them with:

mix test test/pkg_seer_web/controllers/auth_controller_test.exs \
         test/pkg_seer_web/plugs/require_user_test.exs

Testing

See docs/implementation/TESTING.md for comprehensive testing documentation including Mox setup, LiveView testing, and HTTP mocking patterns.

GraphQL Schema Generation

To generate the GraphQL schema SDL (Schema Definition Language) file:

# Generate schema.graphql using the default schema module (PkgSeerWeb.Schema)
mix absinthe.schema.sdl

# Generate to a specific file
mix absinthe.schema.sdl priv/static/schema.graphql

# Specify a different schema module
mix absinthe.schema.sdl --schema PkgSeerWeb.Schema

The generated schema file can be used for documentation, client code generation, or schema validation.

Static Type Analysis

Dialyzer is integrated for static type analysis with a fast development workflow:

• Quick reference: mix dialyzer (run analysis), mix dialyzer --plt (update PLTs)
• Pre-commit workflow: Fast format + tests via Husky + lint-staged
• Manual checks: Run mix dialyzer before merging branches
• Documentation: See docs/implementation/DIALYZER.md for setup, workflow, and error handling

Rate Limiting and Caching

See docs/implementation/RATE_LIMITING_AND_CACHING.md for the detailed implementation of inbound/outbound rate limiting and HTTP caching policies.

CLI Utilities

Command-line tasks are available for profiling and debugging dependency resolution and DAG building:

# Resolve dependencies and show per-package assignments (latest version)
mix packages.resolve <package_name>

# Resolve a specific version
mix packages.resolve <package_name> <version_constraint>

# Show all assignments (no truncation)
mix packages.resolve <package_name> <version_constraint> --all

# Skip TransitiveDependencies caches (ETS/DB) for clean profiling
mix packages.resolve <package_name> <version_constraint> --skip-cache-dag

# Generate a Mermaid DAG diagram (latest or specific version)
mix packages.dag <package_name> [version_constraint]

# Open diagram in browser and bypass DAG caches
mix packages.dag <package_name> [version_constraint] --open --skip-cache-dag

Notes:

• --skip-cache-dag bypasses only DAG caching in TransitiveDependencies (no ETS/DB read/write). Package metadata/version caching remains unchanged.
• Use this flag to measure cold-resolution performance without wiping the database.

Tidewave AI Assistant

The application includes Tidewave AI coding assistant for development:

• Access the web interface at localhost:4000/tidewave
• Use it for code execution, database inspection, and enhanced development workflows

Ready to run in production? Please check our deployment guides.

Learn more

• Official website: https://www.phoenixframework.org/
• Guides: https://hexdocs.pm/phoenix/overview.html
• Docs: https://hexdocs.pm/phoenix
• Forum: https://elixirforum.com/c/phoenix-forum
• Source: https://github.com/phoenixframework/phoenix