Where to find me

https://twitter.com/real_ate
https://twitch.tv/real_ate
real_ate#4200
https://github.com/mansona 🙈

Rename

A Process

Today I’m talking to you about a process that you can adopt to improve your codebase.

That may sound very broad and vague but that is actually true. The process isn’t tied to any single technology, it isn’t even an Ember specific thing and you're already using parts of it. There are just 2 things that I hope you will take away from this talk that might fundamentally change your approach to improving any of your codebases in the future. At least that’s my hope! And if I didn’t quite convince you or if I didn’t quite explain it well enough please do get in touch and let me know. I’m am personally on a constant journey to slowly improve how I communicate this process over time (and yes, that is a bit of foreshadowing for the content of the talk 😉). So let’s start our journey together with a bit of a story.

You, a Developer

Dev

JavaScript

htmlcss

markdown

Code Reviews

A Plan

The Rules Document

Step 2

But what about all the cases that slipped through the cracks before we enforced our RULES document!? Don’t worry, our developer has thought of step two and they have put together a plan to fix the existing issues in the codebase. They don’t have the time to stop everything and write a proper alt description of every broken image in the massive codebase right now, but they have put together a list of all the images that still need alt descriptions and they have shared this list with the team. Now they’re all going to slowly work together to fix the existing images over time alongside their existing work, and not only that! to help motivate the team our Developer has even put together a little graph to show the progress being made as each image is fixed. Never underestimate the power of a graph!!

The Masked Lint

Now I would suspect that everyone here at EmberConf will have picked up my very thin alegory but let’s just spell it out in case anybody missed it. Our Rules document is actually our linting rules. If you have ever worked on an Ember app you will have experience with using linting because a newly generated Ember app has a whole plethora of helpful rules enabled by default and automatically baked into the default testing process. What I mean by that is that if you generate a new Ember app and run npm test then you will automatically run all the pre-configured linting rules. And do you know what? The rule in my example, alt text on images, is one of the lint rules that is automatically enabled for you 🎉 Thanks to Mel Sumner and the amazing work by the Accessibility team there are a whole host of Accessibility rules enabled by default.

Nothing new

So far I haven’t told you anything new. I've just set the scene and hopefully made sure everyone listening has a good foundational understanding of the purpose of a lint rule. But there are two examples in my little story that I suspect a lot of people listening don’t actually have embedded in their daily routines yet, and these are the two things that I said I wanted people to take away with them.

Firstly, I said our Developer “wrote a new rule in their rules document”. Sure our example happens to be of a “rule” that I already exists and comes with every new Ember app. But what if I gave a different example? What if I gave a real example that I recently worked on with a client that I can not only guarantee that there isn’t a pre-written lint rule out there to cover this example, I will also say with some confidence that this rule won’t be that much use to anyone else.

Real world example


<Ui::Button />


<Ui::Button class=“flex” />

Banned

What is a lint rule anyway?

ast tobias

https://github.com/simplabs/ast-workshop

Lint rules in 30 seconds

So I said earlier that you likely have lints baked into your testing flow, when you submit a pull request you will likely have “broken the build” if your lints have failed. I think it’s an interesting thing that we’ve moved to be so rigid with linting in our daily development habits, it’s useful in some regard but it’s also a bit problematic. Linting is not a functional thing. You’re not testing functionality when you write a lint rule, you’re asking a program to read your code and tell you if it things it looks right or if it sees any mistakes. This is important because firstly it’s just a little computer program and it can get things wrong, and secondly linting rules read your static code, it doesn’t try to run anything so it can’t actually tell you when something is actually broken, it can just make suggestions when it things something doesn’t quite look right.

Writing a lint rule

Have you written a test

Writing a lint rule

Have you written a lint rule

AST Explorer

This is an incredibly powerful tool that supports many languages so just make sure you are set to Handlebars templates and glimmer for now.

You can see i've added our example from before <Ui::Button class=“flex” /> to the left hand side of the screen and this object you see on the right is the AST representation of that template. I’ll not go into too much detail there about what an AST really is (again, there's a workshop for that!) but you’ll see why it’s useful now in a second. One of the best tricks of AST explorer is that you can just click the bit that you care about on the left and it highlights the AST representation of that bit on the right! so let’s click the class. Now there is a lot to see here but to skip ahead to the end… you can see that we’re in an ElementNode, that has attributes, that has an attribute named class with a value of flex. And that’s what we need to find with our lint rule.

Custom Rule

ember template lint

Custom Rule

