diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..878a5d1 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,25 @@ +# Review is requested automatically from the owners of the paths a pull request touches. +# +# A CODEOWNERS entry only requests a review by default. To make it a hard requirement, +# turn on "require review from Code Owners" in the main branch ruleset. + +# Everything, unless something below is more specific. +* @ewraj + +# The two documents that define what this product is and what it refuses to be. A change +# here is a change of direction, not an implementation detail. +/ANNOTATECODE_PRODUCT_GIST.md @ewraj +/IMPLEMENTATION_PLAN.md @ewraj + +# Anchoring decides where somebody's handwriting ends up. Getting it wrong moves a note onto +# code it was never about, which the product promises never to do silently. +/src/model/ @ewraj + +# The ink engine, and the coordinate space that keeps strokes welded to the text. +/src/ink/ @ewraj + +# Supply chain, permissions, and anything that can publish to the live site. +/.github/ @ewraj +/package.json @ewraj +/package-lock.json @ewraj +/vite.config.ts @ewraj diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..8e60e3f --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,26 @@ +## What this changes + + + +## Does it make reading and understanding code better? + + + +## How it was tested + +- [ ] `npm run typecheck` +- [ ] `npm test` +- [ ] `npm run build` + + + +## Anything reviewers should look at closely + + + +--- + +- [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md) +- [ ] This is one concern, not several diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3da3adf --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,108 @@ +# Contributing to AnnotateCode + +Thanks for being here. This is a small, deliberately narrow project, and the most useful +thing you can read before opening a pull request is what it refuses to become. + +## The one test + +Every change is measured against a single question, taken from the product gist: + +> Does this make reading and understanding code better? + +If the answer is no, the change does not belong here — however well written it is. + +## Read these first + +- [`ANNOTATECODE_PRODUCT_GIST.md`](ANNOTATECODE_PRODUCT_GIST.md) — what the product is and + what it refuses to be. +- [`IMPLEMENTATION_PLAN.md`](IMPLEMENTATION_PLAN.md) — how it gets built, in what order, and + which decisions are expensive to reverse. §13 is a list of things deliberately deferred, + each with a reason. + +## Things that will be declined + +Not because they are bad ideas, but because they are not this product: + +- Anything that moves it toward being an IDE — IntelliSense, a debugger, a "Run" button, + language servers, refactoring tools. +- Git features. Commits, branches, diffs, blame. The product reads code; it does not manage + it. +- Features added because other developer tools have them. +- Anything that surrounds the code with more UI. The code is the centrepiece. + +If you are unsure whether an idea fits, open an issue before writing the code. It is a much +cheaper conversation than a closed pull request. + +## Ground rules that are not negotiable + +These come from the gist and drive most of the architecture: + +1. **Code and ink behave as one document.** There is exactly one scrolling element. Nothing + in the annotation layer may depend on viewport pixels, window size, or scroll offset. +2. **Tablet and stylus are first-class.** Not an afterthought, and not desktop-only. +3. **Annotations anchor to code, not to pixels or bare line numbers.** +4. **A handwritten note is never silently moved to the wrong code.** `unresolved` is a real, + expected outcome, not a failure to paper over. +5. **Performance over feature count.** + +## Getting set up + +```bash +npm ci +npm run dev # http://localhost:5173 +``` + +Other scripts: + +```bash +npm run typecheck # tsc --noEmit +npm test # vitest +npm run build # typecheck + production build +``` + +## Before you open a pull request + +```bash +npm run typecheck && npm test && npm run build +``` + +CI runs exactly these, so running them locally is the fastest way to find out. + +### Tests + +New behaviour needs a test where the behaviour is testable without a browser. The dense +suites live in `src/model/anchor.test.ts` (anchor resolution) and `src/ink/` (stroke +geometry, undo history, reflow across edits) — match the style there: table-driven, one +assertion per claim, and a name that states the claim rather than the mechanism. + +Anything touching anchoring deserves more tests than you think. Getting it wrong misplaces +somebody's handwriting. + +### Things CI cannot check + +Stylus feel and ink/scroll behaviour have no substitute for a real device. If your change +touches the ink engine, say in the pull request what you tested it on. + +## Commits and pull requests + +- Write commit messages that explain **why**, not what — the diff already says what. Look at + the existing history for the register. +- Keep one concern per pull request. Two unrelated fixes are two pull requests. +- `main` requires a pull request, a passing `verify` check, and a review. Merges are squash + or rebase; the history stays linear. +- Mark it as a draft while it is still moving. + +## Reporting bugs + +Include the browser and OS, whether you were using a mouse, a finger, or a stylus, and what +you expected instead. For anything involving ink or anchoring, the file and roughly where on +it you were drawing helps a great deal. + +## Security + +Please do not open a public issue for a security problem. See [`SECURITY.md`](SECURITY.md). + +## Licence + +By contributing, you agree that your contributions are licensed under the +[MIT Licence](LICENSE) that covers this project. diff --git a/README.md b/README.md index 46709a4..f3e9ade 100644 --- a/README.md +++ b/README.md @@ -67,11 +67,24 @@ The goal isn't to build another giant developer platform. The goal is to build one small tool that does one thing really well. +## Running it locally + +```bash +npm ci +npm run dev # http://localhost:5173 +``` + +```bash +npm run typecheck # tsc --noEmit +npm test # vitest +npm run build # typecheck + production build +``` + ## Contributing Found a bug? Have an idea? Want to improve the annotation experience? -Issues and pull requests are welcome. +Issues and pull requests are welcome. Start with **[CONTRIBUTING.md](CONTRIBUTING.md)** — it covers the setup, what the tests expect, and which ideas get declined and why. If you're contributing, keep the core idea in mind: @@ -79,6 +92,8 @@ If you're contributing, keep the core idea in mind: If a feature makes it feel more like an IDE and less like a document you can write on, it's probably worth questioning. +Found a security problem? Please don't open a public issue — see **[SECURITY.md](SECURITY.md)**. + ## Philosophy Code is usually treated as something you **execute**. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b649953 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,47 @@ +# Security + +## Reporting a vulnerability + +**Please do not open a public issue.** A public report tells everyone about the problem at +the same moment it tells me, including the people who would misuse it. + +Report it privately through GitHub: + +1. Go to the [Security Advisories page](https://github.com/ewraj/Annotate-Code/security/advisories/new). +2. Click **Report a vulnerability**. + +That is a private channel between you and the maintainer. + +Useful things to include: what an attacker can do, the steps to reproduce it, and the +browser and version you saw it on. A proof of concept helps, but a clear description of the +weakness is worth more than a working exploit. + +You can expect an acknowledgement within a few days. This is a small project maintained by +one person, so please be patient — and please give me a chance to ship a fix before +disclosing publicly. + +## Where the risk actually is + +AnnotateCode has no backend and no accounts today. Everything lives in the browser. So the +interesting surface is smaller than it looks, and mostly this: + +- **Your data never leaves your machine.** Files and annotations are held in IndexedDB in + your own browser. There is no server to send them to. +- **Code is rendered, never executed.** Source is syntax-highlighted as text. There is no + "Run" button and nothing evaluates what you open — that is a product decision, and also a + security one. +- **The GitHub integration is unauthenticated and read-only.** Public repository metadata + comes from the GitHub API and file contents from `raw.githubusercontent.com`. The + application never asks for a token, so there is no token to leak. +- **Untrusted input worth thinking about:** the contents of any repository someone opens, + file paths in a tree, and repository URLs. Anything that could turn one of those into + script execution, or reach outside the intended origin, is a real vulnerability — please + report it. + +## Scope + +In scope: this repository, and the site at . + +Out of scope: findings against GitHub, GitHub Pages, or `raw.githubusercontent.com` +themselves — report those to GitHub. Also out of scope: reports with no demonstrated +impact, such as missing headers on a static page with nothing to protect.