diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..0a53fd4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,85 @@ +name: Bug report +description: Report something that isn't working +title: "bug: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to file a bug. The more concrete you can be, + the faster it gets fixed. If you can include the analyzed project's + primary language and an approximate file count, that's gold. + + - type: textarea + id: what-happened + attributes: + label: What happened? + description: What did you do, what did you expect to happen, and what actually happened? + placeholder: | + 1. Ran `/understand --full` on a ~3,000 file Rust project + 2. Expected: dashboard opens with the graph + 3. Got: dashboard shows "Failed to load graph: schema validation error" + validations: + required: true + + - type: textarea + id: reproduce + attributes: + label: Minimal reproduction + description: Smallest set of steps (or a link to a public repo) that reproduces the issue. + validations: + required: false + + - type: input + id: version + attributes: + label: Plugin version + description: Run `/understand --version` or check `~/.claude/plugins/cache/understand-anything/understand-anything/`. + placeholder: "e.g. 2.7.4" + validations: + required: true + + - type: dropdown + id: platform + attributes: + label: Platform / client + multiple: true + options: + - Claude Code (CLI) + - Claude Code (VS Code extension) + - Claude Code (JetBrains) + - Cursor + - GitHub Copilot CLI + - opencode + - Other (please describe in "What happened?") + validations: + required: true + + - type: input + id: os + attributes: + label: OS + Node version + placeholder: "e.g. macOS 14.5 (arm64), Node v22.6.0" + validations: + required: true + + - type: input + id: project-language + attributes: + label: Primary language of the analyzed project + placeholder: "e.g. TypeScript, Python, Swift…" + + - type: input + id: file-count + attributes: + label: Approximate file count of the analyzed project + placeholder: "e.g. ~3,000" + + - type: textarea + id: logs + attributes: + label: Relevant logs + description: | + Any console output, the contents of `.understand-anything/intermediate/` + if it still exists, or screenshots of the dashboard error. + render: shell diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..3da6fc9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: README & docs + url: https://github.com/Lum1104/Understand-Anything#readme + about: Most usage questions are answered in the project README. + - name: Discussions + url: https://github.com/Lum1104/Understand-Anything/discussions + about: For open-ended discussion, design proposals, or sharing how you use the tool. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..bbffd7d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,34 @@ +name: Feature request +description: Suggest an idea or improvement +title: "feat: " +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: What problem are you trying to solve? + description: Describe the user pain or workflow gap. Concrete examples help more than abstract framing. + placeholder: | + When onboarding new engineers to our 8k-file Go monorepo, they spend + days finding the auth boundary. /understand finds the files but the + dashboard doesn't visually separate "trusted" from "untrusted" zones. + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed solution (optional) + description: If you have an idea for what the feature should look like, share it. Skip if you'd rather just describe the problem. + + - type: textarea + id: alternatives + attributes: + label: Alternatives you've considered + description: Other tools, workarounds, or approaches you've tried. + + - type: input + id: scope + attributes: + label: Which part of the project? + placeholder: "skill / dashboard / core / agents / all" diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000..2c0962b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,24 @@ +name: Question / usage help +description: Ask a question about how to use the project +title: "question: " +labels: ["question"] +body: + - type: markdown + attributes: + value: | + For general usage questions. If you found a bug, please use the bug + report template instead — it asks for the information needed to + reproduce. + + - type: textarea + id: question + attributes: + label: Your question + validations: + required: true + + - type: textarea + id: tried + attributes: + label: What have you already tried? + description: Helps avoid suggesting things you've already ruled out. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..fc16fb8 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,26 @@ +## Summary + + + +## Linked issue(s) + + + +## How I tested this + + + +- [ ] `pnpm lint` +- [ ] `pnpm --filter @understand-anything/core test` +- [ ] `pnpm test` +- [ ] Manual smoke test (describe above) + +## Versioning + + + +- [ ] Version bumped in all five manifests, OR +- [ ] N/A — internal/docs-only change diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 69771eb..9825406 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,7 +1,21 @@ name: CI on: + # Run on every PR so a contributor's first push gets feedback. pull_request: + # Also run on direct pushes to main so the "main is green" signal is real. + # Without this, main can silently break for days when someone bypasses + # review. (#249) + push: + branches: [main] + +# Cancel any in-flight CI for the same ref when a new commit is pushed — +# saves runner minutes and keeps the latest commit's status the only one +# anyone reads. `github.ref` is a controlled value (refs/heads/* or +# refs/pull/*/merge), not user-controlled input, so it's safe to interpolate. +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true jobs: ci: diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..d05f492 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,39 @@ +# Code of Conduct + +We want this project to be a welcoming place for everyone who wants to +contribute, learn, or use it — regardless of experience level, background, or +identity. + +## In short + +- **Be respectful.** Treat others the way you'd want to be treated. +- **Assume good intent.** Most disagreements are misunderstandings. +- **Be constructive.** Critique ideas, not people. Suggest improvements. +- **Keep it on-topic.** This project is about understanding codebases. + +## What's not OK + +- Personal attacks, insults, or sustained disruption of discussions. +- Posting someone's private information without their explicit permission. +- Repeatedly ignoring requests from maintainers to change behavior. + +## Reporting + +If you see behavior that violates this code, please open a private email to +the maintainer listed in the repository profile, or use GitHub's +[private vulnerability / abuse reporting](https://docs.github.com/en/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam). + +Maintainers will review reports and take whatever action they think is +appropriate — typically a private warning, sometimes a temporary or permanent +ban from the project. Reports will be kept confidential. + +## Scope + +This code applies in all project spaces: issues, pull requests, discussions, +commits, and any other project-affiliated channel. + +--- + +This document is intentionally short. It's based on the spirit of the +[Contributor Covenant](https://www.contributor-covenant.org/) without +reproducing it verbatim. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..a9fe378 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,51 @@ +# Reporting security issues + +Thanks for taking the time to disclose responsibly. + +## How to report + +Please use GitHub's [private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability) +on this repository. That keeps the report visible to the maintainer without +exposing the details publicly. + +If private reporting is unavailable for any reason, open a regular issue +titled `security: brief description` **without** any exploit details, and +the maintainer will reply with a private channel. + +## What to include + +- A description of the issue and its potential impact. +- Steps to reproduce — minimal is fine, a full PoC is not required. +- Affected versions if you've narrowed them down. +- Whether you'd like to be credited in the eventual fix. + +## What to expect + +- Initial acknowledgement within a few days. +- A fix or mitigation plan within ~30 days for confirmed issues; longer for + cases that require coordinated disclosure with upstream dependencies. +- Public credit once a fix has shipped, if you'd like. + +## Scope + +This project is a **local-only** static-analysis tool. It runs on a +developer's machine, reads the analyzed project, and writes the resulting +graph to `.understand-anything/`. It does not phone home and the dashboard's +file-content endpoint is gated behind an access token and a graph-derived +path allowlist. + +Issues we care about: + +- Code execution triggered by analyzing a hostile project (e.g. a path in a + hostile file leaking outside the analyzed directory, or untrusted JSON in + the graph being executed by the dashboard). +- The dashboard's file-content endpoint serving files outside the allowlist. +- The `/understand` skill running shell commands derived from untrusted + paths or contents. + +Issues that are **out of scope**: + +- Bugs that require a malicious local user with write access to the + analyzed project (they could just edit the source directly). +- Anything that requires the user to copy a malicious URL and paste it back + into the dashboard. diff --git a/package.json b/package.json index efae49a..20b19b4 100644 --- a/package.json +++ b/package.json @@ -2,6 +2,28 @@ "name": "understand-anything", "private": true, "type": "module", + "description": "An open-source tool combining LLM intelligence + static analysis to produce interactive dashboards for understanding codebases.", + "license": "MIT", + "homepage": "https://github.com/Lum1104/Understand-Anything#readme", + "repository": { + "type": "git", + "url": "git+https://github.com/Lum1104/Understand-Anything.git" + }, + "bugs": { + "url": "https://github.com/Lum1104/Understand-Anything/issues" + }, + "keywords": [ + "claude-code", + "codebase-analysis", + "knowledge-graph", + "tree-sitter", + "llm", + "static-analysis", + "developer-tools", + "code-understanding", + "code-onboarding", + "claude-plugin" + ], "main": ".opencode/plugins/understand-anything.js", "packageManager": "pnpm@10.6.2+sha512.47870716bea1572b53df34ad8647b42962bc790ce2bf4562ba0f643237d7302a3d6a8ecef9e4bdfc01d23af1969aa90485d4cebb0b9638fa5ef1daef656f6c1b", "scripts": {