npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

automutate

v0.9.0

Published

Applies waves of mutations provided by other tools, such as linters.

Downloads

4,671

Readme

automutate

Build Status npm

Applies waves of mutations provided by other tools, such as linters or codemods.

There are many linters out there and most include ways to --fix rule failures automatically. This is great but hard to do for a couple of reasons:

  • Overlapping mutations - The possibility of mutations applying to overlapping sets of characters requires logic to handle applying one, then re-running linting, and so on.
  • Code bloat verses duplication - Most linters either provide hooks to apply fixes themselves (which can result in code bloat) or have an external project (which duplicates logic for finding rules).

automutate proposes that linters only propose how to fix rules, via a standardized JSON format.

Having a standardized source-agnostic project to apply mutations brings a couple of benefits:

  • Reduced overhead - Projects no longer need to do this work themselves.
  • Standardized base - Ramp-up time to switch between projects using automutate is reduced with common code.

In general, detecting rule failures is a separate concern from fixing them. Linters need to run quickly over a read-only set of files, often during built processes, while fixers typically run slowly and modify files on user request.

How it works

The main automutate algorithm is started in autoMutator.ts and mostly applied in mutationsApplier.ts:

while mutationsWave = getMutationsWave():
    for (file, fileMutations) of groupMutationsByFile(mutationsWave):
        for mutation of getNonOverlappingMutationsInReverse(fileMutations):
            applyMutation(file, mutation)
  1. getMutationsWave calls to an external tool, such as a linter, to receive a wave of suggested mutations.
  2. groupMutationsByFile organizes the suggested mutations by file.
  3. getNonOverlappingMutationsInReverse removes overlapping mutations that would conflict with each other, and sorts the remainder in reverse order so that later mutations don't interfere with character positions of earlier mutations.
  4. applyMutation modifies files on disk using the remaining mutations.

Mutations

A single mutation contains a unique type identifier, a range of character position(s) to apply to, and optionally other logic.

The following basic text manipulations are provided out of the box:

  • multiple - Container for multiple mutations. This indicates to automutate that these must be applied all at once or not at all, which guarantees consistency with the built-in mutation overlap detection.
  • text-delete - Deletes a range of characters.
  • text-insert - Inserts a string at a point.
  • text-replace - Replaces characters matching a string or regular expression within a range.
  • text-swap - Swaps a range of characters with a new string.

For example:

{
  "ugly-file.txt": [
    {
      "range": {
        "begin": 7,
        "end": 14
      },
      "type": "text-delete"
    },
    {
      "insertion": "inconceivable!",
      "range": {
        "begin": 21
      },
      "type": "text-insert"
    }
  ]
}

Linter-specific utilities may define their own mutations. For example, a language's linter may define a node-rename mutation rather than use a multiple mutation containing text-swap mutations.

See Mutators for more on custom mutators.

Project Onboarding

See Onboarding.

automutate requires NodeJS >= 14.