Classes

FileStats: Represent statistics about source files.
Fix: Container object through which [Rule](#Rule) can pass instructions (of any kind) which a corresponding [Fixer](#Fixer) should follow while modifying the [IntermediateRepresentation](#IntermediateRepresentation) to remediate the issue.
Fixer: Class that applies fixes produced by rules onto the intermediate representation
Formatter: Represent an output formatter
IntermediateRepresentation: Representation of parser results
NotImplementedError: Error thrown when an abstract method is called but not implemented
Parser: common SPI for parser plugins
Plugin: common SPI that all plugins must implement
Result: Represent an ilib-lint rule check result
Rule: Represent an ilib-lint rule.

Constants

withVisibleWhitespace ⇒ string

Replace whitespace in input string with visible representations

The following explicit mapping is used:

Whitespace	Description	Representation	Description
\u0020	regular space	⎵	open box
\u00a0	non-breaking space	⍽	shouldered open box
\t	tabulator	→	tab symbol
\r	carriage return	␍	CR symbol
\n	line feed	␊	LF symbol
\v	vertical tab	␋	VT symbol

Additionally, whitespaces not included in explicit mapping are represented as their Unicode codepoint value, e.g. \u3000 becomes [U+3000].

Functions

isKebabCase(str) ⇒ boolean

Return true if the given string is written with kebab case. Kebab case is where words are separated with dashes, looking like they have been strung out on a kebab stick.

Example: this-is-kebab-case-text

isCamelCase(str) ⇒ boolean

Return true if the given string is written with camel case. Camel case is where words are not separated by spaces but the first letter of each word is capitalized, looking like the humps of a camel.

Example: thisIsCamelCaseText

isSnakeCase(str) ⇒ boolean

Return true if the given string is written with snake case. Snake case is where words are separated with underscores, looking like they have been strung out horizontally like a snake.

Example: this_is_snake_case_text

FileStats

Represent statistics about source files.

Kind: global class

FileStats
- new FileStats([options])
- .addStats(stats) ⇒
- .getFiles() ⇒ Number
- .addFiles(num) ⇒ FileStats
- .getLines() ⇒ Number
- .addLines(num) ⇒ FileStats
- .getBytes() ⇒ Number
- .addBytes(num) ⇒ FileStats
- .getModules() ⇒ Number
- .addModules(num) ⇒ FileStats

new FileStats([options])

Construct an file statistics instance. Each count in the statistics instance is optional except for the files.

Param	Type	Description
[options]	`Object`	options to the constructor
options.files	`Number`	the number of source files being counted. If not given, this defaults to 1.
[options.lines]	`Number`	the number of lines in those source files
[options.bytes]	`Number`	the number of bytes in those source files
[options.modules]	`Number`	the number of modules in those source files. The definition of a "module" are given by the programming language and may mean things like functions or classes. It is up to the parser for that programming language to count these.

fileStats.addStats(stats) ⇒

Add statistics from another instance into this one and return the result.

Kind: instance method of FileStats
Returns:

{FileStats] the current instance

Param	Type	Description
stats	`FileStats`	the other instance to add to the current one

fileStats.getFiles() ⇒ `Number`

Get the number of source files being counted.

Kind: instance method of FileStats
Returns: Number -

the number of source files being counted

fileStats.addFiles(num) ⇒ `FileStats`

Add the given amount to the number of files.

Kind: instance method of FileStats
Returns: FileStats -

the current instance

Param	Type	Description
num	`Number`	the amount to add

fileStats.getLines() ⇒ `Number`

Get the number of source file lines being counted.

Kind: instance method of FileStats
Returns: Number -

the number of source file lines being counted

fileStats.addLines(num) ⇒ `FileStats`

Add the given amount to the number of lines.

Kind: instance method of FileStats
Returns: FileStats -

the current instance

Param	Type	Description
num	`Number`	the amount to add

fileStats.getBytes() ⇒ `Number`

Get the number of source file bytes being counted.

Kind: instance method of FileStats
Returns: Number -

the number of source file bytes being counted

fileStats.addBytes(num) ⇒ `FileStats`

Add the given amount to the number of bytes.

Kind: instance method of FileStats
Returns: FileStats -

the current instance

Param	Type	Description
num	`Number`	the amount to add

fileStats.getModules() ⇒ `Number`

Get the number of source file modules being counted. Modules are filetype-dependent. It is up to the parser instance to determine what is a module and what is not. An example could be that a functional language like C might define a function as a module, whereas an object-oriented language like C++ might define a class as a module.

Kind: instance method of FileStats
Returns: Number -

the number of source file modules being counted

fileStats.addModules(num) ⇒ `FileStats`

Add the given amount to the number of modules.

Kind: instance method of FileStats
Returns: FileStats -

the current instance

Param	Type	Description
num	`Number`	the amount to add

Fix

Container object through which [Rule](#Rule) can pass instructions (of any kind) which a corresponding [Fixer](#Fixer) should follow while modifying the [IntermediateRepresentation](#IntermediateRepresentation) to remediate the issue.

Kind: global abstract class

Fix
- new Fix()
- .type : string
- .applied : boolean

new Fix()

A subclass of Fix can contain any properties - it is up to the corresponding Fixer (i.e. with a matching [Fix.type](Fix.type)) to interpret them appropriately and apply them to the IntermediateRepresentation.

Due to that, a recommended approach is that the Fixer should also be a Fix factory, so that the Rule could only express the Fix instructions with capabilities that the Fixer provides.

Example scenario:

Take an IntermediateRepresentation with type string which stores content of a file verbatim:

birds are not real birds are not real birds are not real

and a Rule (type string) which ensures that the word birds should always be surrounded by quotes.

Rule would produce the following results:

birds are not quoted (span 0 - 5)
birds are not quoted (span 19 - 24)
birds are not quoted (span 38 - 43)

To fix each of them, quotes need to be inserted:

fix: insert quote at 0 and 5
fix: insert quote at 19 and 24
fix: insert quote at 38 and 43

If there are no Fix and Fixer with type string, they could be implemented like in the following example:

class StringFixCommand {
    commandId;
    position;
}
class InsertCommand extends StringFixCommand {
commandId = "INSERT";
content;
}
class RemoveCommand extends StringFixCommand {
commandId = "REMOVE";
length;
}
class StringFix extends Fix {
commands; // StringFixCommand[]
}
class StringFixer {
applyFixes(representation, fixes) {} // applyFixes(representation: IntermediateRepresentation, fixes: StringFix[]): void
createFix(commands) {}               // createFix(commands: StringFixCommand[]): StringFix
insertStringAt(position, content) {} // insertStringAt(position: number, content: string): InsertCommand
removeStringAt(position, length) {}  // removeStringAt(position: number, length: number): RemoveCommand
}

Rule should then accept an instance of a StringFixer, and for each produced result provide a fix:

new Result({
    // ...
    fix: fixer.createFix([fixer.insertStringAt(0, "\""), fixer.insertStringAt(5, "\"")])
});

So that the linter could call

fixer.applyFixes(ir, results.map(r => r.fix))

fix.type : `string`

Unique identifier which allows to dynamically match the Fix to its corresponding Fixer and IntermediateRepresentation onto which it should be applied.

Subclass must define this property.

Kind: instance abstract property of Fix
Read only: true

fix.applied : `boolean`

If the fix had been applied by the fixer. Fixer is expected to set this flag after it had applied the fix.

Kind: instance property of Fix

Fixer

Class that applies fixes produced by rules onto the intermediate representation

Kind: global abstract class

Fixer
- new Fixer([options])
- .type : string
- .applyFixes(ir, fixes) ⇒ void

new Fixer([options])

Param	Type	Description
[options]	`Object`	Placeholder for options that should be provided upon the Fixer subclass instantiation

fixer.type : `string`

Unique identifier which allows to dynamically match the Fixer to its corresponding IntermediateRepresentation onto which it should apply the supplied Fixes.

Subclass must define this property.

Kind: instance abstract property of Fixer
Read only: true

fixer.applyFixes(ir, fixes) ⇒ `void`

Modify the Intermediate Representation instance by applying provided fixes. Fix can be anything as long as the Fixer knows how to apply it onto the IR, as described in [Fix](#Fix).

Fixer should know to avoid applying conflicting fixes (i.e. those that would modify the same part of the underlying representation) or to offset subsequent fixes after applying one of them.

For those fixes that have been applied, Fixer is expected to set the flag [Fix.applied](Fix.applied).

Example scenario:

Take an IntermediateRepresentation with type string which stores content of a file verbatim:

birds are not real birds are not real birds are not real

and a Rule (type string) which ensures that the word birds should always be surrounded by quotes.

The following fixes have been produced:

insert " at 0 and 5
insert " at 19 and 24
insert " at 38 and 43

Expected fixed string is:

"birds" are not real "birds" are not real "birds" are not real

Which contains quotes at 0, 6, 21, 27, 42, 48. In this scenario, fixer needs to know that after every time it inserted some string into the IR, it needs to offset indices of the remaining insertion points appropriately.

Take another Rule which ensures that the file should always begin with an exclamation mark. It would produce the following fix:

insert ! at 0

This fix overlaps with fix from the other rule (insert " at 0 and 5) because the fixer can't tell which symbol goes first ("!birds" or !"birds"). One of those fixes needs to be skipped.

Kind: instance abstract method of Fixer

Param	Type	Description
ir	`IntermediateRepresentation`	Intermediate Representaion instance which will be modified by the fixer when the fixes are applied
fixes	`Array.<Fix>`	Array of fixes which Fixer should attempt to apply

Formatter

Represent an output formatter

Kind: global abstract class

Formatter
- new Formatter([options])
- .getName() ⇒ String
- .getDescription() ⇒ String
- .format(result) ⇒ String

new Formatter([options])

Construct an formatter instance. Formatters and formatter plugins should implement this abstract class.

Param	Type	Description
[options]	`Object`	options to the constructor
options.getLogger	`function`	a callback function provided by the linter to retrieve the log4js logger

formatter.getName() ⇒ `String`

Get the name of the formatter. This should be a unique string.

Kind: instance method of Formatter
Returns: String -

the name of this formatter

formatter.getDescription() ⇒ `String`

Return a general description of the formatter for use in help output.

Kind: instance method of Formatter
Returns: String -

a general description of the formatter

formatter.format(result) ⇒ `String`

Format the given result with the current formatter and return the formatted string.

Kind: instance abstract method of Formatter
Returns: String -

the formatted result

Param	Type	Description
result	`Result`	the result to format

IntermediateRepresentation

Representation of parser results

Kind: global class

IntermediateRepresentation
- new IntermediateRepresentation(params)
- .type : string
- .ir : any
- .filePath : string
- .stats : FileStats | undefined
- .getType() ⇒ String
- .getRepresentation() ⇒ any
- .getPath() ⇒ String

new IntermediateRepresentation(params)

Construct a new intermediate representation of a parsed file.

Param	Type	Description
params	`Object`	parameters for this representation
params.type	`String`	a unique name for this type of representation
params.ir	`any`	the intermediate representation of this file
params.filePath	`String`	the path to the current file
[params.stats]	`FileStats`	statistics about the file that was parsed

intermediateRepresentation.type : `string`

A unique name for this type of representation

Kind: instance property of IntermediateRepresentation
Read only: true

intermediateRepresentation.ir : `any`

Representation that was parsed from the file

Kind: instance property of IntermediateRepresentation

intermediateRepresentation.filePath : `string`

Path to the file that was parsed

Kind: instance property of IntermediateRepresentation
Read only: true

intermediateRepresentation.stats : `FileStats` | `undefined`

Statistics about the file that was parsed

Kind: instance property of IntermediateRepresentation
Read only: true

intermediateRepresentation.getType() ⇒ `String`

Return the type of this representation.

Kind: instance method of IntermediateRepresentation
Returns: String -

The type of this representation

intermediateRepresentation.getRepresentation() ⇒ `any`

Return the representation that was parsed from the file.

Kind: instance method of IntermediateRepresentation
Returns: any -

the representation

intermediateRepresentation.getPath() ⇒ `String`

Return the file path to the file that was parsed.

Kind: instance method of IntermediateRepresentation
Returns: String -

the path to the file that was parsed

NotImplementedError

Error thrown when an abstract method is called but not implemented

Kind: global class

Parser

common SPI for parser plugins

Kind: global abstract class

Parser
- new Parser([options])
- .getLogger : function | undefined
- .name : string
- .description : string
- .extensions : Array.<string>
- .type : string
- .canWrite : boolean
- .init()
- .getName() ⇒ String
- .getDescription() ⇒ String
- .getExtensions() ⇒ Array.<String>
- .parse() ⇒ Array.<IntermediateRepresentation>
- .getType() ⇒ String
- .write(ir) ⇒ void

new Parser([options])

Construct a new plugin.

Param	Type	Description
[options]	`Object`	options to the constructor
[options.filePath]	`string`	path to the file that should be parsed
[options.getLogger]	`function`	a callback function provided by
[options.settings]	`object`	additional settings that can be passed to the parser the linter to retrieve the log4js logger

parser.getLogger : `function` | `undefined`

a callback function provided by the linter to retrieve the log4js logger

Kind: instance property of Parser

parser.name : `string`

name of this type of parser

Subclass must define this property.

Kind: instance abstract property of Parser
Read only: true

parser.description : `string`

description of what this parser does and what kinds of files it handles for users who are trying to discover whether or not to use it

Subclass must define this property.

Kind: instance abstract property of Parser
Read only: true

parser.extensions : `Array.<string>`

list of extensions of the files that this parser handles. The extensions are listed without the dot. eg. ["json", "jsn"]

Subclass must define this property.

Kind: instance abstract property of Parser
Read only: true

parser.type : `string`

type of intermediate representation that this parser produces. The type should be a unique name that matches with the rule type for rules that process this intermediate representation

There are three types that are reserved, however:

resource - the parser returns an array of Resource instances as defined in [https://github.com/ilib-js/ilib-tools-common](https://github.com/ilib-js/ilib-tools-common).
line - the parser produces a set of lines as an array of strings
string - the parser doesn't parse. Instead, it just treats the the file as one long string.

Subclass must define this property.

Kind: instance abstract property of Parser
Read only: true

parser.canWrite : `boolean`

Defines whether this parser is able to write out an intermediate representation back to the file.

Override this flag as true and implement [Parser.write](Parser.write) to allow Rules to auto-fix errors.

Kind: instance property of Parser
Read only: true

parser.init()

Initialize the current plugin.

Kind: instance method of Parser

parser.getName() ⇒ `String`

Return the name of this type of parser. Subclass must define [Parser.name](Parser.name).

Kind: instance method of Parser
Returns: String -

return the name of this type of parser

parser.getDescription() ⇒ `String`

Return a description of what this parser does and what kinds of files it handles for users who are trying to discover whether or not to use it.

Subclass must define [Parser.description](Parser.description).

Kind: instance method of Parser
Returns: String -

a description of this parser.

parser.getExtensions() ⇒ `Array.<String>`

Return the list of extensions of the files that this parser handles. The extensions are listed without the dot. eg. ["json", "jsn"].

Subclass must define [Parser.extensions](Parser.extensions).

Kind: instance method of Parser
Returns: Array.<String> -

a list of file name extensions

parser.parse() ⇒ `Array.<IntermediateRepresentation>`

Parse the current file into intermediate representations. This representation may be anything you like, as long as the rules you implement also can use this same format to check for problems.

Many parsers produce an abstract syntax tree. The tree could have a different style depending on the programming language, but generally, each node has a type, a name, and an array of children, as well as additional information that depends on the type of the node.

Other types of intermediate representation could include:

lines - just split the file into an array of lines in order
string - treat the whole file like a big string
concrete syntax tree - a tree the represents the actual syntactical elements in the file. This can be converted to an abstract syntax tree afterwards, which would be more useful for checking for problems.
resources - array of instances of Resource classes as defined in [https://github.com/ilib-js/ilib-tools-common](https://github.com/ilib-js/ilib-tools-common). This is the preference intermediate representation for resource files like Java properties or xliff. There are many rules that already know how to process Resource instances.

Kind: instance abstract method of Parser
Returns: Array.<IntermediateRepresentation> -

the intermediate representations

parser.getType() ⇒ `String`

Return the type of intermediate representation that this parser produces. The type should be a unique name that matches with the rule type for rules that process this intermediate representation.

Subclass must define [Parser.type](Parser.type).

Kind: instance abstract method of Parser
Returns: String -

the name of the current type of intermediate representation.

parser.write(ir) ⇒ `void`

Write out the intermediate representation back into the file.

Override this method and [Parser.canWrite](Parser.canWrite) if You want to allow Rules to auto-fix errors.

After obtaining the representation from [Parser.parse](Parser.parse), Rules are able to apply fixes by modifying the ir object. Subsequently, in order to commit these fixes to the actual file Parser needs to write out the transformed IntermediateRepresentation instance back to a file from which it was originally parsed (overwriting it in process).

Ideally, when provided with an unchanged ir, this method should produce an unchanged file (or an equivalent of it).

Kind: instance method of Parser

Param	Type	Description
ir	`IntermediateRepresentation`	A modified representation which should be written back to the file.

Plugin

common SPI that all plugins must implement

Kind: global abstract class

Plugin
- new Plugin([options])
- .init() ⇒ Promise.<void> | void
- .getRules() ⇒ Array.<Class>
- .getRuleSets() ⇒ Object
- .getParsers() ⇒ Array.<Class>
- .getFormatters() ⇒ Array.<Class>
- .getFixers() ⇒ Array.<Class>

new Plugin([options])

Construct a new plugin. The options can vary depending on the the plugin.

Param	Type	Description
[options]	`Object`	options to the constructor
options.getLogger	`function`	a callback function provided by the linter to retrieve the log4js logger

plugin.init() ⇒ `Promise.<void>` | `void`

Initialize the current plugin, if necessary.

Kind: instance abstract method of Plugin
Returns: Promise.<void> | void -

a promise to initialize or undefined if the initialization is synchronous or if no initialization is necessary

plugin.getRules() ⇒ `Array.<Class>`

For a plugin that implements rules, this returns a list of Rule classes that this plugin implements. Note this is the class itself, not an instance of the class. The linter may need to instantiate this rule multiple times with different optional parameters.

Kind: instance method of Plugin
Returns: Array.<Class> -

list of Rule classes implemented by this plugin

plugin.getRuleSets() ⇒ `Object`

Return a number of pre-defined rule sets. The idea behind this method is that the plugin can define sets of rules that users of the plugin can rely on. As the plugin developer adds new rules in their plugin, they can also update the rule set to include those new rules and users of this plugin will get enhanced functionality automatically without changing their own configuration.

For example, if there is a plugin named "android", the plugin writer can add support for Java, Kotlin, and properties files in the same plugin by adding parsers and rules for each file type. They can then also add rulesets called "java", "kotlin" and "properties" which will apply all the rules from this plugin that are appropriate for the file types.

By convention, these rulesets are named the same as the file type that they support, but this is not a strict requirement. Plugin writers should document the rulesets that the plugin supports in the README.md for that plugin so that users know that it is available.

Kind: instance method of Plugin
Returns: Object -

an object where the properties are the names of rulesets and the values are objects that configure a ruleset. The properties of this subobject are the names of the rules and the values are the optional parameters for the rule, or "true" to indicate that the rule should be turned on for this set.

plugin.getParsers() ⇒ `Array.<Class>`

For a "parser" type of plugin, this returns a list of Parser classes that this plugin implements. Note this is the class, not an instance of the class. The linter may need to instantiate this parser multiple times.

Kind: instance method of Plugin
Returns: Array.<Class> -

list of Parser classes implemented by this plugin

plugin.getFormatters() ⇒ `Array.<Class>`

For a "formatter" type of plugin, this returns a list of Formatter classes that this plugin implements. Note this is the class, not an instance of the class. The linter may need to instantiate this formatter multiple times.

Kind: instance method of Plugin
Returns: Array.<Class> -

list of Formatter classes implemented by this plugin

plugin.getFixers() ⇒ `Array.<Class>`

For a "fixer" type of plugin, this returns a list of Fixer classes that this plugin implements. Note this is the class, not an instance of the class. The linter may need to instantiate this formatter multiple times.

Kind: instance method of Plugin
Returns: Array.<Class> -

array of Fixer classes implemented by this plugin

Result

Represent an ilib-lint rule check result

Kind: global class

Result
- new Result(fields)
- .severity : "error" | "warning" | "suggestion"
- .description : String
- .pathName : String
- .rule : Rule
- .highlight : String
- .id : String | undefined
- .source : String | undefined
- .lineNumber : Number | undefined
- .charNumber : Number | undefined
- .endLineNumber : Number | undefined
- .endCharNumber : Number | undefined
- .locale : String | undefined
- .fix : Fix | undefined

new Result(fields)

Construct an ilib-lint rule check result. Rules should return this type when reporting issues in the source files.

Some extra notes about the properties in the fields parameter:

severity: Should have one of the following values:
- suggestion - a suggestion of a better way to do things. The current way is not incorrect, but probably not optimal
- warning - a problem that should be fixed, but which does not prevent your app from operating internationally. This is more severe than a suggestion.
- error - a problem that must be fixed. This type of problem will prevent your app from operating properly internationally and could possibly even crash your app in some cases.
description: In order to make the ilib-lint output useful, this description should attempt to make the following things clear:
- What part is wrong
- Why it is wrong
- Suggestions on how to fix it

For the highlight property, a snippet of the input that has a problem is reproduced with XML tags around the problem part, if it is known. The tags are of the form <eX> where X is a digit starting with 0 and progressing to 9 for each subsequent problem. If the file type is XML already, the rest of the line will be XML-escaped first.

Example:

"const str = rb.getString(<e0>id</e0>);"

In this example rule, getString() must be called with a static string in order for the loctool to be able to extract that string. The line above calls getString() with a variable named "id" as a parameter instead of a static string, so it fails this check. The variable is then highlighted with the e0 tag and put into the highlight field of the Result instance. Callers can then translate the open and close tags appropriately for the output device, such as ASCII escapes for a regular terminal, or HTML tags for a web-based device.

Only the severity, description, pathName, and rule are required. All other properties are optional. All fields are stored in this result and are public.

Param	Type	Description
fields	`Object`	result fields
fields.severity	`"error"` \| `"warning"` \| `"suggestion"`	one of "error", "warning", or "suggestion"
fields.description	`String`	description of the problem in the source file
fields.pathName	`String`	name of the file that the issue was found in
fields.rule	`Rule`	the rule that generated this result
fields.highlight	`String`	highlighted text from the source file indicating where the issue was optionally including some context. For resources, this is either the source or target string, where-ever the problem occurred.
[fields.id]	`String`	for rule that check resources, this is the id of of the resource that generated this result
[fields.source]	`String`	for rule that check resources, this is the source string of the resource that generated this result
[fields.lineNumber]	`Number`	if the parser included location information in the intermediate representation, this gives the line number in the source file where the problem occurred
[fields.charNumber]	`Number`	if the parser included location information in the intermediate representation, this gives the character number within the line in the source file where the problem occurred
[fields.endLineNumber]	`Number`	if the parser included location information in the intermediate representation, this gives the last line number in the source file where the problem occurred
[fields.endCharNumber]	`Number`	if the parser included location information in the intermediate representation, this gives the last character number within the line in the source file where the problem occurred
[fields.locale]	`String`	for locale-sensitive rules, this gives an indication of which locale generated this result
[fields.fix]	`Fix`	object which contains info needed by the Fixer to perform the fix for this result