From 14a3551d2fc640664c25e403036bc8aa627c0c12 Mon Sep 17 00:00:00 2001 From: Mistium <92952823+Mistium@users.noreply.github.com> Date: Sun, 1 Nov 2026 01:59:28 +0000 Subject: [PATCH 1/2] Add AGENTS.md and a conventions check AGENTS.md tells coding agents where code goes, what consumers rely on, and which checks to run. scripts/check-conventions.mjs rejects code comments and em dashes in added lines, and runs on pull requests. eslint-config-scratch's require-jsdoc rule contradicted the no-comments rule, so it is off. --- .eslintrc.js | 5 +- .github/workflows/node.js.yml | 3 + AGENTS.md | 26 ++++++++ package-lock.json | 21 ++++++ package.json | 4 +- scripts/check-conventions.mjs | 122 ++++++++++++++++++++++++++++++++++ 6 files changed, 179 insertions(+), 2 deletions(-) create mode 100644 AGENTS.md create mode 100644 scripts/check-conventions.mjs diff --git a/.eslintrc.js b/.eslintrc.js index ad845bc68..46e5b2acc 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -1,4 +1,7 @@ module.exports = { root: true, - extends: ['scratch', 'scratch/node', 'scratch/es6'] + extends: ['scratch', 'scratch/node', 'scratch/es6'], + rules: { + 'require-jsdoc': 'off' + } }; diff --git a/.github/workflows/node.js.yml b/.github/workflows/node.js.yml index 1eaba494d..622cefc5d 100644 --- a/.github/workflows/node.js.yml +++ b/.github/workflows/node.js.yml @@ -11,6 +11,7 @@ jobs: - uses: actions/checkout@v4 with: persist-credentials: false + fetch-depth: 0 - name: Install Node.js uses: actions/setup-node@v4 with: @@ -18,5 +19,7 @@ jobs: cache: npm - run: npm ci - run: npm run lint + - run: node scripts/check-conventions.mjs --base=origin/${{ github.base_ref }} + if: github.event_name == 'pull_request' - run: npm run build - run: npm run test diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..8dd51aea7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,26 @@ +# AGENTS.md + +scratch-render draws the MistWarp stage with WebGL: sprites, pen, text bubbles, collision and touching queries. It is a fork of TurboWarp's renderer, written in CommonJS JavaScript, and scratch-gui pins it to a commit. + +## Where code goes + +- `src/RenderWebGL.js` is the public renderer the VM and GUI call. `Drawable.js` is one drawn item, the `*Skin.js` files are its pixels (bitmap, SVG, pen, text bubble), and `Silhouette.js` is the CPU copy used for collision. +- `src/shaders/` holds the GLSL, and `ShaderManager.js` builds it. + +## Things that look safe to change but are not + +- **Shader source text is public API.** Unsandboxed extensions patch `sprite.vert` and `sprite.frag` by exact string replacement inside `ShaderManager._buildShader`. Never edit those two files for a MistWarp feature. Add a separate shader built outside `_buildShader` and `_shaderCache`, as `triangle.vert` and `triangle.frag` do. `test/unit/ShaderSourceTests.js` guards this. +- **Collision and color sensing must match Scratch.** Changes to `Silhouette`, `Drawable` bounds or pen are measured with the scratch-parity project (git.rotur.dev/Mist/scratch-parity), and its results must not change. +- Keep `RenderWebGL` method names and signatures stable. scratch-vm, scratch-gui and extensions call them directly. + +## Checks + +`npm run lint`, `npm run tap`, `npm run build`, and `npm run check:conventions`, which rejects code comments and em dashes in the lines you add. + +## Working here + +- The default branch is `develop`. This repo is a fork, so open PRs with `gh pr create -R MistWarp/scratch-render --base develop`. +- To try a change in the editor, check this repo out next to scratch-gui and run `pnpm run link` there. +- No code comments: name things so the code explains itself. No em dashes anywhere. +- Never add `Co-Authored-By` or any AI or tool attribution to commits or PRs. +- READMEs are overviews. Documentation goes in MistWarp/docs (https://mistwarp.org/docs/). diff --git a/package-lock.json b/package-lock.json index a08022407..b87683d29 100644 --- a/package-lock.json +++ b/package-lock.json @@ -35,6 +35,7 @@ "scratch-vm": "0.2.0-prerelease.20201125065300", "tap": "11.1.5", "travis-after-all": "1.4.5", + "typescript": "~6.0.3", "uglifyjs-webpack-plugin": "1.3.0", "webpack": "4.47.0", "webpack-cli": "3.3.12", @@ -14848,6 +14849,20 @@ "version": "0.0.6", "license": "MIT" }, + "node_modules/typescript": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz", + "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, "node_modules/uc.micro": { "version": "1.0.6", "dev": true, @@ -26824,6 +26839,12 @@ "typedarray": { "version": "0.0.6" }, + "typescript": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz", + "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==", + "dev": true + }, "uc.micro": { "version": "1.0.6", "dev": true diff --git a/package.json b/package.json index 6d82b768d..4e63caf68 100644 --- a/package.json +++ b/package.json @@ -21,7 +21,8 @@ "tap": "tap test/unit test/integration", "test": "npm run lint && npm run build && npm run tap", "version": "json -f package.json -I -e \"this.repository.sha = '$(git log -n1 --pretty=format:%H)'\"", - "watch": "webpack --progress --colors --watch --watch-poll" + "watch": "webpack --progress --colors --watch --watch-poll", + "check:conventions": "node scripts/check-conventions.mjs" }, "devDependencies": { "babel-core": "6.26.3", @@ -39,6 +40,7 @@ "scratch-vm": "0.2.0-prerelease.20201125065300", "tap": "11.1.5", "travis-after-all": "1.4.5", + "typescript": "~6.0.3", "uglifyjs-webpack-plugin": "1.3.0", "webpack": "4.47.0", "webpack-cli": "3.3.12", diff --git a/scripts/check-conventions.mjs b/scripts/check-conventions.mjs new file mode 100644 index 000000000..04d4a6bc8 --- /dev/null +++ b/scripts/check-conventions.mjs @@ -0,0 +1,122 @@ +import {execFileSync} from 'node:child_process'; +import fs from 'node:fs'; +import ts from 'typescript'; + +const EM_DASH = '\u2014'; +const SOURCE_FILE = /\.(js|jsx|mjs|cjs|ts|tsx)$/; +const TEXT_FILE = /\.(js|jsx|mjs|cjs|ts|tsx|json|md|css|html|yml|yaml|txt)$/; +const SKIPPED_PATHS = [ + /^dist\//, + /^playground\//, + /(^|\/)package-lock\.json$/ +]; +const DIRECTIVE = /^(\/\/|\/\*)\s*(eslint[\s-]|global\s|@ts-|istanbul\s|prettier-ignore|\/\s* option.startsWith('--base=')) || '--base=origin/develop').slice('--base='.length); + +const git = (...args) => execFileSync('git', args, {encoding: 'utf8', maxBuffer: 1 << 30}); + +const diffArgs = staged ? + ['diff', '--cached'] : + ['diff', git('merge-base', base, 'HEAD').trim()]; + +const parseDiff = text => { + const files = new Map(); + const removed = new Set(); + let current = null; + let line = 0; + for (const row of text.split('\n')) { + if (row.startsWith('+++ ')) { + const path = row.slice(4).replace(/^b\//, ''); + current = path === '/dev/null' ? null : path; + if (current && !files.has(current)) files.set(current, new Map()); + } else if (row.startsWith('@@')) { + const match = /\+(\d+)/.exec(row); + line = match ? Number(match[1]) : 0; + } else if (row.startsWith('+') && current) { + files.get(current).set(line, row.slice(1)); + line += 1; + } else if (row.startsWith('-') && !row.startsWith('---')) { + removed.add(row.slice(1).trim()); + } + } + return {files, removed}; +}; + +const lineStarts = text => { + const starts = [0]; + for (let index = 0; index < text.length; index++) { + if (text[index] === '\n') starts.push(index + 1); + } + return starts; +}; + +const lineOf = (starts, position) => { + let low = 0; + let high = starts.length - 1; + while (low < high) { + const middle = Math.ceil((low + high) / 2); + if (starts[middle] <= position) low = middle; + else high = middle - 1; + } + return low + 1; +}; + +const commentRanges = (path, text) => { + const kind = /\.tsx$/.test(path) ? ts.ScriptKind.TSX : + /\.ts$/.test(path) ? ts.ScriptKind.TS : + /\.jsx$/.test(path) ? ts.ScriptKind.JSX : ts.ScriptKind.JS; + const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, kind); + const seen = new Map(); + const collect = ranges => { + for (const range of ranges || []) seen.set(range.pos, range); + }; + const visit = node => { + if (node.kind >= ts.SyntaxKind.FirstToken && node.kind <= ts.SyntaxKind.LastToken) { + collect(ts.getLeadingCommentRanges(text, node.pos)); + collect(ts.getTrailingCommentRanges(text, node.end)); + return; + } + if (node.kind === ts.SyntaxKind.JsxText) return; + collect(ts.getLeadingCommentRanges(text, node.pos)); + node.getChildren(source).forEach(visit); + }; + visit(source); + collect(ts.getLeadingCommentRanges(text, source.endOfFileToken.pos)); + return [...seen.values()]; +}; + +const problems = []; +const {files, removed} = parseDiff(git(...diffArgs, '--unified=0', '--no-color', '--diff-filter=ACMR')); + +for (const [path, added] of files) { + if (SKIPPED_PATHS.some(pattern => pattern.test(path)) || !TEXT_FILE.test(path)) continue; + for (const [line, content] of added) { + if (content.includes(EM_DASH)) problems.push(`${path}:${line} em dash: use a comma, parentheses or "to"`); + } + if (!SOURCE_FILE.test(path)) continue; + const text = staged ? git('show', `:${path}`) : fs.readFileSync(path, 'utf8'); + const starts = lineStarts(text); + for (const range of commentRanges(path, text)) { + const comment = text.slice(range.pos, range.end); + if (DIRECTIVE.test(comment)) continue; + const first = lineOf(starts, range.pos); + const last = lineOf(starts, range.end - 1); + for (let line = first; line <= last; line++) { + const content = added.get(line); + if (typeof content !== 'string' || removed.has(content.trim())) continue; + problems.push(`${path}:${line} code comment: name things so the code explains itself`); + break; + } + } +} + +if (problems.length) { + console.error(problems.join('\n')); + console.error(`\n${problems.length} convention problem${problems.length === 1 ? '' : 's'} in the changed lines.`); + process.exitCode = 1; +} else { + console.log('conventions ok'); +} From f7ff281c52c5bd71c6d47cd3df32f0f442ee32b5 Mon Sep 17 00:00:00 2001 From: Mistium <92952823+Mistium@users.noreply.github.com> Date: Sun, 1 Nov 2026 02:15:23 +0000 Subject: [PATCH 2/2] Follow moved and edited comments in the conventions check, and correct AGENTS.md details The conventions check now reads deleted files, compares comment text instead of whole lines, skips JSX text and allows em dashes on moved lines. require-jsdoc is also off in src/.eslintrc.js, which is a root config the top-level setting never reached. --- scripts/check-conventions.mjs | 18 +++++++++++++----- src/.eslintrc.js | 3 +++ 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/scripts/check-conventions.mjs b/scripts/check-conventions.mjs index 04d4a6bc8..24a5dce5c 100644 --- a/scripts/check-conventions.mjs +++ b/scripts/check-conventions.mjs @@ -74,12 +74,12 @@ const commentRanges = (path, text) => { for (const range of ranges || []) seen.set(range.pos, range); }; const visit = node => { + if (node.kind === ts.SyntaxKind.JsxText || node.kind === ts.SyntaxKind.JsxTextAllWhiteSpaces) return; if (node.kind >= ts.SyntaxKind.FirstToken && node.kind <= ts.SyntaxKind.LastToken) { collect(ts.getLeadingCommentRanges(text, node.pos)); collect(ts.getTrailingCommentRanges(text, node.end)); return; } - if (node.kind === ts.SyntaxKind.JsxText) return; collect(ts.getLeadingCommentRanges(text, node.pos)); node.getChildren(source).forEach(visit); }; @@ -89,12 +89,17 @@ const commentRanges = (path, text) => { }; const problems = []; -const {files, removed} = parseDiff(git(...diffArgs, '--unified=0', '--no-color', '--diff-filter=ACMR')); +const {files, removed: removedLines} = parseDiff(git(...diffArgs, '--unified=0', '--no-color', '--diff-filter=ACMRD')); + +const removedText = [...removedLines].join('\n'); +const wasRemoved = text => text.length > 0 && removedText.includes(text); for (const [path, added] of files) { if (SKIPPED_PATHS.some(pattern => pattern.test(path)) || !TEXT_FILE.test(path)) continue; for (const [line, content] of added) { - if (content.includes(EM_DASH)) problems.push(`${path}:${line} em dash: use a comma, parentheses or "to"`); + if (content.includes(EM_DASH) && !removedLines.has(content.trim())) { + problems.push(`${path}:${line} em dash: use a comma, parentheses or "to"`); + } } if (!SOURCE_FILE.test(path)) continue; const text = staged ? git('show', `:${path}`) : fs.readFileSync(path, 'utf8'); @@ -105,8 +110,11 @@ for (const [path, added] of files) { const first = lineOf(starts, range.pos); const last = lineOf(starts, range.end - 1); for (let line = first; line <= last; line++) { - const content = added.get(line); - if (typeof content !== 'string' || removed.has(content.trim())) continue; + if (typeof added.get(line) !== 'string') continue; + const lineStart = starts[line - 1]; + const lineEnd = line < starts.length ? starts[line] - 1 : text.length; + const portion = text.slice(Math.max(range.pos, lineStart), Math.min(range.end, lineEnd)).trim(); + if (!/[A-Za-z0-9]/.test(portion) || wasRemoved(portion)) continue; problems.push(`${path}:${line} code comment: name things so the code explains itself`); break; } diff --git a/src/.eslintrc.js b/src/.eslintrc.js index 11b4d5aad..349c9147a 100644 --- a/src/.eslintrc.js +++ b/src/.eslintrc.js @@ -7,5 +7,8 @@ module.exports = { }, globals: { Buffer: true // TODO: remove this? + }, + rules: { + 'require-jsdoc': 'off' } };