Merge pull request #1485 from ethereum-optimism/simplify-metadata-logic

fix:simplify-metadata-logic

Author: bradleycamacho

.coderabbit.yaml

@@ -33,11 +33,10 @@ reviews:
             ---
             ```
           3. If any required fields are missing or empty, comment:
-            'This file appears to be missing required metadata. You can fix this by running:
+            'This file appears to be missing required metadata. Please check keywords.config.yaml for valid options and add the required fields manually. You can validate your changes by running:
             ```bash
-            pnpm metadata-batch-cli:dry "path/to/this/file.mdx"
-            ```
-            Review the changes, then run without :dry to apply them.'
+            pnpm validate-metadata
+            ```'
         - Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
         - Avoid gender-specific language and use the imperative form.
         - Monitor capitalization for emphasis. Avoid using all caps, italics, or bold for emphasis.

dist/tsconfig.tsbuildinfo

@@ -1,204 +1,66 @@
-# Metadata Management System
+# Metadata Validation System
 
-Quick guide on using our metadata management system for the OP Stack documentation.
+## Overview
 
-## What the System Does
+This system validates metadata in MDX documentation files against rules defined in `keywords.config.yaml`.
 
-* Validates and updates metadata in .mdx documentation files
-* Ensures consistent metadata across documentation
-* Generates a manifest of processed files
-* Supports dry run mode for previewing changes
-* Automatically detects content categories and types
+## Key Features
 
-## Using the Scripts
+- Validates required metadata fields
+- Ensures only valid keywords are used
+- Provides suggestions from keywords.config.yaml
+- Handles duplicate/imported pages with `is_imported_content` flag
+- No automatic fixes - content writers make manual updates
 
-1. Run a dry run to preview changes:
-   ```bash
-   # Process all .mdx files in a directory and its subdirectories
-   pnpm metadata-batch-cli:dry "pages/superchain/**/*.mdx"
+## Using the Validator
 
-   # Process a specific file with verbose output
-   pnpm metadata-batch-cli:verbose "pages/app-developers/example.mdx"
-
-   # Process multiple directories
-   pnpm metadata-batch-cli:dry "pages/app-developers/**/*.mdx" "pages/node-operators/**/*.mdx"
-   ```
-
-2. Apply the changes (remove :dry):
-   ```bash
-   pnpm metadata-batch-cli "pages/app-developers/**/*.mdx"
-   ```
-
-### Important Note About File Patterns
-
-Use these patterns to match files:
-
-* `directory/**/*.mdx` - matches all .mdx files in a directory and all its subdirectories
-* `directory/*.mdx` - matches only .mdx files in the specific directory
-* `directory/subdirectory/**/*.mdx` - matches all .mdx files in a specific subdirectory tree
-* the quotes around the pattern are important to prevent shell expansion
-
-### Configuration Files
-
-1. **keywords.config.yaml**
-   * Located in the project root
-   * **Single source of truth** for all valid metadata values
-   * Defines validation rules for metadata fields
-   * Specifies required fields for different content types
-   * Contains keyword mappings for category detection
-   * Example configuration:
-```yaml
-metadata_rules:
-  topic:
-    required: true
-    validation_rules:
-      - pattern: "^[a-z0-9-]+$"
-        description: "Must be lowercase with hyphens"
-  personas:
-    required: true
-    multiple: true
-    validation_rules:
-      - enum:
-        - app-developer
-        - node-operator
-        - chain-operator
-        - protocol-developer
-        - partner
-  content_type:
-    required: true
-    validation_rules:
-      - enum:
-        - tutorial
-        - guide
-        - reference
-        - landing-page
-        - troubleshooting
-        - notice
-  categories:
-    required: true
-    multiple: true
-    validation_rules:
-      - enum:
-        - protocol
-        - security
-        - governance
-        - tokens
-        - standard-bridge
-        - interoperable-message-passing
-        - devnets
-        - infrastructure
+To check your changes before committing:
+```bash
+pnpm validate-metadata
 ```
 
-2. **metadata-types.ts**
-   * Defines TypeScript interfaces for metadata
-   * Imports and validates valid values from keywords.config.yaml
-   * Provides type-safe exports for use throughout the system
-   * Used for type checking and validation
-
-## What to Watch For
+This will validate any MDX files you've modified but haven't committed yet. Fix any validation errors before committing your changes.
 
-1. **Before Running**
-   * Commit your current changes
-   * Ensure you're in the docs root directory
-   * Check that keywords.config.yaml exists and is properly configured
-   * **Important**: All metadata values must be defined in keywords.config.yaml
+Note: Additional validation will run automatically when you create a PR.
 
-2. **After Running**
-   * Review the categories assigned to each file
-   * Check that topics and personas are correct
-   * Verify any files marked for review
-   * Make sure network types (mainnet/testnet) are correct for registry files
+## Metadata Requirements
 
-## Content Analysis
+All valid metadata values are defined in `keywords.config.yaml`. This file is the single source of truth for:
 
-The `metadata-analyzer.ts` script handles automatic content analysis and categorization.
+- Required fields
+- Valid personas
+- Valid content types
+- Valid categories
 
-### How It Works
+### Handling Duplicate Pages
 
-1. **Category Detection**
-   * Analyzes file content and paths for relevant keywords
-   * Detects appropriate categories based on context
-   * Handles special cases for chain operators and node operators
-   * Supports parent category inheritance for landing pages
+For pages that are imported or duplicated across sections:
+- Set `is_imported_content: 'true'` for duplicate/imported pages
+- Set `is_imported_content: 'false'` for original pages
+- This helps manage duplicate topics and enables proper filtering
 
-2. **Content Type Detection**
-   * Identifies content type (guide, reference, tutorial, etc.)
-   * Uses filename patterns and content signals
-   * Considers component usage (e.g., <Cards>, <Steps>)
-   * Scores content against multiple type indicators
+## When Validation Fails
 
-### Valid Categories
+1. Review the validation errors
+2. Check keywords.config.yaml for valid options
+3. Update your MDX frontmatter manually
+4. Run validation again to confirm fixes
 
-Categories are defined in `keywords.config.yaml`. Check this file for the current list of valid categories. The metadata validation system uses these definitions to ensure consistency across all documentation.
+## Example Valid Frontmatter
 
-Example of how categories are defined:
 ```yaml
