{"id":51338736,"url":"https://github.com/vcian/project-inspector","last_synced_at":"2026-07-02T05:30:38.759Z","repository":{"id":359133404,"uuid":"1238614521","full_name":"vcian/project-inspector","owner":"vcian","description":"Offline-first static analysis CLI for Node.js \u0026 TypeScript — AST security scanning, architecture \u0026 dependency analysis, interactive HTML dashboard, SARIF + SBOM. No code leaves your machine.","archived":false,"fork":false,"pushed_at":"2026-06-11T13:34:48.000Z","size":546,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T14:16:52.729Z","etag":null,"topics":["ast","ci-cd","cli","code-analysis","code-quality","code-review","developer-tools","devsecops","express","javascript","nextjs","nodejs","owasp","react","sarif","sbom","security","security-tools","static-analysis","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@vcian/project-inspector","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vcian.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-14T09:31:47.000Z","updated_at":"2026-06-11T13:33:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vcian/project-inspector","commit_stats":null,"previous_names":["vcian/project-inspector"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/vcian/project-inspector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vcian%2Fproject-inspector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vcian%2Fproject-inspector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vcian%2Fproject-inspector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vcian%2Fproject-inspector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vcian","download_url":"https://codeload.github.com/vcian/project-inspector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vcian%2Fproject-inspector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35034984,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","ci-cd","cli","code-analysis","code-quality","code-review","developer-tools","devsecops","express","javascript","nextjs","nodejs","owasp","react","sarif","sbom","security","security-tools","static-analysis","typescript"],"created_at":"2026-07-02T05:30:38.235Z","updated_at":"2026-07-02T05:30:38.753Z","avatar_url":"https://github.com/vcian.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @vcian/project-inspector\n\n[![npm version](https://img.shields.io/npm/v/%40vcian%2Fproject-inspector.svg)](https://www.npmjs.com/package/@vcian/project-inspector)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![CI](https://github.com/vcian/project-inspector/actions/workflows/ci.yml/badge.svg)](https://github.com/vcian/project-inspector/actions/workflows/ci.yml)\n[![npm downloads](https://img.shields.io/npm/dm/%40vcian%2Fproject-inspector.svg)](https://www.npmjs.com/package/@vcian/project-inspector)\n\n**Your code never leaves your machine.** `project-inspector` is a fully offline, deterministic static-analysis CLI — no source upload, no remote server, no LLM, no telemetry. Every scan runs locally and produces identical output for identical input, so it is safe for air-gapped environments, regulated codebases, and CI gates where sending proprietary source to a cloud service is a non-starter.\n\nIt scans source code, lockfiles, and project structure to generate production-focused reports for security, architecture, dependencies, API exposure, performance, and release readiness — delivered as a single self-contained interactive HTML dashboard and machine-readable artifacts (`json`, `sarif`).\n\n## Why use this\n\n- Fast local feedback for engineering and AppSec review.\n- Stable, deterministic output suitable for CI gates and trend tracking.\n- Zero LLM dependency; works in restricted or disconnected environments.\n- Produces an interactive HTML dashboard, Markdown reports, and machine-readable artifacts (`json`, `sarif`).\n- No CDN dependencies — the HTML report is fully self-contained and works offline.\n\n## How it compares to SonarQube and Semgrep\n\n`project-inspector` is **not** a replacement for SonarQube or Semgrep — it serves a different point in the workflow, and being honest about that matters:\n\n- **vs SonarQube** — SonarQube is a server-hosted quality platform with deep multi-language coverage, historical dashboards, and a rich rule engine, but it requires running (or paying for) a server and pushing your code/metrics into it. `project-inspector` runs as a single offline CLI with zero infrastructure and a self-contained HTML report. Choose SonarQube for org-wide, long-lived quality governance across many languages; choose `project-inspector` for fast, private, infrastructure-free analysis of Node.js/TypeScript projects.\n- **vs Semgrep** — Semgrep has a far larger, community-maintained rule registry and a powerful custom pattern language for cross-language taint and dataflow analysis. `project-inspector` ships a focused, curated rule set tuned for the Node.js/TS ecosystem and pairs it with architecture, dependency, API-surface, and database/ER analysis plus a production-readiness verdict in one tool. Choose Semgrep when you need breadth of rules or custom dataflow queries; choose `project-inspector` when you want an opinionated, all-in-one readiness report without writing rules.\n\nIn practice these tools are complementary: many teams run `project-inspector` as a fast local/CI gate and keep Semgrep or SonarQube for deeper, language-agnostic coverage.\n\n## Core capabilities\n\n- Static code analysis (AST + rule heuristics).\n- Security signals aligned with OWASP-style categorization.\n- Dependency and migration risk intelligence (offline + optional `npm audit`).\n- API surface discovery (HTTP + CLI command heuristics).\n- Performance and memory anti-pattern detection.\n- Inventory and project topology mapping.\n- Database schema intelligence — ER diagram with entity/relation visualization.\n- CI gate verdict via `check`.\n\n## Interactive HTML dashboard\n\nEvery scan produces `project-report/index.html` — a single-file, fully offline HTML report.\n\n### Dashboard preview\n\n**Overview** — production-readiness gauge, per-axis scores, and severity breakdown:\n\n![project-inspector dashboard — Overview tab showing readiness gauge, scores, and severity breakdown](docs/assets/dashboard-overview.png)\n\n**Performance** — engine findings with severity, source location, and title:\n\n![project-inspector dashboard — Performance tab showing performance and memory findings](docs/assets/dashboard-performance.png)\n\n**Bundle** — every generated report file, openable locally with zero CDN calls:\n\n![project-inspector dashboard — Bundle tab listing all generated report files](docs/assets/dashboard-bundle.png)\n\n\u003e **View a sample report:** the dashboard is generated locally — run `project-inspector scan` in any project and open `project-report/index.html`. Package and source: [npm](https://www.npmjs.com/package/@vcian/project-inspector) · [GitHub](https://github.com/vcian/project-inspector).\n\nThe report has the following tabs:\n\n| Tab | Content |\n|-----|---------|\n| **Issues** | Full findings table with severity badges, filters, owner, fix guidance, and compliance tags |\n| **Bundle** | All generated report files with inline Markdown and JSON preview, syntax-highlighted |\n| **Architecture** | Data-flow pipeline diagram, framework detection, architecture issues list |\n| **Database** | Auto-detected ER diagram (Collections for Mongoose, Tables for SQL/Prisma/TypeORM/Drizzle/Sequelize), relations, indexing hints, schema model cards |\n\nThe dashboard requires no server — open it directly in a browser.\n\n## Supported ecosystems\n\n- Node.js / TypeScript / JavaScript\n- React / Next.js\n- Express / Fastify\n- Heuristic NestJS support\n- MongoDB / Mongoose (Collection-level ER diagram and relation detection)\n- SQL databases via Prisma, TypeORM, Drizzle ORM, Sequelize, or raw `.sql` DDL\n- Monorepo and multi-project workspace detection (heuristic)\n\n## Install\n\n### Global install (recommended for CI runners and local CLI use)\n\n```bash\nnpm install -g @vcian/project-inspector\n```\n\n### Verify install\n\n```bash\nproject-inspector --help\n```\n\n## Quick start\n\n```bash\ncd your-project\nproject-inspector scan\n```\n\nDefault output directory: `./project-report`\n\nOpen the report:\n\n```bash\n# macOS\nopen project-report/index.html\n# Windows\nstart project-report/index.html\n# Linux\nxdg-open project-report/index.html\n```\n\n## CLI commands\n\n| Command | Purpose |\n|--------|---------|\n| `scan` | Run all configured engines and write reports |\n| `check` | Run `scan`, evaluate readiness gates, and exit non-zero on failure |\n| `watch` | Re-run scans on file changes (debounced, single-flight queue) |\n| `chat` | Offline keyword search over previously generated reports (no LLM) |\n| `clear` | Remove report directory (including `.cache`) |\n| `update-vuln-db` | Refresh optional vulnerability override DB from `VULN_DB_URL` (HTTPS) |\n\n## Command usage\n\n### `scan`\n\n```bash\nproject-inspector scan [options]\n```\n\n| Option | Description |\n|--------|-------------|\n| `-c, --cwd \u003cpath\u003e` | Project root. Default: current working directory |\n| `-o, --out \u003cpath\u003e` | Output directory. Default: `\u003ccwd\u003e/project-report` |\n| `-j, --concurrency \u003cn\u003e` | Parallelism for file-level work (`1-32`; default `max(2, cpuCount - 1)`) |\n| `--mode \u003cquick\\|deep\\|diff\u003e` | Scan strategy. `diff` forces git-changed scope |\n| `--online` | Enable online dependency audit (`npm audit`) where supported |\n| `--incremental` | Prefer git-changed files |\n| `--no-cache` | Ignore cached file hash / merged scan reuse |\n| `--rescan` | Force full workspace scan (disable cache + incremental optimization) |\n| `--offline` | Disable vuln DB staleness messaging and auto-refresh behavior |\n| `--auto-update-db` | Best-effort HTTPS refresh of vuln override DB before dependency engine |\n| `--format \u003cmd\\|json\\|sarif\u003e` | Generate extra machine outputs (`results.json` and/or `results.sarif`) |\n\n### `check`\n\n```bash\nproject-inspector check [options]\n```\n\nSame options as `scan`.  \n`check` writes `ci-result.json` and exits with code `1` when gate criteria fail.\n\n### `watch`\n\n```bash\nproject-inspector watch [options]\n```\n\nSame options as `scan`. Uses a `1500ms` debounce and single-flight scheduling to prevent overlapping scans.\n\n### `chat`\n\n```bash\nproject-inspector chat [options]\n```\n\n| Option | Description |\n|--------|-------------|\n| `-c, --cwd \u003cpath\u003e` | Root directory used to locate latest reports |\n\n### `clear`\n\n```bash\nproject-inspector clear [options]\n```\n\n| Option | Description |\n|--------|-------------|\n| `-c, --cwd \u003cpath\u003e` | Project root |\n| `-o, --out \u003cpath\u003e` | Report directory to delete |\n\n### `update-vuln-db`\n\n```bash\nproject-inspector update-vuln-db [options]\n```\n\n| Option | Description |\n|--------|-------------|\n| `-c, --cwd \u003cpath\u003e` | Project root |\n| `-o, --out \u003cpath\u003e` | Report directory |\n\n## Recommended production workflows\n\n### Local developer loop\n\n```bash\nproject-inspector scan --mode quick --incremental\n```\n\n### Pre-merge validation\n\n```bash\nproject-inspector check --mode deep --format json --format sarif\n```\n\n### Large refactor or branch baseline refresh\n\n```bash\nproject-inspector scan --rescan --mode deep\n```\n\n### Air-gapped / strict offline environment\n\n```bash\nproject-inspector scan --offline\n```\n\n## Output files\n\nSecurity findings, performance signals, dependency analysis, and hotspots are all embedded inside `audit-summary.md`, `action-plan.md`, and the `index.html` dashboard — there are no separate `security.md` / `performance.md` files.\n\n| Path | Content |\n|------|---------|\n| `project-report/index.html` | **Interactive HTML dashboard** (Issues, Bundle, Architecture, Database tabs) |\n| `project-report/action-plan.md` | Prioritized remediation checklist with owner assignments and ETAs |\n| `project-report/audit-summary.md` | GitHub-style Markdown summary for PR comments and job summaries |\n| `project-report/api.md` | API surface review — route matrix, auth/validation coverage, endpoint access |\n| `project-report/architecture.md` | Architecture analysis, module-to-datastore map, API-to-DB flow, structural issues |\n| `project-report/database.md` | Database schema analysis, ER relations, indexing hints, ORM findings |\n| `project-report/decision.json` | Machine-readable production verdict and gate status for CI automation |\n| `project-report/scores.json` | Numeric scores across all axes plus segment rollup |\n| `project-report/openapi.json` | OpenAPI **3.1** export auto-generated from detected HTTP routes |\n| `project-report/sbom.cdx.json` | CycloneDX **1.5** SBOM from npm lockfile |\n| `project-report/governance-suppressions.json` | Snapshot of active governance suppressions |\n| `project-report/results.sarif` | SARIF **2.1.0** report (always written) |\n| `project-report/results.json` | Full scan result as JSON — only written with `--format json` |\n| `project-report/ci-result.json` | Gate verdict written by the `check` command |\n| `project-report/.cache/merged-scan.json` | Cached full scan payload for partial/incremental refresh |\n| `project-report/.cache/file-hashes.json` | SHA-256 hash map for incremental file-change detection |\n| `project-report/.cache/dependency-snapshot.json` | Dependency and lockfile fingerprint (includes vuln DB hash) |\n| `project-report/.cache/scan-meta.json` | Scan metadata and per-engine timing |\n| `project-report/.cache/vuln-db-meta.json` | Metadata about the last vuln DB fetch and staleness state |\n| `project-report/.cache/env-snapshot.json` | Environment variable key snapshot for drift detection |\n| `docs/rules-catalog.md` | Generated rules catalog — run `npm run docs:catalog` to refresh |\n\n## CI integration\n\n### GitHub Actions example\n\n```yaml\nname: Static Analysis Gate\n\non:\n  pull_request:\n  push:\n    branches: [main]\n\njobs:\n  inspect:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n      - run: npm install -g @vcian/project-inspector\n      - name: Run production gate\n        run: project-inspector check --cwd . --mode deep --format sarif --format json\n      - name: Upload SARIF\n        if: always()\n        uses: github/codeql-action/upload-sarif@v3\n        with:\n          sarif_file: project-report/results.sarif\n```\n\n## Configuration reference\n\n| Key / Flag | Type | Purpose |\n|------------|------|---------|\n| `LOG_LEVEL` | env | Pino log level (`fatal`, `error`, `warn`, `info`, `debug`, ...) |\n| `--mode` | cli | `quick`, `deep`, `diff` |\n| `--concurrency` | cli | Control parallelism (`1-32`) |\n| `--format` | cli | Additional machine outputs (`json`, `sarif`) |\n| `--auto-update-db` | cli | Best-effort refresh using `VULN_DB_URL` before dependency scan |\n| `--offline` | cli | Disable remote vuln DB staleness flow and auto-refresh |\n| `VULN_DB_URL` | env | HTTPS URL to override vulnerability rule database |\n| `policyPack` | `project-inspector.config.json` | Named overlay (`packs/\u003cid\u003e.json`) merging extra ignore globs / suppress substrings (HIPAA, SOC2, PCI, OWASP ASVS samples ship under `packs/`) |\n\n### `VULN_DB_URL` payload shape\n\n```json\n{\n  \"version\": \"string\",\n  \"updated\": \"ISO-8601 timestamp\",\n  \"rules\": []\n}\n```\n\n## Reliability and security model\n\n### What this tool is good at\n\n- Deterministic static risk discovery.\n- Engineering governance and CI gate standardization.\n- Early issue detection before runtime testing.\n\n### What this tool is not\n\n- Not a replacement for penetration testing or dynamic analysis.\n- Not full inter-procedural taint analysis.\n- Not a complete framework semantic model.\n\nUse findings as high-signal review inputs, then confirm in code review or targeted testing.\n\n## Limitations\n\n- Security engine uses AST + pattern heuristics (no full cross-function data flow).\n- `chat` is offline keyword search over local report text, not an AI assistant.\n- NestJS route/auth/validation classification is decorator-oriented heuristic analysis.\n- Supply-chain insight combines offline rules with optional `npm audit` in `--online` mode.\n- Multi-project auto-detection is heuristic when no explicit workspace config exists.\n- Mongoose schema detection covers `mongoose.Schema`, `new Schema()`, and `mongoose.model()` patterns; non-standard schema factory wrappers may not be captured.\n\n## Performance and determinism notes\n\n- Caching is enabled by default for speed.\n- `--rescan` should be used after major repository churn.\n- `--mode diff` and `--incremental` optimize for changed-file workflows.\n- Machine output contracts (`decision.json`, `ci-result.json`, `results.sarif`) are suited for automation.\n\n## Development and maintenance\n\n### Local development scripts\n\n| Script | Description |\n|--------|-------------|\n| `npm run build` | Compile TypeScript to `dist/` (runs build verification post-step) |\n| `npm run dev` | Run CLI entry in dev mode using `tsx` |\n| `npm run typecheck` | TypeScript strict type check (no emit) |\n| `npm run lint` | ESLint with zero warnings |\n| `npm test` | Node test runner for all configured test files |\n| `npm run test:coverage` | Test suite with lcov + text coverage via `c8` |\n| `npm run ci` | Full local CI gate: typecheck + lint + test |\n| `npm run clean` | Remove `dist/` directory |\n| `npm run refresh-majors` | Refresh curated package major-version metadata (network required) |\n| `npm run docs:catalog` | Generate `docs/rules-catalog.md` from engine rule definitions |\n\n### Node version\n\n- Runtime requirement: `node \u003e= 18.0.0`\n- Recommended for CI: Node.js `20.x` LTS\n\n## Production adoption checklist\n\n- Run `check` in CI on every PR and protected branch push.\n- Upload `results.sarif` to your security platform (GitHub Advanced Security compatible).\n- Track `scores.json` and `decision.json` over time for trend baselining.\n- Use `--rescan` for release branches and major refactors.\n- Keep `VULN_DB_URL` fresh if using private override intelligence.\n- Open `project-report/index.html` locally for the full interactive dashboard view.\n\n## Programmatic API\n\n`project-inspector` can also be used as a library in your own scripts or tools.\n\n```ts\nimport { runScan, writeScanArtifacts, computeScores } from '@vcian/project-inspector';\n\nconst result = await runScan({\n  cwd: process.cwd(),\n  outDir: './project-report',\n  mode: 'deep',\n});\n\nawait writeScanArtifacts(result, './project-report');\nconsole.log(result.scores.productionReadiness);\n```\n\nAll public exports are documented with JSDoc and ship with TypeScript declaration files (`dist/index.d.ts`). Key exports:\n\n| Export | Description |\n|--------|-------------|\n| `runScan(options)` | Run a full project scan and return a `ScanResult` |\n| `writeScanArtifacts(result, outDir)` | Write all report files (HTML, Markdown, SARIF, SBOM, OpenAPI, JSON) |\n| `computeScores(result)` | Compute numeric scores across all analysis axes |\n| `buildScoreDiagnostics(result)` | Per-axis hit counts for human-readable explanations |\n| `computeHotspots(result)` | Top-10 issues ranked by exploitability heuristic |\n| `evaluateCheckGates(result)` | Evaluate a ScanResult against gate thresholds |\n| `writeSarifReport(result, outDir)` | Write a SARIF 2.1.0 report only |\n\n## Open-source governance\n\n- Contribution guide: `CONTRIBUTING.md`\n- Code of conduct: `CODE_OF_CONDUCT.md`\n- Security policy: `SECURITY.md`\n- Support guide: `SUPPORT.md`\n- Change history: `CHANGELOG.md`\n- Release process: `RELEASING.md`\n\n## License\n\nMIT\n\n---\n\n## About ViitorCloud\n\n[ViitorCloud Technologies](https://viitorcloud.com/?utm_source=github\u0026utm_medium=readme\u0026utm_campaign=project-inspector) is a global technology company delivering AI, cloud, and enterprise software engineering solutions. We build developer tooling like `project-inspector` to help teams ship secure, production-ready software.\n\n- 🌐 Website: [viitorcloud.com](https://viitorcloud.com/?utm_source=github\u0026utm_medium=readme\u0026utm_campaign=project-inspector)\n- 📧 Contact: [support@viitorcloud.com](mailto:support@viitorcloud.com)\n- 💼 Services: [viitorcloud.com/services](https://viitorcloud.com/services/?utm_source=github\u0026utm_medium=readme\u0026utm_campaign=project-inspector)\n\nBuilt and maintained with ❤️ by the ViitorCloud team.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvcian%2Fproject-inspector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvcian%2Fproject-inspector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvcian%2Fproject-inspector/lists"}