automate 'Available Log Structures' bullet point list

Author: ndbroadbent

.cspell/project-words.txt

@@ -38,6 +38,7 @@ Sidekiq
 solargraph
 ssns
 testtask
+vercel
 wordlists
 xorshift
 yardoc

site/app/docs/type-safety/page.tsx

@@ -1,8 +1,9 @@
 import { CodeBlock } from '@/components/code-block';
 import { EditPageLink } from '@/components/edit-page-link';
+import { LogStructuresList } from '@/components/log-structures-list';
 import { RubyCodeExample } from '@/components/ruby-code-example';
 
-export default function TypeSafetyPage() {
+export default async function TypeSafetyPage() {
   return (
     <div className="space-y-6">
       <h1 className="text-4xl font-bold">Type Safety</h1>
@@ -33,68 +34,8 @@ export default function TypeSafetyPage() {
         LogStruct provides several typed log structures for different use cases:
       </p>
 
-      <ul className="list-disc list-inside space-y-2 text-neutral-600 dark:text-neutral-400">
-        <li>
-          <code className="px-1 py-0.5 bg-neutral-100 dark:bg-neutral-800 rounded">
-            LogStruct::Log::Plain
-          </code>{' '}
-          - For general purpose logging with a message and context
-        </li>
-        <li>
-          <code className="px-1 py-0.5 bg-neutral-100 dark:bg-neutral-800 rounded">
-            LogStruct::Log::Request
-          </code>{' '}
-          - For HTTP request details
-        </li>
-        <li>
-          <code className="px-1 py-0.5 bg-neutral-100 dark:bg-neutral-800 rounded">
-            LogStruct::Log::Error
-          </code>{' '}
-          - For exception details with stack traces
-        </li>
-        <li>
-          <code className="px-1 py-0.5 bg-neutral-100 dark:bg-neutral-800 rounded">
-            LogStruct::Log::ActionMailer
-          </code>{' '}
-          - For email delivery events
-        </li>
-        <li>
-          <code className="px-1 py-0.5 bg-neutral-100 dark:bg-neutral-800 rounded">
-            LogStruct::Log::ActiveJob
-          </code>{' '}
-          - For background job execution
-        </li>
-        <li>
-          <code className="px-1 py-0.5 bg-neutral-100 dark:bg-neutral-800 rounded">
-            LogStruct::Log::ActiveStorage
-          </code>{' '}
-          - For file storage operations
-        </li>
-        <li>
-          <code className="px-1 py-0.5 bg-neutral-100 dark:bg-neutral-800 rounded">
-            LogStruct::Log::Shrine
-          </code>{' '}
-          - For Shrine file upload events
-        </li>
-        <li>
-          <code className="px-1 py-0.5 bg-neutral-100 dark:bg-neutral-800 rounded">
-            LogStruct::Log::CarrierWave
-          </code>{' '}
-          - For CarrierWave upload events
-        </li>
-        <li>
-          <code className="px-1 py-0.5 bg-neutral-100 dark:bg-neutral-800 rounded">
-            LogStruct::Log::Sidekiq
-          </code>{' '}
-          - For Sidekiq job processing
-        </li>
-        <li>
-          <code className="px-1 py-0.5 bg-neutral-100 dark:bg-neutral-800 rounded">
-            LogStruct::Log::Security
-          </code>{' '}
-          - For security-related events
-        </li>
-      </ul>
+      {/* Dynamic list of log structures from the JSON data */}
+      <LogStructuresList />
 
       <h2 className="text-2xl font-bold mt-10 mb-4">Enums and Constants</h2>
       <p className="text-neutral-600 dark:text-neutral-400 mb-4">

site/components/log-structures-list.tsx

@@ -0,0 +1,48 @@
+import { getLogStructureDescription } from '@/lib/log-structure-descriptions';
+import { cache } from 'react';
+
+// Interface for the structure in the log structs JSON file
+interface LogStructsData {
+  [key: string]: {
+    name: string;
+    fields: Record<string, unknown>;
+  };
+}
+
+// Function to get log structs data from JSON file with caching
+const getLogStructsData = cache(async (): Promise<LogStructsData> => {
+  try {
+    // Use dynamic import to load the JSON file
+    const data = await import('@/lib/log-generation/sorbet-log-structs.json');
+    return data.default as LogStructsData;
+  } catch (error) {
+    console.error('Error loading log structures data:', error);
+    return {};
+  }
+});
+
+/**
+ * Component that displays a bullet point list of LogStruct log structures
+ * with their descriptions
+ */
+export async function LogStructuresList() {
+  // Get the log structs data
+  const structsData = await getLogStructsData();
+  
+  // Extract struct names (sorted alphabetically)
+  const structEntries = Object.entries(structsData)
+    .sort(([, a], [, b]) => a.name.localeCompare(b.name));
+  
+  return (
+    <ul className="list-disc list-inside space-y-2 text-neutral-600 dark:text-neutral-400">
+      {structEntries.map(([fullName, { name }]) => (
+        <li key={fullName}>
+          <code className="px-1 py-0.5 bg-neutral-100 dark:bg-neutral-800 rounded">
+            LogStruct::Log::{name}
+          </code>{' '}
+          - {getLogStructureDescription(name)}
+        </li>
+      ))}
+    </ul>
+  );
+}

site/lib/__tests__/log-structure-descriptions.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from '@jest/globals';
+import {
+  getLogStructureDescription,
+  LOG_STRUCTURE_DESCRIPTIONS,
+} from '../log-structure-descriptions';
+
+describe('Log Structure Descriptions', () => {
+  it('has descriptions for all common log structures', () => {
+    // Test that we have descriptions for the core log structures
+    const expectedStructures = [
+      'Plain',
+      'Request',
+      'Error',
+      'ActiveJob',
+      'ActionMailer',
+      'ActiveStorage',
+      'Shrine',
+      'CarrierWave',
+      'Sidekiq',
+      'Security',
+    ];
+
+    // Check that all expected structures have descriptions
+    expectedStructures.forEach((struct) => {
+      expect(LOG_STRUCTURE_DESCRIPTIONS).toHaveProperty(struct);
+      expect(LOG_STRUCTURE_DESCRIPTIONS[struct]).toBeTruthy();
+    });
+  });
+
+  it('getLogStructureDescription returns the correct description', () => {
+    // Test with a known structure
+    expect(getLogStructureDescription('Plain')).toBe(
+      'For general purpose logging',
+    );
+    expect(getLogStructureDescription('Request')).toBe(
+      'For HTTP request details',
+    );
+  });
+
+  it('getLogStructureDescription throws an error for unknown structures', () => {
+    // Test with an unknown structure
+    expect(() => getLogStructureDescription('NonExistentStructure')).toThrow(
+      'No description found for log structure: NonExistentStructure',
+    );
+  });
+});

site/lib/log-structure-descriptions.ts

@@ -0,0 +1,30 @@
+/**
+ * Descriptions for each LogStruct log structure
+ * These are used in the documentation to explain what each log structure is for
+ */
+export const LOG_STRUCTURE_DESCRIPTIONS: Record<string, string> = {
+  Plain: 'For general purpose logging',
+  Request: 'For HTTP request details',
+  Error: 'For exception details with stack traces',
+  ActionMailer: 'For email delivery events',
+  ActiveJob: 'For background job execution',
+  ActiveStorage: 'For file storage operations',
+  Shrine: 'For Shrine file upload events',
+  CarrierWave: 'For CarrierWave upload events',
+  Sidekiq: 'For Sidekiq job processing',
+  Security: 'For security-related events',
+};
+
+/**
+ * Get the description for a log structure
+ * @param structName The name of the log structure (e.g., "Plain", "Request")
+ * @returns The description of the log structure
+ * @throws Error if no description is found for the structure
+ */
+export function getLogStructureDescription(structName: string): string {
+  const description = LOG_STRUCTURE_DESCRIPTIONS[structName];
+  if (!description) {
+    throw new Error(`No description found for log structure: ${structName}`);
+  }
+  return description;
+}