checkDocFolder function

TodoCitationReport checkDocFolder({ required String docDir, required TodoCorpus corpus, List<String> extraFiles = const [], TodoCitationVocabulary vocabulary = const TodoCitationVocabulary.empty(), })

Scans every *.md directly inside docDir, plus extraFiles, and classifies their citations.

Only the doc folder itself, not its subtree: the TomSpecs doc set is flat by design, and generator output lives in a sibling tree that must not be checked (a generated file is regenerated, not edited).

extraFiles is how the project READMEs join the scan — see defaultCitedReadmes. A file listed there that does not exist is skipped rather than fatal, so a project that has not been checked out beside the clitool does not read as a missing citation.

Implementation

TodoCitationReport checkDocFolder({
  required String docDir,
  required TodoCorpus corpus,
  List<String> extraFiles = const [],
  TodoCitationVocabulary vocabulary = const TodoCitationVocabulary.empty(),
}) {
  final dir = Directory(docDir);
  if (!dir.existsSync()) {
    throw ArgumentError.value(
      docDir,
      'docDir',
      'documentation folder not found',
    );
  }

  final files =
      dir
          .listSync()
          .whereType<File>()
          .where((f) => p.extension(f.path) == '.md')
          .toList()
        ..sort((a, b) => a.path.compareTo(b.path));
  for (final path in extraFiles) {
    final file = File(path);
    if (file.existsSync()) files.add(file);
  }

  final citations = <TodoCitation>[];
  for (final file in files) {
    citations.addAll(
      classifyMarkdown(
        file.readAsStringSync(),
        path: file.path,
        corpus: corpus,
        vocabulary: vocabulary,
      ),
    );
  }

  return TodoCitationReport(
    citations: citations,
    documentCount: files.length,
    corpus: corpus,
  );
}