phorge-phorge/src/docs/user/userguide/arcanist_extending_lint.diviner

@title Arcanist User Guide: Customizing Existing Linters
@group userguide

Explains how to customize existing linters.

This is a configuration guide that helps you set up advanced features. If you're
just getting started, you don't need to look at this yet. Instead, start with
the @{article:Arcanist User Guide}.

This guide explains how to refine lint behavior. To configure lint in the first
place, see @{article:Arcanist User Guide: Configuring a New Project} and
@{article:Arcanist User Guide: Lint}.

= Overview =

Arcanist ships with a number of linters which you may want to reuse in whole
or in part in other projects. This document explains how to customize existing
linters for use in new engines.

First, you should set up an engine by following the instructions in
@{article:Arcanist User Guide: Lint} and possibly
@{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}.
Then, follow this guide to customize linters.

= General Guidelines =

You should customize linters by configuring or composing them, not by extending
them -- their implementations are not necessarily stable. If a linter's
configuration options aren't flexible enough to meet your needs, sending a patch
which improves its configurability is better than one that makes it
nonfinal.

= Changing Rule Severities =

By default, most linters raise lint messages as errors. You may want to reduce
the severity of some messages (e.g., reduce errors to warnings). Do this by
calling `setCustomSeverityMap()`:

  $linter = new ArcanistTextLinter();

  // Change "missing newline at end of file" message from error to warning.
  $linter->setCustomSeverityMap(
    array(
      ArcanistTextLinter::LINT_EOF_NEWLINE
        => ArcanistLintSeverity::SEVERITY_WARNING,
    ));

See @{class@arcanist:ArcanistLintSeverity} for a list of available severity
constants.

= Disabling Rules =

To disable rules entirely, set their severities to `SEVERITY_DISABLED`:

  $linter = new ArcanistTextLinter();

  // Disable "Tab Literal" message.
  $linter->setCustomSeverityMap(
    array(
      ArcanistTextLinter::LINT_TAB_LITERAL
        => ArcanistLintSeverity::SEVERITY_DISABLED,
    ));

= Running Multiple Rulesets =

If you want to run the same linter on different types of files but vary the
configuration based on the file type, just instantiate it twice and configure
each instance appropriately. For instance, this will enforce different column
widths on different languages:

  $linters = array();

  // Warn on JS/CSS lines longer than 80 columns.
  $linters['TextLinter80Col'] = id(new ArcanistTextLinter())
    ->setPaths(preg_grep('/\.(js|css)$/', $paths));

  // Warn on Java lines longer than 120 columns.
  $linters['TextLinter120Col'] = id(new ArcanistTextLinter())
    ->setMaxLineLength(120)
    ->setPaths(preg_grep('/\.(java)$/', $paths));

  // ...

  return $linters;

= Customizing Specific Linters =

Some linters are specifically customizable or configurable. Some common
options are documented here, consult class documentation for complete
information.

== ArcanistTextLinter ==

  - Use `setMaxLineLength()` to change the 80-column warning to something
    else.

== ArcanistXHPASTLinter ==

  - Use `lint.xhpast.naminghook` in `.arcconfig` to override naming
    convention rules. See @{class@arcanist:ArcanistXHPASTLintNamingHook}
    for details.
  - Use `getXHPASTTreeForPath()` to reuse the AAST in other linters.