// Copyright (c) 2017, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

import 'package:analyzer/dart/element/element.dart';
import 'package:analyzer/file_system/file_system.dart';
import 'package:dartdoc/src/dartdoc_options.dart';
import 'package:dartdoc/src/logging.dart';
import 'package:dartdoc/src/model/model.dart';
import 'package:dartdoc/src/package_meta.dart';
import 'package:dartdoc/src/tuple.dart';

abstract class PackageWarningOptionContext implements DartdocOptionContextBase {
  bool get allowNonLocalWarnings =>
      optionSet['allowNonLocalWarnings'].valueAt(context);

  // allowWarningsInPackages, ignoreWarningsInPackages, errors, warnings, and ignore
  // are only used indirectly via the synthetic packageWarningOptions option.
  PackageWarningOptions get packageWarningOptions =>
      optionSet['packageWarningOptions'].valueAt(context);

  bool get verboseWarnings => optionSet['verboseWarnings'].valueAt(context);
}

Future<List<DartdocOption<Object>>> createPackageWarningOptions(
  PackageMetaProvider packageMetaProvider,
) async {
  var resourceProvider = packageMetaProvider.resourceProvider;
  return [
    DartdocOptionArgOnly<bool>('allowNonLocalWarnings', false, resourceProvider,
        negatable: true,
        help: 'Show warnings from packages we are not documenting locally.'),

    // Options for globally enabling/disabling all warnings and errors
    // for individual packages are command-line only.  This will allow
    // meta-packages like Flutter to control whether warnings are displayed for
    // packages they don't control.
    DartdocOptionArgOnly<List<String>>(
        'allowWarningsInPackages', null, resourceProvider,
        help:
            'Package names to display warnings for (ignore all others if set).'),
    DartdocOptionArgOnly<List<String>>(
        'allowErrorsInPackages', null, resourceProvider,
        help: 'Package names to display errors for (ignore all others if set)'),
    DartdocOptionArgOnly<List<String>>(
        'ignoreWarningsInPackages', null, resourceProvider,
        help: 'Package names to ignore warnings for.  Takes priority over '
            'allow-warnings-in-packages'),
    DartdocOptionArgOnly<List<String>>(
        'ignoreErrorsInPackages', null, resourceProvider,
        help: 'Package names to ignore errors for. Takes priority over '
            'allow-errors-in-packages'),
    // Options for globally enabling/disabling warnings and errors across
    // packages.  Loaded from dartdoc_options.yaml, but command line arguments
    // will override.
    DartdocOptionArgFile<List<String>>('errors', null, resourceProvider,
        help: 'Additional warning names to force as errors.  Specify an empty '
                'list to force defaults (overriding dartdoc_options.yaml)\nDefaults:\n' +
            (packageWarningDefinitions.values
                    .where(
                        (d) => d.defaultWarningMode == PackageWarningMode.error)
                    .toList()
                      ..sort())
                .map((d) => '   ${d.warningName}: ${d.shortHelp}')
                .join('\n')),
    DartdocOptionArgFile<List<String>>('ignore', null, resourceProvider,
        help: 'Additional warning names to ignore.  Specify an empty list to '
                'force defaults (overriding dartdoc_options.yaml).\nDefaults:\n' +
            (packageWarningDefinitions.values
                    .where((d) =>
                        d.defaultWarningMode == PackageWarningMode.ignore)
                    .toList()
                      ..sort())
                .map((d) => '   ${d.warningName}: ${d.shortHelp}')
                .join('\n')),
    DartdocOptionArgFile<List<String>>('warnings', null, resourceProvider,
        help:
            'Additional warning names to show as warnings (instead of error or '
                    'ignore, if not warning by default).\nDefaults:\n' +
                (packageWarningDefinitions.values
                        .where((d) =>
                            d.defaultWarningMode == PackageWarningMode.warn)
                        .toList()
                          ..sort())
                    .map((d) => '   ${d.warningName}: ${d.shortHelp}')
                    .join('\n')),
    // Synthetic option uses a factory to build a PackageWarningOptions from all the above flags.
    DartdocOptionSyntheticOnly<PackageWarningOptions>(
      'packageWarningOptions',
      (DartdocSyntheticOption<PackageWarningOptions> option, Folder dir) =>
          PackageWarningOptions.fromOptions(option, dir, packageMetaProvider),
      resourceProvider,
    ),
  ];
}

