jcjolley / muddler

Transpile, test, and minify your hackmud scripts.

Muddler

Transpile, Unit Test, and Minify your hackmud scripts (TypeScript or JavaScript) with ease. Works with hackmud version 1.4.10

Changelog - most recent entry

1.5.0 - 2017-10-25

Added

• TypeScript testing support! You can now write .test.ts files instead of test.js files. #2
• Added '-t' option to specify a testing directory. #1
• Added '-R' option to specify a custom mocha reporter

Fixed

• Temp files are now removed like they should be.
• Temp files are now created in the same directory as the source script, to make unit testing easier. #3
• -V option returns the correct version now. #4
• Mocha was caching testing results and returning false positives. We now run Mocha in a child process, and errors are reported as expected.

Changed

• We all needed a little more Nyan in our lives.
• Debounced testing while watching to 2000ms per file so transpiled ts files don't triggler double muddling.
• Modifying a test while watching re-runs the target file. #5

Full changelog can be found here

Prerequisites

This project requires Java 7+ and Google's Closure Compiler on your PATH to function.

Installation

npm install muddler -g

Usage

    -V, --version                output the version number
    -o, --out-file <filename>    the name of the output file
    -w, --watch                  watch the current directory for changes
    -W, --watch-dir <directory>  watch the provided directory for changes
    -d, --out-dir <directory>    what directory to save files to
    -c, --config <filename>      the location of your config file (defaults to muddle.json in the current directory)
    -v, --verbose                increase program verbosity. Good for debugging, or checking for sneaky hacks.
    -q, --quiet                  disable all program output
    -s, --skip-tests             skip tests if they exist
    -t, --test-dir <directory>   the directory to search for tests.
    -R, --reporter <reporter>    Pass this in if you want to use a different mocha test reporter
    -h, --help                   output usage information

Examples:

muddle -W C:\dev\hackmud -d C:\User\1337H4x0r\AppData\Roaming\hackmud\1337H4x0r\scripts

This will watch C:\dev\hackmud for changes to *.ts and *.js files, run any *.test.js files, and then write *_mud.js files to your hackmud folder. I think this is the most useful option.

muddle

This will watch the current working directory for changes to *.ts and *.js files, run any *.test and write *_mud.js files to the current directory.

muddle <filename>

This will test <filename>.test.js, and then write a minified <filename>_mud.js to the current directory.

Testing

[New Feature] If you don't want to clutter up your scripts folder with tests, you can now create a test directory to store your tests in. You still need to follow the <filename>.test.(t|j)s naming convention. Don't like the 'test' dir? Add -t and specify your own test folder name

If you wish to unit test your files, create a test file with the same name as your script, but with an extension of .test.js. I'll hopefully add support for writing tests in TypeScript someday, but today is not that day. Done. Write unit tests as you normally would for Mocha, with the following exceptions:

• anywhere you would use '#', use '$' instead.
• at the top of your file add const window = {}
• to call the main function in your script, call muddled(context, args)
• remember that you're going to have to mock context, args, $fs.scripts.lib(), etc..

See sample.test.ts for simple example of testing

Config file

Create a muddle.json file in your development directory (!!not AppData/hackmud/user/scripts !!) muddle your life. The available settings are the options for the program, but camelCased instead of kebab-cased. e.g.

{
  "watchDir": "C:\dev\hackmud" 
  "outDir": "C:\User\1337H4x0r\AppData\Roaming\hackmud\1337H4x0r\scripts"
}

Caveats

• The Clojure Compiler (v20170910) is still working to support all of es6. One thing they do NOT support yet is array destructuring. You'll have to manually edit your script to rename your variables to non-clashing variables if you use destructuring.
• If you wish to preserve your object property names, provide them as strings.
• I haven't tested this with scripts that use the DB. If you run into problems, please make an issue on the github repo and I'll fix it asap.
• For now, if you want to do testing, you have to save the test files in the same folder as your .ts/.js scripts.

Credits

This project was inspired by Gerow's Mudify. (@gerow on hackmud). The testing portion of the project was blatantly stolen from Jer0ge's hackmud-unit-poc.

