// Copyright 2017 The Bazel Authors. All rights reserved.
//
// 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.devtools.skylark.skylint;

import com.google.common.truth.Truth;
import com.google.devtools.build.lib.syntax.BuildFileAST;
import java.util.List;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.junit.runners.JUnit4;

/** Tests the lint done by {@link DocstringChecker}. */
@RunWith(JUnit4.class)
public class DocstringCheckerTest {
  private static List<Issue> findIssues(String... lines) {
    String content = String.join("\n", lines);
    BuildFileAST ast =
        BuildFileAST.parseString(
            event -> {
              throw new IllegalArgumentException(event.getMessage());
            },
            content);
    return DocstringChecker.check(ast);
  }

  @Test
  public void reportMissingDocString() throws Exception {
    String errorMessage =
        findIssues(
                "# no module docstring",
                "def function():",
                "  # no function docstring",
                "  print(1) # make sure the function is long enough",
                "  print(2)",
                "  print(3)",
                "  print(4)",
                "  print(5)")
            .toString();
    Truth.assertThat(errorMessage)
        .contains("1:1-2:1: file has no module docstring [missing-module-docstring]");
    Truth.assertThat(errorMessage)
        .contains(
            "2:1-4:2: function 'function' has no docstring"
                + " (if this function is intended to be private,"
                + " the name should start with an underscore: '_function')"
                + " [missing-function-docstring]");
  }

  @Test
  public void reportMissingParameterDocumentation() throws Exception {
    List<Issue> errors =
        findIssues(
            "\"\"\" module docstring \"\"\"",
            "def f(param1, *args, **kwargs):",
            "  \"\"\"summary",
            "",
            "  more description",
            "  \"\"\"",
            "  pass");
    Truth.assertThat(errors).hasSize(1);
    Truth.assertThat(errors.toString())
        .contains(
            "3:3-6:5: incomplete docstring: the function parameters are not documented"
                + " (no 'Args:' section found)\n"
                + "The parameter documentation should look like this:\n"
                + "\n"
                + "Args:\n"
                + "  param1: ...\n"
                + "  *args: ...\n"
                + "  **kwargs: ...\n"
                + "\n"
                + " [inconsistent-docstring]");
  }

  @Test
  public void reportUndocumentedParameters() throws Exception {
    String errorMessage =
        findIssues(
                "def function(foo, bar, baz):",
                "  \"\"\"summary",
                "",
                "  Args:",
                "    bar: blabla",
                "  \"\"\"",
                "  pass")
            .toString();
    Truth.assertThat(errorMessage)
        .contains(
            "2:3-6:5: incomplete docstring: parameter 'foo' not documented"
                + " [inconsistent-docstring]");
    Truth.assertThat(errorMessage)
        .contains(
            "2:3-6:5: incomplete docstring: parameter 'baz' not documented"
                + " [inconsistent-docstring]");
  }

  @Test
  public void reportArgumentsUse() throws Exception {
    String errorMessage =
        findIssues(
                "def function(foo, bar):",
                "  \"\"\"summary",
                "",
                "  Arguments:",
                "    foo: bla",
                "    bar: blabla",
                "  \"\"\"",
                "  pass")
            .toString();
    Truth.assertThat(errorMessage)
        .contains(
            "4:3-4:13: Prefer 'Args:' to 'Arguments:' when documenting function arguments."
                + " [args-arguments-docstring]");
  }

  @Test
  public void reportObsoleteParameterDocumentation() throws Exception {
    String errorMessage =
        findIssues(
                "def function(bar):",
                "  \"\"\"summary",
                "",
                "  Args:",
                "    foo: blabla",
                "    bar: blabla",
                "    baz: blabla",
                "  \"\"\"",
                "  pass")
            .toString();
    Truth.assertThat(errorMessage)
        .contains(
            "2:3-8:5: inconsistent docstring: parameter 'foo' appears in docstring"
                + " but not in function signature [inconsistent-docstring]");
    Truth.assertThat(errorMessage)
        .contains(
            "2:3-8:5: inconsistent docstring: parameter 'baz' appears in docstring"
                + " but not in function signature [inconsistent-docstring]");
  }

