pkg/api_summary/lib/api_summary.dart

// Copyright (c) 2026, 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/file_system/physical_file_system.dart';
import 'src/api_description.dart';
import 'src/api_summary_customizer.dart';
import 'src/node.dart';

export 'src/api_summary_customizer.dart' show ApiSummaryCustomizer;

/// Creates a human-readable text summary of the public API of a package, in a
/// format suitable for auditing with a `diff` tool.
///
/// [packagePath] is the path to the directory containing the package's
/// `pubspec.yaml` file.
///
/// [packageName] is the name of the package.
///
/// If [createCustomizer] is provided, it will be called to create an instance
/// of [ApiSummaryCustomizer] which will be used to customize the behavior of
/// the tool.
Future<String> summarizePackage(
  String packagePath,
  String packageName, {
  ApiSummaryCustomizer Function()? createCustomizer,
}) async {
  var provider = PhysicalResourceProvider.INSTANCE;
  var libPath = provider.pathContext.join(packagePath, 'lib');
  var collection = AnalysisContextCollection(
    resourceProvider: provider,
    includedPaths: [libPath],
  );
  // Use `.single` to make sure that `collection` just contains a single
  // context. This ensures that `publicApi.build` will see all the files in
  // the package.
  var context = collection.contexts.single;
  var publicApi = ApiDescription(
    packageName,
    createCustomizer?.call() ?? ApiSummaryCustomizer(),
  );
  var stringBuffer = StringBuffer();
  printNodes(stringBuffer, await publicApi.build(context));
  return stringBuffer.toString();
}