Metadata-Version: 2.4
Name: janky-jit
Version: 1.0.0
Summary: Hyper-optimized, multi-language polyglot JIT framework for Python.
Author: Adam
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Compilers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: systems
Provides-Extra: zig
Provides-Extra: nim
Provides-Extra: all
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: provides-extra
Dynamic: requires-python
Dynamic: summary

# 🏗️ 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:

```bash
# 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:

```bash
# 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:

```bash
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!

```python
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.