class PackageWarningDefinition implements Comparable<PackageWarningDefinition> {
  final String warningName;
  final String shortHelp;
  final List<String> longHelp;
  final PackageWarning kind;
  final PackageWarningMode defaultWarningMode;

  const PackageWarningDefinition(this.kind, this.warningName, this.shortHelp,
      {List<String> longHelp, PackageWarningMode defaultWarningMode})
      : longHelp = longHelp ?? const [],
        defaultWarningMode = defaultWarningMode ?? PackageWarningMode.warn;

  @override
  int compareTo(PackageWarningDefinition other) {
    return warningName.compareTo(other.warningName);
  }
}

/// Same as [packageWarningDefinitions], except keyed by the warning name.
final Map<String, PackageWarningDefinition> packageWarningsByName =
    Map.fromEntries(packageWarningDefinitions.values
        .map((definition) => MapEntry(definition.warningName, definition)));

/// Provides description text and command line flags for warnings.
/// TODO(jcollins-g): Actually use this for command line flags.
final Map<PackageWarning, PackageWarningDefinition> packageWarningDefinitions =
    const {
  PackageWarning.ambiguousDocReference: PackageWarningDefinition(
      PackageWarning.ambiguousDocReference,
      'ambiguous-doc-reference',
      'A comment reference could refer to two or more different objects'),
  PackageWarning.ambiguousReexport: PackageWarningDefinition(
      PackageWarning.ambiguousReexport,
      'ambiguous-reexport',
      'A symbol is exported from private to public in more than one library and dartdoc can not determine which one is canonical',
      longHelp: [
        "Use {@canonicalFor @@name@@} in the desired library's documentation to resolve",
        "the ambiguity and/or override dartdoc's decision, or structure your package ",
        'so the reexport is less ambiguous.  The symbol will still be referenced in ',
        'all candidates -- this only controls the location where it will be written ',
        'and which library will be displayed in navigation for the relevant pages.',
        'The flag --ambiguous-reexport-scorer-min-confidence allows you to set the',
        'threshold at which this warning will appear.'
      ]),
  PackageWarning.ignoredCanonicalFor: PackageWarningDefinition(
      PackageWarning.ignoredCanonicalFor,
      'ignored-canonical-for',
      'A @canonicalFor tag refers to a library which this symbol can not be '
          'canonical for'),
  PackageWarning.noCanonicalFound: PackageWarningDefinition(
      PackageWarning.noCanonicalFound,
      'no-canonical-found',
      'A symbol is part of the public interface for this package, but no '
          'library documented with this package documents it so dartdoc can '
          'not link to it'),
  PackageWarning.noDefiningLibraryFound: PackageWarningDefinition(
      PackageWarning.noDefiningLibraryFound,
      'no-defining-library-found',
      'The defining library for an element could not be found; the library may '
          'be imported or exported with a non-standard URI',
      defaultWarningMode: PackageWarningMode.error),
  PackageWarning.notImplemented: PackageWarningDefinition(
      PackageWarning.notImplemented,
      'not-implemented',
      'The code makes use of a feature that is not yet implemented in dartdoc'),
  PackageWarning.noDocumentableLibrariesInPackage: PackageWarningDefinition(
    PackageWarning.noDocumentableLibrariesInPackage,
    'no-documentable-libraries',
    'The package is to be documented but has no Dart libraries to document',
    longHelp: [
      'Dartdoc could not find any public libraries to document in @@name@@, ',
      'but documentation was requested.  This might be expected for an ',
      'asset only package, in which case, disable this warning in your ',
      'dartdoc_options.yaml file.',
    ],
  ),
  PackageWarning.noLibraryLevelDocs: PackageWarningDefinition(
      PackageWarning.noLibraryLevelDocs,
      'no-library-level-docs',
      'There are no library level docs for this library'),
  PackageWarning.packageOrderGivesMissingPackageName: PackageWarningDefinition(
      PackageWarning.packageOrderGivesMissingPackageName,
      'category-order-gives-missing-package-name',
      'The category-order flag on the command line was given the name of a nonexistent package'),
  PackageWarning.reexportedPrivateApiAcrossPackages: PackageWarningDefinition(
      PackageWarning.reexportedPrivateApiAcrossPackages,
      'reexported-private-api-across-packages',
      'One or more libraries reexports private API members from outside its own package'),
  PackageWarning.unresolvedDocReference: PackageWarningDefinition(
      PackageWarning.unresolvedDocReference,
      'unresolved-doc-reference',
      'A comment reference could not be found in parameters, enclosing class, enclosing library, or at the top level of any documented library with the package'),
  PackageWarning.brokenLink: PackageWarningDefinition(PackageWarning.brokenLink,
      'broken-link', 'Dartdoc generated a link to a non-existent file'),
  PackageWarning.unknownDirective: PackageWarningDefinition(
      PackageWarning.unknownDirective,
      'unknown-directive',
      'A comment contains an unknown directive'),
  PackageWarning.unknownMacro: PackageWarningDefinition(
      PackageWarning.unknownMacro,
      'unknown-macro',
      'A comment reference contains an unknown macro'),
  PackageWarning.orphanedFile: PackageWarningDefinition(
      PackageWarning.orphanedFile,
      'orphaned-file',
      'Dartdoc generated files that are unreachable from the index'),
  PackageWarning.unknownFile: PackageWarningDefinition(
      PackageWarning.unknownFile,
      'unknown-file',
      'A leftover file exists in the tree that dartdoc did not write in this pass'),
  PackageWarning.missingFromSearchIndex: PackageWarningDefinition(
      PackageWarning.missingFromSearchIndex,
      'missing-from-search-index',
      'A file generated by dartdoc is not present in the generated index.json'),
  PackageWarning.typeAsHtml: PackageWarningDefinition(
      PackageWarning.typeAsHtml,
      'type-as-html',
      'Use of <> in a comment for type parameters is being treated as HTML by markdown',
      defaultWarningMode: PackageWarningMode.ignore),
  PackageWarning.invalidParameter: PackageWarningDefinition(
      PackageWarning.invalidParameter,
      'invalid-parameter',
      'A parameter given to a dartdoc directive was invalid.',
      defaultWarningMode: PackageWarningMode.error),
  PackageWarning.toolError: PackageWarningDefinition(PackageWarning.toolError,
      'tool-error', 'Unable to execute external tool.',
      defaultWarningMode: PackageWarningMode.error),
  PackageWarning.deprecated: PackageWarningDefinition(PackageWarning.deprecated,
      'deprecated', 'A dartdoc directive has a deprecated format.'),
  PackageWarning.unresolvedExport: PackageWarningDefinition(
      PackageWarning.unresolvedExport,
      'unresolved-export',
      'An export refers to a URI that cannot be resolved.',
      defaultWarningMode: PackageWarningMode.error),
  PackageWarning.duplicateFile: PackageWarningDefinition(
      PackageWarning.duplicateFile,
      'duplicate-file',
      'Dartdoc is trying to write to a duplicate filename based on the names of Dart symbols.',
      longHelp: [
        'Dartdoc generates a path and filename to write to for each symbol.',
        '@@name@@ conflicts with another symbol in the generated path, and',
        'therefore can not be written out.  Changing the name, library name, or',
        'class name (if appropriate) of one of the conflicting items can resolve',
        "the conflict.   Alternatively, use the @nodoc tag in one symbol's",
        'documentation comments to hide it.'
      ],
      defaultWarningMode: PackageWarningMode.error),
  PackageWarning.missingConstantConstructor: PackageWarningDefinition(
      PackageWarning.missingConstantConstructor,
      'missing-constant-constructor',
      'Dartdoc can not show the value of a constant because its constructor could not be resolved.',
      longHelp: [
        'To resolve a constant into its literal value, Dartdoc relies on the',
        "analyzer to resolve the constructor.  The analyzer didn't provide",
        'the constructor for @@name@@, which is usually due to an error in the',
        'code.  Use the analyzer to find missing imports.',
      ],
      // Defaults to ignore as this doesn't impact the docs severely but is
      // useful for debugging package structure.
      defaultWarningMode: PackageWarningMode.ignore),
};

