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

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 directory. | | maybeTodos | The linting data, converted to TodoData format. | | options | An object containing write options. |

readTodos(baseDir, shouldLock) ⇒

Reads all todo files in the .lint-todo directory.

Kind: global function
Returns: - A Map of FilePath/TodoMatcher.

| Param | Default | Description | | --- | --- | --- | | baseDir | | The base directory that contains the .lint-todo storage directory. | | shouldLock | true | True if the .lint-todo storage file should be locked, otherwise false. Default: true. |

readTodosForFilePath(todoStorageDir, filePath, shouldLock) ⇒

Reads todo files in the .lint-todo directory for a specific filePath.

Kind: global function
Returns: - A Map of FilePath/TodoMatcher.

| Param | Description | | --- | --- | | todoStorageDir | The .lint-todo storage directory. | | filePath | The relative file path of the file to return todo items for. | | shouldLock | True if the .lint-todo storage file should be locked, otherwise false. Default: true. |

readTodoData(baseDir) ⇒

Reads todo files in the .lint-todo directory 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 directory. |

getTodoBatches(maybeTodos, existing, options) ⇒

Gets 4 maps containing todo items to add, remove, those that are expired, or 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 directory. | | 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. |

ADD_OPERATIONS_ONLY(operation) ⇒

Compact strategy to leave only add operations in the todo storage file.

Kind: global function
Returns: True if the line matches an add operation, otherwise false.

| Param | Description | | --- | --- | | operation | The single line operation read from the todo storage file. |

EXCLUDE_EXPIRED(operation) ⇒

Compact strategy to remove all expired operations from the todo storage file.

Kind: global function
Returns: True if the operation is not expired, otherwise false.

| Param | Description | | --- | --- | | operation | The single line operation read from the todo storage file. |

compactTodoStorageFile(baseDir, compactStrategy) ⇒

Compacts the .lint-todo storage file based on the compact strategy.

Kind: global function
Returns: The count of compacted todos.

| Param | Description | | --- | --- | | baseDir | The base directory that contains the .lint-todo storage directory. | | compactStrategy | The strategy to use when compacting the storage file. Default: ADD_OPERATIONS_ONLY |

getTodoConfig(baseDir, engine, customDaysToDecay) ⇒

Gets the todo configuration. Config values can be present in

The package.json

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

{
  "lintTodo": {
    "some-engine": {
      "daysToDecay": {
        "warn": 5,
        "error": 10
      },
      "daysToDecayByRule": {
        "no-bare-strings": { "warn": 10, "error": 20 }
      }
    }
  }
}

A .lint-todorc.js file Example

module.exports = {
  "some-engine": {
    "daysToDecay": {
      "warn": 5,
      "error": 10
    },
    "daysToDecayByRule": {
      "no-bare-strings": { "warn": 10, "error": 20 }
    }
  }
}

Environment variables (TODO_DAYS_TO_WARN or TODO_DAYS_TO_ERROR) - Env vars override package.json config

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 |