import { Rule } from 'ember-template-lint';

export default class NoFlex extends Rule {
  visitor() {
    return {
      ElementNode(node) {
      }
    };
  }
};

Custom Rule

import { Rule } from 'ember-template-lint';

export default class NoFlex extends Rule {
  visitor() {
    return {
      ElementNode(node) {
        if (node.tag === 'Ui::Button') {

        }
      }
    };
  }
};

Custom Rule

import { Rule } from 'ember-template-lint';

export default class NoFlex extends Rule {
  visitor() {
    return {
      ElementNode(node) {
        if (node.tag === 'Ui::Button') {
          let classAttribute = node.attributes.find(
            (attr) => attr.name === 'class'
          );
        }
      }
    };
  }
};

Custom Rule

import { Rule } from 'ember-template-lint';

export default class NoFlex extends Rule {
  visitor() {
    return {
      ElementNode(node) {
        if (node.tag === 'Ui::Button') {
          let classAttribute = node.attributes.find(
            (attr) => attr.name === 'class'
          );

          if( classAttribute && classAttribute.value.chars.includes('flex')) {
            // complain!!!
          }
        }
      }
    };
  }
};

Custom Rule

import { Rule } from 'ember-template-lint';

export default class NoFlex extends Rule {
  visitor() {
    return {
      ElementNode(node) {
        if (node.tag === 'Ui::Button') {
          let classAttribute = node.attributes.find(
            (attr) => attr.name === 'class'
          );

          if( classAttribute && classAttribute.value.chars.includes('flex')) {
            this.log({
              message: `You can't provide the 'flex' class to a Ui::Button.`,
              node: node,
            })
          }
        }
      }
    };
  }
};

and we need to make sure to pass in the node along side the message. This tells the linting system where to draw the red squiggly line in our editors and what the message should be.

And that’s it! I know this has been a bit of a whirlwind example, and I’m telling you now that it’s a bit of a simplification because it’s leaving out a few edge cases but hopefully at least one of you watching is saying to themselves “wow that’s more approachable than I expected”. As I said earlier, this isn’t actually a master class on how to write lint rules, it’s more of a message of inspiration to encourage more people to try to write their own rules! If this talk has inspired you to try write a lint rule please let me know on twitter. I always like to hear when people try things that I have talked about.

Part 2 Lint to the Future

lttf

All the errors

Errors

All the warnings

warnings

File based ignore


{{!-- template-lint-disable first-rule second-rule --}}

Install Lint to the Future


npm install lint-to-the-future lint-to-the-future-ember-template

Back to the Errors

Errors

Ignore those errors


npx lint-to-the-future ignore

The Dashboard

dashboard

List those ignores


npx lint-to-the-future list --stdout

List those ignores

list output

Output


npx lint-to-the-future output -o lttf

Output

Yesterday's News


npx lint-to-the-future output -o lttf
  --previous-results https://ember-learn.github.io/ember-styleguide/data.json

take a peek if you're interested
https://ember-learn.github.io/ember-styleguide/data.json

GitHub action

name: Lint to the Future
on:
  push:
    branches:
      - master

jobs:
  deploy:
    uses: mansona/lint-to-the-future-dashboard-action/.github/workflows/dashboard.yml@main

Dashboard demo

Here is a little demo I recorded just moving through the dashboard and showing it off. Firstly you will notice the awesome styling of this dark mode. Major props to Anne-Greeth for this. And a little birdy tells me that she will be talking a little bit about designing for dark-mode so watch this space.

You’ll see that we have a graph for each of the rules that are failing. But you can see that we have a contiguous graph from our first data point until “today”, this is actually filling in any gaps that you might have if you haven’t actually built it every day. You can also switch to week view and month view. You’ll see that everything on this graph started out in month view, it does this automatically once something crosses a certain threshold (and Anne-Greeth also contributed the month view so thanks again for that).

Other than the graphs you can click this link here to see the list of all the files that still need to be improved. This is just here in case you wanted to cross reference or something, but really this app is all about the graphs!!

Thank you all!

https://twitter.com/real_ate
https://twitch.tv/real_ate
https://github.com/mansona
So that’s it for my talk. I hope I have given you all nice foundational perspective on what lints are, how useful they can be and how unlocking the skill of writing your own lint rules can be an incredibly powerful tool to gradually improve your codebase in a way that you personally design. And don’t forget to try out lint-to-the-future and setup your dashboard, never underestimate the power of a nice graph.

Lint Your Code Into the Future