Zero-config project intelligence for JavaScript and TypeScript repositories.
npx sourcepulseSourcePulse 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.
| 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 |
Scan the current directory:
npx sourcepulseScan another project:
npx sourcepulse ../my-projectExample 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
| 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--fix only removes packages detected as unused and refreshes package-lock.json when present.
npx sourcepulse --fix
git diffReview the resulting diff before committing. Static analysis can require project-specific judgment.
Add SourcePulse to GitHub Actions:
- name: Run SourcePulse
run: npx sourcepulse --ci --json --score-min=70The command exits with code 1 when the score falls below the selected minimum.
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 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"],
};- Node.js
20or newer - npm for dependency checks
- Git for repository freshness and committed
.envdetection
npm install
npm run build-check
npm run lint
npm test
npm run build