From 29b8a335b422e956f9dcebdbf5c2de33af84410a Mon Sep 17 00:00:00 2001 From: Raj Date: Thu, 17 Sep 2026 21:44:56 +0530 Subject: [PATCH] Add the documents an outside contributor needs The repository asks for contributions but never said what it wants from them, which for a project this opinionated is the expensive gap: the gist refuses a long list of features, and someone can only find that out by having a pull request declined. CONTRIBUTING.md leads with the governing test - does this make reading and understanding code better - and then states plainly what will be declined and why, so that conversation happens before the code is written rather than after. It also records the two things CI cannot check: stylus feel, and whether ink stays welded to the text while scrolling. CODEOWNERS routes review by blast radius rather than by file count. The gist and the plan are direction, not implementation. Anchoring decides where somebody's handwriting ends up. Workflows and lockfiles can publish to the live site. SECURITY.md sends reports to a private advisory instead of a public issue, and describes where the risk actually is: no backend, no accounts, no token, and code that is rendered but never executed. The surface worth probing is the untrusted repository content the app renders. --- .github/CODEOWNERS | 25 +++++++ .github/pull_request_template.md | 26 ++++++++ CONTRIBUTING.md | 108 +++++++++++++++++++++++++++++++ README.md | 17 ++++- SECURITY.md | 47 ++++++++++++++ 5 files changed, 222 insertions(+), 1 deletion(-) create mode 100644 .github/CODEOWNERS create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md 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.