Skip to content

About

Zero-config project intelligence CLI for JavaScript and TypeScript repositories

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SourcePulse

npm version license

Zero-config project intelligence for JavaScript and TypeScript repositories.

npx sourcepulse

SourcePulse scans a local repository and produces a scored health report with practical cleanup suggestions. It runs locally, does not upload your source code, and does not require a configuration file.

What It Checks

Area Checks
Dependencies Outdated packages, unused packages, npm audit vulnerabilities
Dead code Unused exports and orphan files
Environment Defined-but-unused variables and referenced-but-missing variables
Imports Circular dependency chains
Security Likely hardcoded credentials and committed .env files
Freshness Recent commits, releases, and stale branches

Quick Start

Scan the current directory:

npx sourcepulse

Scan another project:

npx sourcepulse ../my-project

Example output:

sourcepulse v0.4.1

Scanning my-app (Next.js + Prisma + Vitest)

Overall Score: 82/100 (B)

Dependencies
  - Outdated: 4
  - Unused: 1
  - Vulnerabilities: 0

Dead Code
  - Unused exports: 3
  - Orphan files: 1

Environment
  - Ghost vars: 1
  - Phantom refs: 0

Quick Wins
  1. Remove unused package "left-pad"
  2. Delete or connect orphan file src/legacy.ts
  3. Remove unused environment variable OLD_API_URL

CLI Options

Option Description
--json Print the complete report as JSON
--ci Enable CI exit behavior with a default minimum score of 70
--score-min <score> Exit with code 1 when the score is below the selected threshold
--only <scanners> Run selected scanners, such as deps,env,security
--offline Skip network-backed npm outdated and npm audit checks
--fix Remove detected unused packages from package.json

Examples:

npx sourcepulse --json
npx sourcepulse --only=deps,env,security
npx sourcepulse --offline
npx sourcepulse --ci --score-min=80

Using --fix

--fix only removes packages detected as unused and refreshes package-lock.json when present.

npx sourcepulse --fix
git diff

Review the resulting diff before committing. Static analysis can require project-specific judgment.

CI Usage

Add SourcePulse to GitHub Actions:

- name: Run SourcePulse
  run: npx sourcepulse --ci --json --score-min=70

The command exits with code 1 when the score falls below the selected minimum.

Optional Configuration

SourcePulse works without configuration. To customize behavior, add sourcepulse.config.ts in the project root:

import type { SourcePulseConfig } from "sourcepulse";

export default {
  weights: {
    security: 30,
    deps: 20,
  },
  ignoreDependencies: ["@types/node"],
  ignoreEnvVars: ["NODE_ENV"],
  ignoreFiles: ["**/generated/**"],
  externalChecks: true,
  staleBranchDays: 60,
} satisfies SourcePulseConfig;

Supported config filenames:

sourcepulse.config.ts
sourcepulse.config.mts
sourcepulse.config.js
sourcepulse.config.mjs
sourcepulse.config.cjs
sourcepulse.config.json

Legacy stackradar.config.* and stackprobe.config.* filenames are also supported.

Plugins

Plugins can add project-specific findings:

import type { SourcePulsePlugin } from "sourcepulse";

export default {
  name: "license-policy",
  scan: async ({ root }) => {
    return [{ message: `Review licenses in ${root}`, penalty: 2 }];
  },
} satisfies SourcePulsePlugin;

Register the plugin from your config file:

export default {
  plugins: ["./tools/sourcepulse-license-plugin.ts"],
};

Requirements

  • Node.js 20 or newer
  • npm for dependency checks
  • Git for repository freshness and committed .env detection

Development

npm install
npm run build-check
npm run lint
npm test
npm run build

License

MIT

About

Zero-config project intelligence CLI for JavaScript and TypeScript repositories

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages