P4RS3LT0NGV3/CONTRIBUTING.md

Contributing to P4RS3LT0NGV3

Thank you for your interest in contributing! This guide will help you understand the project structure and how to add new features.

📁 Project Structure

P4RS3LT0NGV3/
├── js/
│   ├── app.js              # Main Vue.js application entry point
│   ├── core/                # Core feature modules (shared libraries)
│   │   ├── decoder.js      # Universal decoder
│   │   ├── steganography.js # Steganography encoding/decoding
│   │   └── toolRegistry.js  # Tool registry system
│   ├── bundles/             # Build-generated files (auto-created)
│   │   └── transforms-bundle.js  # Generated bundle from src/transformers/
│   ├── config/              # Configuration constants
│   │   └── constants.js
│   ├── data/                # Generated or static data files (auto-created)
│   │   ├── emojiData.js     # Generated from Unicode emoji data
│   │   └── emojiCompatibility.js
│   ├── utils/               # Utility functions
│   │   ├── clipboard.js
│   │   ├── emoji.js
│   │   ├── escapeParser.js
│   │   ├── focus.js
│   │   ├── history.js
│   │   ├── notifications.js
│   │   └── theme.js
│   └── tools/               # Tool implementations (Vue integration)
│       ├── Tool.js          # Base class
│       ├── TransformTool.js
│       ├── DecodeTool.js
│       ├── EmojiTool.js
│       ├── TokenadeTool.js
│       ├── MutationTool.js
│       ├── TokenizerTool.js
│       ├── SplitterTool.js
│       └── GibberishTool.js
├── src/
│   ├── emojiWordMap.js      # Emoji keyword mappings (merged into emojiData.js)
│   └── transformers/        # Transformer modules (source - bundled at build time)
│       ├── BaseTransformer.js
│       ├── ancient/         # Elder Futhark, Hieroglyphics, Ogham, Roman Numerals
│       ├── case/            # Camel, Kebab, Snake, Title, etc.
│       ├── cipher/          # Caesar, ROT13, Vigenère, Atbash, etc.
│       ├── encoding/        # Base64, Hex, Binary, URL, etc.
│       ├── fantasy/         # Quenya, Tengwar, Klingon, Aurebesh, Dovahzul
│       ├── format/          # Leetspeak, Pig Latin, Reverse, etc.
│       ├── special/         # Randomizer
│       ├── technical/       # Morse, NATO, Braille, Brainfuck, etc.
│       ├── unicode/         # Upside-down, Fullwidth, Bubble, etc.
│       └── visual/          # Disemvowel, Rovarspraket, Ubbi-dubbi, etc.
├── templates/               # HTML templates for tools (injected at build time)
│   ├── decoder.html
│   ├── steganography.html
│   ├── transforms.html
│   ├── tokenade.html
│   ├── fuzzer.html
│   ├── tokenizer.html
│   ├── splitter.html
│   └── gibberish.html
├── build/                   # Build scripts
│   ├── build-index.js       # Generates transformer index
│   ├── build-transforms.js  # Bundles transformers into js/bundles/
│   ├── build-emoji-data.js # Generates emojiData.js from Unicode data
│   ├── inject-tool-scripts.js # Auto-discovers and registers tools
│   └── inject-tool-templates.js # Injects templates into index.html
├── tests/                   # Test suites
│   ├── test_universal.js
│   └── test_steganography_options.js
├── css/                     # Stylesheets
│   ├── style.css
│   └── notification.css
├── index.template.html      # Base HTML template (templates injected here)
├── index.html               # Generated file (created by build process)
└── docs/                    # Documentation

🎯 Key Concepts

Core vs Tools

• js/core/ - Shared business logic and infrastructure

  • These are NOT tool-specific
  • Examples:
    • decoder.js (used by DecodeTool + app.js)
    • steganography.js (used by EmojiTool + decoder.js)
    • emojiLibrary.js (used by EmojiTool)
    • toolRegistry.js (ToolRegistry class - infrastructure for the tool system)

