FluxSharp - Implementation Summary

Overview

This document summarizes implemented FluxSharp compiler features, especially include processing and main entry-point validation.

Functionalities Implemented

1. Include Processing System (

process_includes

)

Purpose

Allows FluxSharp programs to include other

files using include directives.

Syntax

// #include "filename.fsh"

Features

• .fsh

  -only validation: include directives can only include

  .fsh

  files

• Recursive processing: included files may include other files

• Circular include detection: prevents circular includes (A includes B and B includes A)

• Secure path validation: blocks path traversal attempts

• Clear error messages for invalid include scenarios

Error Messages

Included file not found:

❌ INCLUDE FILE NOT FOUND

Cannot find included file: 'filename.fsh'
Looked in: "path/to/filename.fsh"

Invalid include format:

❌ INVALID INCLUDE FILE

Include directive at line contains non-.fsh file: 'filename.txt'
Only .fsh files are allowed.

Correct format:
// #include "myfile.fsh"

Circular include:

❌ CIRCULAR INCLUDE

Circular include detected: 'circular_a.fsh' already included.

2. Main Class Validation (

validatemainclass

)

Purpose

Validates that a FluxSharp program meets entry-point requirements.

Requirements

1. Exactly one

   Main

   class: the program must contain one and only one class named

   Main

2. Exactly one

   main()

   method: the

   Main

   class must contain one and only one

   void main()

   method

Error Messages

Missing Main class:

❌ MISSING MAIN CLASS

Your program must have exactly one 'class Main' with a 'void main()' method.

Example:
public class Main {
    public void main() {
        print("Hello, World!");
    }
}

Multiple Main classes:

❌ MULTIPLE MAIN CLASSES

Your program has X 'class Main' declarations.
You must have exactly one 'class Main'.

Missing main method:

❌ MISSING MAIN METHOD

Your 'class Main' must have exactly one 'void main()' method.

Example:
public class Main {
    public void main() {
        print("Hello, World!");
    }
}

Multiple main methods:

❌ MULTIPLE MAIN METHODS

Your 'class Main' has X 'void main()' methods.
You must have exactly one 'void main()' method.

Integration Point

Both features are integrated into the compilation pipeline:

// 1. Read source file
let content = fs::readtostring(input)?;

// 2. Process includes
let processedcontent = processincludes(&content, &input.parent().unwrapor(&PathBuf::from(".")))?;

// 3. Validate Main class
validatemainclass(&processedcontent)?;

// 4. Compile to ASM
let asmoutput = compilefshtoasm(&processed_content, input)?;

Test Cases

Test 1: Include Missing File

File:

Result: ✅ PASS - Displays the "INCLUDE FILE NOT FOUND" error message

Test 2: Include Valid File

File:

Result: ✅ PASS - Correctly includes

and displays "📥 Including: helper.fsh"

Test 3: Circular Include Detection

Files:

and

(mutually include each other) File:

Result: ✅ PASS - Detects circular include and displays the error message

Test 4: Missing Main Class

File:

Result: ✅ PASS - Displays the "MISSING MAIN CLASS" error message

Test 5: Multiple Main Classes

File:

Result: ✅ PASS - Displays the "MULTIPLE MAIN CLASSES" error message

Test 6: Missing Main Method

File:

Result: ✅ PASS - Displays the "MISSING MAIN METHOD" error message

Test 7: Multiple Main Methods

File:

Result: ✅ PASS - Displays the "MULTIPLE MAIN METHODS" error message

Security Features

1. Path Traversal Protection

• Validates that include paths do not contain

  ..

• Validates that resolved paths remain inside allowed directories

• Blocks malicious symlinks

2. File Size Limits

• 50 MB limit per included file

• Non-empty file validation

3. Circular Dependency Detection

• Shared HashSet across recursive calls to track included files

• Immediate detection when a file is included twice

4. Input Validation

• Verifies that the included file exists before path validation

• Verifies that the target is a regular file (not a directory or symlink)

Future Improvements

1. Include Chains: Support tracing include chains in circular-include errors

``

`

`

`

`

`

• ✅ Code compiles without errors

• ✅ All tests pass

• ⚠️ Warnings: 8 warnings (currently from unused

  error_handler` helper functions)

Last Updated: 2026-04-03 Status: Complete and Tested