script/tool/lib/src/readme_check_command.dart

// Copyright 2013 The Flutter Authors. 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:file/file.dart';
import 'package:git/git.dart';
import 'package:platform/platform.dart';
import 'package:yaml/yaml.dart';

import 'common/core.dart';
import 'common/package_looping_command.dart';
import 'common/process_runner.dart';
import 'common/repository_package.dart';

const String _instructionWikiUrl =
    'https://github.com/flutter/flutter/wiki/Contributing-to-Plugins-and-Packages';

/// A command to enforce README conventions across the repository.
class ReadmeCheckCommand extends PackageLoopingCommand {
  /// Creates an instance of the README check command.
  ReadmeCheckCommand(
    Directory packagesDir, {
    ProcessRunner processRunner = const ProcessRunner(),
    Platform platform = const LocalPlatform(),
    GitDir? gitDir,
  }) : super(
          packagesDir,
          processRunner: processRunner,
          platform: platform,
          gitDir: gitDir,
        ) {
    argParser.addFlag(_requireExcerptsArg,
        help: 'Require that Dart code blocks be managed by code-excerpt.');
  }

  static const String _requireExcerptsArg = 'require-excerpts';

  // Standardized capitalizations for platforms that a plugin can support.
  static const Map<String, String> _standardPlatformNames = <String, String>{
    'android': 'Android',
    'ios': 'iOS',
    'linux': 'Linux',
    'macos': 'macOS',
    'web': 'Web',
    'windows': 'Windows',
  };

  @override
  final String name = 'readme-check';

  @override
  final String description =
      'Checks that READMEs follow repository conventions.';

  @override
  bool get hasLongOutput => false;

  @override
  Future<PackageResult> runForPackage(RepositoryPackage package) async {
    final List<String> errors = _validateReadme(package.readmeFile,
        mainPackage: package, isExample: false);
    for (final RepositoryPackage packageToCheck in package.getExamples()) {
      errors.addAll(_validateReadme(packageToCheck.readmeFile,
          mainPackage: package, isExample: true));
    }

    // If there's an example/README.md for a multi-example package, validate
    // that as well, as it will be shown on pub.dev.
    final Directory exampleDir = package.directory.childDirectory('example');
    final File exampleDirReadme = exampleDir.childFile('README.md');
    if (exampleDir.existsSync() && !isPackage(exampleDir)) {
      errors.addAll(_validateReadme(exampleDirReadme,
          mainPackage: package, isExample: true));
    }

    return errors.isEmpty
        ? PackageResult.success()
        : PackageResult.fail(errors);
  }

  List<String> _validateReadme(File readme,
      {required RepositoryPackage mainPackage, required bool isExample}) {
    if (!readme.existsSync()) {
      if (isExample) {
        print('${indentation}No README for '
            '${getRelativePosixPath(readme.parent, from: mainPackage.directory)}');
        return <String>[];
      } else {
        printError('${indentation}No README found at '
            '${getRelativePosixPath(readme, from: mainPackage.directory)}');
        return <String>['Missing README.md'];
      }
    }

    print('${indentation}Checking '
        '${getRelativePosixPath(readme, from: mainPackage.directory)}...');

    final List<String> readmeLines = readme.readAsLinesSync();
    final List<String> errors = <String>[];

    final String? blockValidationError =
        _validateCodeBlocks(readmeLines, mainPackage: mainPackage);
    if (blockValidationError != null) {
      errors.add(blockValidationError);
    }

    errors.addAll(_validateBoilerplate(readmeLines,
        mainPackage: mainPackage, isExample: isExample));

    // Check if this is the main readme for a plugin, and if so enforce extra
    // checks.
    if (!isExample) {
      final Pubspec pubspec = mainPackage.parsePubspec();
      final bool isPlugin = pubspec.flutter?['plugin'] != null;
      if (isPlugin && (!mainPackage.isFederated || mainPackage.isAppFacing)) {
        final String? error = _validateSupportedPlatforms(readmeLines, pubspec);
        if (error != null) {
          errors.add(error);
        }
      }
    }

    return errors;
  }

