com.google.javascript.jscomp.WarningsGuard Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of closure-compiler Show documentation

Closure Compiler is a JavaScript optimizing compiler. It parses your JavaScript, analyzes it, removes dead code and rewrites and minimizes what's left. It also checks syntax, variable references, and types, and warns about common JavaScript pitfalls. It is used in many of Google's JavaScript apps, including Gmail, Google Web Search, Google Maps, and Google Docs.

There is a newer version: v20240317

Show newest version

/*
 * Copyright 2008 The Closure Compiler Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.google.javascript.jscomp;

import com.google.javascript.jscomp.base.Tri;
import java.io.Serializable;
import org.jspecify.nullness.Nullable;

/**
 * Class that allows to flexibly manage what to do with a reported warning/error.
 *
 * Guard has several choices: - return OFF - suppress the warning/error - return WARNING - return
 * ERROR report it with high severity - return null. Does not know what to do with it. Lets the
 * other guard decide what to do with it.
 *
 * 
Although the interface is very simple, it allows you easily customize what warnings you are
 * interested in.
 *
 * 
For example there are could be several implementations: StrictGuard - {return ERROR}. All
 * warnings should be treat as errors. SilentGuard - {if (WARNING) return OFF}. Suppress all
 * warnings but still fail if JS has errors. AllowlistGuard (if !allowlistErrors.contains(error)
 * return ERROR) return error if it does not present in the allowlist.
 */
public abstract class WarningsGuard implements Serializable {

  /** Priority */
  public enum Priority {
    MAX(1),
    MIN(100),
    STRICT(100),
    DEFAULT(50),
    SUPPRESS_BY_ALLOWLIST(40),
    SUPPRESS_DOC(20),
    FILTER_BY_PATH(1);

    final int value;

    Priority(int value) {
      this.value = value;
    }

    public int getValue() {
      return value;
    }
  }

  /**
   * Returns a new check level for a given error.
   *
   * 
`null` means that this guard does not know what to do with the error. `null` can be used it
   * chain multiple guards; if current guard returns null, then the next in the chain should process
   * it.
   *
   * @param error a reported error.
   * @return what level given error should have.
   */
  public abstract @Nullable CheckLevel level(JSError error);

  /**
   * Do checks for `group` still need to be run if this guard is installed?
   *
   * 

   *   TRUE: Enables one or more types in the group, so it must be checked.
   *   
FALSE: Disables all types in the group, so it need not be checked.
   *   
UNKNOWN: Does not affect or only partially disables the group, so checking is undecided.
   * 
   *
   * @param group a group to check.
   */
  public Tri mustRunChecks(DiagnosticGroup group) {
    return Tri.UNKNOWN;
  }

  /**
   * The priority in which warnings guards are applied. Lower means the guard will be applied
   * sooner. Expressed on a scale of 1 to 100.
   */
  protected int getPriority() {
    return Priority.DEFAULT.value;
  }
}