-metadata_rules:
-  categories:
-    required: true
-    multiple: true
-    validation_rules:
-      - enum:
-        - protocol
-        - security
-        - governance
-        # ... see keywords.config.yaml for complete list
-```
-
-### Example Analysis
-
-Input file with chain operator content:
-```yaml
----
-title: Genesis Creation
-description: Learn how to create a genesis file.
 ---
-```
-
-Detected categories:
-```yaml
+title: Example Page
+description: A clear description
+topic: example-topic
+personas:
+  - app-developer
+content_type: guide
 categories:
   - protocol
-  - devnets
-  - governance
-  - security
+  - infrastructure
+is_imported_content: 'false'  # Required: 'true' for imported/duplicate pages
+---
 ```
 
-### Special Cases
-
-* **Landing Pages**: Categories are determined by analyzing the child content they link to (typically via `<Cards>` components)
-* **Chain Operators**: Additional category detection for specific features
-* **Node Operators**: Special handling for node operation content
-* **Imported Content**: Skip category review flags for imported content
-
-## Implementation Files
-
-* `utils/metadata-manager.ts`: Main metadata management system
-* `utils/metadata-analyzer.ts`: Content analysis and categorization logic
-* `utils/metadata-batch-cli.ts`: CLI tool for batch updates
-* `utils/types/metadata-types.ts`: TypeScript type definitions
-* `keywords.config.yaml`: Validation rules and keyword mappings
-
-## Automated PR Checks
-
-The documentation repository includes automated checks for metadata completeness:
-
-1. **CircleCI Validation**
-   * Automatically runs on all PRs
-   * Checks metadata in modified .mdx files
-   * Fails if required metadata is missing
-   * Run locally with: `pnpm validate-pr-metadata`
-
-2. **CodeRabbit Review**
-   * Reviews frontmatter in modified files
-   * Checks for required fields based on content type
-   * Suggests running metadata-batch-cli when metadata is incomplete
-
-### When to Run Metadata Updates
-
-* When CircleCI metadata validation fails
-* When CodeRabbit suggests missing metadata
-* When adding new documentation files
-* When specifically asked to update metadata
-
-Do not run the script on files that already have correct metadata, as this may overwrite manual customizations.
+Remember: All valid options are in keywords.config.yaml

notes/metadata-update.md

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "lint": "eslint . --ext mdx --max-warnings 0 && pnpm spellcheck:lint && pnpm check-breadcrumbs && pnpm check-redirects && pnpm validate-metadata && pnpm link-checker",
-    "fix": "eslint . --ext mdx --fix && pnpm spellcheck:fix && pnpm fix-redirects && pnpm metadata-batch-cli && pnpm fix-links",
+    "fix": "eslint . --ext mdx --fix && pnpm spellcheck:fix && pnpm fix-redirects && pnpm fix-links",
     "spellcheck:lint": "cspell lint \"**/*.mdx\"",
     "prepare": "husky",
     "spellcheck:fix": "cspell --words-only --unique \"**/*.mdx\" | sort --ignore-case | uniq > words.txt",
@@ -15,11 +15,8 @@
     "fix-redirects": "NODE_NO_WARNINGS=1 node --loader ts-node/esm utils/fix-redirects.ts",
     "link-checker": "NODE_NO_WARNINGS=1 node --loader ts-node/esm utils/link-checker.ts",
     "fix-links": "NODE_NO_WARNINGS=1 node --loader ts-node/esm utils/fix-broken-links.ts",
-    "metadata-batch-cli": "NODE_NO_WARNINGS=1 node --loader ts-node/esm utils/metadata-batch-cli.ts",
-    "metadata-batch-cli:dry": "NODE_NO_WARNINGS=1 node --loader ts-node/esm utils/metadata-batch-cli.ts --dry-run",
-    "metadata-batch-cli:verbose": "pnpm metadata-batch-cli --verbose",
-    "validate-metadata": "CHANGED_FILES=$(git diff --name-only HEAD) pnpm metadata-batch-cli:dry",
-    "validate-pr-metadata": "NODE_NO_WARNINGS=1 node --loader ts-node/esm utils/metadata-manager.ts --pr",
+    "validate-metadata": "CHANGED_FILES=$(git diff --name-only --cached) NODE_NO_WARNINGS=1 node --loader ts-node/esm utils/metadata-validator.ts",
+    "validate-pr-metadata": "NODE_NO_WARNINGS=1 node --loader ts-node/esm utils/metadata-validator.ts --pr",
     "dev": "next dev",
     "build": "next build",
     "start": "next start",