  /// Validates that code blocks (``` ... ```) follow repository standards.
  String? _validateCodeBlocks(
    List<String> readmeLines, {
    required RepositoryPackage mainPackage,
  }) {
    final RegExp codeBlockDelimiterPattern = RegExp(r'^\s*```\s*([^ ]*)\s*');
    const String excerptTagStart = '<?code-excerpt ';
    final List<int> missingLanguageLines = <int>[];
    final List<int> missingExcerptLines = <int>[];
    bool inBlock = false;
    for (int i = 0; i < readmeLines.length; ++i) {
      final RegExpMatch? match =
          codeBlockDelimiterPattern.firstMatch(readmeLines[i]);
      if (match == null) {
        continue;
      }
      if (inBlock) {
        inBlock = false;
        continue;
      }
      inBlock = true;

      final int humanReadableLineNumber = i + 1;

      // Ensure that there's a language tag.
      final String infoString = match[1] ?? '';
      if (infoString.isEmpty) {
        missingLanguageLines.add(humanReadableLineNumber);
        continue;
      }

      // Check for code-excerpt usage if requested.
      if (getBoolArg(_requireExcerptsArg) && infoString == 'dart') {
        if (i == 0 || !readmeLines[i - 1].trim().startsWith(excerptTagStart)) {
          missingExcerptLines.add(humanReadableLineNumber);
        }
      }
    }

    String? errorSummary;

    if (missingLanguageLines.isNotEmpty) {
      for (final int lineNumber in missingLanguageLines) {
        printError('${indentation}Code block at line $lineNumber is missing '
            'a language identifier.');
      }
      printError(
          '\n${indentation}For each block listed above, add a language tag to '
          'the opening block. For instance, for Dart code, use:\n'
          '${indentation * 2}```dart\n');
      errorSummary = 'Missing language identifier for code block';
    }

    // If any blocks use code excerpts, make sure excerpting is configured
    // for the package.
    if (readmeLines.any((String line) => line.startsWith(excerptTagStart))) {
      const String buildRunnerConfigFile = 'build.excerpt.yaml';
      if (!mainPackage.getExamples().any((RepositoryPackage example) =>
          example.directory.childFile(buildRunnerConfigFile).existsSync())) {
        printError('code-excerpt tag found, but the package is not configured '
            'for excerpting. Follow the instructions at\n'
            '$_instructionWikiUrl\n'
            'for setting up a build.excerpt.yaml file.');
        errorSummary ??= 'Missing code-excerpt configuration';
      }
    }

    if (missingExcerptLines.isNotEmpty) {
      for (final int lineNumber in missingExcerptLines) {
        printError('${indentation}Dart code block at line $lineNumber is not '
            'managed by code-excerpt.');
      }
      printError(
          '\n${indentation}For each block listed above, add <?code-excerpt ...> '
          'tag on the previous line, and ensure that a build.excerpt.yaml is '
          'configured for the source example as explained at\n'
          '$_instructionWikiUrl');
      errorSummary ??= 'Missing code-excerpt management for code block';
    }

    return errorSummary;
  }

