node-moss

📖 Overview

node-moss is a modern, strictly-typed Node.js client for Stanford's MOSS (Measure of Software Similarity).

Designed for academic integrity and code review automation, this package provides a programmatic interface to submit code files to the MOSS server. It wraps the socket communication in a clean, Promise-based API, making it easy to integrate into grading scripts, CI/CD pipelines, or educational platforms.

Key Features

• 🧩 TypeScript Native: Written in TypeScript with complete type definitions included.
• ⚡ Asynchronous: Fully Promise-based (async/await) architecture.
• 📂 Wildcard Support: Effortless bulk file loading using glob patterns (e.g., src/**/*.cpp).
• 🛡️ Base Code Handling: Easily filter out boilerplate/skeleton code to avoid false positives.

---

🚀 Installation

Install the package via npm:

npm install node-moss

---

🔧 Usage

Here is a complete example of how to configure the client, load files, and generate a report.

import { MOSS } from 'node-moss';

(async () => {
  // 1. Initialize with your MOSS User ID
  const client = new MOSS("YOUR_USER_ID");

  // 2. Configure Analysis Settings
  client.setLanguage("cc");      // Set language to C++
  client.setResultLimit(10);     // Limit report to top 10 matches
  client.setComment("Assignment #1: Data Structures"); // Add a label

  try {
    // 3. Load Base Code (Optional)
    // Code provided to students (boilerplate) that should be ignored.
    await client.addBaseFile("./skeleton/main.cpp");

    // 4. Load Submissions
    // Option A: Add specific files
    await client.addFile("./submissions/student_A.cpp");
    await client.addFile("./submissions/student_B.cpp");

    // Option B: Bulk load using wildcards
    await client.addByWildcard("./submissions/**/*.cpp");

    // 5. Submit to MOSS Server
    console.log("🚀 Uploading files to MOSS server...");
    const reportUrl = await client.send();

    console.log(`✅ Report generated successfully: ${reportUrl}`);

  } catch (error) {
    console.error("❌ An error occurred:", error);
  }
})();

---

🌍 Supported Languages

MOSS supports the following languages (use the exact code with setLanguage()):

Language	Code
C	c
C++	cc
Java	java
ML	ml
Pascal	pascal
Ada	ada
Lisp	lisp
Scheme	scheme
Haskell	haskell
Fortran	fortran
ASCII files	ascii
VHDL	vhdl
Perl	perl
MATLAB	matlab
Python	python
MIPS assembly	mips
Prolog	prolog
SPICE	spice
Visual Basic	vb
C#	csharp
Modula-2	modula2
8086 assembly	a8086
JavaScript	javascript
PL/SQL	plsql
Verilog	verilog

Note: This is the full list from the official MOSS Perl script. May Some changes are done.

---

The Methods

🔍 Getters

Retrieve current configuration values.

Method	Returns	Description
getUserID()	string	Returns the current User ID.
getSupportedLanguages()	string[]	Returns a list of all supported languages.
getComment()	string	Returns the current comment string.
getDirectoryMode()	number	Returns 0 or 1.
getIgnoreLimit()	number	Returns the current ignore limit.
getResultLimit()	number	Returns the current result limit.
getExperimentalServer()	number	Returns the experimental server status.

🛠️ Configuration (Setters)

Customize how MOSS processes your files.

Method	Description	Default Value
setLanguage(lang)	Set the programming language (e.g., 'c', 'java', 'python').	'c'
setDirectoryMode(mode)	Set to 1 to group files by directory (useful for multi-file projects).	0 (Off)
setResultLimit(n)	The number of matching files to show in the results.	250
setIgnoreLimit(n)	Ignore code passages that appear in more than n files (helps ignore common boilerplate).	10
setComment(text)	A string attached to the report for your own reference.	""
setExperimentalServer(x)	Set to 1 to use the experimental MOSS server.	0
setUserID(id)	Updates the User ID (if not set in constructor).	-

📂 File Management

Methods to load student code and skeleton code.

Method	Description	Async?
addFile(path)	Adds a specific submission file to be checked.	✅ Yes
addBaseFile(path)	Adds "skeleton" or "base" code. MOSS will ignore matches found in these files.	✅ Yes
addByWildcard(pattern)	Adds multiple files using a glob pattern (e.g., ./src/*.js).	✅ Yes

🚀 Execution

The command to start the analysis.

Method	Description	Returns
send()	Uploads all files and settings to Stanford MOSS and awaits the response.	Promise<string> (The URL)

---

⚠️ Important Note

This is a client. You still need a valid MOSS User ID from Stanford.

• Don't have one? Send an email to moss@moss.stanford.edu with the body registeruser-mail <your_email>.

---

🤝 Contributing

Found a bug? Want to add support?
Your are welcomed! Fork it, fix it, ship it.

---

📜 License

This project is licensed under MIT License LICENSE file.
2025 MIT © Abdelhalim Yasser