Diffusion Phabricator (feature/better-testing) Browse

better-testing

arcanist_extending_lint.diviner
View Options

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

phab/src/docs/user/userguide/arcanist_extending_lint.diviner88e7cd158f28feature/better-testing

arcanist_extending_lint.divinerView Options

phab/src/docs/user/userguide/arcanist_extending_lint.diviner
88e7cd158f28feature/better-testing

arcanist_extending_lint.diviner
View Options