@thanh01.pmt/algorithm-judge-kit

Pure, decoupled library providing Headless Algorithm Judging (I/O testcases), Static AST Barem Grading (Structural checks), and AST Plagiarism Detection for Scratch 3.0 (.sb3) projects.

Features

• Headless Scratch Execution (ScratchRunner): Runs .sb3 projects in jsdom + scratch-vm (Turbo mode) with TLE guard, DOS protection, and early termination.
• Structural Barem Evaluator (StructuralRunner): Static AST analyzer supporting boolean DSL expressions (AND, OR, NOT, parentheses) and declarative object checks with 0 eval().
• AST Plagiarism Checker (detectPlagiarismBatch): Tokenizes opcode sequences into AST fingerprints and computes similarity using Jaccard index and n-gram shingling.
• Problem Schema Validation (validateProblemDefinition): Strict Zod schemas validating weights, testcases, and structural checks.

Installation

pnpm add @thanh01.pmt/algorithm-judge-kit

Quick Start

1. Structural Barem Grading

import { StructuralRunner } from '@thanh01.pmt/algorithm-judge-kit';

const result = await StructuralRunner.analyze(sb3Buffer, [
  {
    id: 'sc1',
    weight: 50,
    check: 'sprites.count >= 2',
    description: 'Có ít nhất 2 nhân vật',
  },
  {
    id: 'sc2',
    weight: 50,
    check: "variables.exists('Score')",
    description: 'Có biến tên Score',
  },
]);

console.log(result.scorePercentage, result.passed);

2. I/O Testcase Judging

import { ScratchRunner, validateProblemDefinition } from '@thanh01.pmt/algorithm-judge-kit';

const problem = validateProblemDefinition(problemJson);
const evalResult = await ScratchRunner.evaluateProblem({
  sb3Buffer,
  problem,
  timeLimitMsOverride: 5000,
});

console.log(evalResult.scorePercentage, evalResult.testCases);