  @Test
  public void reportParametersDocumentedInDifferentOrder() throws Exception {
    String errorMessage =
        findIssues(
                "def function(p1, p2):",
                "  \"\"\"summary",
                "",
                "  Args:",
                "    p2: blabla",
                "    p1: blabla",
                "  \"\"\"",
                "  pass")
            .toString();
    Truth.assertThat(errorMessage)
        .contains(
            "2:3-7:5:"
                + " inconsistent docstring: order of parameters differs from function signature\n"
                + "Declaration order:   p1, p2\n"
                + "Documentation order: p2, p1\n"
                + " [inconsistent-docstring]");
  }

  @Test
  public void reportInvalidDocstringFormat() throws Exception {
    String errorMessage = findIssues("\"\"\"summary", "missing blank line\"\"\"").toString();
    Truth.assertThat(errorMessage)
        .contains(
            "2:1-2:18: bad docstring format: "
                + "the one-line summary should be followed by a blank line [bad-docstring-format]");

    errorMessage =
        findIssues(
                "def f():",
                "  \"\"\"summary",
                "",
                "  foo",
                " bad indentation in this line",
                "\"\"\"")
            .toString();
    Truth.assertThat(errorMessage)
        .contains(
            "5:1-5:29: bad docstring format: "
                + "line indented too little (here: 1 spaces; expected: 2 spaces)"
                + " [bad-docstring-format]");
  }

  @Test
  public void reportMissingReturnDocumentation() throws Exception {
    List<Issue> errors =
        findIssues(
            "\"\"\" module docstring \"\"\"",
            "def f():",
            "  \"\"\"summary",
            "",
            "  more description",
            "  \"\"\"",
            "  return True");
    Truth.assertThat(errors).hasSize(1);
    Truth.assertThat(errors.toString())
        .contains(
            "3:3-6:5: incomplete docstring: the return value is not documented"
                + " (no 'Returns:' section found) [inconsistent-docstring]");
  }

  @Test
  public void dontReportReturnDocumentationIfNoReturnValue() throws Exception {
    Truth.assertThat(
            findIssues(
                "\"\"\" module docstring \"\"\"",
                "def f():",
                "  \"\"\"summary",
                "",
                "  more description",
                "  \"\"\"",
                "  return"))
        .isEmpty();
  }

  @Test
  public void dontReportExistingDocstrings() throws Exception {
    Truth.assertThat(
            findIssues(
                "\"\"\"This is a module docstring",
                "\n\"\"\"",
                "def function():",
                "  \"\"\" This is a function docstring",
                "",
                "  \"\"\""))
        .isEmpty();
  }

  @Test
  public void dontReportSingleLineDocstring() throws Exception {
    Truth.assertThat(
            findIssues(
                "\"\"\"module docstring\"\"\"",
                "def function(param1, param2):",
                "  \"\"\"single line docstring is fine\"\"\"",
                "  return True"))
        .isEmpty();
  }

  @Test
  public void dontReportPrivateFunctionWithoutDocstring() throws Exception {
    Truth.assertThat(
            findIssues(
                "\"\"\" Module docstring\n\"\"\"",
                "def _private_function():",
                "  pass # no docstring necessary for private functions"))
        .isEmpty();
  }

  @Test
  public void dontReportShortFunctionWithoutDocstring() throws Exception {
    Truth.assertThat(findIssues("\"\"\"Module docstring\"\"\"", "def function():", "  pass"))
        .isEmpty();
  }

  @Test
  public void dontReportCorrectFunctionDocstring() throws Exception {
    Truth.assertThat(
            findIssues(
                "\"\"\" module docstring \"\"\"",
                "def function(param1, param2, *args, **kwargs):",
                "  \"\"\"summary",
                "",
                "  Args:",
                "    param1: foo",
                "    param2 (foo, bar): baz",
                "    *args: foo",
                "    **kwargs: bar",
                "",
                "  Returns:",
                "    True",
                "  \"\"\"",
                "  return True"))
        .isEmpty();
  }
}