janky-jit 1.0.0

Hyper-optimized, multi-language polyglot JIT framework for Python.

🏗️ Janky

It is not a bug, it is architectural dominance.

Janky is a hyper-optimized, native compilation polyglot JIT framework for Python. It allows you to embed raw Assembly (64-bit and retro 32-bit), C++, Rust, Zig (Jig), Pure C, Nim, Raw Machine Code Hex Strings (Jinary), and Brainfuck source strings directly within your Python scripts, compilation-cached via OpenSSL SHA-256 fingerprinting, and executed at bare-metal speeds with zero abstraction overhead.

The core C compilation engines are secured behind an absolute systems-level Linux virtual filesystem lock (chattr +i). Janky bypasses Python's runtime limitations by loading compiled .so binaries directly into active memory using dlopen or mapping execution blocks natively into memory via mprotect.

---

🚀 The Native Core Lineup

Extension	Language	Backend Toolchain	Best Used For	Boilerplate Magic
jasm	x86-64 Assembly	nasm	Raw register control, vector ops	Pure sysv ABI assembly
jasm86	32-bit x86 Assembly	nasm	Stack-based legacy shellcode hacking	32-bit memory sandbox execution
jcpp	C++	g++	Heavy OOP, Matrix math, game physics	Requires extern "C" linkage
just	Rust	rustc	Memory-safe pipelines, hyper-threading	Requires #[no_mangle] pub extern "C"
jig	Zig	zig	Ultra-modern, low-overhead algorithms	Requires export fn notation
jc	Pure C	gcc / clang	Fastest cold compilation, retro tasks	Native C symbol preservation
jnim	Nim	nim	Python-like syntax at bare-metal speeds	Requires {.exportc, cdecl.}
jinary	Raw Binary Hex	mprotect Runtime	Direct execution of raw opcode arrays	Requires raw x86-64 executable hex
jbrainfuck	Brainfuck	Native JIT Gen	Melting-fast esoteric logic execution	Emits optimized x86-64 opcodes directly

---

💾 Installation & Setup

1. Install System Dependencies

Ensure your machine is weaponized with the required system compilers:

# Core Build Tools & OpenSSL development headers
sudo apt update
sudo apt install build-essential nasm libssl-dev

# Modern Compiler Ecosystem
sudo apt install zig nim
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Compile the Janky Extension Matrix

Navigate to your project directory, activate your virtual environment, and fire the build:

# Clean out any old stale build artifacts
rm -rf build/

# Compile and register all 9 native extension wrappers
pip install .

3. Seal the Fortress 🔒

Protect your foundational compiler engines from accidental edits or late-night programming accidents by locking them directly into the Linux Kernel space:

sudo chattr -R +i janky/compiler

Note: If you ever need to upgrade the core engines, lift the spell with sudo chattr -R -i janky/compiler.

---

🎸 Quick Start Tour (Polyglot Blitz)

You can now import and utilize any low-level native engine from anywhere on your machine as long as your virtual environment is active!

import time
from janky.compiler import jasm, just, jig, jc, jnim, jinary, jbrainfuck

# ==============================================================================
# 1. JINARY (Raw Executable Machine Code Opcodes)
# ==============================================================================
# Raw hex bytes for: mov rax, rdi (48 89 f8); add rax, rsi (48 01 f0); ret (c3)
hex_code = "4889f84801f0c3"
jinary_engine = jinary.compile(hex_code, "raw_exec")
print(f"Jinary Machine Code Add: {jinary_engine(20, 22)}")  # 42


# ==============================================================================
# 2. BRAINFUCK (Natively Optimized JIT Compiler)
# ==============================================================================
bf_code = "++++++++++[>+++++++>++++++++++<<-]>++.>+.[-]"
jbf_engine = jbrainfuck.compile(bf_code, "bf_run")
tape = bytearray(30000)
print("Executing JIT Brainfuck:")
jbf_engine(tape)  # Prints 'Hi' directly via optimized native write syscalls


# ==============================================================================
# 3. PURE C (Fastest Cold Compile)
# ==============================================================================
c_code = """
#include <stdint.h>
uint64_t c_factorial(uint64_t n) {
    return (n <= 1) ? 1 : n * c_factorial(n - 1);
}
"""
jc_engine = jc.compile(c_code, "c_factorial")
print(f"Pure C Factorial(5): {jc_engine(5)}")  # 120


# ==============================================================================
# 4. RUST (Memory Safe & Optimizing)
# ==============================================================================
rust_code = """
#[no_mangle]
pub extern "C" fn rust_cube(x: u64) -> u64 {
    x * x * x
}
"""
rust_engine = just.compile(rust_code, "rust_cube")
print(f"Rust Cube(3): {rust_engine(3)}")  # 27


# ==============================================================================
# 5. ZIG / JIG (Modern & Transparent)
# ==============================================================================
zig_code = """
export fn zig_xor(a: u64, b: u64) u64 {
    return a ^ b;
}
"""
jig_engine = jig.compile(zig_code, "zig_xor")
print(f"Zig Bitwise XOR: {jig_engine(1024, 1)}")  # 1025


# ==============================================================================
# 6. NIM (Pythonic Syntax, C Execution Speed)
# ==============================================================================
nim_code = """
proc nim_fib(n: int64): int64 {.exportc, cdecl.} =
  if n <= 1: return n
  else: return nim_fib(n - 1) + nim_fib(n - 2)
"""
jnim_engine = jnim.compile(nim_code, "nim_fib")
print(f"Nim Fibonacci(10): {jnim_engine(10)}")  # 55


# ==============================================================================
# 7. X86-64 ASSEMBLY (Ultimate Control)
# ==============================================================================
asm_code = """
global asm_add
section .text
asm_add:
    mov rax, rdi    ; rdi is first argument (a)
    add rax, rsi    ; rsi is second argument (b)
    ret             ; Return value stored in rax
"""
jasm_engine = jasm.compile(asm_code, "asm_add")
print(f"Raw Assembly Add: {jasm_engine(40, 2)}")  # 42

---

🛠️ Performance & Architecture

Every time you execute a .compile() string across any language module:

1. Fingerprinting: Janky hashes the source code token string using OpenSSL SHA-256.
2. Hit Detection: If the hash exists inside the .janky_cache/ directory, the compiler execution is completely skipped, instantly performing a high-speed dlopen read on the pre-compiled .so block or reusing memory allocated regions.
3. Arguments Passthrough: Up to 6 standard integer variables or direct raw memory block pointer addresses (via Python's buffer protocol) can be funneled directly into function parameters with zero serialization penalty.

🛑 Project Boundaries / Guardrails

• Do not modify janky/compiler/ contents. The kernel will throw a hard Operation not permitted.
• Argument Constraint: Maximum of 6 arguments map natively to system registers under the current C calling architecture wrapper.

---

📜 License

Unlicensed. Pure hacking freedom. Go break some memory limits.