lint-todo@lint-todo/utils
A collection of utilities to generate and store lint item metadata.
Those utilities are:
Functions
- buildTodoDatum(lintResult, lintMessage, todoConfig) ⇒
Adapts a LintResult to a TodoData. FilePaths are absolute when received from a lint result, so they're converted to relative paths for stability in serializing the contents to disc.
- todoStorageFileExists(baseDir) ⇒
Determines if the .lint-todo storage file exists.
- ensureTodoStorageFile(baseDir) ⇒
Creates, or ensures the creation of, the .lint-todo file.
- getTodoStorageFilePath(baseDir) ⇒
- hasConflicts(todoContents) ⇒
Determines if the .lint-todo storage file has conflicts.
- resolveConflicts(operations) ⇒
Resolves git conflicts in todo operations by removing any lines that match conflict markers.
- readTodoStorageFile(todoStorageFilePath) ⇒
Reads the .lint-todo storage file.
- writeTodoStorageFile(todoStorageFilePath, operations)
Writes the operations to the .lint-todo storage file to the path provided by todoStorageFilePath.
- writeTodos(baseDir, maybeTodos, options) ⇒
Writes files for todo lint violations. One file is generated for each violation, using a generated hash to identify each.
Given a list of todo lint violations, this function will also delete existing files that no longer have a todo lint violation.
- readTodos(baseDir, options, shouldLock) ⇒
Reads all todo files in the .lint-todo file.
- readTodosForFilePath(baseDir, options, shouldLock) ⇒
Reads todo files in the .lint-todo file for a specific filePath.
- readTodoData(baseDir, options) ⇒
Reads todos in the .lint-todo file and returns Todo data in an array.
- readTodoDataForFilePath(baseDir, options) ⇒
Reads todos for a single filePath in the .lint-todo file and returns Todo data in an array.
- generateTodoBatches(baseDir, maybeTodos, options) ⇒
Gets 4 data structures containing todo items to add, remove, those that are expired, and those that are stable (not to be modified).
- getTodoBatches(maybeTodos, existing, options) ⇒
Gets 4 data structures containing todo items to add, remove, those that are expired, and those that are stable (not to be modified).
- applyTodoChanges(baseDir, add, remove, shouldLock)
Applies todo changes, either adding or removing, based on batches from
getTodoBatches.- compactTodoStorageFile(baseDir) ⇒
Compacts the .lint-todo storage file.
- getTodoConfig(baseDir, engine, customDaysToDecay) ⇒
Gets the todo configuration from one of a number of locations.
- validateConfig(baseDir) ⇒
Validates whether we have a unique config in a single location.
- getSeverity(todo, today) ⇒
Returns the correct severity level based on the todo data's decay dates.
- isExpired(date, today) ⇒
Evaluates whether a date is expired (earlier than today)
- getDatePart(date) ⇒
Converts a date to include year, month, and day values only (time is zeroed out).
- differenceInDays(startDate, endDate) ⇒
Returns the difference in days between two dates.
- format(date) ⇒
Formats the date in short form, eg. 2021-01-01
- buildRange(line, column, endLine, endColumn) ⇒
Converts node positional numbers into a Range object.
- readSource(filePath) ⇒
Reads a source file, optionally caching it if it's already been read.
- getSourceForRange(source, range) ⇒
Extracts a source fragment from a file's contents based on the provided Range.
buildTodoDatum(lintResult, lintMessage, todoConfig) ⇒
Adapts a LintResult to a TodoData. FilePaths are absolute when received from a lint result, so they're converted to relative paths for stability in serializing the contents to disc.
Kind: global function
Returns: - A TodoData object.
| Param | Description |
|---|---|
| lintResult | The lint result object. |
| lintMessage | A lint message object representing a specific violation for a file. |
| todoConfig | An object containing the warn or error days, in integers. |
todoStorageFileExists(baseDir) ⇒
Determines if the .lint-todo storage file exists.
Kind: global function
Returns: - true if the todo storage file exists, otherwise false.
| Param | Description |
|---|---|
| baseDir | The base directory that contains the .lint-todo storage file. |
ensureTodoStorageFile(baseDir) ⇒
Creates, or ensures the creation of, the .lint-todo file.
Kind: global function
Returns: - The todo storage file path.
| Param | Description |
|---|---|
| baseDir | The base directory that contains the .lint-todo storage file. |
getTodoStorageFilePath(baseDir) ⇒
Kind: global function
Returns: - The todo storage file path.
| Param | Description |
|---|---|
| baseDir | The base directory that contains the .lint-todo storage file. |
hasConflicts(todoContents) ⇒
Determines if the .lint-todo storage file has conflicts.
Kind: global function
Returns: true if the file has conflicts, otherwise false.
| Param | Description |
|---|---|
| todoContents | The unparsed contents of the .lint-todo file. |
resolveConflicts(operations) ⇒
Resolves git conflicts in todo operations by removing any lines that match conflict markers.
Kind: global function
Returns: An array of string operations excluding any operations that were identified as git conflict lines.
| Param | Description |
|---|---|
| operations | An array of string operations that are used to recreate todos. |
readTodoStorageFile(todoStorageFilePath) ⇒
Reads the .lint-todo storage file.
Kind: global function
Returns: A array of todo operations.
| Param | Description |
|---|---|
| todoStorageFilePath | The .lint-todo storage file path. |
writeTodoStorageFile(todoStorageFilePath, operations)
Writes the operations to the .lint-todo storage file to the path provided by todoStorageFilePath.
Kind: global function
| Param | Description |
|---|---|
| todoStorageFilePath | The .lint-todo storage file path. |
| operations | An array of string operations that are used to recreate todos. |
writeTodos(baseDir, maybeTodos, options) ⇒
Writes files for todo lint violations. One file is generated for each violation, using a generated hash to identify each.
Given a list of todo lint violations, this function will also delete existing files that no longer have a todo lint violation.
Kind: global function
Returns: - The counts of added and removed todos.
| Param | Description |
|---|---|
| baseDir | The base directory that contains the .lint-todo storage file. |
| maybeTodos | The linting data, converted to TodoData format. |
| options | An object containing write options. |
readTodos(baseDir, options, shouldLock) ⇒
Reads all todo files in the .lint-todo file.
Kind: global function
Returns: - A Map of FilePath/TodoMatcher.
| Param | Default | Description |
|---|---|---|
| baseDir | The base directory that contains the .lint-todo storage file. | |
| options | An object containing read options. | |
| shouldLock | true |
True if the .lint-todo storage file should be locked, otherwise false. Default: true. |
readTodosForFilePath(baseDir, options, shouldLock) ⇒
Reads todo files in the .lint-todo file for a specific filePath.
Kind: global function
Returns: - A Map of FilePath/TodoMatcher.
| Param | Default | Description |
|---|---|---|
| baseDir | The base directory that contains the .lint-todo storage file. | |
| options | An object containing read options. | |
| shouldLock | true |
True if the .lint-todo storage file should be locked, otherwise false. Default: true. |
readTodoData(baseDir, options) ⇒
Reads todos in the .lint-todo file and returns Todo data in an array.
Kind: global function
Returns: An array of TodoData
| Param | Description |
|---|---|
| baseDir | The base directory that contains the .lint-todo storage file. |
| options | An object containing read options. |
readTodoDataForFilePath(baseDir, options) ⇒
Reads todos for a single filePath in the .lint-todo file and returns Todo data in an array.
Kind: global function
Returns: An array of TodoData
| Param | Description |
|---|---|
| baseDir | The base directory that contains the .lint-todo storage file. |
| options | An object containing read options. |
generateTodoBatches(baseDir, maybeTodos, options) ⇒
Gets 4 data structures containing todo items to add, remove, those that are expired, and those that are stable (not to be modified).
Kind: global function
Returns: - An object of TodoBatches.
| Param | Description |
|---|---|
| baseDir | The base directory that contains the .lint-todo storage file. |
| maybeTodos | The linting data for violations. |
| options | An object containing write options. |
getTodoBatches(maybeTodos, existing, options) ⇒
Gets 4 data structures containing todo items to add, remove, those that are expired, and those that are stable (not to be modified).
Kind: global function
Returns: - An object of TodoBatches.
| Param | Description |
|---|---|
| maybeTodos | The linting data for violations. |
| existing | Existing todo lint data. |
| options | An object containing write options. |
applyTodoChanges(baseDir, add, remove, shouldLock)
Applies todo changes, either adding or removing, based on batches from getTodoBatches.
Kind: global function
| Param | Default | Description |
|---|---|---|
| baseDir | The base directory that contains the .lint-todo storage file. | |
| add | Batch of todos to add. | |
| remove | Batch of todos to remove. | |
| shouldLock | true |
True if the .lint-todo storage file should be locked, otherwise false. Default: true. |
compactTodoStorageFile(baseDir) ⇒
Compacts the .lint-todo storage file.
Kind: global function
Returns: The count of compacted todos.
| Param | Description |
|---|---|
| baseDir | The base directory that contains the .lint-todo storage file. |
getTodoConfig(baseDir, engine, customDaysToDecay) ⇒
Gets the todo configuration from one of a number of locations.
Kind: global function
Returns: - The todo config object.
| Param | Description |
|---|---|
| baseDir | The base directory that contains the project's package.json. |
| engine | The engine for this configuration, eg. eslint |
| customDaysToDecay | The optional custom days to decay configuration. |
Example
Using the package.json
{
"lintTodo": {
"some-engine": {
"daysToDecay": {
"warn": 5,
"error": 10
},
"daysToDecayByRule": {
"no-bare-strings": { "warn": 10, "error": 20 }
}
}
}
}
Example
Using the .lint-todorc.js file
module.exports = {
"some-engine": {
"daysToDecay": {
"warn": 5,
"error": 10
},
"daysToDecayByRule": {
"no-bare-strings": { "warn": 10, "error": 20 }
}
}
}
Example
Using environment variables (`TODO_DAYS_TO_WARN` or `TODO_DAYS_TO_ERROR`)
- Env vars override package.json config
Example
Passed in directly, such as from command line options.
- Passed in options override both env vars and package.json config
validateConfig(baseDir) ⇒
Validates whether we have a unique config in a single location.
Kind: global function
Returns: A ConfigValidationResult that indicates whether a config is unique
| Param | Description |
|---|---|
| baseDir | The base directory that contains the project's package.json. |
getSeverity(todo, today) ⇒
Returns the correct severity level based on the todo data's decay dates.
Kind: global function
Returns: Severity - the lint severity based on the evaluation of the decay dates.
| Param | Description |
|---|---|
| todo | The todo data. |
| today | A number representing a date (UNIX Epoch - milliseconds) |
isExpired(date, today) ⇒
Evaluates whether a date is expired (earlier than today)
Kind: global function
Returns: true if the date is earlier than today, otherwise false
| Param | Description |
|---|---|
| date | The date to evaluate |
| today | A number representing a date (UNIX Epoch - milliseconds) |
getDatePart(date) ⇒
Converts a date to include year, month, and day values only (time is zeroed out).
Kind: global function
Returns: Date - A date with the time zeroed out eg. '2021-01-01T08:00:00.000Z'
| Param | Description |
|---|---|
| date | The date to convert |
differenceInDays(startDate, endDate) ⇒
Returns the difference in days between two dates.
Kind: global function
Returns: a number representing the days between the dates
| Param | Description |
|---|---|
| startDate | The start date |
| endDate | The end date |
format(date) ⇒
Formats the date in short form, eg. 2021-01-01
Kind: global function
Returns: A string representing the formatted date
| Param | Description |
|---|---|
| date | The date to format |
buildRange(line, column, endLine, endColumn) ⇒
Converts node positional numbers into a Range object.
Kind: global function
Returns: A range object.
| Param | Description |
|---|---|
| line | The source start line. |
| column | The source start column. |
| endLine | The source end line. |
| endColumn | The source end column. |
readSource(filePath) ⇒
Reads a source file, optionally caching it if it's already been read.
Kind: global function
Returns: The file contents.
| Param | Description |
|---|---|
| filePath | The path to the source file. |
getSourceForRange(source, range) ⇒
Extracts a source fragment from a file's contents based on the provided Range.
Kind: global function
Returns: The source fragment.
| Param | Description |
|---|---|
| source | The file contents. |
| range | A Range object representing the range to extract from the file contents. |