Skip to content

Commit 33b44d2

Browse files
srawlinssrawlins
authored
Migrate doc-related tasks to package:args commands (#3459)
1 parent 2522559 commit 33b44d2

File tree

4 files changed

+241
-158
lines changed

4 files changed

+241
-158
lines changed

‎tool/grind.dart

Lines changed: 12 additions & 155 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ import 'package:dartdoc/src/package_meta.dart';
1111
import 'package:grinder/grinder.dart';
1212
import 'package:path/path.dart' as p;
1313

14-
import 'subprocess_launcher.dart';
14+
import 'src/subprocess_launcher.dart';
15+
import 'src/warnings_collection.dart';
1516
import 'task.dart' as task;
1617

1718
void main(List<String> args) => grind(args);
@@ -105,8 +106,6 @@ Future<FlutterRepo> get cleanFlutterRepo async {
105106

106107
final String _dartdocDocsPath = createTempSync('dartdoc').path;
107108

108-
final Directory _sdkDocsDir = createTempSync('sdkdocs').absolute;
109-
110109
Directory cleanFlutterDir = Directory(
111110
p.join(p.context.resolveTildePath('~/.dartdoc_grinder'), 'cleanFlutter'));
112111

@@ -243,107 +242,7 @@ void presubmit() {}
243242
void buildbot() {}
244243

245244
@Task('Generate docs for the Dart SDK')
246-
Future<void> buildSdkDocs() async {
247-
log('building SDK docs');
248-
await _buildSdkDocs(_sdkDocsDir.path, Future.value(Directory.current.path));
249-
}
250-
251-
class WarningsCollection {
252-
final String tempDir;
253-
final Map<String, int> warningKeyCounts;
254-
final String branch;
255-
final String? pubCachePath;
256-
257-
WarningsCollection(this.tempDir, this.pubCachePath, this.branch)
258-
: warningKeyCounts = {};
259-
260-
static const String kPubCachePathReplacement = '_xxxPubDirectoryxxx_';
261-
static const String kTempDirReplacement = '_xxxTempDirectoryxxx_';
262-
263-
String _toKey(String text) {
264-
var key = text.replaceAll(tempDir, kTempDirReplacement);
265-
var pubCachePath = this.pubCachePath;
266-
if (pubCachePath != null) {
267-
key = key.replaceAll(pubCachePath, kPubCachePathReplacement);
268-
}
269-
return key;
270-
}
271-
272-
String _fromKey(String text) {
273-
var key = text.replaceAll(kTempDirReplacement, tempDir);
274-
if (pubCachePath != null) {
275-
key = key.replaceAll(kPubCachePathReplacement, pubCachePath!);
276-
}
277-
return key;
278-
}
279-
280-
void add(String text) {
281-
var key = _toKey(text);
282-
warningKeyCounts.update(key, (e) => e + 1, ifAbsent: () => 1);
283-
}
284-
285-
/// Output formatter for comparing warnings. `this` is the original.
286-
String getPrintableWarningDelta(String title, WarningsCollection current) {
287-
var printBuffer = StringBuffer();
288-
var quantityChangedOuts = <String>{};
289-
var onlyOriginal = <String>{};
290-
var onlyCurrent = <String>{};
291-
var identical = <String>{};
292-
var allKeys = <String>{
293-
...warningKeyCounts.keys,
294-
...current.warningKeyCounts.keys
295-
};
296-
297-
for (var key in allKeys) {
298-
if (warningKeyCounts.containsKey(key) &&
299-
!current.warningKeyCounts.containsKey(key)) {
300-
onlyOriginal.add(key);
301-
} else if (!warningKeyCounts.containsKey(key) &&
302-
current.warningKeyCounts.containsKey(key)) {
303-
onlyCurrent.add(key);
304-
} else if (warningKeyCounts.containsKey(key) &&
305-
current.warningKeyCounts.containsKey(key) &&
306-
warningKeyCounts[key] != current.warningKeyCounts[key]) {
307-
quantityChangedOuts.add(key);
308-
} else {
309-
identical.add(key);
310-
}
311-
}
312-
313-
if (onlyOriginal.isNotEmpty) {
314-
printBuffer.writeln(
315-
'*** $title : ${onlyOriginal.length} warnings from $branch, missing in ${current.branch}:');
316-
for (var key in onlyOriginal) {
317-
printBuffer.writeln(_fromKey(key));
318-
}
319-
}
320-
if (onlyCurrent.isNotEmpty) {
321-
printBuffer.writeln(
322-
'*** $title : ${onlyCurrent.length} new warnings in ${current.branch}, missing in $branch');
323-
for (var key in onlyCurrent) {
324-
printBuffer.writeln(current._fromKey(key));
325-
}
326-
}
327-
if (quantityChangedOuts.isNotEmpty) {
328-
printBuffer.writeln('*** $title : Identical warning quantity changed');
329-
for (var key in quantityChangedOuts) {
330-
printBuffer.writeln(
331-
'* Appeared ${warningKeyCounts[key]} times in $branch, ${current.warningKeyCounts[key]} in ${current.branch}:');
332-
printBuffer.writeln(current._fromKey(key));
333-
}
334-
}
335-
if (onlyOriginal.isEmpty &&
336-
onlyCurrent.isEmpty &&
337-
quantityChangedOuts.isEmpty) {
338-
printBuffer.writeln(
339-
'*** $title : No difference in warning output from $branch to ${current.branch}${allKeys.isEmpty ? "" : " (${allKeys.length} warnings found)"}');
340-
} else if (identical.isNotEmpty) {
341-
printBuffer.writeln(
342-
'*** $title : Difference in warning output found for ${allKeys.length - identical.length} warnings (${allKeys.length} warnings found)"');
343-
}
344-
return printBuffer.toString();
345-
}
346-
}
245+
Future<void> buildSdkDocs() async => await task.docSdk();
347246

348247
/// Returns a map of warning texts to the number of times each has been seen.
349248
WarningsCollection jsonMessageIterableToWarnings(
@@ -363,27 +262,6 @@ WarningsCollection jsonMessageIterableToWarnings(
363262
return warningTexts;
364263
}
365264

366-
@Task('Display delta in SDK warnings')
367-
Future<void> compareSdkWarnings() async {
368-
var originalDartdocSdkDocs =
369-
Directory.systemTemp.createTempSync('dartdoc-comparison-sdkdocs');
370-
var originalDartdoc = createComparisonDartdoc();
371-
var currentDartdocSdkBuild = _buildSdkDocs(
372-
_sdkDocsDir.path, Future.value(Directory.current.path), 'current');
373-
var originalDartdocSdkBuild =
374-
_buildSdkDocs(originalDartdocSdkDocs.path, originalDartdoc, 'original');
375-
var currentDartdocWarnings = jsonMessageIterableToWarnings(
376-
await currentDartdocSdkBuild, _sdkDocsDir.path, null, 'HEAD');
377-
var originalDartdocWarnings = jsonMessageIterableToWarnings(
378-
await originalDartdocSdkBuild,
379-
originalDartdocSdkDocs.absolute.path,
380-
null,
381-
dartdocOriginalBranch);
382-
383-
print(originalDartdocWarnings.getPrintableWarningDelta(
384-
'SDK docs', currentDartdocWarnings));
385-
}
386-
387265
/// Helper function to create a clean version of dartdoc (based on the current
388266
/// directory, assumed to be a git repository). Uses [dartdocOriginalBranch]
389267
/// to checkout a branch or tag.
@@ -468,29 +346,6 @@ Future<void> testWithAnalyzerSdk() async {
468346
}
469347
}
470348

471-
Future<Iterable<Map<String, Object?>>> _buildSdkDocs(
472-
String sdkDocsPath, Future<String> futureCwd,
473-
[String label = '']) async {
474-
if (label != '') label = '-$label';
475-
var launcher = SubprocessLauncher('build-sdk-docs$label');
476-
var cwd = await futureCwd;
477-
await launcher.runStreamed(Platform.resolvedExecutable, ['pub', 'get'],
478-
workingDirectory: cwd);
479-
return await launcher.runStreamed(
480-
Platform.resolvedExecutable,
481-
[
482-
'--enable-asserts',
483-
p.join('bin', 'dartdoc.dart'),
484-
'--output',
485-
sdkDocsPath,
486-
'--sdk-docs',
487-
'--json',
488-
'--show-progress',
489-
..._extraDartdocParameters,
490-
],
491-
workingDirectory: cwd);
492-
}
493-
494349
Future<Iterable<Map<String, Object?>>> _buildTestPackageDocs(
495350
String outputDir, String cwd,
496351
{List<String> params = const [],
@@ -609,7 +464,7 @@ Future<void> serveSdkDocs() async {
609464
'--port',
610465
'8000',
611466
'--path',
612-
_sdkDocsDir.path,
467+
task.sdkDocsDir.path,
613468
]);
614469
}
615470

@@ -638,7 +493,7 @@ Future<void> compareFlutterWarnings() async {
638493
envOriginal['PUB_CACHE'],
639494
dartdocOriginalBranch);
640495

641-
print(originalDartdocWarnings.getPrintableWarningDelta(
496+
print(originalDartdocWarnings.warningDeltaText(
642497
'Flutter repo', currentDartdocWarnings));
643498

644499
if (Platform.environment['SERVE_FLUTTER'] == '1') {
@@ -1076,7 +931,7 @@ void validateSdkDocs() {
1076931
const expectedLibCounts = 0;
1077932
const expectedSubLibCount = {19, 20, 21};
1078933
const expectedTotalCount = {19, 20, 21};
1079-
var indexHtml = joinFile(_sdkDocsDir, ['index.html']);
934+
var indexHtml = joinFile(task.sdkDocsDir, ['index.html']);
1080935
if (!indexHtml.existsSync()) {
1081936
fail("No 'index.html' found for the SDK docs");
1082937
}
@@ -1098,17 +953,19 @@ void validateSdkDocs() {
1098953
log('$foundSubLibs index.html dart: entries in categories found');
1099954

1100955
// check for the existence of certain files/dirs
1101-
var libsLength =
1102-
_sdkDocsDir.listSync().where((fs) => fs.path.contains('dart-')).length;
956+
var libsLength = task.sdkDocsDir
957+
.listSync()
958+
.where((fs) => fs.path.contains('dart-'))
959+
.length;
1103960
if (!expectedTotalCount.contains(libsLength)) {
1104961
fail('Docs not generated for all the SDK libraries; expected '
1105962
'$expectedTotalCount directories, but $libsLength directories were '
1106963
'generated');
1107964
}
1108965
log("Found $libsLength 'dart:' libraries");
1109966

1110-
var futureConstFile =
1111-
joinFile(_sdkDocsDir, [p.join('dart-async', 'Future', 'Future.html')]);
967+
var futureConstFile = joinFile(
968+
task.sdkDocsDir, [p.join('dart-async', 'Future', 'Future.html')]);
1112969
if (!futureConstFile.existsSync()) {
1113970
fail('no Future.html found for dart:async Future constructor');
1114971
}

‎tool/subprocess_launcher.dart renamed to ‎tool/src/subprocess_launcher.dart

File renamed without changes.

‎tool/src/warnings_collection.dart

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
// Copyright (c) 2023, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
5+
class WarningsCollection {
6+
final String dir;
7+
final Map<String, int> warningKeyCounts = {};
8+
final String branch;
9+
final String? pubCachePath;
10+
11+
WarningsCollection(this.dir, this.pubCachePath, this.branch);
12+
13+
static const String kPubCachePathReplacement = '_xxxPubDirectoryxxx_';
14+
static const String kTempDirReplacement = '_xxxTempDirectoryxxx_';
15+
16+
String _toKey(String text) {
17+
var key = text.replaceAll(dir, kTempDirReplacement);
18+
var pubCachePath = this.pubCachePath;
19+
if (pubCachePath != null) {
20+
key = key.replaceAll(pubCachePath, kPubCachePathReplacement);
21+
}
22+
return key;
23+
}
24+
25+
String _fromKey(String text) {
26+
var key = text.replaceAll(kTempDirReplacement, dir);
27+
if (pubCachePath != null) {
28+
key = key.replaceAll(kPubCachePathReplacement, pubCachePath!);
29+
}
30+
return key;
31+
}
32+
33+
void add(String text) {
34+
var key = _toKey(text);
35+
warningKeyCounts.update(key, (e) => e + 1, ifAbsent: () => 1);
36+
}
37+
38+
/// Outputs formatted for comparing warnings between this (the "original"
39+
/// code) and the "current" code.
40+
String warningDeltaText(String title, WarningsCollection current) {
41+
var buffer = StringBuffer();
42+
var quantityChangedOuts = <String>{};
43+
var onlyOriginal = <String>{};
44+
var onlyCurrent = <String>{};
45+
var identical = <String>{};
46+
var allKeys = <String>{
47+
...warningKeyCounts.keys,
48+
...current.warningKeyCounts.keys,
49+
};
50+
51+
for (var key in allKeys) {
52+
if (warningKeyCounts.containsKey(key) &&
53+
!current.warningKeyCounts.containsKey(key)) {
54+
onlyOriginal.add(key);
55+
} else if (!warningKeyCounts.containsKey(key) &&
56+
current.warningKeyCounts.containsKey(key)) {
57+
onlyCurrent.add(key);
58+
} else if (warningKeyCounts.containsKey(key) &&
59+
current.warningKeyCounts.containsKey(key) &&
60+
warningKeyCounts[key] != current.warningKeyCounts[key]) {
61+
quantityChangedOuts.add(key);
62+
} else {
63+
identical.add(key);
64+
}
65+
}
66+
67+
if (onlyOriginal.isNotEmpty) {
68+
buffer
69+
.writeln('*** $title: ${onlyOriginal.length} warnings from $branch, '
70+
'missing in ${current.branch}:');
71+
for (var key in onlyOriginal) {
72+
buffer.writeln(_fromKey(key));
73+
}
74+
}
75+
if (onlyCurrent.isNotEmpty) {
76+
buffer.writeln(
77+
'*** $title: ${onlyCurrent.length} new warnings in ${current.branch}, '
78+
'missing in $branch');
79+
for (var key in onlyCurrent) {
80+
buffer.writeln(current._fromKey(key));
81+
}
82+
}
83+
if (quantityChangedOuts.isNotEmpty) {
84+
buffer.writeln('*** $title : Identical warning quantity changed');
85+
for (var key in quantityChangedOuts) {
86+
buffer.writeln('* Appeared ${warningKeyCounts[key]} times in $branch, '
87+
'${current.warningKeyCounts[key]} in ${current.branch}:');
88+
buffer.writeln(current._fromKey(key));
89+
}
90+
}
91+
if (onlyOriginal.isEmpty &&
92+
onlyCurrent.isEmpty &&
93+
quantityChangedOuts.isEmpty) {
94+
buffer.writeln('*** $title: No difference in warning output from '
95+
'$branch to ${current.branch}');
96+
if (allKeys.isNotEmpty) {
97+
buffer.write(' (${allKeys.length} warnings found)');
98+
}
99+
} else if (identical.isNotEmpty) {
100+
buffer.writeln('*** $title: Difference in warning output found for '
101+
'${allKeys.length - identical.length} warnings '
102+
'(${allKeys.length} warnings found)"');
103+
}
104+
return buffer.toString();
105+
}
106+
}

0 commit comments

Comments
 (0)