Automate Internal Link Updates Using Redirects File #1119

krofax · 2024-11-15T15:34:51Z

Description

Add scripts to manage redirect links:

check-redirects: Scans and reports broken internal links
fix-redirects: Automatically updates links based on _redirects

The scripts help maintain link integrity when pages are relocated, using _redirects as source of truth.

Changes:

Add utils/check-redirects.ts
Add utils/fix-redirects.ts
Add documentation for redirect link management
Update package.json with new scripts

Tests

Additional context

Metadata

Fixes - https://github.com/ethereum-optimism/devrel/issues/426

netlify · 2024-11-15T15:35:08Z

✅ Deploy Preview for docs-optimism ready!

Name	Link
🔨 Latest commit	`2da87a6`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-optimism/deploys/673786a705ee0600088b8ca2
😎 Deploy Preview	https://deploy-preview-1119--docs-optimism.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

coderabbitai · 2024-11-15T15:40:19Z

📝 Walkthrough

Walkthrough

The pull request introduces several changes across multiple files, primarily focusing on documentation and script enhancements related to link management. The lychee.toml file has been updated with a newline at the end, while notes/fix-redirects.md provides a comprehensive guide for managing redirect links within the documentation system, detailing two scripts: check-redirects and fix-redirects. The package.json file has been modified to integrate these scripts into the existing lint and fix commands, enhancing the functionality related to redirect management.

Various documentation files have undergone updates to hyperlinks, redirecting users to more relevant resources, particularly shifting from specific wallet and CEX developer links to broader app developer overviews. The changes span multiple sections, including builders, stack differences, and interoperability, ensuring that links are current and accurately reflect the intended navigation structure. Additionally, new utility scripts have been introduced to automate the checking and fixing of outdated links in Markdown and MDX files, improving the overall integrity of the documentation.

Suggested labels

documentation, tutorial

Suggested reviewers

bradleycamacho
cpengilly

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Generate unit testing code for this file.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai generate unit testing code for this file.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and generate unit testing code.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

coderabbitai

Actionable comments posted: 9

🧹 Outside diff range and nitpick comments (18)

pages/builders.mdx (1)

Line range hint 1-20: Consider restructuring navigation cards for better organization

The "Wallets & CEXs" section is now redirecting to the app developers overview. Consider:

Either renaming the card to better reflect its new destination

Or creating a dedicated section for Wallet/CEX documentation under app developers
pages/builders/chain-operators/tutorials.mdx (1)
Line range hint 11-11: Maintain consistent capitalization of technical terms

The introductory paragraph contains inconsistent capitalization of technical terms. Please update the following:

"l2" should be "L2"

"da" and "Da" should be consistently capitalized as "DA"
-This section provides information on adding attributes to the derivation function, adding a precompile, creating your own l2 rollup testnet, integrating a new da layer with alt da, modifying predeployed contracts and using viem. You'll find overview, tutorial, guide to help you understand and work with these topics.
+This section provides information on adding attributes to the derivation function, adding a precompile, creating your own L2 rollup testnet, integrating a new DA layer with alt DA, modifying predeployed contracts and using viem. You'll find overview, tutorial, guide to help you understand and work with these topics.
notes/fix-redirects.md (4)
6-7: Add context about the _redirects file

Consider adding a brief explanation of the _redirects file's location and format to help users understand the system better.

Add something like:
*   `check-redirects`: Identifies links that need updating based on the `_redirects` file.
*   `fix-redirects`: Automatically updates links to match `_redirects` entries.
+
+The `_redirects` file should be located in the `public` folder and follows the format:
+```
+/old-path    /new-path
+```
🧰 Tools

🪛 LanguageTool

