@hyperfrontend/linter/helpershelpers
What a rule asks of a file beyond the tree it is handed: the tokens and comments around a node, scopes and variables, the properties of a JSON document, line and column positions, globs, a fix merged from several edits, and the parse of another file. The packaged rules use the same functions.
Usage
import { defineRule } from '@hyperfrontend/linter'
import { findVariable, scopeAnalysisOf, scopeOf } from '@hyperfrontend/linter/helpers'
export default defineRule({
id: 'local/no-shadowed-name',
language: 'code',
fixable: false,
create: (context) => ({
Identifier(node) {
if (node.name !== 'name') return
const scope = scopeOf(scopeAnalysisOf(context), node)
if (findVariable(scope, 'name') === null) return
const message = 'Rename the local "name".'
context.report({ start: node.start, end: node.end, message })
},
}),
})What is here
| Area | Functions |
|---|---|
| Tokens | tokenBefore, tokenAfter, tokensBetween, tokenText, commentsBetween, isParenthesised |
| Tree | childrenOf, parseCode |
| Scopes | scopeAnalysisOf, scopeOf, findVariable, referenceOf, isGlobalReference |
| JSON | rootObject, propertyOf, isString, stringsUnder, wholeDocument, indentationAt |
| Positions | positionAt, lineText |
| Globs | compileGlob, matchesAny |
| Fixes | mergeEdits |
Scope analysis is computed once per file and shared by every rule that asks for it, so calling scopeAnalysisOf from several listeners costs one analysis.
API Reference§
ƒ Functions
The children of a node, in source order.
Returns
Node[The child nodes
Example
List an if statement's children
const { tree } = parseCode('if (ready) start()', '.ts')
childrenOf(tree.body[0]).map((child) => child.kind)
// => ['Identifier', 'ExpressionStatement'] (the null alternate is skipped)The comments starting at or after one offset and ending at or before another.
Parameters
Returns
SourceComment[The comments, in source order
Example
Find the comments inside a range
// file.text: 'const total = price * 2 // doubled'
commentsBetween(file, 0, file.text.length)
// => [{ start: 24, end: 34, text: ' doubled', ... }]Compiles a pattern.
Parameters
| Name | Type | Description |
|---|---|---|
§pattern | string | The text as a configuration wrote it |
Returns
GlobThe same text with a matcher beside it
Example
Match alternatives, everything below, or a whole directory
const entries = compileGlob('src/index.{ts,tsx}')
entries.test('src/index.tsx') // => true
entries.test('src/index.js') // => false
compileGlob('src/**').test('src/ui/button.tsx') // => true
const dist = compileGlob('dist/')
dist.test('dist/index.js') // => true
dist.test('distance.ts') // => falseThe variable a name resolves to from a scope, looking outward.
Returns
VariableThe variable, or null when no scope in reach declares it
Example
Resolve a name outward from a function's scope
const count = findVariable(scopeOf(analysis, step), 'count')
count.scope.kind // => 'module'
count.references.map((reference) => reference.direction)
// => ['write', 'read-write']
findVariable(scopeOf(analysis, step), 'missing') // => nullThe whitespace that precedes a node on its line.
Returns
stringThe spaces and tabs between the line start and the node
Example
Match a property's indentation in a fix
const text = '{\n "files": ["dist"]\n}'
indentationAt(text, 4) // => ' 'Whether an identifier refers to a global: a name the language or the configuration declares, which no declaration of the program shadows, or a name nothing declares at all.
Parameters
| Name | Type | Description |
|---|---|---|
§analysis | ScopeAnalysis | The program's scope analysis |
§identifier | Node | The identifier tested |
Returns
booleanWhether the reference resolves to no declaration of the program
Example
Tell the language's undefined from a parameter named undefined
// program: limit + undefined
// function read(undefined) { return undefined }
isGlobalReference(analysis, undefinedInSum) // => true
isGlobalReference(analysis, undefinedInRead) // => false (the parameter)Whether a node sits directly between an opening and a closing parenthesis.
Parameters
Returns
booleanWhether the tokens around it are parentheses
Example
Tell a wrapped operand from its expression
// file.text: 'const total = (price) * 2'
isParenthesised(program, file, price) // => true
isParenthesised(program, file, init) // => false (the whole BinaryExpression)Whether a node is a string literal.
Returns
unknownTrue for a string
Example
Narrow a property value to a string
// { "name": "@acme/ui", "private": true }
isString(propertyOf(manifest, 'name').value) // => true
isString(propertyOf(manifest, 'private').value) // => falseThe text of a line.
Parameters
Returns
stringThat line's characters without the break that ends it
Example
Read a line without its break
const map = lineMap('first\r\nsecond\n')
lineText(map, 1) // => 'first'
lineText(map, 3) // => '' (the empty line after the last break)Whether a path matches any of the patterns.
Parameters
Returns
booleanTrue when one matches
Example
Check a path against ignore patterns
const ignores = [compileGlob('dist/'), compileGlob('*.config.ts')]
matchesAny(ignores, 'jest.config.ts') // => true
matchesAny(ignores, 'src/app.ts') // => falseFolds edits that do not overlap into one replacement.
Parameters
Returns
FixOne replacement covering them all
Example
Fold a keyword change and an annotation removal into one fix
const text = 'let total: any = 0'
mergeEdits(text, [{ start: 9, end: 14, text: '' }, { start: 0, end: 3, text: 'const' }])
// => { start: 0, end: 14, text: 'const total' }§functionparseCode(
parseCode(
Parses a code file.
Parameters
| Name | Type | Description |
|---|---|---|
§text | string | The source text |
§extension | string | The file's extension with its dot |
§sourceType | "module" | "script" | "commonjs" | Whether the text is a module, a script or a CommonJS module; a script's strings may hold legacy escapes(default: 'module') |
§declaration | boolean | Whether the text is a declaration file, where declarations need no initialiser or body(default: false) |
Returns
ParsedCodeThe tree, comments and tokens, or the error
Example
Parse a file, or read why it did not parse
const parsed = parseCode('const total = price * 2 // doubled', '.ts')
parsed.tree.kind // => 'Program'
parsed.comments[0].text // => ' doubled'
parseCode('const = 1', '.ts').error
// => { message: 'Identifier expected.', offset: 6 }The line and column of an offset.
Parameters
Returns
PositionThe 1-based position
Example
Turn an offset into a 1-based position
const map = lineMap('const a = 1\nconst b = 2')
positionAt(map, 0) // => { line: 1, column: 1 }
positionAt(map, 18) // => { line: 2, column: 7 }A property of an object by name.
Parameters
| Name | Type | Description |
|---|---|---|
§object | JsonObjectNode | The node whose properties are searched |
§name | string | The key to look for |
Returns
JsonPropertyNodeThe first property with that name, or null
Example
Look up a field of package.json
// { "name": "@acme/ui", "files": ["dist"] }
propertyOf(manifest, 'files')?.value.kind // => 'array'
propertyOf(manifest, 'version') // => nullThe reference an identifier makes, found through the analysis of its program.
Parameters
| Name | Type | Description |
|---|---|---|
§analysis | ScopeAnalysis | The program's scope analysis |
§identifier | Node | The identifier looked up |
Returns
ReferenceThe reference, or null when the identifier makes none
Example
Follow a use of a name back to its variable
// program: const limit = 10 / limit + 1 / function check() {}
referenceOf(analysis, limitInSum)?.resolved?.name // => 'limit'
referenceOf(analysis, checkDeclaration.id) // => null (a declaration, not a use)The root object of a document.
Parameters
| Name | Type | Description |
|---|---|---|
§node | JsonTreeNode | The node a document listener received |
Returns
JsonObjectNodeThe root when it is an object, or null
Example
Start a rule from the document's root object
document(node) {
const manifest = rootObject(node)
if (manifest === null) return // the document is an array or a literal
}The scope analysis of the program a rule is linting, built on first request.
Parameters
| Name | Type | Description |
|---|---|---|
§context | RuleContext< | The rule's context |
Returns
ScopeAnalysisThe analysis, the same object on every request for the program
Example
Share one analysis across a rule's handlers
const analysis = scopeAnalysisOf(context)
scopeAnalysisOf(context) === analysis // => true, built once per programThe innermost scope a node sits in: for the program itself the global scope, for any other node the innermost scope its nearest scope-opening ancestor opened, which for a named function expression is the function's scope rather than its name's.
Parameters
| Name | Type | Description |
|---|---|---|
§analysis | ScopeAnalysis | The program's analysis |
§node | Node | The node whose scope is wanted |
Returns
ScopeThe innermost scope enclosing the node
Example
Find the scope an identifier sits in
// program: 'let count = 0\nfunction bump(step) {\n count += step\n}'
// step: the Identifier read inside bump
scopeOf(analysis, step).kind // => 'function'
scopeOf(analysis, program).kind // => 'global'Every string literal under a node, in source order: the node itself, or the values nested in its objects and arrays.
Returns
JsonStringNode[The string nodes
Example
Collect the strings of a nested value
// "files": ["dist", { "glob": "src" }, 3]
stringsUnder(files.value).map((node) => node.value) // => ['dist', 'src']The first token starting at or after an offset.
Parameters
Returns
SourceTokenThe token, or null when none starts there or later
Example
Find the token after a node
// file.text: 'const total = (price) * 2', price: its Identifier node
tokenText(file, tokenAfter(program, price.end)) // => ')'
tokenAfter(program, file.text.length) // => nullThe last token ending at or before an offset.
Parameters
Returns
SourceTokenThe token, or null when none ends before it
Example
Find the token before a node
// file.text: 'const total = (price) * 2', price: its Identifier node
const open = tokenBefore(program, price.start)
tokenText(file, open) // => '('
tokenBefore(program, 0) // => nullThe tokens starting at or after one offset and ending at or before another.
Parameters
Returns
SourceToken[The tokens, in source order
Example
List the tokens a node spans
// file.text: 'const total = (price) * 2', init: the BinaryExpression
const tokens = tokensBetween(program, init.start, init.end)
tokens.map((token) => tokenText(file, token))
// => ['(', 'price', ')', '*', '2']The text of a token.
Parameters
| Name | Type | Description |
|---|---|---|
§file | RuleFile | The file linted |
§token | SourceToken | The token read |
Returns
stringIts characters
Example
Read a token's characters
// file.text: 'const total = 2'
tokenText(file, program.tokens[1]) // => 'total'The span of the whole document, where a rule reports a fact about the file as a whole.
Returns
JsonSpanA problem's start and end
Example
Report a fact about the whole file
context.report({ ...wholeDocument(context.file), message: 'Missing "license" field.' })
// wholeDocument(file) for an 86-character file => { start: 0, end: 86 }◈ Interfaces
One declaration of a variable.
A compiled pattern.
Properties
A string literal node.
Properties
What parsing a text produced.
Properties
Why a text did not parse.
Properties
One use of a name.
Properties
Methods
Example
A read keeps no write expression
const reference = new Reference(
identifier, scope, 'read', 'value', initialiser, true
)
reference.writeExpr // => null
reference.init // => false
reference.isRead() // => trueOne scope.
Properties
Example
A block scope's var declarations land in the module scope
const global = new Scope('global', program, null, false)
const module = new Scope('module', program, global, true)
const block = new Scope('block', statement, module, true)
global.children.length // => 1
block.variableScope === module // => trueThe scopes of one program.
A name declared in a scope, or known to the global scope.
Properties
§
readonly globalKind:ReferenceKindFor a global: the positions it is valid in; null for a declared variable.§
get isType:booleanWhether the variable is valid in a type position; a global with fixed positions keeps them whatever a script declares.§
get isValue:booleanWhether the variable is valid in a value position; a global with fixed positions keeps them whatever a script declares.Example
A global's positions are fixed, a declared variable's follow its definitions
const options = { kind: 'value', writable: false }
const window = new Variable('window', globalScope, options)
window.isType // => false
window.writable // => false
const total = new Variable('total', moduleScope, null)
total.writable // => null (not a global)
total.isType // => true until a definition says otherwise◆ Types
How a text is read as a module or a script.
type SourceType = indexedAccess