projscan 3.0.7 → 3.0.8

package/CONTRIBUTING.md

@@ -0,0 +1,209 @@
+# Contributing to projscan
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+```bash
+git clone https://github.com/abhiyoheswaran1/projscan.git
+cd projscan
+npm install
+npm run build
+```
+
+### Running locally
+
+```bash
+# Run the CLI directly from source
+node dist/cli/index.js doctor
+
+# Watch mode for development
+npm run dev
+```
+
+### Running tests
+
+```bash
+npm test              # Run all tests
+npm run test:watch    # Watch mode
+```
+
+### Linting and formatting
+
+```bash
+npm run lint          # ESLint
+npm run format        # Prettier
+```
+
+## How to Contribute
+
+### Reporting Bugs
+
+For security vulnerabilities, do not open a public issue. Follow [SECURITY.md](SECURITY.md).
+
+For ordinary bugs, open an [issue](https://github.com/abhiyoheswaran1/projscan/issues/new?template=bug_report.md) with:
+- Steps to reproduce
+- Expected vs actual behavior
+- Node.js version and OS
+
+### Suggesting Features
+
+Open an [issue](https://github.com/abhiyoheswaran1/projscan/issues/new?template=feature_request.md) describing:
+- The problem you're trying to solve
+- Your proposed solution
+- Alternative approaches you've considered
+
+### Submitting Pull Requests
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes
+3. Add or update tests as needed
+4. Run `npm test` and `npm run lint` to verify
+5. Write a clear PR description explaining the change
+
+## Legal requirements for contributions
+
+By contributing to projscan, you agree that your contribution will be licensed under the MIT License.
+
+You also certify the [Developer Certificate of Origin 1.1](https://developercertificate.org/) for your contribution. In practical terms:
+
+- you wrote the contribution, or you have the right to submit it under the project license
+- you are not adding code, docs, images, datasets, or generated output that you cannot license to this project
+- you understand that contributions are public and may be redistributed under the MIT License
+
+Maintainers may ask for signed-off commits. Add a sign-off with:
+
+```bash
+git commit --amend --signoff
+```
+
+Do not include secrets, private customer data, proprietary source code, or confidential vulnerability details in issues, pull requests, examples, screenshots, or fixtures.
+
+The MIT License covers project code and docs. It does not grant rights to use the projscan or Baseframe Labs names, icons, or wordmarks in a way that implies endorsement. See [TRADEMARKS.md](TRADEMARKS.md).
+
+## Project Structure
+
+```
+src/
+├── cli/          # Command definitions (Commander.js)
+├── core/         # Scanners, detectors, issue engine, hotspots, file inspector
+│   └── languages/  # LanguageAdapter + per-language parsers (JS via babel, Python via tree-sitter)
+├── analyzers/    # Issue checkers (eslint, prettier, test, architecture, deps, security, python*)
+├── fixes/        # Auto-fix implementations (ESLint, Prettier, Vitest, EditorConfig)
+├── reporters/    # Output formatters (console, JSON, markdown, SARIF)
+├── mcp/          # MCP server - tools, prompts, resources for AI agents
+└── utils/        # Shared utilities (config loader, changed-files, baseline, banner, logger)
+```
+
+### Adding a language
+
+As of 0.10, projscan has a `LanguageAdapter` interface (`src/core/languages/LanguageAdapter.ts`). Adding a new language means:
+
+1. Implement the interface in `src/core/languages/<lang>Adapter.ts`. The Python adapter (`pythonAdapter.ts`) is the reference - it wraps a tree-sitter grammar, extracts imports/exports/symbol defs, resolves imports, and detects package roots.
+2. Register the adapter in `src/core/languages/registry.ts`.
+3. If the parser needs a grammar binary (e.g. another tree-sitter language), vendor the wasm under `dist/grammars/` via `scripts/copy-wasm.mjs` and add a test in `tests/integration/packSmokeTest.test.ts` that asserts it ships in the tarball.
+4. Add language-specific analyzers under `src/analyzers/<lang>*.ts` (see `pythonTestCheck.ts`, `pythonLinterCheck.ts` for the pattern) and wire them into `src/core/issueEngine.ts`.
+5. Add tests mirroring `tests/core/languages/pythonAdapter.*.test.ts` coverage (parse, imports, exports, resolver, package roots).
+
+## Code Style
+
+- TypeScript with strict mode
+- ESLint + Prettier for formatting
+- Keep dependencies minimal - avoid adding new runtime dependencies unless necessary
+- Write tests for new analyzers and fixers
+
+## Stable surface
+
+The MCP tool inventory, CLI command list, and exit codes documented in `docs/STABILITY.md` are the **public contract**. CI runs `npm run check:stability` which compares the current build against `stability-baseline.json` checked into the repo root.
+
+- **Adding** a new MCP tool, optional argument, or CLI command is fine - the guard prints additions but does not fail.
+- **Removing** or **renaming** anything in the stable surface fails the guard. Either restore the surface or, if the change is intentional and warrants a major version bump, regenerate the baseline:
+
+  ```sh
+  npm run build
+  node scripts/check-stability.mjs --update
+  ```
+
+  Only run `--update` when you genuinely intend to break the contract (i.e. a major-version release). The friction is the point.
+
+## Areas wanting help
+
+Concrete on-ramps for new contributors. Each is scoped to fit a first PR. Pre-drafted starter tasks live under [`.github/seed-issues/`](.github/seed-issues/) — pick one and either claim its corresponding GitHub issue or open one and link the file.
+
+- **New language adapters.** The `LanguageAdapter` interface (`src/core/languages/LanguageAdapter.ts`) is the cleanest entry point. Seven languages are wired today (JS, TS, Python, Go, Java, Ruby, Rust). The Python and Rust adapters are good references — Python for the simplest shape, Rust for a recent end-to-end example. Each adapter is ~200 LOC plus walkers (imports, exports, CC, per-fn CC, callSites) and a vendored tree-sitter grammar wasm. Pre-drafted tickets: [PHP](.github/seed-issues/02-add-php-language-adapter.md), [C#](.github/seed-issues/03-add-c-sharp-language-adapter.md). Plus a [step-by-step walkthrough doc](.github/seed-issues/08-doc-walkthrough-language-adapter.md) is itself an open issue.
+- **New analyzers.** Issue checkers live in `src/analyzers/`. Each is a pure function `(rootPath, files) => Promise<Issue[]>`. Existing ones (`testCheck`, `prettierCheck`, `securityCheck`, `dependencyRiskCheck`, `cycleCheck`) are good shape templates. Wire into `src/core/issueEngine.ts`. Tests in `tests/analyzers/`.
+- **New reporters.** Output formatters in `src/reporters/`. Implement the same surface as `consoleReporter.ts` / `markdownReporter.ts` / `jsonReporter.ts` / `htmlReporter.ts`. Pre-drafted tickets: [HTML for `pr-diff`](.github/seed-issues/04-html-reporter-for-pr-diff.md), [HTML for `coverage`](.github/seed-issues/05-html-reporter-for-coverage.md).
+- **MCP tools.** Each tool is a `{name, description, inputSchema, handler}` object exported from `src/mcp/tools/<name>.ts` and registered in `src/mcp/tools.ts`. Mirror an existing one (e.g. `src/mcp/tools/coupling.ts` is a clean shape). Add a `tools/list` assertion to `tests/mcp/server.test.ts`.
+- **Fix-suggest templates.** The rule-driven action-prompt registry in `src/core/fixSuggest.ts` covers ~12 issue families. Each new template is ~25 LOC. Pre-drafted ticket: [eslint-* template](.github/seed-issues/06-eslint-fix-suggest-template.md).
+- **UX polish.** Small, high-leverage CLI ergonomics. Pre-drafted ticket: [impact-symbol disambiguation warning](.github/seed-issues/07-impact-cli-symbol-disambiguation.md).
+- **Documentation.** `docs/GUIDE.md` covers the agent journey + per-command reference; tighter sections still wanted: per-analyzer "what triggers / how to silence" tables, monorepo setup walkthroughs, framework-specific guides.
+
+### First-time contributor walkthrough
+
+If you've never landed a PR on this repo before, the smallest possible loop:
+
+```sh
+# 1. Fork on GitHub, then locally:
+git clone git@github.com:<your-username>/projscan.git
+cd projscan
+
+# 2. Verify the baseline works (no code changes yet)
+npm install
+npm test                              # 800+ tests, ~6s
+npm run lint                          # eslint, no errors expected
+npm run build                         # tsc + wasm copy + manifest generation
+npm run check:stability               # baseline diff; should be clean
+
+# 3. Pick a seed issue, mirror the template it points at
+#    e.g. .github/seed-issues/06-eslint-fix-suggest-template.md
+#    -> open src/core/fixSuggest.ts, find the existing templates,
+#       mirror one, write tests, run npm test
+
+# 4. Commit + push to your fork
+git checkout -b feat/eslint-fix-template
+git add -A
+git commit -m "Add fix-suggest template for eslint-* rules"
+git push origin feat/eslint-fix-template
+
+# 5. Open a PR back to abhiyoheswaran1/projscan:main
+#    Reference the seed issue file in the PR description.
+```
+
+CI runs the same checks (`npm test`, `npm run lint`, `npm run check:stability`) on every PR. As long as those pass, a maintainer will review.
+
+For larger work (refactors, cross-cutting changes), open an issue first to discuss the approach. We'd rather agree on the shape before you spend a weekend on it.
+
+## Releasing
+
+A release is a four-step ritual now that `.github/workflows/release.yml` does the heavy lifting. Steps 1-3 prep and ship the npm, GitHub Release, and MCP Registry surfaces; step 4 is the website surface that lives in the separate website repo.
+
+1. **Bump version + write the CHANGELOG entry** in a PR against `main`:
+   - `package.json#version` → new semver (patch for fixes, minor for features, major if anything breaks).
+   - `.github/mcp-registry/server.json` — bump BOTH `version` fields (top-level and `packages[0].version`). Description must stay ≤ 100 chars (registry limit).
+   - `CHANGELOG.md` — add a `## [X.Y.Z] — YYYY-MM-DD` section at the top in Keep-a-Changelog format. Cover Added / Changed / Removed / Notes; be honest about tradeoffs. The release workflow slices this verbatim into the GitHub Release body.
+   - Sweep for "X tools" / "Y languages" counts in `README.md`, `docs/GUIDE.md`, `docs/ROADMAP.md` and update them.
+   - **Regenerate the dogfood health badge.** Run `npx projscan badge` against the prepped tree. If the letter or score in the README badge changed, update `README.md` to match. **A drop in letter (e.g., A → B) is a release blocker** — fix the underlying signal before tagging. (The badge is a static `img.shields.io/badge` snapshot, not a live endpoint, so it stays consistent until the next release intentionally moves it.)
+   - Run `npm run release:check`. It reports version/changelog drift, dirty worktree state, tag state, and the next release action. When there are no metadata or git blockers, it also runs the build, release gate, tests, lint, stability check, SBOM generation, and packed install smoke.
+
+2. **Merge the PR.** Per the project's PR-and-review rule, every change including release prep goes through review. Wait for CI to pass on the merged `main` commit before tagging.
+
+3. **Tag and push.** Tags are allowed from `main` only. Never tag or publish from a feature, fix, release, or temporary branch. From a clean, current `main` checkout, run:
+   ```
+   git switch main
+   git pull --ff-only origin main
+   npm run release:check
+   git tag -a vX.Y.Z -m "Release vX.Y.Z"
+   git push origin vX.Y.Z
+   ```
+   The `Release` workflow fires automatically. It validates versions, runs the full build / test / lint / stability gate, slices the CHANGELOG entry, publishes to npm with provenance, creates the GitHub Release with `dist/tool-manifest.json` and the SBOM attached, and republishes the MCP Registry metadata through GitHub OIDC. If anything fails before npm, no GitHub Release is created and no npm publish happens. If anything fails after npm, fix it and use the workflow's `workflow_dispatch` re-run with the same tag; npm, GitHub Release, and MCP Registry steps are idempotent.
+
+4. **Bump the website's expectations** (separate repo). In the personal-website repo, open `tools.astro` (or wherever the EXPECTED block lives) and edit:
+   - The hardcoded **manifest URL pin** → swap `releases/download/vX.Y.Z/tool-manifest.json` for the new tag.
+   - `EXPECTED.minVersion` → the new version.
+   - `EXPECTED.requiredTools` → append any new MCP tool names the release added.
+
+   The website build refuses to run until all three edits are in. That friction is the feature — it prevents the docs page from drifting out of sync with the published tool surface. The changelog page is regenerated from `CHANGELOG.md` on `main` at build time, so the next site build naturally picks up the new entry.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License. See [LICENSE](LICENSE), [DISCLAIMER.md](DISCLAIMER.md), and [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

package/DISCLAIMER.md

@@ -0,0 +1,9 @@
+# Disclaimer
+
+projscan is provided under the MIT License and ships without warranties. See [LICENSE](LICENSE) for the binding license terms.
+
+projscan reports are developer-assistance signals. They are not legal, security, compliance, financial, or professional advice. A human maintainer remains responsible for release decisions, vulnerability handling, dependency review, and production changes.
+
+Security, dataflow, supply-chain, and quality findings can be incomplete or wrong. Treat `block`, `caution`, and `proceed` verdicts as review inputs, not guarantees.
+
+Local plugins run as local code when enabled. Only run plugins you trust.

package/PRIVACY.md

@@ -0,0 +1,35 @@
+# projscan Privacy Notice
+
+projscan is a local, open-source developer tool. This notice applies to the projscan CLI, MCP server, package contents, generated local artifacts, and repository docs.
+
+projscan is part of the Baseframe Labs family of products (https://www.baseframelabs.com). Baseframe Labs is an umbrella brand, not the legal subject of this notice. This notice applies to projscan only.
+
+## Local-first behavior
+
+By default, projscan runs on your machine and reads files in the repository where you run it. It does not upload source code, dependency data, scan results, telemetry, or usage analytics to a projscan service.
+
+projscan may write local files when you ask it to, such as `.projscan-cache/`, `.projscan-feedback.json`, baselines, handoff files, generated policies, generated GitHub Actions, or reports.
+
+## Commands that can involve network access
+
+Some workflows can involve network access because they call external tooling or package managers:
+
+- installing projscan with npm or running it through npx contacts the npm registry before projscan starts
+- `projscan audit` shells out to npm audit behavior for the current project
+- commands or modes that explicitly ask for registry checks may contact the configured package registry
+- semantic search can download an optional local embedding model when the optional `@xenova/transformers` peer is installed and the user opts into semantic mode
+- local analyzer or reporter plugins can do anything their code does; only enable plugins you trust
+
+## Environment variables and secrets
+
+projscan may pass `process.env` to child processes such as Git or npm so those tools work normally. projscan does not intentionally inspect `.env` values, API keys, session tokens, or private credentials for telemetry or product analytics.
+
+Security analyzers may flag committed secret-looking strings in repository files. Those findings stay in local output unless you choose to copy, save, or publish them.
+
+## Feedback artifacts
+
+`projscan feedback` creates local JSON evidence about reviewer usefulness, minutes saved, prevented bad edits, false positives, owner clarity, next-command clarity, and repeat PR use. Treat that artifact as team data. Do not commit it if it contains private PR URLs, reviewer handles, or internal notes you do not want public.
+
+## Contact
+
+For privacy or security questions about projscan, contact support@baseframelabs.com.

package/README.md

@@ -9,9 +9,9 @@
 
 **Agent-first code intelligence.** An MCP server that lets AI coding agents (Claude Code, Codex, Cursor, Gemini, Windsurf, Cline, Continue, Zed — any MCP-aware client) query your codebase — with a CLI for humans and a local plugin layer for team-specific policy and reporting.
 
-[AI Agent Quick Start](#ai-agent-integration-mcp) · [CLI Quick Start](#quick-start) · [Commands](#commands) · [Full Guide](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.7/docs/GUIDE.md) · [Roadmap](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.7/docs/ROADMAP.md)
+[AI Agent Quick Start](#ai-agent-integration-mcp) · [CLI Quick Start](#quick-start) · [Commands](#commands) · [Full Guide](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.8/docs/GUIDE.md) · [Roadmap](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.8/docs/ROADMAP.md)
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.7/docs/projscan-reporter-plugin.png" alt="projscan reporter plugin running in a macOS-style terminal window with a team health summary" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.8/docs/projscan-reporter-plugin.png" alt="projscan reporter plugin running in a macOS-style terminal window with a team health summary" width="700">
 
 </div>
 
@@ -19,15 +19,13 @@
 
 ## Why?
 
-AI coding agents are becoming the primary interface to code. Today, when you ask your agent *"which files implement auth?"* or *"what breaks if I bump React from 18 to 19?"* - it either guesses from names, or it shells out to grep and reads raw output not built for it.
+AI coding agents are becoming the primary interface to code. When you ask an agent *"which files implement auth?"* or *"what breaks if I bump React from 18 to 19?"*, it needs structured repo context, not raw grep output.
 
-**projscan is the first code-intelligence tool built for agents, not for humans.** Your agent gets a fast, AST-accurate, context-budget-aware view of your codebase through structured MCP tools. It can run a preflight safety gate before edits or merge, including supply-chain IOC evidence, query a stable v3 semantic graph, detect bridge-helper dataflow risks, find symbol definitions, preview upgrades, rank hotspots, diff structural changes between refs, surface coupling/cycle hotspots, get an **intent-grounded** one-call PR review (now with new-taint-flow and bridge-dataflow detection that *blocks* unsafe merges, plus an optional natural-language intent arg that labels each finding expected / unexpected / out-of-scope), request structured fix-action prompts for any open issue and **mechanically apply** the safe ones with rollback, ask "what breaks if I change this?" via transitive blast-radius analysis (across registered sibling repos too), surface source-to-sink taint flows, share a durable session across multiple agent invocations, and learn from how you use it — quieting accumulated noise on this specific repo over time without ever phoning home.
+**projscan is code intelligence built for agents.** MCP clients get a fast, AST-backed, context-budget-aware view of your codebase: semantic graph, dataflow risks, review verdicts, hotspots, ownership, preflight gates, fix prompts, impact analysis, and durable session context. Everything is local and offline.
 
-The stable local plugin platform turns that same pipeline into a team substrate: analyzer plugins add project-specific findings, and reporter plugins render `doctor`, `analyze`, and `ci` in your team's own voice without changing the underlying scan.
+For teams, projscan turns that context into a repeatable PR habit. `projscan init team` creates policy, CI, ownership, and baseline memory. `projscan evidence-pack --pr-comment` gives reviewers a compact verdict with top risks, First Fix, owner routing, baseline trend memory, and exact next commands. `projscan feedback`, `projscan dogfood`, and `projscan trial` measure whether the loop actually saved time, prevented risky edits, and stayed trustworthy across real repos.
 
-The 3.0.7 loop focuses on the first useful team PR and measured repeat use: `projscan init team` creates policy, CI, ownership, and baseline memory; `projscan evidence-pack --pr-comment` posts a compact verdict with trust calibration, top risks, a First Fix, owner routing, baseline trend memory, reviewer feedback prompts, and exact next commands; `projscan dogfood` checks whether that loop is ready across real repos. `projscan trial` rolls those signals into an adoption verdict with first-fix, repeat-use, and website-proof follow-ups.
-
-Humans get the same thing through the CLI.
+The local plugin platform lets teams add project-specific findings and render `doctor`, `analyze`, and `ci` in their own voice without changing the scan pipeline. Humans get the same information through the CLI.
 
 **Everything is offline-first. Zero network calls. No API keys.**
 
@@ -35,7 +33,7 @@ Humans get the same thing through the CLI.
 npx projscan
 ```
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.7/docs/projscan-reporter-plugin.gif" alt="projscan doctor rendered through a local reporter plugin in a macOS-style terminal window" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.8/docs/projscan-reporter-plugin.gif" alt="projscan doctor rendered through a local reporter plugin in a macOS-style terminal window" width="700">
 
 Run `projscan doctor` for a focused health check:
 
@@ -43,7 +41,7 @@ Run `projscan doctor` for a focused health check:
 npx projscan doctor
 ```
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.7/docs/npx%20projscan%20doctor.gif" alt="npx projscan doctor" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.8/docs/npx%20projscan%20doctor.gif" alt="npx projscan doctor" width="700">
 
 ## Install
 
@@ -80,7 +78,7 @@ projscan evidence-pack --website-prompt  # Approval packet with product evidence
 projscan evidence-pack --pr-comment # PR comment with trust calibration + First Fix
 projscan feedback init --output .projscan-feedback.json # Create reviewer feedback evidence
 projscan dogfood --repo ../api --repo ../web --format json # Multi-repo adoption proof loop
-projscan trial --repo ../api --repo ../web --feedback .projscan-feedback.json --format json # Executive adoption-readiness report
+projscan trial --repo ../api --repo ../web --feedback .projscan-feedback.json --format json # Adoption-readiness report
 projscan regression-plan --level full    # Risk-based verification matrix
 projscan handoff                    # Concise next-agent handoff
 projscan handoff --write docs/agent-handoff.md # Persist next-agent handoff artifact
@@ -109,9 +107,9 @@ projscan plugin test .projscan-plugins/policy.projscan-plugin.json
 PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor --reporter team-radar
 ```
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.7/docs/npx%20projscan%20--help.gif" alt="npx projscan --help" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.8/docs/npx%20projscan%20--help.gif" alt="npx projscan --help" width="700">
 
-For a comprehensive walkthrough, see the **[Full Guide](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.7/docs/GUIDE.md)**.
+For a comprehensive walkthrough, see the **[Full Guide](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.8/docs/GUIDE.md)**.
 
 ## Commands
 
@@ -175,31 +173,31 @@ projscan --help
 <details>
 <summary><strong>projscan structure</strong> - Directory tree with file counts</summary>
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.7/docs/npx%20projscan%20structure.gif" alt="npx projscan structure" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.8/docs/npx%20projscan%20structure.gif" alt="npx projscan structure" width="700">
 </details>
 
 <details>
 <summary><strong>projscan diagram</strong> - Architecture visualization</summary>
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.7/docs/npx%20projscan%20diagram.gif" alt="npx projscan diagram" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.8/docs/npx%20projscan%20diagram.gif" alt="npx projscan diagram" width="700">
 </details>
 
 <details>
 <summary><strong>projscan dependencies</strong> - Dependency analysis</summary>
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.7/docs/npx%20projscan%20dependencies.gif" alt="npx projscan dependencies" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.8/docs/npx%20projscan%20dependencies.gif" alt="npx projscan dependencies" width="700">
 </details>
 
 <details>
 <summary><strong>projscan explain</strong> - File explanation</summary>
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.7/docs/npx%20projscan%20explain.gif" alt="npx projscan explain" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.8/docs/npx%20projscan%20explain.gif" alt="npx projscan explain" width="700">
 </details>
 
 <details>
 <summary><strong>projscan badge</strong> - Health badge generation</summary>
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.7/docs/npx%20projscan%20badge.gif" alt="npx projscan badge" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.8/docs/npx%20projscan%20badge.gif" alt="npx projscan badge" width="700">
 </details>
 
 ### Output Formats
@@ -221,7 +219,7 @@ Run `projscan help` for the generated command-by-command support matrix.
 
 projscan can load local plugins from `.projscan-plugins/` when `PROJSCAN_PLUGINS_PREVIEW=1` is set. The environment flag is kept for explicit local-code opt-in. Analyzer plugins emit normal projscan issues; reporter plugins render supported CLI commands with team-specific output.
 
-**2.0 upgrade notes:** migrating from 1.x or authoring plugins? Start with the [2.0 Migration Guide](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.7/docs/2.0-MIGRATION.md), then use [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.7/docs/PLUGIN-AUTHORING.md), the [Plugin Gallery](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.7/docs/PLUGIN-GALLERY.md), and the [manifest schema](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.7/docs/plugin.schema.json) as the stable contract.
+**2.0 upgrade notes:** migrating from 1.x or authoring plugins? Start with the [2.0 Migration Guide](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.8/docs/2.0-MIGRATION.md), then use [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.8/docs/PLUGIN-AUTHORING.md), the [Plugin Gallery](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.8/docs/PLUGIN-GALLERY.md), and the [manifest schema](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.8/docs/plugin.schema.json) as the stable contract.
 
 ```bash
 projscan plugin list
@@ -230,9 +228,9 @@ PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor --reporter team-radar
 PROJSCAN_PLUGINS_PREVIEW=1 projscan ci --reporter team-radar --min-score 80
 ```
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.7/docs/projscan-reporter-plugin.gif" alt="projscan local reporter plugin rendering a team health report" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.8/docs/projscan-reporter-plugin.gif" alt="projscan local reporter plugin rendering a team health report" width="700">
 
-Reporter plugins are intentionally CLI-only. MCP tools keep returning structured JSON-compatible payloads so agents can reason over stable data, while humans can get a polished local report for their team. Custom presentation, team-branded summaries, and white-label reports belong in reporter plugins rather than new core HTML theming flags. See [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.7/docs/PLUGIN-AUTHORING.md) for manifest shape, `render(context)`, validation, and the trust model.
+Reporter plugins are intentionally CLI-only. MCP tools keep returning structured JSON-compatible payloads so agents can reason over stable data, while humans can get a polished local report for their team. Custom presentation, team-branded summaries, and white-label reports belong in reporter plugins rather than new core HTML theming flags. See [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.8/docs/PLUGIN-AUTHORING.md) for manifest shape, `render(context)`, validation, and the trust model.
 
 ### Options
 
@@ -393,7 +391,7 @@ If you read projscan's [Socket report](https://socket.dev/npm/package/projscan),
 ### Audit it yourself
 
 - **Source is open** at [github.com/abhiyoheswaran1/projscan](https://github.com/abhiyoheswaran1/projscan). The npm tarball matches the `dist/` produced by `npm run build` at the matching tag.
-- **Public API surface is locked** by `scripts/check-stability.mjs`, which runs in CI on every PR and fails on any rename or removal of an MCP tool, CLI command, or exit code. See [`docs/STABILITY.md`](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.7/docs/STABILITY.md).
+- **Public API surface is locked** by `scripts/check-stability.mjs`, which runs in CI on every PR and fails on any rename or removal of an MCP tool, CLI command, or exit code. See [`docs/STABILITY.md`](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.8/docs/STABILITY.md).
 - **Run it offline:** `npm install -g projscan` followed by anything except `audit` and `--mode semantic` works without network.
 - **Drop privilege further:** in CI, run projscan in a sandbox that disallows network egress; everything except `audit` will pass.
 
@@ -423,14 +421,15 @@ For adoption proof, run the product against multiple real repos and capture firs
 ```sh
 projscan evidence-pack --pr-comment
 projscan feedback init --output .projscan-feedback.json
-projscan feedback add --file .projscan-feedback.json --repo api --pr https://github.com/acme/api/pull/42 --reviewer @alice --useful true --minutes-saved 10
+projscan feedback add --file .projscan-feedback.json --repo api --pr https://github.com/acme/api/pull/42 --reviewer @alice --useful true --minutes-saved 10 --owner-routing-clear true --next-command-clear true
+projscan feedback summary --file .projscan-feedback.json --format json
 projscan dogfood --repo ../api --repo ../web --repo ../worker --feedback .projscan-feedback.json --format json
 projscan trial --repo ../api --repo ../web --repo ../worker --feedback .projscan-feedback.json --format json
 ```
 
-The dogfood report checks PR-comment readiness, repeat-use commands, MCP readiness, measured minutes saved, prevented bad edits, false positives, and repeat PR usage before rollout.
+The dogfood and trial reports check PR-comment readiness, repeat-use commands, MCP readiness, measured minutes saved, prevented bad edits, false positives, owner clarity, next-command clarity, and repeat PR usage before rollout.
 
-The hotspots projscan finds in itself are real signals — the reporters in particular have grown organically across releases and are candidates for a 2.0-era refactor (tracked in `docs/ROADMAP.md` "Under consideration"). We choose to ship the signal honestly rather than tune the score to hide it.
+The hotspots projscan finds in itself are real signals — the reporters in particular have grown organically across releases and remain future refactor candidates in the roadmap. We choose to ship the signal honestly rather than tune the score to hide it.
 
 ## CI/CD Integration
 
@@ -443,7 +442,7 @@ projscan ci --changed-only                     # Gate only on this PR's diff
 projscan ci --format sarif > projscan.sarif    # SARIF for Code Scanning
 ```
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.7/docs/npx%20projscan%20ci%20--min-score%2070.gif" alt="npx projscan ci --min-score 70" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.8/docs/npx%20projscan%20ci%20--min-score%2070.gif" alt="npx projscan ci --min-score 70" width="700">
 
 ### GitHub Action (recommended)
 
@@ -512,7 +511,7 @@ Fields:
 - `hotspots.limit` / `hotspots.since` - defaults for the `hotspots` command
 - `monorepo.importPolicy` - cross-package import allow/deny rules in monorepos *(0.14+)*
 
-See [`docs/GUIDE.md` → Configuration](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.7/docs/GUIDE.md#configuration-projscanrc) for the full reference (field types, validation behavior, embedding config in `package.json`, monorepo `importPolicy` semantics).
+See [`docs/GUIDE.md` → Configuration](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.8/docs/GUIDE.md#configuration-projscanrc) for the full reference (field types, validation behavior, embedding config in `package.json`, monorepo `importPolicy` semantics).
 
 ## Tracking Health Over Time
 
@@ -525,7 +524,7 @@ projscan diff                       # Compare against baseline
 projscan diff --format markdown     # Markdown diff for PRs
 ```
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.7/docs/npx%20projscan%20diff%20--save-baseline.gif" alt="npx projscan diff --save-baseline" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.8/docs/npx%20projscan%20diff%20--save-baseline.gif" alt="npx projscan diff --save-baseline" width="700">
 
 ## Hotspots - Where to Fix First
 
@@ -614,7 +613,7 @@ Coverage is also automatically joined into `projscan hotspots` when one of those
 
 **This is the primary way to use projscan.** `projscan mcp` starts an [MCP](https://modelcontextprotocol.io) server over stdio so AI coding agents can query your codebase with real structural accuracy - not regex, not grep.
 
-<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.7/docs/projscan-agent-demo.gif" alt="projscan answering two agent questions: what breaks if I rename buildCodeGraph (impact analysis with definitions, direct callers, transitive reach), and where should I fix first (ranked hotspots with cyclomatic complexity)" width="700">
+<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v3.0.8/docs/projscan-agent-demo.gif" alt="projscan answering two agent questions: what breaks if I rename buildCodeGraph (impact analysis with definitions, direct callers, transitive reach), and where should I fix first (ranked hotspots with cyclomatic complexity)" width="700">
 
 Two questions an agent asks; structural answers in milliseconds. *"What breaks if I rename `buildCodeGraph`?"* → 31 direct callers, 97 files reachable. *"Where should I fix first?"* → ranked hotspots with AST cyclomatic complexity, churn, and ownership signals.
 
@@ -811,7 +810,7 @@ Capability is advertised under `experimental.fileChanged` on `initialize` so cli
 - **`projscan_apply_fix`** *(1.6)* - mechanically execute the safe fix templates. Default is dry-run; pass `confirm: true` to write. Atomic writes, per-apply rollback record at `.projscan-cache/rollbacks/<id>.json`. Reverse with `action: "rollback", rollback_id: ...`. Six templates supported at this release: `unused-dependency-*`, `missing-test-framework`, `missing-eslint`, `missing-prettier`, `missing-editorconfig`, `missing-readme`.
 - **`projscan_taint`** *(1.6)* - source-to-sink reachability over the per-function call graph. Built-in defaults cover common JS / Python sources (`process.env`, `req.body`, etc.) and sinks (`exec`, `eval`, `db.query`, etc.). Project-specific names go in `.projscanrc.json` `taint`. `projscan_review` automatically diffs taint flows between base and head and **blocks any PR that introduces a new flow**. In 3.0.2, review surfaces hardened `newDataflowRisks`, compact `graphEvidence`, and graph-readiness gates for safer handoff.
 
-Analyzer plugins can optionally read graph/dataflow context through `check(rootPath, files, context)` while staying on manifest schema v1. The packaged `graph-context` example shows `context.getSemanticGraph()` and `context.getDataflow()` in a real analyzer. For analyzer and reporter plugin authoring, manifest validation, `--reporter <name>`, and the trust model, see [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.7/docs/PLUGIN-AUTHORING.md).
+Analyzer plugins can optionally read graph/dataflow context through `check(rootPath, files, context)` while staying on manifest schema v1. The packaged `graph-context` example shows `context.getSemanticGraph()` and `context.getDataflow()` in a real analyzer. For analyzer and reporter plugin authoring, manifest validation, `--reporter <name>`, and the trust model, see [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v3.0.8/docs/PLUGIN-AUTHORING.md).
 
 ### Context-window budgeting
 
@@ -880,11 +879,18 @@ projscan caches parsed ASTs at `.projscan-cache/graph.json` (auto-gitignored). F
 
 ## Contributing
 
-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. Contributions are accepted under the MIT License and the DCO 1.1 certification described there.
+
+## Legal and Trust
 
-## License
+- License: [MIT](LICENSE)
+- Disclaimer: [DISCLAIMER.md](DISCLAIMER.md)
+- Security policy: [SECURITY.md](SECURITY.md)
+- Privacy notice: [PRIVACY.md](PRIVACY.md)
+- Trademark and brand policy: [TRADEMARKS.md](TRADEMARKS.md)
+- Third-party notices: [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)
 
-MIT
+projscan is free and open source. The CLI and MCP server are local-first and do not upload source code, scan results, telemetry, or usage analytics to a projscan service.
 
 <p align="center">
   <a href="https://www.baseframelabs.com" target="_blank" rel="noopener" title="Part of Baseframe Labs">

package/SECURITY.md

@@ -0,0 +1,42 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please do not report security vulnerabilities in public GitHub issues.
+
+Email vulnerability reports to support@baseframelabs.com with:
+
+- affected projscan version
+- operating system and Node.js version
+- steps to reproduce
+- impact you believe the issue has
+- whether the report includes secret material or private repository data
+
+We will acknowledge reports as soon as practical and will coordinate a fix, disclosure notes, and release timing based on severity.
+
+## Supported versions
+
+Security fixes target the latest published npm version of `projscan`. Older versions may receive guidance, but we do not promise backports unless a maintainer explicitly says so in the advisory.
+
+## Scope
+
+In scope:
+
+- vulnerabilities in the `projscan` CLI, MCP server, local plugin loader, generated GitHub Action templates, and packaged runtime artifacts
+- cases where projscan unintentionally reads, exposes, uploads, or persists sensitive local data
+- supply-chain or package-integrity issues in the published npm package
+
+Out of scope:
+
+- vulnerabilities in a user's repository that projscan reports
+- issues caused only by untrusted local plugins enabled through `PROJSCAN_PLUGINS_PREVIEW=1`
+- npm, Git, or operating-system behavior outside projscan's control
+- social engineering, spam, or denial-of-service reports without a concrete projscan defect
+
+## Safe harbor
+
+Good-faith testing is welcome when it avoids harm, privacy violations, data destruction, service disruption, and access to systems or data you do not own. Stop testing and contact us if you reach sensitive data.
+
+## Security contact and brand note
+
+Baseframe Labs is the umbrella brand for this product family. It is not currently a formed legal entity. Please do not address legal notices to Baseframe Labs with any corporate designator.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,52 @@
+# Third-Party Notices
+
+projscan is licensed under MIT. It also depends on third-party open-source packages that keep their own licenses.
+
+This notice summarizes direct runtime dependencies, optional peer dependencies, and bundled grammar artifacts used by the published package. Transitive dependencies keep their package metadata and license files through npm.
+
+## Direct runtime dependencies
+
+| Package | License |
+|---|---|
+| `@babel/parser` | MIT |
+| `@babel/types` | MIT |
+| `chalk` | MIT |
+| `commander` | MIT |
+| `fast-glob` | MIT |
+| `ora` | MIT |
+| `tree-sitter-c-sharp` | MIT |
+| `tree-sitter-go` | MIT |
+| `tree-sitter-java` | MIT |
+| `tree-sitter-php` | MIT |
+| `tree-sitter-python` | MIT |
+| `tree-sitter-ruby` | MIT |
+| `tree-sitter-rust` | MIT |
+| `web-tree-sitter` | MIT |
+
+## Optional peer dependency
+
+| Package | License | Notes |
+|---|---|---|
+| `@xenova/transformers` | Apache-2.0 | Optional semantic-search peer. Not required for default BM25 search. |
+
+## Bundled grammar artifacts
+
+projscan packages Tree-sitter wasm grammars under `dist/grammars/` so scans work offline after install.
+
+| Artifact | Source package | License |
+|---|---|---|
+| `web-tree-sitter.wasm` | `web-tree-sitter` | MIT |
+| `tree-sitter-python.wasm` | `tree-sitter-python` | MIT |
+| `tree-sitter-go.wasm` | `tree-sitter-go` | MIT |
+| `tree-sitter-java.wasm` | `tree-sitter-java` | MIT |
+| `tree-sitter-ruby.wasm` | `tree-sitter-ruby` | MIT |
+| `tree-sitter-rust.wasm` | `tree-sitter-rust` | MIT |
+| `tree-sitter-php.wasm` | `tree-sitter-php` | MIT |
+| `tree-sitter-c_sharp.wasm` | `tree-sitter-c-sharp` | MIT |
+| `tree-sitter-kotlin.wasm` | `tree-sitter-kotlin` | MIT |
+| `tree-sitter-swift.wasm` | `tree-sitter-swift` | MIT |
+| `tree-sitter-cpp.wasm` | `tree-sitter-cpp` | MIT |
+
+## Notes for redistributors
+
+If you redistribute projscan, keep the projscan MIT license and preserve required third-party license notices for the packages you redistribute.

package/TRADEMARKS.md

@@ -0,0 +1,29 @@
+# Trademark and Brand Policy
+
+The MIT License covers the projscan source code and documentation. It does not grant trademark rights in the projscan name, projscan icon, Baseframe Labs name, Baseframe Labs wordmarks, or related branding.
+
+## Allowed uses
+
+You may use the projscan name to:
+
+- describe the unmodified projscan project or package
+- link to the official repository or npm package
+- state that your project works with projscan
+- include the unmodified projscan icon in documentation that clearly refers to projscan
+
+## Uses that need permission
+
+Please ask before you:
+
+- use projscan or Baseframe Labs branding in a product, company, domain, social handle, conference booth, paid course, or merchandise
+- imply endorsement, certification, partnership, or official status
+- use a confusingly similar name or logo for a fork, plugin marketplace, hosted service, or commercial wrapper
+- modify the official icon or wordmarks in a way that makes the source or endorsement unclear
+
+## Forks and plugins
+
+Forks and plugins should make their status clear. Use names like "plugin for projscan" or "fork of projscan" instead of names that suggest official ownership.
+
+## Baseframe Labs note
+
+Baseframe Labs is an umbrella brand for related products. It is not currently a formed legal entity. Do not use Baseframe Labs with any corporate designator.

package/dist/projscan-sbom.cdx.json

@@ -1,23 +1,23 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:1ffa9356-04fc-4a36-8369-3e7918f6ffb6",
+  "serialNumber": "urn:uuid:47448f57-6e78-4632-8ae7-fb9a97d0daaa",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-31T21:39:35.637Z",
+    "timestamp": "2026-06-01T06:27:58.024Z",
     "tools": [
       {
         "vendor": "projscan",
         "name": "projscan-sbom-generator",
-        "version": "3.0.7"
+        "version": "3.0.8"
       }
     ],
     "component": {
       "type": "application",
-      "bom-ref": "pkg:npm/projscan@3.0.7",
+      "bom-ref": "pkg:npm/projscan@3.0.8",
       "name": "projscan",
-      "version": "3.0.7",
-      "purl": "pkg:npm/projscan@3.0.7"
+      "version": "3.0.8",
+      "purl": "pkg:npm/projscan@3.0.8"
     }
   },
   "components": [

package/dist/tool-manifest.json

@@ -1,8 +1,8 @@
 {
   "name": "projscan",
-  "version": "3.0.7",
+  "version": "3.0.8",
   "mcpProtocolVersion": "2025-03-26",
-  "generatedAt": "2026-06-01T04:01:07.722Z",
+  "generatedAt": "2026-06-01T06:28:03.236Z",
   "toolCount": 40,
   "tools": [
     {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "projscan",
   "mcpName": "io.github.abhiyoheswaran1/projscan",
-  "version": "3.0.7",
+  "version": "3.0.8",
   "description": "Agent-first code intelligence. MCP server (2025-03-26) with AST parsing for JavaScript, TypeScript, Python, Go, Java, Ruby, Rust, PHP, C#, Kotlin, Swift, and C++; stable v3 semantic graph (projscan_semantic_graph), dataflow risk engine with bridge-helper detection (projscan_dataflow), code graph, file + per-function AST cyclomatic complexity, per-function fan-in + fan-out, coupling + cycle detection, structural PR diff with HTML reporter, coverage report with HTML reporter, intent-grounded one-call PR review (projscan_review with optional `intent` arg, new taint flows, contract changes, and newDataflowRisks) and long-running PR-watch mode with structured per-bucket deltas (projscan_review_watch), first-60-seconds workflow orientation (projscan_start), agent workplans (projscan_workplan), bug-hunt queues (projscan_bug_hunt), product-line planning (projscan_release_train), evidence packs (projscan_evidence_pack), regression planning (projscan_regression_plan), agent briefs (projscan_agent_brief), quality scorecards (projscan_quality_scorecard), and preflight with supply-chain IOC evidence, rule-driven fix suggestions + mechanical apply layer with rollback (projscan_apply_fix, projscan_fix_suggest, projscan_explain_issue), source-to-sink taint analysis (projscan_taint) with truncation reporting, transitive blast-radius analysis with cross-repo mode (projscan_impact for files and symbols), cross-repo workspace registration + intelligence (projscan_workspace_graph), per-function semantic search chunks (sub-file embeddings), per-rule confidence + severity drift + cost-summary analytics with live streaming (projscan_cost_summary), stable local analyzer + reporter plugin API (projscan_plugin, CLI --reporter, opt-in via PROJSCAN_PLUGINS_PREVIEW=1), monorepo workspace awareness with cross-package import policy + per-package dependencies / outdated / audit, BM25 + optional semantic search, cursor pagination, progress notifications, context-budgeted output, and a stable-surface CI guard. CLI on the side.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,14 @@
     "docs/plugin.schema.json",
     "docs/examples/plugins",
     "public/brand/baseframe-labs",
-    "public/.well-known/security.txt"
+    "public/.well-known/security.txt",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "PRIVACY.md",
+    "DISCLAIMER.md",
+    "TRADEMARKS.md",
+    "THIRD-PARTY-NOTICES.md",
+    "public/projscan-icon.svg"
   ],
   "scripts": {
     "build": "tsc && node scripts/copy-wasm.mjs && node scripts/generate-tool-manifest.mjs",

package/public/projscan-icon.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <defs>
+    <clipPath id="projscan-icon-mask">
+      <rect x="0" y="0" width="512" height="512" rx="114" ry="114" />
+    </clipPath>
+  </defs>
+  <g clip-path="url(#projscan-icon-mask)">
+    <!-- App icon background: dark rounded square, matching the site's gray-900 -->
+    <rect x="0" y="0" width="512" height="512" fill="#111827" />
+    <!-- Terminal / code icon (Heroicons command-line, scaled to fill ~62% of the tile) -->
+    <!-- Original viewBox 0 0 24 24, scaled to 320x320, centered at (256,256) = offset 96,96 -->
+    <g transform="translate(96,96) scale(13.333)">
+      <path
+        fill="none"
+        stroke="#4ade80"
+        stroke-width="1.5"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        d="M6.75 7.5l3 2.25-3 2.25m4.5 0h3M5.25 20.25h13.5A2.25 2.25 0 0021 18V6a2.25 2.25 0 00-2.25-2.25H5.25A2.25 2.25 0 003 6v12a2.25 2.25 0 002.25 2.25z"
+      />
+    </g>
+  </g>
+</svg>