[uncategorized] ~6-~6: Loose punctuation mark.
Context: ...ges are redirect: * check-redirects: Identifies links that need updating bas...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~7-~7: Loose punctuation mark.
Context: ...e _redirects file. * fix-redirects: Automatically updates links to match `_...

(UNLIKELY_OPENING_PUNCTUATION)

9-9: Fix markdown heading formatting

Remove extra spaces after the hash symbol.
-##  Checking for broken links
+## Checking for broken links
🧰 Tools

🪛 Markdownlint

9-9: null
Multiple spaces after hash on atx style heading

(MD019, no-multiple-space-atx)

45-45: Make heading unique for better navigation

The heading "What it does" is duplicated. Consider making it more specific.
-## What it does
+## How fix-redirects works
🧰 Tools

🪛 Markdownlint

45-45: null
Multiple headings with the same content

(MD024, no-duplicate-heading)

82-83: Enhance common issues section

The section needs grammar fixes and could benefit from more scenarios.
-*   Script fails: Ensure `_redirects` file exists in public folder, it should always be there!
-*   No broken links found: Verify `_redirects` entries are correct.
+*   Script fails: Ensure the `_redirects` file exists in the public folder, it should always be there!
+*   No broken links found: Verify `_redirects` entries are correct.
+*   Partial updates: Some links might be skipped if they don't exactly match entries in `_redirects`
+*   Case sensitivity: Links might not match due to case differences
+*   Error handling: Check console output for detailed error messages
🧰 Tools

🪛 LanguageTool

[uncategorized] ~82-~82: You might be missing the article “the” here.
Context: ...ils: Ensure _redirects file exists in public folder, it should always be there! * ...

(AI_EN_LECTOR_MISSING_DETERMINER_THE)
package.json (1)

12-13: Consider adding error handling documentation.

The new redirect scripts are well-named and follow the project's TypeScript execution pattern. Consider documenting:

Expected exit codes

Error scenarios

Required file permissions

Performance impact on large documentation sets

Consider adding a README.md in the utils directory to document these aspects for maintainability.

pages/chain/getting-started.mdx (1)

Line range hint 8-13: Replace personal pronouns with proper nouns

Replace "we" with "OP Mainnet" to maintain consistency in communal documentation:

"we run" → "OP Mainnet runs"
pages/stack/interop/assets/deploy-superchain-erc20.mdx (1)
16-16: Improve sentence structure and formality

Consider revising the sentence to be more direct and formal:
-This guide explains how to issue new assets with the `SuperchainERC20` and bridge them effectively using the `SuperchainERC20Bridge`. If you want more information about the `SuperchainERC20 standard`, see our [`SuperchainERC20` standard explainer](/stack/interop/assets/superchain-erc20)
+This guide explains how to issue new assets with the `SuperchainERC20` and bridge them effectively using the `SuperchainERC20Bridge`. For more information about the `SuperchainERC20 standard`, refer to the [`SuperchainERC20` standard explainer](/stack/interop/assets/superchain-erc20)
🧰 Tools

🪛 LanguageTool

[style] ~16-~16: Consider using a more formal alternative.
Context: ...he SuperchainERC20Bridge. If you want more information about the SuperchainERC20 standard, s...

(MORE_INFO)
pages/builders/app-developers/overview.mdx (1)

Line range hint 1-100: Maintain consistent capitalization of technical terms

The document generally follows the style guidelines well. However, consider these refinements:

Use "Layer 1" and "Layer 2" consistently in the tutorial table (currently shows variations like "layer 2").

Ensure "EVM equivalent" is properly capitalized as it's a technical term.

🧰 Tools

🪛 LanguageTool

[misspelling] ~16-~16: Did you mean “your”?
Context: ...t applications. ## Getting started If you're brand new to OP Mainnet, try starting w...

(YOUR_NN)
pages/chain/testing/dev-node.mdx (1)
27-27: Add hyphen to "double-check"

For grammatical correctness, "double check" should be hyphenated when used as a compound verb.
-to double check that everything
+to double-check that everything
🧰 Tools

🪛 LanguageTool

[style] ~27-~27: ‘exactly the same’ might be wordy. Consider a shorter alternative.
Context: ...evm-equivalence-5c2021deb306), it's not exactly the same as Ethereum. If you're building an appl...

(EN_WORDINESS_PREMIUM_EXACTLY_THE_SAME)

[grammar] ~27-~27: The verb “double-check” is spelled with a hyphen.
Context: ...se the local development environment to double check that everything is running as expected....

(DOUBLE_HYPHEN)
pages/builders/app-developers/tutorials/cross-dom-bridge-erc20.mdx (1)
34-34: Consider rephrasing for better readability

To improve variety in the text, consider rephrasing:
- If you want to use a network that isn't included by default,
+ For networks not included by default,
🧰 Tools

🪛 LanguageTool

[style] ~34-~34: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ... included in the SDK by default. If you want to use a network that isn't included by de...

(REP_WANT_TO_VB)
pages/stack/interop/explainer.mdx (1)

Line range hint 1-24: Improve header capitalization and remove personal pronouns

According to the documentation guidelines:

Headers should use sentence case (except for technical terms)

Personal pronouns should be replaced with proper nouns

Apply these changes:

Change "Interoperability explainer" to "Interoperability Explainer" (title)

Change "Secure message passing" to "Secure Message Passing"

Replace "our specs repo" with "the specs repository"
utils/fix-redirects.ts (2)
36-49: Handle potential errors from recursive file reading

The findMdxFiles function does not currently handle exceptions that may occur during file system operations, such as permission issues or non-existent directories.

Wrap the recursive calls and file operations in try-catch blocks to handle exceptions:
 async function findMdxFiles(dir: string): Promise<string[]> {
   const files: string[] = [];
+  try {
     const entries = await fs.readdir(dir, { withFileTypes: true });

     for (const entry of entries) {
       const fullPath = path.join(dir, entry.name);
       if (entry.isDirectory() && !entry.name.startsWith('_')) {
         files.push(...await findMdxFiles(fullPath));
       } else if (entry.isFile() && /\.(md|mdx)$/.test(entry.name)) {
         files.push(fullPath);
       }
     }
+  } catch (error) {
+    console.error(`${YELLOW}Error reading directory "${dir}":${RESET}`, error);
+  }
   return files;
 }
This ensures that any errors encountered during directory traversal are logged, and the function continues processing other directories.

77-82: Consistent use of ANSI color codes for summary output

While ANSI color codes are used in the printSummary function, the skipped files count is displayed in white, which may not stand out.

Consider using a different color for better readability:
 function printSummary(summary: Summary) {
   console.log('\nSummary:');
   console.log(`${WHITE}Total files 🔍 - ${summary.total}`);
   console.log(`${GREEN}Files fixed ✅ - ${summary.fixed}`);
-  console.log(`${WHITE}Files skipped ⏭️  - ${summary.skipped}${RESET}`);
+  console.log(`${YELLOW}Files skipped ⏭️  - ${summary.skipped}${RESET}`);
 }
This change enhances the visual distinction between different summary metrics.
utils/redirects.ts (3)
79-84: Optimize redirects lookup with a Map for better performance

Currently, the code uses Array.find, which has O(n) complexity per lookup. For a large number of redirects, this could affect performance. Using a Map for redirects can improve efficiency.

Modify the getRedirects function to return a Map:
-async function getRedirects(): Promise<Redirect[]> {
+async function getRedirects(): Promise<Map<string, string>> {
   const content = await fs.readFile(redirectsPath, 'utf-8');
-  return content.split('\n')
+  const redirects = new Map<string, string>();
+  content.split('\n')
     .filter(line => line.trim() && !line.startsWith('#'))
     .forEach(line => {
       const [from, to] = line.split(/\s+/);
-      return { from, to };
+      redirects.set(from, to);
     });
+  return redirects;
 }

 async function checkFile(filePath: string, redirects: Map<string, string>): Promise<void> {
   const content = await fs.readFile(filePath, 'utf-8');
   const links = extractLinks(content);
   const relativeFilePath = path.relative(rootDir, filePath);

   links.forEach(link => {
-    const redirect = redirects.find(r => r.from === link);
-    if (redirect) {
-      warnings.push(formatWarning(relativeFilePath, link, redirect.to));
+    if (redirects.has(link)) {
+      const toLink = redirects.get(link)!;
+      warnings.push(formatWarning(relativeFilePath, link, toLink));
     }
   });
 }
This change reduces the lookup time to O(1) per link, enhancing performance when processing many redirects.

30-38: Add validation for redirects to handle malformed entries

The getRedirects function assumes all lines are well-formed. If the _redirects file contains malformed entries, it may cause runtime errors. Introduce validation to ensure robustness.

Modify the getRedirects function:
 async function getRedirects(): Promise<Redirect[]> {
   const content = await fs.readFile(redirectsPath, 'utf-8');
   return content.split('\n')
     .filter(line => line.trim() && !line.startsWith('#'))
     .map(line => {
       const [from, to] = line.split(/\s+/);
+      if (!from || !to) {
+        console.warn(`${YELLOW}Warning: Malformed redirect entry ignored: "${line}"${RESET}`);
+        return null;
+      }
       return { from, to };
-    });
+    })
+    .filter((redirect): redirect is Redirect => redirect !== null);
 }
This ensures that only valid redirects are processed, and malformed entries are reported and skipped gracefully.

117-125: Consider using exit codes to indicate success or failure explicitly

In the main function, the script exits with code 1 regardless of the error type. You might want to differentiate between types of exits using specific exit codes.

For example:
       if (warnings.length > 0) {
         console.log(`${YELLOW}${BOLD}Links that need updating:${RESET}`);
         warnings.forEach(warning => console.log(warning));
         printSummary(summary);
-        process.exit(1);
+        process.exit(2); // Exit code 2 indicates outdated links found
       } else {
         console.log(`${GREEN}All internal links are up to date.${RESET}`);
         printSummary(summary);
       }
Similarly, adjust exit codes in error handling to reflect different error types for better debugging and automation.

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL

📥 Commits

Reviewing files that changed from the base of the PR and between 3dc670f and d69fb35.

📒 Files selected for processing (18)

lychee.toml (1 hunks)
notes/fix-redirects.md (1 hunks)
package.json (1 hunks)
pages/builders.mdx (1 hunks)
pages/builders/app-developers/overview.mdx (1 hunks)
pages/builders/app-developers/tutorials/cross-dom-bridge-erc20.mdx (1 hunks)
pages/builders/chain-operators/tutorials.mdx (1 hunks)
pages/chain/getting-started.mdx (1 hunks)
pages/chain/testing/dev-node.mdx (1 hunks)
pages/index.mdx (1 hunks)
pages/stack/differences.mdx (1 hunks)
pages/stack/features/send-raw-transaction-conditional.mdx (1 hunks)
pages/stack/getting-started.mdx (1 hunks)
pages/stack/interop/assets/deploy-superchain-erc20.mdx (1 hunks)
pages/stack/interop/explainer.mdx (1 hunks)
utils/fix-redirects.ts (1 hunks)
utils/redirects.ts (1 hunks)
words.txt (0 hunks)

💤 Files with no reviewable changes (1)

words.txt

✅ Files skipped from review due to trivial changes (1)

lychee.toml

🧰 Additional context used

📓 Path-based instructions (12)

pages/builders.mdx (1)