pkg/analyzer/test/verify_diagnostics_test.dart - sdk.git - Git at Google

 // Copyright (c) 2019, the Dart project authors. Please see the AUTHORS file
 // for details. 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:analyzer/dart/analysis/analysis_context_collection.dart';
 import 'package:analyzer/dart/analysis/results.dart';
 import 'package:analyzer/dart/analysis/session.dart';
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/dart/ast/token.dart';
 import 'package:analyzer/error/error.dart';
 import 'package:analyzer/file_system/physical_file_system.dart';
 import 'package:front_end/src/testing/package_root.dart' as package_root;
 import 'package:path/path.dart';
 import 'package:test/test.dart';

 import '../tool/diagnostics/generate.dart';
 import 'src/dart/resolution/driver_resolution.dart';

 /// Validate the documentation associated with the declarations of the error
 /// codes.
 void main() async {
   Context pathContext = PhysicalResourceProvider.INSTANCE.pathContext;
   //
   // Validate that the input to the generator is correct.
   //
   String packageRoot = pathContext.normalize(package_root.packageRoot);
   String analyzerPath = pathContext.join(packageRoot, 'analyzer');
   List<String> docPaths = [
     pathContext.join(
         analyzerPath, 'lib', 'src', 'dart', 'error', 'hint_codes.dart'),
     pathContext.join(analyzerPath, 'lib', 'src', 'error', 'codes.dart'),
   ];

   DocumentationValidator validator = DocumentationValidator(docPaths);
   validator.validate();
   //
   // Validate that the generator has been run.
   //
   if (pathContext.style != Style.windows) {
     String outputPath =
         pathContext.join(analyzerPath, 'tool', 'diagnostics', 'diagnostics.md');
     String actualContent = PhysicalResourceProvider.INSTANCE
         .getFile(outputPath)
         .readAsStringSync();

     StringBuffer sink = StringBuffer();
     DocumentationGenerator generator = DocumentationGenerator(docPaths);
     generator.writeDocumentation(sink);
     String expectedContent = sink.toString();

     if (actualContent != expectedContent) {
       fail('The diagnostic documentation needs to be regenerated.\n'
           'Please run tool/diagnostics/generate.dart.');
     }
   }
 }

 /// A class used to validate diagnostic documentation.
 class DocumentationValidator {
   /// The sequence used to mark the start of an error range.
   static const String errorRangeStart = '[!';

   /// The sequence used to mark the end of an error range.
   static const String errorRangeEnd = '!]';

   /// The absolute paths of the files containing the declarations of the error
   /// codes.
   final List<String> docPaths;

   /// The buffer to which validation errors are written.
   final StringBuffer buffer = StringBuffer();

   /// The path to the file currently being verified.
   String filePath;

   /// A flag indicating whether the [filePath] has already been written to the
   /// buffer.
   bool hasWrittenFilePath = false;

   /// The name of the error code currently being verified.
   String codeName;

   /// A flag indicating whether the [codeName] has already been written to the
   /// buffer.
   bool hasWrittenCodeName = false;

   /// Initialize a newly created documentation validator.
   DocumentationValidator(this.docPaths);

   /// Validate the documentation.
   void validate() async {
     AnalysisContextCollection collection = new AnalysisContextCollection(
         includedPaths: docPaths,
         resourceProvider: PhysicalResourceProvider.INSTANCE);
     for (String docPath in docPaths) {
       _validateFile(_parse(collection, docPath));
     }
     if (buffer.isNotEmpty) {
       fail(buffer.toString());
     }
   }

   /// Extract documentation from the given [field] declaration.
   List<String> _extractDoc(FieldDeclaration field) {
     Token comments = field.firstTokenAfterCommentAndMetadata.precedingComments;
     if (comments == null) {
       return null;
     }
     List<String> docs = [];
     while (comments != null) {
       String lexeme = comments.lexeme;
       if (lexeme.startsWith('// TODO')) {
         break;
       } else if (lexeme.startsWith('// ')) {
         docs.add(lexeme.substring(3));
       } else if (lexeme == '//') {
         docs.add('');
       }
       comments = comments.next;
     }
     if (docs.isEmpty) {
       return null;
     }
     return docs;
   }

   _SnippetData _extractSnippetData(String snippet) {
     int rangeStart = snippet.indexOf(errorRangeStart);
     if (rangeStart < 0) {
       _reportProblem('No error range in example');
       return _SnippetData(snippet, -1, 0);
     }
     int rangeEnd = snippet.indexOf(errorRangeEnd, rangeStart + 1);
     if (rangeEnd < 0) {
       _reportProblem('No end of error range in example');
       return _SnippetData(snippet, -1, 0);
     } else if (snippet.indexOf(errorRangeStart, rangeEnd) > 0) {
       _reportProblem('More than one error range in example');
     }
     return _SnippetData(
         snippet.substring(0, rangeStart) +
             snippet.substring(rangeStart + 1, rangeEnd) +
             snippet.substring(rangeEnd + 1),
         rangeStart,
         rangeEnd - rangeStart - 1);
   }

   /// Extract the snippets of Dart code between the start (inclusive) and end
   /// (exclusive) indexes.
   List<String> _extractSnippets(List<String> lines, int start, int end) {
     List<String> snippets = [];
     int snippetStart = lines.indexOf('```dart', start);
     while (snippetStart >= 0 && snippetStart < end) {
       int snippetEnd = lines.indexOf('```', snippetStart + 1);
       snippets.add(lines.sublist(snippetStart + 1, snippetEnd).join('\n'));
       snippetStart = lines.indexOf('```dart', snippetEnd + 1);
     }
     return snippets;
   }

   /// Use the analysis context [collection] to parse the file at the given
   /// [path] and return the result.
   ParsedUnitResult _parse(AnalysisContextCollection collection, String path) {
     AnalysisSession session = collection.contextFor(path).currentSession;
     if (session == null) {
       throw new StateError('No session for "$path"');
     }
     ParsedUnitResult result = session.getParsedUnit(path);
     if (result.state != ResultState.VALID) {
       throw new StateError('Unable to parse "$path"');
     }
     return result;
   }

   /// Report a problem with the current error code.
   void _reportProblem(String problem, {List<AnalysisError> errors = const []}) {
     if (!hasWrittenFilePath) {
       buffer.writeln();
       buffer.writeln('In $filePath');
       hasWrittenFilePath = true;
     }
     if (!hasWrittenCodeName) {
       buffer.writeln('  $codeName');
       hasWrittenCodeName = true;
     }
     buffer.writeln('    $problem');
     for (AnalysisError error in errors) {
       buffer.write(error.errorCode);
       buffer.write(' (');
       buffer.write(error.offset);
       buffer.write(', ');
       buffer.write(error.length);
       buffer.write(') ');
       buffer.writeln(error.message);
     }
   }

   /// Extract documentation from the file that was parsed to produce the given
   /// [result].
   void _validateFile(ParsedUnitResult result) {
     filePath = result.path;
     hasWrittenFilePath = false;
     CompilationUnit unit = result.unit;
     for (CompilationUnitMember declaration in unit.declarations) {
       if (declaration is ClassDeclaration) {
         String className = declaration.name.name;
         for (ClassMember member in declaration.members) {
           if (member is FieldDeclaration) {
             List<String> docs = _extractDoc(member);
             if (docs != null) {
               VariableDeclaration variable = member.fields.variables[0];
               String variableName = variable.name.name;
               codeName = '$className.$variableName';
               hasWrittenCodeName = false;

               int exampleStart = docs.indexOf('#### Example');
               int fixesStart = docs.indexOf('#### Common fixes');

               List<String> exampleSnippets =
                   _extractSnippets(docs, exampleStart + 1, fixesStart);
               for (String snippet in exampleSnippets) {
                 _SnippetData data = _extractSnippetData(snippet);
                 _validateSnippet(data.snippet, data.offset, data.length);
               }

               List<String> fixesSnippets =
                   _extractSnippets(docs, fixesStart + 1, docs.length);
               for (String snippet in fixesSnippets) {
                 _validateSnippet(snippet, -1, 0);
               }
             }
           }
         }
       }
     }
   }

   /// Resolve the [snippet]. If the [offset] is less than zero, then verify that
   /// no diagnostics are reported. If the [offset] is greater than or equal to
   /// zero, verify that one error whose name matches the current code is
   /// reported at that offset with the given [length].
   void _validateSnippet(String snippet, int offset, int length) async {
     // TODO(brianwilkerson) Implement this.
     DriverResolutionTest test = DriverResolutionTest();
     test.setUp();
     test.addTestFile(snippet);
     await test.resolveTestFile();
     List<AnalysisError> errors = test.result.errors;
     int errorCount = errors.length;
     if (offset < 0) {
       if (errorCount > 0) {
         _reportProblem('Expected no errors but found $errorCount.',
             errors: errors);
       }
     } else {
       if (errorCount == 0) {
         _reportProblem('Expected one error but found none.');
       } else if (errorCount == 1) {
         AnalysisError error = errors[0];
         if (error.errorCode != codeName) {
           _reportProblem(
               'Expected an error with code $codeName, found ${error.errorCode}.');
         }
         if (error.offset != offset) {
           _reportProblem(
               'Expected an error at $offset, found ${error.offset}.');
         }
         if (error.length != length) {
           _reportProblem(
               'Expected an error of length $length, found ${error.length}.');
         }
       } else {
         _reportProblem('Expected one error but found $errorCount.',
             errors: errors);
       }
     }
   }
 }

 /// A data holder used to return multiple values when extracting an error range
 /// from a snippet.
 class _SnippetData {
   final String snippet;
   final int offset;
   final int length;

   _SnippetData(this.snippet, this.offset, this.length);
 }
	// Copyright (c) 2019, the Dart project authors. Please see the AUTHORS file
	// for details. 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:analyzer/dart/analysis/analysis_context_collection.dart';
	import 'package:analyzer/dart/analysis/results.dart';
	import 'package:analyzer/dart/analysis/session.dart';
	import 'package:analyzer/dart/ast/ast.dart';
	import 'package:analyzer/dart/ast/token.dart';
	import 'package:analyzer/error/error.dart';
	import 'package:analyzer/file_system/physical_file_system.dart';
	import 'package:front_end/src/testing/package_root.dart' as package_root;
	import 'package:path/path.dart';
	import 'package:test/test.dart';

	import '../tool/diagnostics/generate.dart';
	import 'src/dart/resolution/driver_resolution.dart';

	/// Validate the documentation associated with the declarations of the error
	/// codes.
	void main() async {
	Context pathContext = PhysicalResourceProvider.INSTANCE.pathContext;
	//
	// Validate that the input to the generator is correct.
	//
	String packageRoot = pathContext.normalize(package_root.packageRoot);
	String analyzerPath = pathContext.join(packageRoot, 'analyzer');
	List<String> docPaths = [
	pathContext.join(
	analyzerPath, 'lib', 'src', 'dart', 'error', 'hint_codes.dart'),
	pathContext.join(analyzerPath, 'lib', 'src', 'error', 'codes.dart'),
	];

	DocumentationValidator validator = DocumentationValidator(docPaths);
	validator.validate();
	//
	// Validate that the generator has been run.
	//
	if (pathContext.style != Style.windows) {
	String outputPath =
	pathContext.join(analyzerPath, 'tool', 'diagnostics', 'diagnostics.md');
	String actualContent = PhysicalResourceProvider.INSTANCE
	.getFile(outputPath)
	.readAsStringSync();

	StringBuffer sink = StringBuffer();
	DocumentationGenerator generator = DocumentationGenerator(docPaths);
	generator.writeDocumentation(sink);
	String expectedContent = sink.toString();

	if (actualContent != expectedContent) {
	fail('The diagnostic documentation needs to be regenerated.\n'
	'Please run tool/diagnostics/generate.dart.');
	}
	}
	}

	/// A class used to validate diagnostic documentation.
	class DocumentationValidator {
	/// The sequence used to mark the start of an error range.
	static const String errorRangeStart = '[!';

	/// The sequence used to mark the end of an error range.
	static const String errorRangeEnd = '!]';

	/// The absolute paths of the files containing the declarations of the error
	/// codes.
	final List<String> docPaths;

	/// The buffer to which validation errors are written.
	final StringBuffer buffer = StringBuffer();

	/// The path to the file currently being verified.
	String filePath;

	/// A flag indicating whether the [filePath] has already been written to the
	/// buffer.
	bool hasWrittenFilePath = false;

	/// The name of the error code currently being verified.
	String codeName;

	/// A flag indicating whether the [codeName] has already been written to the
	/// buffer.
	bool hasWrittenCodeName = false;

	/// Initialize a newly created documentation validator.
	DocumentationValidator(this.docPaths);

	/// Validate the documentation.
	void validate() async {
	AnalysisContextCollection collection = new AnalysisContextCollection(
	includedPaths: docPaths,
	resourceProvider: PhysicalResourceProvider.INSTANCE);
	for (String docPath in docPaths) {
	_validateFile(_parse(collection, docPath));
	}
	if (buffer.isNotEmpty) {
	fail(buffer.toString());
	}
	}

	/// Extract documentation from the given [field] declaration.
	List<String> _extractDoc(FieldDeclaration field) {
	Token comments = field.firstTokenAfterCommentAndMetadata.precedingComments;
	if (comments == null) {
	return null;
	}
	List<String> docs = [];
	while (comments != null) {
	String lexeme = comments.lexeme;
	if (lexeme.startsWith('// TODO')) {
	break;
	} else if (lexeme.startsWith('// ')) {
	docs.add(lexeme.substring(3));
	} else if (lexeme == '//') {
	docs.add('');
	}
	comments = comments.next;
	}
	if (docs.isEmpty) {
	return null;
	}
	return docs;
	}

	_SnippetData _extractSnippetData(String snippet) {
	int rangeStart = snippet.indexOf(errorRangeStart);
	if (rangeStart < 0) {
	_reportProblem('No error range in example');
	return _SnippetData(snippet, -1, 0);
	}
	int rangeEnd = snippet.indexOf(errorRangeEnd, rangeStart + 1);
	if (rangeEnd < 0) {
	_reportProblem('No end of error range in example');
	return _SnippetData(snippet, -1, 0);
	} else if (snippet.indexOf(errorRangeStart, rangeEnd) > 0) {
	_reportProblem('More than one error range in example');
	}
	return _SnippetData(
	snippet.substring(0, rangeStart) +
	snippet.substring(rangeStart + 1, rangeEnd) +
	snippet.substring(rangeEnd + 1),
	rangeStart,
	rangeEnd - rangeStart - 1);
	}

	/// Extract the snippets of Dart code between the start (inclusive) and end
	/// (exclusive) indexes.
	List<String> _extractSnippets(List<String> lines, int start, int end) {
	List<String> snippets = [];
	int snippetStart = lines.indexOf('```dart', start);
	while (snippetStart >= 0 && snippetStart < end) {
	int snippetEnd = lines.indexOf('```', snippetStart + 1);
	snippets.add(lines.sublist(snippetStart + 1, snippetEnd).join('\n'));
	snippetStart = lines.indexOf('```dart', snippetEnd + 1);
	}
	return snippets;
	}

	/// Use the analysis context [collection] to parse the file at the given
	/// [path] and return the result.
	ParsedUnitResult _parse(AnalysisContextCollection collection, String path) {
	AnalysisSession session = collection.contextFor(path).currentSession;
	if (session == null) {
	throw new StateError('No session for "$path"');
	}
	ParsedUnitResult result = session.getParsedUnit(path);
	if (result.state != ResultState.VALID) {
	throw new StateError('Unable to parse "$path"');
	}
	return result;
	}

	/// Report a problem with the current error code.
	void _reportProblem(String problem, {List<AnalysisError> errors = const []}) {
	if (!hasWrittenFilePath) {
	buffer.writeln();
	buffer.writeln('In $filePath');
	hasWrittenFilePath = true;
	}
	if (!hasWrittenCodeName) {
	buffer.writeln(' $codeName');
	hasWrittenCodeName = true;
	}
	buffer.writeln(' $problem');
	for (AnalysisError error in errors) {
	buffer.write(error.errorCode);
	buffer.write(' (');
	buffer.write(error.offset);
	buffer.write(', ');
	buffer.write(error.length);
	buffer.write(') ');
	buffer.writeln(error.message);
	}
	}

	/// Extract documentation from the file that was parsed to produce the given
	/// [result].
	void _validateFile(ParsedUnitResult result) {
	filePath = result.path;
	hasWrittenFilePath = false;
	CompilationUnit unit = result.unit;
	for (CompilationUnitMember declaration in unit.declarations) {
	if (declaration is ClassDeclaration) {
	String className = declaration.name.name;
	for (ClassMember member in declaration.members) {
	if (member is FieldDeclaration) {
	List<String> docs = _extractDoc(member);
	if (docs != null) {
	VariableDeclaration variable = member.fields.variables[0];
	String variableName = variable.name.name;
	codeName = '$className.$variableName';
	hasWrittenCodeName = false;

	int exampleStart = docs.indexOf('#### Example');
	int fixesStart = docs.indexOf('#### Common fixes');

	List<String> exampleSnippets =
	_extractSnippets(docs, exampleStart + 1, fixesStart);
	for (String snippet in exampleSnippets) {
	_SnippetData data = _extractSnippetData(snippet);
	_validateSnippet(data.snippet, data.offset, data.length);
	}

	List<String> fixesSnippets =
	_extractSnippets(docs, fixesStart + 1, docs.length);
	for (String snippet in fixesSnippets) {
	_validateSnippet(snippet, -1, 0);
	}
	}
	}
	}
	}
	}
	}

	/// Resolve the [snippet]. If the [offset] is less than zero, then verify that
	/// no diagnostics are reported. If the [offset] is greater than or equal to
	/// zero, verify that one error whose name matches the current code is
	/// reported at that offset with the given [length].
	void _validateSnippet(String snippet, int offset, int length) async {
	// TODO(brianwilkerson) Implement this.
	DriverResolutionTest test = DriverResolutionTest();
	test.setUp();
	test.addTestFile(snippet);
	await test.resolveTestFile();
	List<AnalysisError> errors = test.result.errors;
	int errorCount = errors.length;
	if (offset < 0) {
	if (errorCount > 0) {
	_reportProblem('Expected no errors but found $errorCount.',
	errors: errors);
	}
	} else {
	if (errorCount == 0) {
	_reportProblem('Expected one error but found none.');
	} else if (errorCount == 1) {
	AnalysisError error = errors[0];
	if (error.errorCode != codeName) {
	_reportProblem(
	'Expected an error with code $codeName, found ${error.errorCode}.');
	}
	if (error.offset != offset) {
	_reportProblem(
	'Expected an error at $offset, found ${error.offset}.');
	}
	if (error.length != length) {
	_reportProblem(
	'Expected an error of length $length, found ${error.length}.');
	}
	} else {
	_reportProblem('Expected one error but found $errorCount.',
	errors: errors);
	}
	}
	}
	}

	/// A data holder used to return multiple values when extracting an error range
	/// from a snippet.
	class _SnippetData {
	final String snippet;
	final int offset;
	final int length;

	_SnippetData(this.snippet, this.offset, this.length);
	}