sketch-hq / sketch-assistant-utils

Utility functions for running Sketch Assistants

This package has moved to https://github.com/sketch-hq/sketch-assistants.

sketch-assistant-utils's Issues

Evolve core rule titles

Step 1

The current design groups violations by rule title, and requires more descriptive rule titles that interpolate config values into the copy. E.g.

The rule title here is in the format,

Minimum height should be {minimumHeight}px

Where the minimumHeight value is presumably comes from the current Assistant's config object.

Currently the Assistant types and utils don't support this.

Proposal here is to update the RuleDefinition type so that it's title can either be a string (as now), or optionally a function that returns a string and takes the current Assistant config as an argument.

title: string | (ruleConfig: RuleConfig) => string

This will allow rule definitions to flexibly return strings based on their own config values. Additionally if the rule definition uses some i18n system this can be used to generate the string too.

Rule title values defined as functions would need to be invoked before returning to Sketch, or displayed elsewhere.

Step 2

Run through the current core rule titles and re-write them to be more in the style indicated by the designs, e.g. Minimum height should be {minimumHeight}px etc.

Future steps...

A tone-of-voice review, and after that internationalisation.

Full rule option validation

Add option validation logic in rules, that throws an error if an option is in the wrong format. We should be able to do this automatically using the option schema when a rule requests it's options.

Augment nodes with a layer name path string

While processing a Sketch file in sketch-lint-core we augment each object with a JSON Pointer. It will also prove useful to augment it with a layer name path too, e.g. /Page 1/Artboard Foo/Rectangle.

Rules may frequently wanting to adjust logic based on the hierarchy of layer names they find themselves in. We'll also need this feature when we come to ignoring violations based on layer names.

Revisit config level ignore options

Revisit config level ignore options based on this discussion #24 (comment)

Probably this means removing support for them at this stage. Ignoring things via the Sketch UI should be the focus initially.

Extract ruleset into its own package

We'll introduce a convention that all lint ruleset packages are named with a prefix sketch-lint-ruleset-, so will name the new package sketch-lint-ruleset-core.

Swap to external types package

• Move types to https://github.com/sketch-hq/sketch-assistant-types
• Use new package in this repo

This is so Assistants don't have to add this utils repo as a dependency, and run the risk of swelling their bundle size, when they only need the types.

Handle Assistants packages exported as transpiled ES Modules

When TypeScript or Babel transpiles a ESModule to CommonJS it uses a technique called "ES Module interoperability" to make the module CommonJS compatible.

So this ES Module syntax,

const foo = {}

export default foo

Ends up looking like this CommonJS syntax,

const foo = {}

module.exports = {
  __esModule: true,
  default: foo
}

This change ensures that when we are working with assistant packages (specifically initializing them before a lint run) we handle the case where some of them might have been transpiled from ES Module syntax to CommonJS (indeed our official Assistants will mostly look like this, since we generally want to use ES Modules where possible).

Add iterate parents util

Give rule functions a utility for iterate back through the parents of any given node. This will allow rules to easily branch lint logic based on where nodes find themselves in the tree.

testRule should throw an error if the rule id is not found

Refactor core utils for assistants

• Refactor for assistant architectural changes
• Ensure assistants can be initialized lazily
• Throw an error if reserved names are used for rule options
• Assistant extension mechanism

Ensure ignoreName path patterns begin with a forward slash

Name paths to match will now always start with a slash. This doesn't change anything when matching a portion of the name path, but will be useful if users want to match from the name path root.

Also as part of this I'm renaming the option to the more explicit/descriptive ignoreNamePathPatterns.

Example,

{
  "borders-no-disabled": {
    "active": true,
    "ignoreNamePathPatterns": [
      "/Page 2/Rectangle"
    ]
  }
}

Config level ignores

Add optional ignoreClasses and ignoreNames rule config options.

ignoreClasses

This option allows config authors to suppress violations from rules using an array of file format _class values.

E.g. with the rule config below violations from pages are filtered out of the final result.

{
  "groups-max-layers": {
    "active": true,
    "maxLayers": 10,
    "ignoreClasses": ["page"]
  }
}

ignoreNames

This option allows config authors to supply an array of regex patterns that when matched with a node's "name path" would suppress violations for that rule.

The "name path" for any given node in the file data is defined as a / separated string comprised of all the name values leading up to and including the node, from the document root. If a node's name already contains / characters, as is a blessed convention in Sketch, then those are just concatenated into the final path.

Examples name paths:

/Page 1/Rectangle
/Symbols/UI/Buttons/Round
/Symbols/UI/Inputs/Password
/Symbols/UI/Media/Controls

E.g. The rule config below would suppress violations for any symbols in the UI/Inputs group

{
  "groups-max-layers": {
    "active": true,
    "maxLayers": 10,
    "ignoreNames": ["UI\/Inputs"]
  }
}

Start to add some documentation

Begin some documentation for sketch-lint-core APIs and functionality. Specifically rule functions and their utilities.