Generate the diagnostic pages from data files

site/lib/src/components/common/tags.dart

@@ -22,26 +22,46 @@ class Tags extends StatelessComponent {
 ///
 /// Generally displayed within a [Tags] component.
 class Tag extends StatelessComponent {
-  const Tag(this.content, {this.icon, this.title, this.label, this.color});
+  const Tag(
+    this.content, {
+    this.icon,
+    this.title,
+    this.label,
+    this.color,
+    this.link,
+  });
 
   final String content;
   final String? icon;
   final String? title;
   final String? label;
   final String? color;
+  final String? link;
 
   @override
   Component build(BuildContext context) {
+    final children = [
+      if (icon case final iconId?) MaterialIcon(iconId),
+      span([text(content)]),
+    ];
+    final attributes = {
+      'title': ?title,
+      'aria-label': ?(label ?? title),
+    };
+
+    if (link case final link?) {
+      return a(
+        href: link,
+        classes: 'tag-label',
+        attributes: attributes,
+        children,
+      );
+    }
+
     return div(
       classes: 'tag-label',
-      attributes: {
-        'title': ?title,
-        'aria-label': ?(label ?? title),
-      },
-      [
-        if (icon case final iconId?) MaterialIcon(iconId),
-        span([text(content)]),
-      ],
+      attributes: attributes,
+      children,
     );
   }
 }

site/lib/src/models/diagnostic_model.dart

@@ -0,0 +1,44 @@
+// Copyright (c) 2025, 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 'dart:convert' show jsonDecode;
+import 'dart:io';
+
+import 'package:path/path.dart' as p;
+
+import '../util.dart';
+
+extension type DiagnosticInfo.fromJson(Map<String, Object?> info) {
+  String get id => info['id'] as String;
+  String get description => info['description'] as String;
+  String? get documentation => info['documentation'] as String?;
+  bool get hasDocumentation => info['hasDocumentation'] as bool? ?? false;
+  bool get fromLint => info['fromLint'] as bool? ?? false;
+  List<String> get previousNames =>
+      (info['previousNames'] as List<Object?>).cast<String>();
+}
+
+/// Reads and parses information about diagnostics from
+/// the `src/data/diagnostics.json` file.
+List<DiagnosticInfo> readAndLoadDiagnostics() {
+  if (_loadedDiagnostics case final alreadyLoadedDiagnostics?) {
+    return alreadyLoadedDiagnostics;
+  }
+
+  final diagnosticsFile = File(
+    p.join(siteSrcDirectoryPath, 'data', 'diagnostics.json'),
+  );
+  final rawDiagnosticInfo =
+      jsonDecode(diagnosticsFile.readAsStringSync()) as List<Object?>;
+
+  final diagnostics = rawDiagnosticInfo
+      .cast<Map<String, Object?>>()
+      .map(DiagnosticInfo.fromJson)
+      .toList(growable: false);
+
+  return _loadedDiagnostics = diagnostics;
+}
+
+/// A cache of the loaded and parsed diagnostic info.
+List<DiagnosticInfo>? _loadedDiagnostics;

site/lib/src/pages/custom_pages.dart

@@ -5,12 +5,13 @@
 import 'dart:convert';
 
 import 'package:collection/collection.dart';
-import 'package:jaspr/jaspr.dart' show Component;
+import 'package:jaspr/jaspr.dart' show Component, a, p, span, text;
 import 'package:jaspr_content/jaspr_content.dart';
-import 'package:path/path.dart' as p;
+import 'package:path/path.dart' as path;
 
 import '../components/common/tags.dart';
 import '../markdown/markdown_parser.dart';
+import '../models/diagnostic_model.dart';
 import '../models/lints.dart';
 import 'glossary.dart';
 
@@ -21,6 +22,7 @@ List<MemoryPage> get allMemoryPages => [
   _allLinterRulesPage,
   _allLinterRulesJson,
   ..._lintMemoryPages,
+  ..._diagnosticMemoryPages,
 ];
 
 /// The `/resources/glossary` page which hosts the [GlossaryIndex].
@@ -42,9 +44,97 @@ MemoryPage get _glossaryPage => MemoryPage.builder(
   },
 );
 
-/// The date the lint rule docs were last extracted from the SDK.
+/// The date the diagnostic and lint docs were last extracted from the SDK.
 /// Should be in `yyyy-mm-dd` format.