I'm typically playing as @s1mply_me on hackmud go by Jolley in the Discord channel Feel free to hit me up (or even send some sweet sweet GC my way ;) ).

What's next?

So, you've got a muddler, but no scripts to muddle? Get started scripting with this excellent guide by @ciastex_ and @i20k.

muddler's Issues

modifying a test file should trigger the target file to re-run

Special script commands result in a parse error

When I try to use stuff like #D, #FMCL or #G in my script, muddler throws out:

Muddling C:\Users\uname\AppData\Roaming\hackmud\gname\scripts\crack.js

==========================================
C:/Users/uname/AppData/Roaming/hackmud/gname/scripts/crack.temp.js:14: ERROR - Parse error. '}' expected
            #D("EZ_21")
            ^

1 error(s), 0 warning(s)
==========================================

This is what the code looks like:

if(l.includes('EZ_21')) {
    #D("EZ_21")
    for(var i=0;i<EZ.length;++i) {
        g["ez_21"]=EZ[i]
        c()
        if(!f.includes('LOCK_ERROR')){
            #D("Cracked")
            l_num = l_num + 1  
            break
        }
    }
}

(Yes, it's a lock cracker)

Add a cli option to specify a test folder directory

This is probably over kill, but I can see this being useful.

Encoding issue when muddling

There seems to be an encoding issue with special characters. See below for the original and muddled versions.

var corruptRegex = /`\w[¡¢£¤¥¦§¨©ª]`/g

l=/`\w[\u00a1\u00a2\u00a3\u00a4\u00a5\u00a6\u00a7\u00a8\u00a9\u00aa]`/g

I'm assuming it's just not handling utf-8 encoding/decoding properly?

---

EDIT: I guess it's more of a problem specific to hackmud, now that I think about it. The output from hackmud is as follows:

{retval:"PARSE ERROR my.script (line 0 char 261): cannot use \\u00XX or \\u{00XX} unicode identifiers in ascii range in scripts. Please use hex escape (\\xXX)",success:false}

muddle -v outputs the wrong version number

How to avoid muddling scriptors?

I couldn't find anything regarding this (unless I didn't look hard enough), but is there a way to script muddling scriptors and calls to them?

Below is an example of what currently happens.

var d = #fs.dtr.lib()
var m = d.pp(args)

becomes

var g=#fs.h.lib()
var j=g.l(b)

Add support for .test.ts files

I should add support for testing using TypeScript.

<filename>.temp.js is written in the output folder, rather than the location of the script

When testing, it's reasonable to assume that the temp file will be written beside the script you're transpiling. Currently, it's being written next to the output file.

--skip-tests breaks muddling

It doesn't matter whether tests exist, but when using --skip-tests muddling simply terminates after it has generated the .temp.js file.

> muddle harvest.js --skip-tests --out-file harvest_mud.js
Muddling harvest.js
> 

> muddle harvest.js --out-file harvest_mud.js             
Muddling harvest.js
Success - harvest_mud_mud.js
> 

--test-dir doesn't appear to be working

Full command/parameters I'm using right now:

muddle --watch-dir ~/.config/hackmud/scripts_dev --test-dir ~/.config/hackmud/scripts_dev/tests --out-dir ~/.config/hackmud/user/scripts

This seems to script tests (named script.test.js) in scripts_dev/tests, but works fine if I move the tests to the same directory where the scripts themselves are, so it's almost like it's not taking --test-dir in to account at all?

If I'm doing something wrong here, let me know, since I'm still struggling trying to get even a simple test to run. :)

Probably not related, but I can't seem to get any further than this when testing:

function (context, args) {
         ^
SyntaxError: Unexpected token (

EDIT: Not sure if it matters, but I don't use TypeScript at all, just JavaScript.

Issues running on macOS due to line endings

Running muddler produces this error:

env: node\r: No such file or directory

This is due to /usr/local/bin/muddle (or muddle.js) having line endings in the DOS format. A similar issue can be seen here.

The fix is to simply convert the line endings from DOS to unix, at which point it should be compatible across all platforms.

A long term solution to this might be a simple as adding a .gitattributes file that does the formatting on it's own, as seen here.