checkDocCoverage function

Future<DocCoverageReport> checkDocCoverage({ required DocCoverageManifest manifest, required String containerRoot, })

Walks manifest against the tree under containerRoot.

Implementation

Future<DocCoverageReport> checkDocCoverage({
  required DocCoverageManifest manifest,
  required String containerRoot,
}) async {
  final violations = <DocCoverageViolation>[];
  final results = <DocCoverageResult>[];
  final floors = <String, int>{};

  final measured = {for (final e in manifest.entries) e.path};
  for (final path in manifest.exempt) {
    if (measured.contains(path)) {
      violations.add(
        DocCoverageViolation(
          path,
          'is exempt (tom_specs_documentation_standard.md §5: '
          'generated, coverage is the emitter\'s '
          'responsibility) but carries a threshold — remove the entry',
        ),
      );
    }
  }
  for (final path in manifest.excluded) {
    if (measured.contains(path)) {
      violations.add(
        DocCoverageViolation(
          path,
          'is excluded from documentation scope '
          '(tom_specs_documentation_standard.md §6) but carries a '
          'threshold — remove the entry',
        ),
      );
    }
  }

  for (final entry in manifest.entries) {
    floors[entry.path] = entry.floor;
    final abs = p.join(containerRoot, entry.path);
    if (!Directory(abs).existsSync()) {
      violations.add(
        DocCoverageViolation(
          entry.path,
          'is in the manifest but no such directory exists',
        ),
      );
      continue;
    }
    final r = await measurePackage(packagePath: abs, relativePath: entry.path);
    results.add(r);

    if (!r.lintEnabled) {
      violations.add(
        DocCoverageViolation(
          entry.path,
          'does not enable `public_member_api_docs` in its '
          'analysis_options.yaml — the gate records the bar, that lint holds '
          'it at edit time, and a measured package needs both',
        ),
      );
    }
    if (r.percent < entry.floor) {
      final missing = r.undocumented.take(5).join(', ');
      violations.add(
        DocCoverageViolation(
          entry.path,
          'coverage ${r.percent}% is below its floor of ${entry.floor}% '
          '(${r.documented}/${r.total}); undocumented: $missing'
          '${r.undocumented.length > 5 ? ", +${r.undocumented.length - 5} more" : ""}',
        ),
      );
    }
  }

  DocCoverageReport.bindFloors(floors);
  return DocCoverageReport(results: results, violations: violations);
}