-const String _lintsLastUpdated = '2025-08-16';
+const String _diagnosticsLastUpdated = '2025-12-07';
+
+/// The individual diagnostic message pages,
+/// rendered at `/tools/diagnostics/<name>`.
+List<MemoryPage> get _diagnosticMemoryPages {
+  final diagnostics = readAndLoadDiagnostics();
+
+  return [
+    for (final diagnostic in diagnostics.where((d) => d.hasDocumentation)) ...[
+      MemoryPage.builder(
+        path: path.join(
+          'tools',
+          'diagnostics',
+          '${diagnostic.id}.md',
+        ),
+        initialData: {
+          'page': <String, Object?>{
+            'title': diagnostic.id,
+            'underscore_breaker_titles': true,
+            'description':
+                'Details about the \'${diagnostic.id}\' diagnostic '
+                'produced by the Dart analyzer.',
+            'bodyClass': 'highlight-diagnostics',
+            'sitemap': {
+              'lastmod': _diagnosticsLastUpdated,
+            },
+          },
+        },
+        builder: (context) {
+          return Component.fragment(
+            [
+              if (diagnostic.fromLint)
+                Tags([
+                  Tag(
+                    'Lint rule',
+                    icon: 'toggle_on',
+                    title:
+                        'Learn about the lint rule that '
+                        'enables this diagnostic.',
+                    link: '/tools/linter-rules/${diagnostic.id}',
+                  ),
+                ]),
+              DashMarkdown(
+                content:
+                    '''
+${diagnostic.previousNames.map((oldName) => '_(Previously known as `$oldName`._)').join('\n\n')}
+
+${diagnostic.description}
+
+${diagnostic.documentation}
+''',
+              ),
+            ],
+          );
+        },
+      ),
+      for (final previousDiagnosticName in diagnostic.previousNames)
+        MemoryPage.builder(
+          path: path.join(
+            'tools',
+            'diagnostics',
+            '$previousDiagnosticName.md',
+          ),
+          initialData: {
+            'page': <String, Object?>{
+              'title': previousDiagnosticName,
+              'underscore_breaker_titles': true,
+              'description':
+                  'Details about the \'$previousDiagnosticName\' diagnostic '
+                  'produced by the Dart analyzer.',
+              'canonical':
+                  'https://dart.dev/tools/diagnostics/${diagnostic.id}',
+              'redirectTo': '/tools/diagnostics/${diagnostic.id}',
+              'noindex': true,
+              'sitemap': false,
+            },
+          },
+          builder: (context) {
+            return p([
+              span([text('Diagnostic renamed to: ')]),
+              a(href: '/tools/diagnostics/${diagnostic.id}', [
+                text(diagnostic.id),
+              ]),
+            ]);
+          },
+        ),
+    ],
+  ];
+}
 
 /// The individual linter rules pages, rendered to `/tools/linter-rules/<name>`.
 List<MemoryPage> get _lintMemoryPages {
@@ -53,7 +143,7 @@ List<MemoryPage> get _lintMemoryPages {
   return [
     for (final lint in lintRules)
       MemoryPage.builder(
-        path: p.join(
+        path: path.join(
           'tools',
           'linter-rules',
           '${lint.id}.md',
@@ -68,7 +158,7 @@ List<MemoryPage> get _lintMemoryPages {
               'sitemap': false,
             } else
               'sitemap': {
-                'lastmod': _lintsLastUpdated,
+                'lastmod': _diagnosticsLastUpdated,
               },
           },
         },
@@ -224,7 +314,7 @@ MemoryPage get _allLinterRulesPage {
         'description':
             'Auto-generated configuration enabling all linter rules.',
         'sitemap': {
-          'lastmod': _lintsLastUpdated,
+          'lastmod': _diagnosticsLastUpdated,
         },
       },
     },

site/lib/src/pages/diagnostic_index.dart

@@ -11,6 +11,7 @@ import '../components/common/client/copy_button.dart';
 import '../components/common/fragment_target.dart';
 import '../components/common/material_icon.dart';
 import '../markdown/markdown_parser.dart';
+import '../models/diagnostic_model.dart';
 import '../util.dart';
 
 class DiagnosticIndex extends StatelessComponent {
@@ -20,7 +21,7 @@ class DiagnosticIndex extends StatelessComponent {
   Component build(BuildContext context) {
     final diagnostics = (context.page.data['diagnostics'] as List<Object?>)
         .cast<Map<String, Object?>>()
-        .map(_DiagnosticInfo._)
+        .map(DiagnosticInfo.fromJson)
         .toList(growable: false);
     return div(
       id: 'diagnostic-index',
@@ -35,7 +36,7 @@ class DiagnosticIndex extends StatelessComponent {
 class _DiagnosticCard extends StatelessComponent {
   const _DiagnosticCard(this.diagnostic);
 
-  final _DiagnosticInfo diagnostic;
+  final DiagnosticInfo diagnostic;
 
   @override
   Component build(BuildContext context) {
@@ -77,12 +78,3 @@ class _DiagnosticCard extends StatelessComponent {
     );
   }
 }
-
-extension type _DiagnosticInfo._(Map<String, Object?> info) {
-  String get id => info['id'] as String;
-  String get description => info['description'] as String;
-  bool get hasDocumentation => info['hasDocumentation'] as bool? ?? false;
-  bool get fromLint => info['fromLint'] as bool? ?? false;
-  List<String> get previousNames =>
-      (info['previousNames'] as List<Object?>).cast<String>();
-}