/// Something that package warnings can be called on.  Optionally associated
/// with an analyzer [element].
abstract class Warnable implements Canonicalization {
  void warn(PackageWarning warning,
      {String message, Iterable<Locatable> referredFrom});

  Element get element;

  Warnable get enclosingElement;

  Package get package;
}

// The kinds of warnings that can be displayed when documenting a package.
enum PackageWarning {
  ambiguousDocReference,
  ambiguousReexport,
  ignoredCanonicalFor,
  noCanonicalFound,
  noDefiningLibraryFound,
  notImplemented,
  noDocumentableLibrariesInPackage,
  noLibraryLevelDocs,
  packageOrderGivesMissingPackageName,
  reexportedPrivateApiAcrossPackages,
  unresolvedDocReference,
  unknownDirective,
  unknownMacro,
  unknownHtmlFragment,
  brokenLink,
  duplicateFile,
  orphanedFile,
  unknownFile,
  missingFromSearchIndex,
  typeAsHtml,
  invalidParameter,
  toolError,
  deprecated,
  unresolvedExport,
  missingConstantConstructor,
  missingExampleFile,
}

/// Used to declare defaults for a particular package warning.
enum PackageWarningMode {
  ignore,
  warn,
  error,
}

/// Warnings it is OK to skip if we can determine the warnable isn't documented.
/// In particular, this set should not include warnings around public/private
/// or canonicalization problems, because those can break the isDocumented()
/// check.
final Set<PackageWarning> skipWarningIfNotDocumentedFor = {
  PackageWarning.unresolvedDocReference,
  PackageWarning.typeAsHtml
};