• Source files (src/) - Source files used by build process

  • emojiWordMap.js - Emoji keyword mappings (merged into emojiData.js during build)
  • transformers/ - Transformer modules (bundled into transforms-bundle.js)

• Generated files (js/bundles/)

  • transforms-bundle.js - Generated bundle from src/transformers/ (created by npm run build:transforms)

• js/tools/ - Vue.js integration layer for UI features

  • Each tool represents a tab/feature in the UI
  • Tools use core modules and utilities for functionality
  • Example: DecodeTool.js uses window.universalDecode from core/decoder.js

Transformers vs Tools

• Transformers (src/transformers/) - Text transformation logic (encoding/decoding)
• Tools (js/tools/) - UI features/tabs (Transform tab, Decoder tab, Emoji tab)

🚀 Getting Started

Prerequisites

• Node.js (for running tests and builds)
• Modern web browser (for testing)

Setup

# Clone the repository
git clone <repo-url>
cd P4RS3LT0NGV3

# Install dependencies (if any)
npm install

# Build transformers bundle
npm run build

# Run tests
npm test

✨ Adding New Features

1. Adding a New Transformer

Transformers are the core text transformation logic. See src/transformers/README.md for detailed instructions.

Quick Start:

1. Create a new file in the appropriate category directory:

   src/transformers/ciphers/my-cipher.js
   

2. Use the BaseTransformer class:

   import BaseTransformer from '../BaseTransformer.js';
   
   export default new BaseTransformer({
       name: 'My Cipher',
       priority: 60,              // See priority guide in transformers/README.md
       category: 'ciphers',
       func: function(text) {
           // Encoding logic
           return encoded;
       },
       reverse: function(text) {
           // Decoding logic
           return decoded;
       },
       detector: function(text) {
           // Optional: pattern detection for universal decoder
           return /pattern/.test(text);
       }
   });
   

3. Rebuild the bundle:

   npm run build
   

4. Test it:

   • Open index.html in a browser
   • Your transformer will appear in the Transform tab automatically
   • Test encoding/decoding
   • Test with the Universal Decoder

5. Add tests (optional but recommended):

   • Add test cases to tests/test_universal.js
   • Run npm test to verify

Important: Transformers are automatically discovered and bundled. No manual registration needed!

2. Adding a New Tool (New Tab/Feature)

Tools represent UI features/tabs. Examples: Transform tab, Decoder tab, Emoji tab.

Steps:

1. Create a new tool class in js/tools/:

   // js/tools/MyNewTool.js
   class MyNewTool extends Tool {
       constructor() {
           super({
               id: 'myfeature',        // Unique ID (used for tab switching)
               name: 'My Feature',     // Display name
               icon: 'fa-star',        // Font Awesome icon class
               title: 'My Feature (M)', // Tooltip with keyboard shortcut
               order: 5                // Display order (lower = earlier)
           });
       }
   
       getVueData() {
           return {
               // Vue data properties for this tool
               myInput: '',
               myOutput: ''
           };
       }
   
       getVueMethods() {
           return {
               // Vue methods for this tool
               doSomething: function() {
                   // Your logic here
               }
           };
       }
   
       getTabContentHTML() {
           return `
               <!-- HTML template for this tool's tab -->
               <div class="my-feature-layout">
                   <textarea v-model="myInput"></textarea>
                   <div>{{ myOutput }}</div>
               </div>
           `;
       }
   }
   

2. Run the build script to auto-register your tool:

   npm run build:tools
   

   This will:

   • Auto-discover your new tool file
   • Add script tag to index.template.html
   • Generate registration code in toolRegistry.js

3. If you created a template file, build templates:

   npm run build:templates
   

4. Test it:

   • Open index.html
   • Your new tab should appear automatically
   • Test all functionality

See js/tools/Tool.js for the base class API and js/tools/TransformTool.js for a complete example.

3. Adding a New Utility Function

Utilities are shared helper functions used across the app. Currently, utility functions are typically added directly to the modules that need them or as part of core modules.

If you need to create a new utility module:

