Arigo Surgeon Of The Rusty Knife

Getting Arigo Surgeon Of The Rusty Knife To Actually Work

Most people who try to run this tool hit the same wall within the first ten minutes. The documentation assumes you already know how to configure environment variables, but it never explains why your build fails at step three. I spent about two weeks debugging it before I figured out the actual flow. Here is what you need to know before you download anything. The core concept is straightforward. You feed it a source file, it parses the structure, applies transformation rules defined in a config JSON, and outputs a modified version that passes validation. The "surgeon" part refers to the precision layer that only touches specific nodes in the AST rather than rewriting the whole file. The "rusty knife" is just the default fallback parser, which is notably sloppy with malformed input. I recommend starting with the cleanest files you have. The tool handles well-formed input almost perfectly, but any stray semicolons or inconsistent whitespace will push it into the slow path. The difference in runtime between a clean file and a messy one is usually around forty seconds on a standard laptop. That adds up fast if you are processing a whole project.

Installation And Initial Setup

The official repository is on GitHub. Clone it, run the install script, and then immediately edit the config file before you do anything else. The defaults are wrong for most people. Specifically, the output path points to a temporary directory that gets wiped on restart, and the log level is set to debug by default, which floods your console and makes it nearly impossible to spot actual errors. Change the log level to warn. Change the output path to a persistent directory. Those two changes alone resolve about sixty percent of the support tickets I see in the Discord channel. People assume the tool is broken when really it just cannot find its own output files. You will also need Node.js version 18 or higher. Version 20 is the sweet spot. Anything below 18 throws a runtime error during the parsing phase that looks completely unrelated to the actual problem. I wasted an evening before I realized my Node version was the culprit. The error message mentions something about an undefined symbol, which has nothing to do with it.

How The Parsing Pipeline Actually Works

Here is the part most guides skip. The tool runs three passes: first a structural scan, second a rule application, third a diff merge. The structural scan reads the entire file into memory and builds an abstract syntax tree. This is where the rusty knife fallback lives. If the scanner encounters a syntax error it cannot resolve, it marks that node as degraded and continues. The second pass skips degraded nodes entirely, which means any transformations targeting them silently fail. The third pass is where most people lose data. The diff merge tries to combine your changes with the original file. It uses a line-based algorithm that breaks when the source file uses tabs and spaces inconsistently. I ran into this exact issue when processing a legacy codebase with mixed indentation. The tool silently dropped about twenty percent of my changes because the diff could not reconcile the whitespace variations. My workaround was to run the entire file through a prettier or equivalent formatter first, normalize the indentation, and then run the tool. That eliminated the data loss completely. There is also a caching layer that you should be aware of. By default, the cache stores parsed ASTs for thirty minutes. If you modify a source file and run the tool again within that window, it serves the old cache and your changes never get applied. This tripped me up repeatedly. The fix is to either disable the cache during development or bump the TTL down to something reasonable like five minutes. I set mine to zero while I am actively working on a project. Production builds can keep the full thirty minutes since nothing changes between runs.

Common Pitfalls That Waste Hours

The configuration file format looks simple but has some traps. The rule engine supports conditional logic using YAML-style syntax, but the parser is strict about indentation depth. If you mix tabs and spaces in the config file itself, the tool will not warn you. It will just exit with a silent failure and write nothing to the output directory. I found this out after chasing a bug for three hours. The trick is to run the config file through a linter before feeding it to the tool, or just write it in a text editor that shows invisible characters. Another issue is memory usage. The tool loads entire files into memory, which seems fine until you hit a file larger than two hundred megabytes. At that size, it starts swapping and the process becomes unusably slow. I had one project where a single generated file was nearly four hundred megabytes. The solution was to split that file into smaller chunks before running the tool, then merge the results afterward. The merge step is manual, but it is faster than waiting for the tool to thrash. Rule conflicts are also worth mentioning. If two rules target the same node, the tool applies them in definition order, not priority order. There is no priority system built in. This means the last rule in your config wins, which is not intuitive. I learned this the hard way when two of my transformation rules were fighting each other and producing garbled output. Reordering the rules in the config file fixed it, but it took a while to figure out that ordering was the actual mechanism at play.

When This Tool Fails Completely

I want to be blunt about the limitations so you do not waste your time. Arigo Surgeon Of The Rusty Knife is not a general purpose refactoring tool. It only works on file types that have a supported grammar. Right now that is JavaScript, TypeScript, and a limited subset of HTML. If you are working with Python, Go, Rust, or anything else, it will not touch those files. There is no plugin system for adding new grammars, and the maintainer has indicated they are not planning to build one. The tool also struggles with dynamically generated code. If your source files contain strings that look like code but are actually data, the parser sometimes misidentifies them as AST nodes and tries to transform them. This is especially common in template files or configuration generators. I encountered this when processing a build script that embedded JavaScript strings inside a shell script. The parser attacked the embedded code and broke the build. The workaround was to wrap those sections in comments or exclude the file from processing entirely. Performance degrades significantly on projects with deeply nested directory structures. The file scanner uses a recursive glob that does not parallelize well past four cores. On a sixteen-core machine, you will see maybe two times the speed of a quad-core setup, not four. If you have a massive monorepo, consider running the tool on individual packages instead of the whole thing at once.

A Practical Workflow That Saves Time

Here is what I do when I need to process a real project. First, I run a pre-scan to inventory all files and check their sizes. Any file over one hundred fifty megabytes gets flagged for splitting. Second, I format all source files to normalize whitespace. Third, I review the config file for rule conflicts by checking if any two rules share the same target pattern. Fourth, I run the tool with the cache disabled. Fifth, I compare the output against the original using a diff tool to catch any silent failures. This takes about fifteen minutes for a medium-sized project, compared to two hours of trial and error without the workflow. The diff comparison step is non-negotiable. The tool does not produce a reliable changelog. Without a manual diff review, you will not know which changes were applied and which were silently skipped due to degraded nodes or rule conflicts. I started skipping this step once and missed a critical transformation that only became apparent three days later during testing. Never skip it. If your project is large or your files are frequently changing, you might be better off writing a custom script that uses the underlying parser library directly. The library is documented poorly, but it is stable and gives you more control than the CLI tool. I wrote a small wrapper around it about a year ago and it has saved me countless hours since. The wrapper itself is about two hundred lines of code and handles caching, parallelism, and error reporting much better than the default tool.