  /// Validates that the plugin has a supported platforms table following the
  /// expected format, returning an error string if any issues are found.
  String? _validateSupportedPlatforms(
      List<String> readmeLines, Pubspec pubspec) {
    // Example table following expected format:
    // |                | Android | iOS      | Web                    |
    // |----------------|---------|----------|------------------------|
    // | **Support**    | SDK 21+ | iOS 10+* | [See `camera_web `][1] |
    final int detailsLineNumber = readmeLines
        .indexWhere((String line) => line.startsWith('| **Support**'));
    if (detailsLineNumber == -1) {
      return 'No OS support table found';
    }
    final int osLineNumber = detailsLineNumber - 2;
    if (osLineNumber < 0 || !readmeLines[osLineNumber].startsWith('|')) {
      return 'OS support table does not have the expected header format';
    }

    // Utility method to convert an iterable of strings to a case-insensitive
    // sorted, comma-separated string of its elements.
    String sortedListString(Iterable<String> entries) {
      final List<String> entryList = entries.toList();
      entryList.sort(
          (String a, String b) => a.toLowerCase().compareTo(b.toLowerCase()));
      return entryList.join(', ');
    }

    // Validate that the supported OS lists match.
    final YamlMap pluginSection = pubspec.flutter!['plugin'] as YamlMap;
    final dynamic platformsEntry = pluginSection['platforms'];
    if (platformsEntry == null) {
      logWarning('Plugin not support any platforms');
      return null;
    }
    final YamlMap platformSupportMaps = platformsEntry as YamlMap;
    final Set<String> actuallySupportedPlatform =
        platformSupportMaps.keys.toSet().cast<String>();
    final Iterable<String> documentedPlatforms = readmeLines[osLineNumber]
        .split('|')
        .map((String entry) => entry.trim())
        .where((String entry) => entry.isNotEmpty);
    final Set<String> documentedPlatformsLowercase =
        documentedPlatforms.map((String entry) => entry.toLowerCase()).toSet();
    if (actuallySupportedPlatform.length != documentedPlatforms.length ||
        actuallySupportedPlatform
                .intersection(documentedPlatformsLowercase)
                .length !=
            actuallySupportedPlatform.length) {
      printError('''
${indentation}OS support table does not match supported platforms:
${indentation * 2}Actual:     ${sortedListString(actuallySupportedPlatform)}
${indentation * 2}Documented: ${sortedListString(documentedPlatformsLowercase)}
''');
      return 'Incorrect OS support table';
    }

    // Enforce a standard set of capitalizations for the OS headings.
    final Iterable<String> incorrectCapitalizations = documentedPlatforms
        .toSet()
        .difference(_standardPlatformNames.values.toSet());
    if (incorrectCapitalizations.isNotEmpty) {
      final Iterable<String> expectedVersions = incorrectCapitalizations
          .map((String name) => _standardPlatformNames[name.toLowerCase()]!);
      printError('''
${indentation}Incorrect OS capitalization: ${sortedListString(incorrectCapitalizations)}
${indentation * 2}Please use standard capitalizations: ${sortedListString(expectedVersions)}
''');
      return 'Incorrect OS support formatting';
    }

    // TODO(stuartmorgan): Add validation that the minimums in the table are
    // consistent with what the current implementations require. See
    // https://github.com/flutter/flutter/issues/84200
    return null;
  }

  /// Validates [readmeLines], outputing error messages for any issue and
  /// returning an array of error summaries (if any).
  ///
  /// Returns an empty array if validation passes.
  List<String> _validateBoilerplate(
    List<String> readmeLines, {
    required RepositoryPackage mainPackage,
    required bool isExample,
  }) {
    final List<String> errors = <String>[];

    if (_containsTemplateFlutterBoilerplate(readmeLines)) {
      printError('${indentation}The boilerplate section about getting started '
          'with Flutter should not be left in.');
      errors.add('Contains template boilerplate');
    }

    // Enforce a repository-standard message in implementation plugin examples,
    // since they aren't typical examples, which has been a source of
    // confusion for plugin clients who find them.
    if (isExample && mainPackage.isPlatformImplementation) {
      if (_containsExampleBoilerplate(readmeLines)) {
        printError('${indentation}The boilerplate should not be left in for a '
            "federated plugin implementation package's example.");
        errors.add('Contains template boilerplate');
      }
      if (!_containsImplementationExampleExplanation(readmeLines)) {
        printError('${indentation}The example README for a platform '
            'implementation package should warn readers about its intended '
            'use. Please copy the example README from another implementation '
            'package in this repository.');
        errors.add('Missing implementation package example warning');
      }
    }

    return errors;
  }

  /// Returns true if the README still has unwanted parts of the boilerplate
  /// from the `flutter create` templates.
  bool _containsTemplateFlutterBoilerplate(List<String> readmeLines) {
    return readmeLines.any((String line) =>
        line.contains('For help getting started with Flutter'));
  }

  /// Returns true if the README still has the generic description of an
  /// example from the `flutter create` templates.
  bool _containsExampleBoilerplate(List<String> readmeLines) {
    return readmeLines
        .any((String line) => line.contains('Demonstrates how to use the'));
  }

  /// Returns true if the README contains the repository-standard explanation of
  /// the purpose of a federated plugin implementation's example.
  bool _containsImplementationExampleExplanation(List<String> readmeLines) {
    return readmeLines.contains('# Platform Implementation Test App') &&
        readmeLines
            .any((String line) => line.contains('This is a test app for'));
  }
}