Grader

Grader is a VS Code extension for running ccgrader against 42-style submissions. It is designed for strict local review, not as an official school grading tool.

What It Does

• Runs a bundled Go-based grading engine from VS Code on supported platforms, with optional local engine override.
• Detects the current project from the active editor/workspace so Grade Workspace can run without picking a folder or project.
• Lets you pin a project manually with Grader: Configure Project... when auto-detection picks the wrong target.
• Adds Activity Bar, editor title, and status-bar launchers for grading and quick settings.
• Supports English and Japanese extension UI/report text with grader.language.
• Runs subject-backed Bonus checks only when explicitly enabled, so mandatory-only submissions are not failed for missing optional files.
• Detects Python Module submissions from module folders or individual ex*/ exercise folders.
• Uses a project .venv, venv, or env Python interpreter before falling back to system python3.
• Shows live grading progress from the engine while checks are running.
• Shows projects and behavior checks in the VS Code Testing view.
• Runs one shared engine grade when several Testing-view nodes from the same project are selected.
• Publishes failures to Problems diagnostics when a check maps to a submitted file.
• Opens a readable HTML report for grade, doctor, resource-check, and self-check results.
• Displays v2 target and observed verdicts, finality, coverage, and separate mandatory/Bonus track status instead of treating every non-failure as a final pass.
• Shows a status bar indicator for engine availability, running state, last failure count, and last report.
• Provides a Getting Started walkthrough and view welcome actions for first-run grading.
• Copies the last engine command so failures can be reproduced in a terminal.
• Shows clause-backed criteria, executed coverage, and every manual, unavailable, or Fast-deferred check instead of inventing a confidence percentage.
• Keeps protected subject resources out of the Marketplace package.

Supported Platforms

• Linux
• WSL
• macOS x64 bundled; macOS arm64 can use the bundled x64 engine with Rosetta or a custom arm64 enginePath

Windows native execution is not supported for strict C grading. Use WSL for Windows environments.

Setup

1. Open a submission workspace or any file inside a submission.
2. Click the Grader icon in the Activity Bar, editor title, or status bar, then run Grade Current Project.
3. The extension detects the current project and uses the bundled ccgrader engine when available.
4. Run Grader: Setup only if you need a custom engine path or private/local resource root.
5. Turn on Bonus Checks from the Grader Activity Bar only when the submitted project includes the subject bonus part.
6. Select the cumulative Minimum, Normal, or Strict profile and choose Fast for provisional editing feedback or Deep for final automated review.
7. Run Grader: Doctor to verify tools such as cc, make, norminette, valgrind, docker, python3, and uv.

The Marketplace extension does not assume any local absolute path. Windows native execution is not supported; use WSL.

Workspace Trust is respected. When a workspace is untrusted, the extension allows specification browsing but does not execute the local grading engine.

Resource Policy

The Marketplace VSIX includes only self-authored extension code, public specifications, fixtures, and harness metadata.

It does not bundle:

• subject PDFs
• official checker binaries
• third-party tester repositories
• resource archives such as .zip, .tar, .tgz, .gz, or .whl

Configure grader.resourceRoot to point at a private/local resource tree when you have the right to use those resources locally.

Precision Profiles

Minimum, Normal, and Strict are cumulative: Normal includes Minimum criteria, and Strict includes both earlier levels. Fast does not weaken the selected profile; checks intentionally deferred by Fast remain visible as REVIEW, and the report remains provisional. Deep attempts every automated check in the selected profile and can become automatic-final; manual evidence still remains explicit.

Every grade report distinguishes the checks that actually ran (observed) from the verdict for the whole selected target (target). A Fast run can therefore show observed PASS while target remains REVIEW. Mandatory and Bonus tracks are reported separately, and Bonus stays opt-in.

The project aims for at least 99% agreement on its labeled regression corpus, but it does not turn that engineering target into an unsupported probability for an arbitrary submission. Reports expose the actual denominator: required, executed, passed, failed, pending, blocked, unavailable, Fast-deferred, and excluded checks.

The catalog also exposes a resource-pack precision target. Public Marketplace builds do not bundle PDFs, official checkers, third-party archives, or reference answers, but when grader.resourceRoot points at a private/local material tree the engine enables resource-backed checks such as subject/criteria/reference availability and Python reference API parity.

Deep C projects such as ft_printf, libft, get_next_line, and push_swap have the strongest automated coverage. Projects that require a VM, browser, live containers, LLM resources, or interactive defense are marked as hybrid or manual-heavy and show exactly what remains unverified.

Bonus checks are opt-in. With grader.enableBonus off, bonus-only deliverables and fixtures appear as SKIP with bonus.disabled. With it on, the engine passes -bonus and grades subject-specific bonus behavior such as ft_printf width/precision/flags, get_next_line bonus multi-fd/static-variable rules, and the push_swap checker.

Python dependency checks separate required libraries from sufficient/runtime-complete libraries. Missing required library declarations fail the manifest check; missing installed packages in the current virtual environment are shown as dependency SKIP with setup hints.

Commands

• Grader: Setup
• Grader: Quick Actions
• Grader: Grade Workspace
• Grader: Grade Folder...
• Grader: Doctor
• Grader: Resource Check
• Grader: Self Check Materials
• Grader: Open Specification Catalog
• Grader: Configure Engine...
• Grader: Configure Project...
• Grader: Configure Profile...
• Grader: Configure Mode...
• Grader: Configure Parallelism...
• Grader: Toggle Bonus Checks
• Grader: Open Last Report
• Grader: Copy Last Engine Command
• Grader: Show Output

Configuration

• grader.enginePath: optional override path to a local grading engine
• grader.resourceRoot: path to private/local subject resources
• grader.defaultProject: project selection override. Use auto, ask, all, or a concrete project id
• grader.profile: cumulative minimum, normal, or strict criteria
• grader.mode: fast provisional feedback or deep final automated review
• grader.enableNorm: run Norm checks when available
• grader.enableMemcheck: run valgrind checks when available
• grader.enableBonus: pass -bonus to the engine and run optional subject bonus checks
• grader.parallelism: maximum project workers for multi-project grading; 0 lets the engine choose
• grader.autoOpenReport: open the HTML report after grading
• grader.runDoctorAfterSetup: run Doctor after setup in trusted workspaces
• grader.language: ja, en, or auto
• grader.extraArgs: additional engine arguments

Development

npm run build:engines
npm test
npm run package:vsix

During development, scripts/build-engines.sh builds Linux/macOS engines from the sibling grading engine repository into engines/. You can still point grader.enginePath at another binary while testing.

On older 42 environments, global @vscode/vsce may require a newer Node version. If npm config get prefix points to /usr or /usr/local, set a user prefix first:

mkdir -p ~/.local
npm config set prefix ~/.local
npm install -g @vscode/vsce

If the host Node is too old for the current @vscode/vsce, use a newer Node runtime for publishing.

Publishing

Local publish secrets go in .env.publish.local.

VSCE_PAT=
PUBLISHER=harnakam
PUBLISH_VSIX_PATH=grader-<version>.vsix

Use npm run publish:dry-run before publishing. It builds the VSIX, validates the package contents, and verifies the PAT. Use npm run publish:marketplace only when the package is ready to go public.

See PUBLISHING.md for the longer runbook.

Disclaimer

This project is an independent local review tool. It is stricter in some places, incomplete in others, and may skip checks that depend on unavailable local tools or private resources. Always compare against the current subject and official evaluation process.