How evanzhoudev/polycompiler works
Project Type and Purpose
• Polycompiler is an experimental, command-line tool intended to merge separate Python and JavaScript source files into one polyglot file. The resulting file behaves differently when run with Node (executing JS code) versus Python (executing Python code). Its purpose is to serve as a “polyglot” solution—for fun, and potentially for use cases where both runtimes must be supported in one file.
Analyzing the File Structure
• Top-level Directories and Files:
• .gitignore and package.json/package-lock.json indicate this is a Node-based project.
• README.md documentation explains usage and design.
• The “bin” directory (specifically bin/merge.js) is likely the entry point for merging the two files.
• Architectural Implications:
• The core functionality is implemented as a command-line utility (the “polycompiler” command) that wraps the merging algorithm.
• There is a clear separation between the merging script (in merge.js) and the external interfaces (the CLI, the input source files, and the output merged file).
Core Components & Interactions
a. Command-Line Interface (CLI): The entry point where users run the “polycompiler” command with the three file paths (JS input, Python input, output file).
b. Merge Module (bin/merge.js): This is the core logic that reads the two input files and creates the combined output.
c. File System: Indicate where the input files (in.js and in.py) are read from and where the output file (e.g., out.py.js) is written.
d. Runtime Environments:
• Node.js runtime, which processes the JS code when the output file is executed via “node out.py.js.”
• Python runtime, which processes the Python code when executed with “python3 out.py.js.”
• Relationships and Data Flow:
• A user inputs file paths via the CLI.
• The merge.js module is invoked by the Node.js platform.
• The module reads the two source files from disk.
• The merging logic embeds both code sections into one JavaScript file, carefully ordering and decorating them so that when run in one runtime, only the intended portion is executed.
• The output file is saved to disk.
• Finally, the runtime (either Node or Python) interprets the resulting file appropriately.
Architectural Patterns, Design Principles, and Technologies
• Given the simple yet clever merging approach, highlight:
• The use of conditional code execution based on language interpreter behavior (i.e., Python ignores JS-labeled constructs and vice versa).
• Separation of concerns: the CLI handles input parameters and file path specifications, while the merging logic encapsulated in merge.js performs the actual code combination.
• Minimalistic design: relying on Node/NPM for packaging and distribution.
• Relevant technologies:
• Node.js (for execution of merge.js and packaging with NPM).
• The file system libraries available in Node.js (for reading and writing files).
• The dual language environments (Python 3 and Node.js) as part of the runtime behavior of the merged file.