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..24a5dce5c --- /dev/null +++ b/scripts/check-conventions.mjs @@ -0,0 +1,130 @@ +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.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; + } + 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: 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) && !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'); + 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++) { + 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; + } + } +} + +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'); +} 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' } };