1. Create a new file in js/ (root level) or js/core/:

   // js/myUtility.js
   window.MyUtility = {
       doSomething: function(param) {
           // Your utility function
           return result;
       }
   };
   

2. Add script tag to index.html (before app.js):

   <script src="js/myUtility.js"></script>
   

3. Use it in your code:

   window.MyUtility.doSomething(value);
   

Guidelines:

• Keep utilities pure (no side effects when possible)
• Use window namespace for browser compatibility
• Document with JSDoc comments
• Consider adding to existing modules if functionality is related

Note: The js/utils/ directory contains utility functions: clipboard, escapeParser, focus, history, notifications, and theme. The js/config/ directory contains configuration constants.

🧪 Testing

Running Tests

# Run all tests
npm test

# Run specific test suite
npm run test:universal      # Universal decoder tests
npm run test:steg           # Steganography options tests

Writing Tests

• Transformer tests: Add to tests/test_universal.js

  • Tests are automatically discovered
  • Add limitations/expected behavior to the limitations object if needed

• Steganography tests: Add to tests/test_steganography_options.js

  • Tests encoding/decoding round-trips with various option combinations

• New test files: Create in tests/ directory

  • Use path.resolve(__dirname, '..') to get project root
  • Use path.join(projectRoot, '...') for file paths

📝 Code Style

JavaScript

• Use ES6+ features (arrow functions, const/let, template literals)
• Use meaningful variable names
• Add JSDoc comments for public functions
• Follow existing code style in the file you're editing

File Organization

• Core modules (js/core/) - Shared business logic (e.g., decoder.js)
• Root-level modules (js/) - Feature libraries (e.g., steganography.js, emojiLibrary.js)
• Tools (js/tools/) - Vue.js UI integration layer
• Templates (templates/) - HTML templates for tools (injected at build time)
• Transformers (src/transformers/) - Text transformation logic
• Bundles (js/bundles/) - Build-generated files

Naming Conventions

• Files: camelCase.js for utilities/tools, kebab-case.js for transformers
• Classes: PascalCase (e.g., DecodeTool)
• Functions: camelCase (e.g., runUniversalDecode)
• Constants: UPPER_SNAKE_CASE (e.g., MAX_HISTORY_ITEMS)

🔧 Build Process

Building Templates

npm run build:templates

This:

1. Reads all .html files from templates/ directory
2. Injects them into index.html at the #tool-content-container marker
3. Creates a single static HTML file for fast loading

When to run:

• After editing any template in templates/
• Before committing template changes

Build Script Details

• Directory Creation: Build scripts automatically create output directories (js/bundles/, js/data/) if they don't exist
• Full Build: Run npm run build to execute all build steps in order
• Individual Builds: Each build script can be run independently

Note: Transformers are loaded from js/bundles/transforms-bundle.js which may be pre-built or generated separately.

🐛 Debugging

Common Issues

1. Template changes not showing: Run npm run build:templates to inject templates into index.html
2. Tool not showing: Check that:
   • Tool is registered in js/core/toolRegistry.js
   • Script tag is in index.html before app.js
   • Template file exists in templates/ directory
3. Tests failing: Check file paths use path.join(projectRoot, '...')

Browser Console

• Open browser DevTools (F12)
• Check console for errors
• Use window.transforms to see all transformers
• Use window.steganography to access steganography functions
• Use window.emojiLibrary to access emoji functions

📚 Documentation

• Project README: README.md - Overview and user guide
• Templates: templates/README.md - How to edit tool templates
• Build Process: build/README.md - Build script documentation
• Tool System: docs/TOOL-SYSTEM.md - Tool architecture details
• Code Review: docs/CODE-REVIEW.md - Architecture and code review guidelines

✅ Checklist Before Submitting

• Code follows existing style
• Tests pass (npm test)
• Templates built (npm run build:templates) if template files were edited
• Tested in browser (open index.html)
• No console errors
• Documentation updated (if needed)
• JSDoc comments added (for new functions)

🤝 Questions?

• Check existing code for examples
• Review docs/CODE_REVIEW.md for architecture details
• Look at similar features to understand patterns

Thank you for contributing! 🎉