Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .eslintrc.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
module.exports = {
root: true,
extends: ['scratch', 'scratch/node', 'scratch/es6']
extends: ['scratch', 'scratch/node', 'scratch/es6'],
rules: {
'require-jsdoc': 'off'
}
};
3 changes: 3 additions & 0 deletions .github/workflows/node.js.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,15 @@ jobs:
- uses: actions/checkout@v4
with:
persist-credentials: false
fetch-depth: 0
- name: Install Node.js
uses: actions/setup-node@v4
with:
node-version: 22
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
26 changes: 26 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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/).
21 changes: 21 additions & 0 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 3 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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",
Expand Down
130 changes: 130 additions & 0 deletions scripts/check-conventions.mjs
Original file line number Diff line number Diff line change
@@ -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*<reference)/;

const options = process.argv.slice(2);
const staged = options.includes('--staged');
const base = (options.find(option => 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');
}
3 changes: 3 additions & 0 deletions src/.eslintrc.js
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,8 @@ module.exports = {
},
globals: {
Buffer: true // TODO: remove this?
},
rules: {
'require-jsdoc': 'off'
}
};
Loading