<h1>Never Wait</h1>
<blockquote>
<p><em>Preface:</em> This post is specifically about Pull Requests for <a href="https://github.com/Automattic/harper">Harper</a>.
Read the contributor guidelines for a project before opening a PR.</p>
</blockquote>
<p>I get it.
Opening a pull request is an intimidating proposition.</p>
<p>It is non-trivial to put your blood, sweat, and (let's be honest) tears into code and put that onto the internet for the world to see.
I remember my first pull-request: it wasn't pretty either.</p>
<p>But I want to highlight a couple reasons why I want potential contributors to open their pull requests as early as possible.</p>
<h2>Drafts Reduce Duplicate Work</h2>
<p>When a contributor to a project is assessing the viability or usefulness of some work they're preparing to do,
most look at existing Pull Requests first.
Even if you're still working on the patch, it's a great idea to open a "draft" PR so no one starts work that could go to waste.</p>
<p>Further, if you have a draft open whose CI is failing, a maintainer may see it and fix whatever the problem may be.
I find myself frequently browsing <a href="https://github.com/Automattic/harper/pulls">Harper's Pull Requests</a> looking for failing builds, since I'm often the best equipped to find the issue.</p>
<h2>It Helps With Debugging</h2>
<p>I try to make myself available to contributors in case they have any questions regarding the architecture of Harper.
I'm also game to help debug their code, partly because I am of the opinion that debugging is a skill which is best learned by example.</p>
<p>But it is hard for me to debug code if I don't have it.
If a draft PR has been opened, I can usually see the problem without even cloning the code, since our CI is so comprehensive.</p>
<h2>Conclusion</h2>
<p>So please don't wait; open that PR.
I am thrilled each time I see a name I don't recognize on a GitHub notification.</p>

Never Wait

<h1>Continuations on Transformation-based Learning</h1>
<img src="/images/clear_creek_steps.webp" alt="Steps near Clear Creek. Taken by me.">
<p>The most common type of machine learning out there takes the form of some kind of neural network. Inspired by how our own brains work, these systems act as function approximations. They are great, but they come with a few key pitfalls.</p>
<p>First and foremost, they start out with very little baked-in understanding of the context they live in. This is fine—usually enough data can be provided to bridge the gap. It does mean, however, that they spend an inordinate amount of time learning the fundamentals of their field. This translates to a larger model size and longer inference time (especially at <a href="https://en.wikipedia.org/wiki/Edge_computing">the edge</a>).</p>
<p>Secondly, most neural networks are initialized with randomness, which results in extremely high entropy. High entropy means that these models cannot be compressed easily (if at all).</p>
<p>This disqualifies neural networks from many aspects of <a href="https://writewithharper.com/">Harper's architecture</a>. Harper tries to be fast and small, so it can be shipped and run wherever our users are. Neural networks (especially in the world of natural language processing) are neither fast nor small.</p>
<p>This is why we've taking an alternative approach to machine learning, as evidenced by last week's post on <a href="https://elijahpotter.dev/articles/transformation-based_learning">transformation-based learning</a>.</p>
<h2>Transformation-Based Learning: A Refresher</h2>
<p>Transformation-based learning is remarkably simple. It boils down to just four steps:</p>
<ul>
<li>Use a simple, stochastic model t label your data. This can be as simple as tagging each token (or other discrete component) with that variant’s most common tag. It doesn’t need to super accurate, just enough to establish a baseline.</li>
<li>Identify the errors between the tags in your canonical data and that which produced by your baseline model.</li>
<li>Using a finite list of human-defined templates, generate candidate rules that transform the output of the baseline model into something else. This is where the term “transformation-based” comes from.</li>
<li>Apply each of the candidate rules to the baseline model’s output. Check if the result is more accurate than before. If so, save the rule for future use.</li>
</ul>
<p>These saved candidates become your model.</p>
<p>If you're interested how this could be applied to POS tagging, I've since updated my original post on the subject to better explain the process. I'd recommend taking a look.</p>
<h2>Nominal Phrase Chunking</h2>
<p>It's often useful, especially when building a grammar checker, to be able to identify the subjects and objects of sentences. Suppose, for example, that we want to insert the missing Oxford comma in a list of fruits: "I like apples, bananas and oranges". In this trivial example, this can be done with POS tagging. If we have more complex subjects, like in the phrase "I like green apples, deliciously pernicious bananas and fresh oranges," POS tagging starts to fall apart. Identifying multi-token subjects is the job of a nominal phrase chunker.</p>
<p>I've been wanting to build a nominal phrase chunker for a while, but haven't had the tools to do so. Now that I have pipeline in place (from last week), it should be relatively straightforward.</p>
<p>For the purposes of this model, we'll be tagging each token with a boolean; it is either a member of a noun phrase, or it is not.</p>
<p>I started by assigning each token to a nominal phrase if a POS tagger marks it as a noun. This is our baseline model. It performs poorly because the resulting nominal phrases do not include determiners or any adjectives.</p>
<p>Similar to our POS tagging model, I used a Universal Dependencies treebank to determine the accuracy of our baseline. After generating candidate rules using the same patch templates as the POS tagging system and running them against the treebank, I have a model with a 90% accuracy.</p>
<p>I feel as though there should be more details to share, but that was pretty much it. I spent a good amount of time optimizing the training code. There's still a lot of work left to do to incorporate it into the rest of Harper. I am also unsatisfied with the model's current accuracy. To get it closer to 100%, I suspect I'll need to do a good amount of data cleaning.</p>

The most common type of machine learning out there takes the form of some kind of neural network. Inspired by how our own brains work, these systems act as function approximations. They are great, but they come with a few key pitfalls.

<p>The most common type of machine learning out there takes the form of some kind of neural network. Inspired by how our own brains work, these systems act as function approximations. They are great, but they come with a few key pitfalls.</p>

More Transformation Based Learning

<h1>Harper is in Cursor and Visual Studio Code</h1>
<p>Harper is a grammar checker for developers. Its roots are in code editors like Neovim, Helix, Zed, and you guessed it—Visual Studio Code. I don't think a lot of my followers know this, so I thought I'd give it a little shout-out here.</p>
<p>Since Cursor and Windsurf are forks of Visual Studio Code, Harper is available for both <a href="https://marketplace.visualstudio.com/items?itemName=elijah-potter.harper">via the Visual Studio Marketplace</a>. Give us a good rating over there if you install the plugin and end up liking it!</p>
<img src="/images/harper_vscode_screenshot.png" alt="A screenshot of the Harper Visual Studio Code extension checking its own source code">
<h2>How Does it Work?</h2>
<p>Harper works similarly to a number of other extensions you may have installed. Like Pylance or ESLint, it runs in the background as <a href="https://microsoft.github.io/language-server-protocol/">a language server</a>. Each time a modification is made to your document, it reads your comments for grammatical mistakes and typos and displays them as errors or warnings (it's configurable).</p>
<h2>Does It Support My Programming Language?</h2>
<p>The Harper language server, thanks to contributions from the community, supports a pretty <a href="https://writewithharper.com/docs/integrations/language-server#Supported-Languages">wide range of programming and markup languages</a>. We've only recently added support for PHP, so if that's your thing, know you're in somewhat uncharted territory. If you find issues, <a href="https://github.com/Automattic/harper/issues">let us know</a>.</p>

Harper Is in Cursor and Visual Studio Code

footguns_of_the_rust_webassembly_target

<h1>Footguns of the Rust WebAssembly Target</h1>
<img src="/images/rail.webp" alt="A trail in Golden, Colorado">
<p>WebAssembly—even after several years of standardization—is still a nascent technology.</p>
<p>I've been working with Rust and WebAssembly for nearly four years now.
This post is intended to be a distillate of that experience, formatted for developers who are interested in publishing WebAssembly code to npm.
Specifically, these are the footguns I've personally encountered while working on <a href="https://writewithharper.com/docs/harperjs/introduction"><code>harper.js</code></a>, a WebAssembly-powered package for grammar checking at the edge.
This page should be valuable if you are even speculating on the possibility of using WebAssembly in your codebase.</p>
<hr>
<h2>1. Exposing Only Synchronous Functions</h2>
<p>The Harper package exposes one interface that captures all of its WebAssembly interactions: the <strong>Linter</strong>. This is an object that handles downloading and compiling the Harper WebAssembly module, as well as invoking functions in it. Every function returns a <code>Promise</code>. There are several good reasons for that:</p>
<ul>
<li>WebAssembly modules larger than 4 kilobytes must be instantiated <strong>asynchronously</strong> to avoid blocking the event loop during download or compilation. This is a technical limitation that cannot be avoided with clever logic.</li>
<li>If most functions are asynchronous, you can centralize computation and caching into a single instance of the WebAssembly module, hiding the complexity of instantiation and making caches easier to build.</li>
<li>If your problem domain can be computationally intense, it might be prudent to offload jobs onto a <strong>web worker</strong>, which is easier if every function of your facade is asynchronous.</li>
<li>It will be easier for both you and your users to expose any important function as asynchronous out of the gate.</li>
</ul>
<h2>2. Assume Rust Can Trivially Do IO</h2>
<p>Whatever you do: avoid assuming that Rust libraries (like <code>reqwest</code> or <code>rand</code>) will be able to perform IO without some work on your end. WebAssembly alone is <strong>not capable of IO</strong>, which means any function in that category will require some amount of JavaScript to work properly.</p>
<p>Rather than leaving that up to the Rust toolchain to figure out, save yourself the headache and <strong>inject the necessary JavaScript functions</strong> directly into the WebAssembly module by passing them through <code>wasm_bindgen</code>.</p>
<hr>
<h2>3. Just Inline the WebAssembly Module</h2>
<p><strong>Obsidian plugins</strong>, for example, must be composed of exactly one JavaScript file, which means everything must be inlined. In the interest of keeping the bundle size small, it's much easier for the package developer (of <code>harper.js</code>) to set up inlining than the plugin developer.</p>
<p>On the other side of the spectrum, <strong>Chrome's Manifest V3</strong> disallows WebAssembly from being loaded inline.</p>
<p>If you plan for your package to be consumed by a variety of applications, know that it will also be consumed by a variety of <strong>bundlers</strong>. Both bundlers and applications are pretty inconsistent with their inlining and tree-shaking behavior. To avoid problems, you should provide <strong>two versions</strong> of your package:</p>
<ul>
<li>One where your WebAssembly module is already inlined.</li>
<li>One where it isn't.</li>
</ul>
<h1>Wrapping it Up</h1>
<p>Harper’s problem domain is not your problem domain.
We have to integrate with a variety of unique applications, which means we must keep our system flexible.
That may not be the case for you, which may mean these footguns do not apply.
If you have any questions about any other problems the Harper project might have faced, let me know.</p>

Four years in Rust + WebAssembly taught me these 3 lethal footguns—don’t learn them the hard way.

<p>Four years in Rust + WebAssembly taught me these 3 lethal footguns—don’t learn them the hard way.</p>

Elijah Potter

Footguns of the Rust WebAssembly Target

1. Exposing Only Synchronous Functions

2. Assume Rust Can Trivially Do IO

3. Just Inline the WebAssembly Module

Wrapping it Up

Other Stuff

Never Wait

More Transformation Based Learning

Harper Is in Cursor and Visual Studio Code