readLints function

LintState readLints(
  1. String optionsPath, {
  2. required String? read(
    1. String path
    ),
  3. required String? packageDir(
    1. String path
    ),
})

Reads the lint rules in force for the options file at optionsPath.

Follows include: — a string or, since Dart 3.6, a list — the way the analyzer merges it: every included file first, in order, then the file's own rules on top, so a later word wins. linter: rules: is either a list (each entry switched on) or a map (true on, false off). A rule that analyzer: errors: sets to ignore is off, whatever enabled it.

Pure: read returns a file's contents or null when it does not exist, and packageDir returns the directory a package:<name>/ URI starts in — the package's lib/ — or null when the package is not resolved. Paths are written with /.

Implementation

LintState readLints(
  String optionsPath, {
  required String? Function(String path) read,
  required String? Function(String package) packageDir,
}) {
  final enabled = <String, String>{};
  final ignored = <String>{};
  final problems = <String>[];
  final visiting = <String>{};

  void apply(String path, String label) {
    if (!visiting.add(path)) {
      problems.add('$label includes itself, directly or through another '
          'file. It is read once.');
      return;
    }

    final text = read(path);
    if (text == null) {
      problems.add('$label could not be read. Its rules are unknown here.');
      visiting.remove(path);
      return;
    }

    final Object? yaml;
    try {
      yaml = loadYaml(text);
    } on Object catch (error) {
      problems.add('$label is not valid YAML — '
          '${'$error'.split('\n').first.replaceFirst(RegExp('^Error on '), '')}'
          '. Its rules are unknown here.');
      visiting.remove(path);
      return;
    }
    if (yaml is! YamlMap) {
      visiting.remove(path);
      return;
    }

    final include = yaml['include'];
    final includes = include is String
        ? [include]
        : include is YamlList
            ? include.whereType<String>().toList()
            : const <String>[];
    for (final reference in includes) {
      final target =
          _resolveInclude(reference, from: path, packageDir: packageDir);
      if (target == null) {
        problems.add('`include: $reference` in $label does not resolve — run '
            '`dart pub get`, so the rules it brings can be read.');
        continue;
      }
      apply(target, reference);
    }

    final linter = yaml['linter'];
    final rules = linter is YamlMap ? linter['rules'] : null;
    if (rules is YamlList) {
      for (final rule in rules.whereType<String>()) {
        enabled[rule] = label;
      }
    } else if (rules is YamlMap) {
      for (final entry in rules.entries) {
        final rule = '${entry.key}';
        // `directives_ordering:` with no value switches nothing on — the
        // analyzer reads it as off, and an include's `true` still stands.
        if (entry.value == null) continue;
        if (entry.value == false) {
          enabled.remove(rule);
        } else {
          enabled[rule] = label;
        }
      }
    }

    final analyzer = yaml['analyzer'];
    final errors = analyzer is YamlMap ? analyzer['errors'] : null;
    if (errors is YamlMap) {
      for (final entry in errors.entries) {
        final rule = '${entry.key}';
        if (entry.value == 'ignore') {
          ignored.add(rule);
        } else {
          ignored.remove(rule);
        }
      }
    }

    visiting.remove(path);
  }

  apply(_normalize(optionsPath), 'analysis_options.yaml');
  enabled.removeWhere((rule, _) => ignored.contains(rule));
  return LintState(enabled, problems);
}