@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.