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.

Version 0.7.0 is a normal Marketplace release built from the standard catalog tier. Rank00 through Rank04 are fully machine graded: every selected criterion must execute to PASS or FAIL, and missing tools, isolation, artifacts, or runtime observations fail closed. There is no manual-review, UNAVAILABLE, or external evidence-root grading path in those ranks.

What It Does

• Runs a bundled Go-based grading engine from VS Code on Linux x64 and WSL x64, with an explicit development-only 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.
• Breaks grading results down by the learner-facing unit: Libft functions such as ft_split, Python exN exercises, and project-specific criteria or features. The same item_id hierarchy is available in JSON, CLI output, the Results tree, and HTML reports.
• Excludes explicitly classified cyber checks (for example secret scans, sandbox/adversarial probes, and multi-user security probes) before execution while preserving ordinary subject-policy checks such as forbidden-function validation.
• Displays binary PASS/FAIL outcomes and separate mandatory/Bonus track status for Rank00 through Rank04.
• 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.
• Groups clause-backed results into closed Project setup, Norm and style, Compile and build, Memory and resources, Behavior and tests, Integration and runtime, Security, Documentation, and Other panels. Rank00 through Rank04 panels expose only PASS/FAIL outcomes.
• Keeps protected subject resources out of the Marketplace package.

Supported Platforms

The Marketplace VSIX supports Linux x64 and WSL x64 only. Dynamic learner-code checks fail closed when the bundled engine cannot establish the required isolation or evidence prerequisites.

macOS, Linux arm64, and native Windows execution are not supported by this release. On Windows, use an x64 WSL environment. A custom engine supplied through grader.enginePath or PATH on another host is an unsupported development path; it does not make that platform supported and does not bypass the engine's isolation checks.

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. On Linux x64 or WSL x64, the extension detects the current project and uses the bundled ccgrader engine when available.
4. Run Grader: Setup only if you need a private/local resource root or an unsupported development-only custom engine.
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. Extension grading always runs Deep so every selected Rank00-through-Rank04 criterion receives a final machine outcome.
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. Native Windows execution is not supported; use an x64 WSL environment.

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.

Profiles and Accuracy Evidence

Minimum, Normal, and Strict are cumulative: Normal includes Minimum criteria, and Strict includes both earlier levels. Deep is the final Rank00-through-Rank04 path and requires every selected criterion to execute. Fast remains editing feedback; it does not certify a final result.

The release build measures Fast mode over a fixed three-subject frontier for 30 engine runs and rejects the package when p95 exceeds one second. This is a responsiveness budget for a provisional Fast report, not a claim that every Deep or environment-dependent check finishes in one second.

For Rank00 through Rank04, every selected result must be machine-executed PASS or FAIL. Missing runners, prerequisites, or trusted evidence are configuration errors or fail-closed FAIL results, never a synthetic pass or manual-review request. 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 does not publish guessed per-project percentages or a resource-pack precision target. Public Marketplace builds do not bundle PDFs, official checkers, third-party archives, or reference answers; grader.resourceRoot can enable explicitly identified local evidence without turning unavailable checks into PASS.

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 show the unavailable automatic evidence and their reduced coverage explicitly.

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: fixed to deep for complete 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

The release build runs on Linux x64 and scripts/build-engines.sh produces and smokes only the Linux x64 engine from the sibling grading engine repository. During development, you can still point grader.enginePath at another binary, but that does not extend the Marketplace support matrix.

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

The ignored .env.publish.local may provide the Marketplace token without copying it into the extension:

PUBLISHER=harnakam
VSCE_PAT=

The publish script validates the exact 0.7.0 VSIX and its structured fresh-install record before reading a token file. Keep the token in the ignored .env.publish.local and pass its absolute path as PUBLISH_ENV_FILE.

Use npm run publish:dry-run before publishing. It builds and validates the VSIX once and prints its exact digest without reading credentials. Fresh-install that same file, create the structured smoke record, then use npm run publish:marketplace to revalidate and publish only those exact bytes.

See PUBLISHING.md for the longer runbook.

Disclaimer

This project is an independent local review tool. Rank00 through Rank04 fail closed when required tools or trusted machine evidence are missing. Always compare against the current subject and official evaluation process.