class PackageWarningOptions {
  final Map<PackageWarning, PackageWarningMode> warningModes = {};

  PackageWarningOptions() {
    for (var definition in packageWarningDefinitions.values) {
      switch (definition.defaultWarningMode) {
        case PackageWarningMode.warn:
          {
            warn(definition.kind);
          }
          break;
        case PackageWarningMode.error:
          {
            error(definition.kind);
          }
          break;
        case PackageWarningMode.ignore:
          {
            ignore(definition.kind);
          }
          break;
      }
    }
  }

  static PackageWarningOptions fromOptions(
    DartdocSyntheticOption<PackageWarningOptions> option,
    Folder dir,
    PackageMetaProvider packageMetaProvider,
  ) {
    // First, initialize defaults.
    var newOptions = PackageWarningOptions();
    var packageMeta = packageMetaProvider.fromDir(dir);

    // Interpret errors/warnings/ignore options.  In the event of conflict, warning overrides error and
    // ignore overrides warning.
    for (String warningName in option.parent['errors'].valueAt(dir) ?? []) {
      if (packageWarningsByName[warningName] != null) {
        newOptions.error(packageWarningsByName[warningName].kind);
      }
    }
    for (String warningName in option.parent['warnings'].valueAt(dir) ?? []) {
      if (packageWarningsByName[warningName] != null) {
        newOptions.warn(packageWarningsByName[warningName].kind);
      }
    }
    for (String warningName in option.parent['ignore'].valueAt(dir) ?? []) {
      if (packageWarningsByName[warningName] != null) {
        newOptions.ignore(packageWarningsByName[warningName].kind);
      }
    }

    // Check whether warnings are allowed at all in this package.
    List<String> allowWarningsInPackages =
        option.parent['allowWarningsInPackages'].valueAt(dir);
    List<String> allowErrorsInPackages =
        option.parent['allowErrorsInPackages'].valueAt(dir);
    List<String> ignoreWarningsInPackages =
        option.parent['ignoreWarningsInPackages'].valueAt(dir);
    List<String> ignoreErrorsInPackages =
        option.parent['ignoreErrorsInPackages'].valueAt(dir);
    if (allowWarningsInPackages != null &&
        !allowWarningsInPackages.contains(packageMeta.name)) {
      PackageWarning.values
          .forEach((PackageWarning kind) => newOptions.ignore(kind));
    }
    if (allowErrorsInPackages != null &&
        !allowWarningsInPackages.contains(packageMeta.name)) {
      PackageWarning.values
          .forEach((PackageWarning kind) => newOptions.ignore(kind));
    }
    if (ignoreWarningsInPackages != null &&
        ignoreWarningsInPackages.contains(packageMeta.name)) {
      PackageWarning.values
          .forEach((PackageWarning kind) => newOptions.ignore(kind));
    }
    if (ignoreErrorsInPackages != null &&
        ignoreErrorsInPackages.contains(packageMeta.name)) {
      PackageWarning.values
          .forEach((PackageWarning kind) => newOptions.ignore(kind));
    }
    return newOptions;
  }

  void ignore(PackageWarning kind) =>
      warningModes[kind] = PackageWarningMode.ignore;

  void warn(PackageWarning kind) =>
      warningModes[kind] = PackageWarningMode.warn;

  void error(PackageWarning kind) =>
      warningModes[kind] = PackageWarningMode.error;

  PackageWarningMode getMode(PackageWarning kind) => warningModes[kind];
}

class PackageWarningCounter {
  final Map<Element, Set<Tuple2<PackageWarning, String>>> countedWarnings = {};
  final _items = <Jsonable>[];
  final _displayedWarningCounts = <PackageWarning, int>{};
  final PackageGraph packageGraph;

  PackageWarningCounter(this.packageGraph);

  /// Actually write out the warning.  Assumes it is already counted with add.
  void _writeWarning(PackageWarning kind, PackageWarningMode mode,
      bool verboseWarnings, String name, String fullMessage) {
    if (mode == PackageWarningMode.ignore) {
      return;
    }
    String type;
    if (mode == PackageWarningMode.error) {
      type = 'error';
    } else if (mode == PackageWarningMode.warn) {
      type = 'warning';
    }
    if (type != null) {
      var entry = '  $type: $fullMessage';
      _displayedWarningCounts.putIfAbsent(kind, () => 0);
      _displayedWarningCounts[kind] += 1;
      if (_displayedWarningCounts[kind] == 1 &&
          verboseWarnings &&
          packageWarningDefinitions[kind].longHelp.isNotEmpty) {
        // First time we've seen this warning.  Give a little extra info.
        final separator = '\n            ';
        final nameSub = r'@@name@@';
        var verboseOut =
            '$separator${packageWarningDefinitions[kind].longHelp.join(separator)}'
                .replaceAll(nameSub, name);
        entry = '$entry$verboseOut';
      }
      assert(entry == entry.trimRight());
      _items.add(_JsonWarning(type, kind, fullMessage, entry));
    }
    for (var item in _items) {
      logWarning(item);
    }
    _items.clear();
  }

  /// Returns true if we've already warned for this.
  bool hasWarning(Warnable element, PackageWarning kind, String message) {
    var warningData = Tuple2<PackageWarning, String>(kind, message);
    if (countedWarnings.containsKey(element?.element)) {
      return countedWarnings[element?.element].contains(warningData);
    }
    return false;
  }

  /// Adds the warning to the counter, and writes out the fullMessage string
  /// if configured to do so.
  void addWarning(Warnable element, PackageWarning kind, String message,
      String fullMessage) {
    assert(!hasWarning(element, kind, message));
    // TODO(jcollins-g): Make addWarning not accept nulls for element.
    PackageWarningOptionContext config =
        element?.config ?? packageGraph.defaultPackage.config;
    var warningMode = config.packageWarningOptions.getMode(kind);
    if (!config.allowNonLocalWarnings && !(element?.package?.isLocal ?? true)) {
      warningMode = PackageWarningMode.ignore;
    }
    if (warningMode == PackageWarningMode.warn) {
      warningCount += 1;
    } else if (warningMode == PackageWarningMode.error) {
      errorCount += 1;
    }
    var warningData = Tuple2<PackageWarning, String>(kind, message);
    countedWarnings.putIfAbsent(element?.element, () => {}).add(warningData);
    _writeWarning(kind, warningMode, config.verboseWarnings,
        element?.fullyQualifiedName, fullMessage);
  }

  int errorCount = 0;
  int warningCount = 0;

  @override
  String toString() {
    var errors = '$errorCount ${errorCount == 1 ? "error" : "errors"}';
    var warnings =
        '$warningCount ${warningCount == 1 ? "warning" : "warnings"}';
    return [errors, warnings].join(', ');
  }
}

class _JsonWarning extends Jsonable {
  final String type;
  final PackageWarning kind;
  final String message;

  @override
  final String text;

  _JsonWarning(this.type, this.kind, this.message, this.text);

  @override
  Map<String, dynamic> toJson() => {
        'type': type,
        'kind': packageWarningDefinitions[kind].warningName,
        'message': message,
        'text': text
      };
}