איך Modern Web Guidance משדרג את בסיס הקוד שלכם – ולמה כדאי לעשות את זה

רוב הפיתוח לאינטרנט לא מתחיל מאפס. זה קורה בבסיסי קוד קיימים שצברו שנים של פתרונות עקיפים, פוליפילים וכלי שירות של JavaScript (שינוי גודל אוטומטי, פריצות לעיצוב של תיבות סימון בהתאמה אישית, מאזינים ל-scrollHeight) לדברים שהדפדפן מטפל בהם עכשיו באופן מקורי. אבל הבעיה היא שקוד ישן לא נשבר. הוא עובד, אז אף אחד לא מדווח על באג. צריך גם אמון כדי לארגן את הקוד מחדש בקוד עובד, גם אם הוא ישן, ולכן מובן למה המפתחים לא רוצים לעשות את זה.

מצד שני, אם לא תשכתבו קוד ישן כדי להשתמש בתכונות אינטרנט מודרניות, זה יעלה לכם בשקט בגודל החבילה, בתגובה של הדף ובנגישות. גרוע מכך, כשמשתמשים בסוכני תכנות בפרויקטים האלה, הם מעתיקים את המוסכמות שמסביב משנת 2015 יחד עם הדפוסים המיושנים מנתוני האימון שלהם.

כשאתם מפתחים משהו חדש, Modern Web Guidance מכוון את הסוכן לתכונות Baseline מודרניות. בקוד קיים, גרסה 1.0 של Modern Web Guidance מוסיפה תהליך עבודה של מודרניזציה שסורק את הפרויקט כדי לאתר דפוסים מדור קודם ועוזר לסוכן לשדרג אותם.

מה קורה בתהליך העבודה של המודרניזציה

כשמבקשים מהסוכן לשדרג פרויקט (או כשמריצים את הפקודה legacy-scan ישירות), זה מה שקורה:

  • סריקה מקומית דטרמיניסטית: סריקה מהירה של קובצי HTML,‏ CSS,‏ JavaScript/TypeScript, רכיבים ספציפיים ל-framework ו-package.json באמצעות מנתחי Abstract Syntax Tree‏ (AST),‏ DOM ו-CSS באופן מקומי, בלי קריאות ל-LLM או עלות אסימונים.
  • קטלוג כללים מדור קודם: סורק שמסמן יותר מדי דברים בכל הפעלה, המשתמשים מתעלמים ממנו. בדקנו כללים מועמדים בכ-45,000 מאגרים של קוד פתוח שחולקו לשניים: הכללים נכתבו ועברו כוונון בחצי של כתיבת הכללים, ודורגו בחצי השני שלא נראה. זרקנו יותר כללים מועמדים ממה ששמרנו, דילגנו על תכונות שאין להן מקבילה בקוד מדור קודם והוצאנו משימוש החלפות של תחביר בלבד ללא תועלת אמיתית (כמו שכתוב של סלקטורים אחים פועלים של + או ~ ל-:has()). כדי לשלוח כברירת מחדל, כלל חייב להגיע לדיוק של לפחות 80% בהתאמה סטטית ולדיוק של 90% לאחר אימות בקוד שלא נראה.
  • סינון תוצאות חיוביות מוטעות בהתאם להקשר: כל התאמה לכלל מגיעה עם קטגוריות מפורשות של keepWhen/dropWhen. כך הסוכן יודע להעריך את הקוד שמסביב, ולהתעלם מ-fallbacks מכוונים, מ-guards של CSS @supports או מ-lookalikes לפני שהוא מציג את הממצאים שלו.
  • היקף מוגבל לתבניות קוד קודמות ברמת סבירות גבוהה (והיקף שמתרחב): legacy-scan בודק את קבוצת המשנה של כ-200 המדריכים שלנו (כ-20%) שבהם אפשר לזהות קוד קודם באופן דטרמיניסטי בלי תוצאות חיוביות מוטעות, ואנחנו מרחיבים את הכיסוי הזה עם הזמן. לגבי שאר הקטלוג, הסוכן מחפש ומאחזר מדריכים תוך כדי שאתם יוצרים.

איך מפעילים את תהליך העבודה של המודרניזציה

כדי לשדרג קוד באמצעות Modern Web Guidance, צריך להשתמש בגרסה 1.0 ומעלה. מתקינים או מעדכנים אותו באמצעות npm, או דרך זירת המסחר של הפלאגינים של הסוכן:

# Install Modern Web Guidance 1.0 in your project
npx modern-web-guidance@latest install

# Or update an existing installation
npx modern-web-guidance@latest update

תהליך העבודה של המודרניזציה הוא חלק מהגדרת המיומנות העיקרית, ולכן אתם יכולים להפעיל את הסורק באמצעות שפה טבעית. פשוט מבקשים מהנציג לבדוק "דפוסים מדור קודם" או "לשדרג" במאגר או בתיקייה.

הערה: אם תציינו שם של רכיב אחד, תתבצע במקום זאת פעולת חיפוש רגילה במדריך.

כדי להדגים, הנה הנחיה לדוגמה לסריקת מאגר שלם:

Modernize this repository using Modern Web Guidance. Scan our frontend files for legacy patterns, verify the findings, and propose a modernization plan before making any code edits.

אפשר גם להפנות אותו לתיקייה ספציפית:

Check src/components/forms for legacy web patterns that can be refactored to modern Baseline features.

כרגע אפשר להריץ את legacy-scan באופן ידני בטרמינל, אבל שילובים אוטומטיים של צינורות עיבוד נתונים של CI/CD נמצאים כרגע בפיתוח.

דוגמאות לתבניות שהכלי מזהה ומתקן

הכללים המתאימים מתמקדים בתבניות אנטי-תבניות נפוצות מדור קודם בארבעה תחומים: טפסים וממשק משתמש, תיבות דו-שיח ופקדים, פריסת CSS, טיפוגרפיה ועיצוב חזותי ואבטחה. בטבלה הבאה מוצגות דוגמאות לתבניות ישנות ולתבניות המודרניות שמחליפות אותן:

דומיין זוהתה תבנית מדור קודם תחליף מודרני
טפסים וממשק משתמש ‫JS scrollHeight textarea auto-resize hooks ‫CSS field-sizing: content (form-fields-automatically-fit-contents)
טפסים וממשק משתמש הזנת keydown פונקציות טיפול בשליחה ללא הגנות IME if (e.isComposing || e.keyCode === 229) return; (ime-safe-enter-submit)
טפסים וממשק משתמש עיצוב CSS מוקדם של :invalid בקלט שלא נגעו בו בזמן הטעינה :user-invalid ו-:user-valid (validate-input-after-interaction)
טפסים וממשק משתמש חסרים טוקנים של autocomplete בטפסים של אימות ותשלום ערכי autocomplete סטנדרטיים (autofill-sign-in-form,‏ autofill-payment-form)
תיבות דו-שיח ואמצעי בקרה ‫e.target === dialog רכיבי click listener שמשבשים את בחירת הגרירה ‫<dialog closedby="any"> עם שיפור הדרגתי (תיבת דו-שיח)
תיבות דו-שיח ואמצעי בקרה רכיבי click listener מסוג addEventListener לשכבות-על מאפייני popover ו-popovertarget הצהרתיים (declarative-dialog-popover-control)
פריסת CSS, טיפוגרפיה ועיצוב חזותי ‫max-height: 9999px טריקים לאנימציות של אקורדיון ‫interpolate-size: allow-keywords ו-calc-size() (animate-to-intrinsic-sizes)
פריסת CSS, טיפוגרפיה ועיצוב חזותי החלפת מצב של מחלקת הורה ב-JS על סמך מצב הצאצא סלקטורים יחסיים :has(:checked) / :has(:focus-visible) (child-state-based-styling)
פריסת CSS, טיפוגרפיה ועיצוב חזותי שוכפלו @media (prefers-color-scheme: dark) בלוקים פונקציית CSS light-dark()‏ (dark-mode,‏ dark-mode-toggle)
אבטחה תגי סקריפט של CDN חיצוניים ללא Subresource Integrity (תקינות משאבי משנה) המאפיינים integrity ו-crossorigin="anonymous" ‏(secure-external-subresources)

דוגמאות לשינוי קוד

כשמבקשים ממנו, סוכן התכנות יכול להפוך תבניות אנטי-דפוס (antipattern) מדור קודם לתבניות מודרניות באמצעות תהליך העבודה של המודרניזציה. הנה כמה דוגמאות:

רכיבי <textarea> שמתרחבים אוטומטית

קוד JavaScript מדור קודם שמודד את scrollHeight בכל אירוע input מאלץ שינויים תכופים בפריסה. זה יכול לגרום לבעיות בביצועים, במיוחד במדד מהירות התגובה לאינטראקציה באתר (INP). בעזרת תהליך העבודה של המודרניזציה, הנציג יכול לתקן את זה:

// Before: Imperative layout recalculation on every keystroke
textarea.addEventListener('input', () => {
  textarea.style.height = 'auto';
  textarea.style.height = `${textarea.scrollHeight}px`;
});

כיום לא צריך JavaScript בשביל זה. תהליך המודרניזציה מנחה את הנציג להחליף את הקוד ב-CSS:

/* After: Native declarative field sizing */
textarea {
  field-sizing: content;
  min-block-size: 3lh;
  max-block-size: 15lh;
}

חלונות קופצים הצהרתיים

אפשר להחליף לוגיקה מותאמת אישית של מודאלים וחלונות קופצים שמשתמשת ברכיבי event listener ב-JavaScript במאפייני HTML סטנדרטיים:

<!-- Before: a click listener that only calls showPopover() -->
<button id="openBtn">Open Menu</button>
<div id="menu" popover>Menu Content</div>
<script>
  openBtn.addEventListener('click', () => menu.showPopover());
</script>

<!-- After: declarative control, no JavaScript -->
<button popovertarget="menu">Open Menu</button>
<div id="menu" popover>Menu Content</div>

שליחה בטוחה של מקש Enter ב-IME

מאזינים לא מוגנים למקש Enter מפעילים שליחת הודעות לפני הזמן כשמשתמשים מקלידים בעורכי שיטות קלט (IME) ביפנית, בסינית או בקוריאנית.

הנציג מוסיף הגנות על מצב הקומפוזיציה:

// Before: Fires mid-composition when confirming kanji/hanzi characters
textarea.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' && !e.shiftKey) {
    e.preventDefault();
    sendMessage();
  }
});


// After: Accurately checks IME composition state
textarea.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' && !e.shiftKey) {
    e.preventDefault();
    if (e.isComposing || e.keyCode === 229) return;
    sendMessage();
  }
});

איך זה עובד: תהליך העבודה בן ארבעת השלבים למודרניזציה

כדי לשכתב קוד שעובד באפליקציה קיימת צריך אמון, כי אף אחד לא רוצה שינויים אוטומטיים או רגרסיות קלות. זו גם הסיבה שאין דגל --fix: גם מודרניזציות שנראות פשוטות מתגלות לעיתים קרובות כשינויי קוד חוצי-שכבות – כמו מחיקה של מאזין JS הכרחי או חבילת npm והעברת ההתנהגות ל-HTML ול-CSS – עם התנהגות עדינה ואתגרים בתמיכה בדפדפן.

במקום זאת, תהליך העבודה של המודרניזציה מריץ לולאה בת ארבעה שלבים עם סוכן התכנות:

  1. סריקה (legacy-scan): הנציג מריץ את npx modern-web-guidance legacy-scan <path> --json, שבודק מראש קבצים כדי למצוא מחרוזות משנה רלוונטיות, כך שהוא מפעיל מנתחי AST, ‏ CSS ו-HTML רק בקבצים ובכללים מועמדים. אם ממצא מגיע לשלב הזה, יש כבר סבירות גבוהה (כ-92%) שהוא לא חיובי מוטעה. כל התאמה כוללת רשימת משימות לאימות שהנציג צריך לבצע.
  2. אימות לפי הקשר (keepWhen/dropWhen): מכיוון שהמאגר פתוח לסוכן התכנות, הוא בודק את הקוד שמסביב לכל התאמה לפי קריטריוני האימות של הכלל הזה. אם קריאה של scrollHeight היא חלק מגלילה וירטואלית ולא פריצה של <textarea>, או אם בדיקה של @supports כבר מגינה על המאפיין, הממצא נמחק בלי להודיע על כך.
  3. דוח: הנציג מסכם את הממצאים המאומתים (ומציין ש-legacy-scan מכסה את קבוצת המשנה של המדריכים עם כללים דטרמיניסטיים, וגם את תוכנית המודרניזציה אם ביקשתם לבדוק תוכנית לפני ביצוע שינויים).
  4. אחזור המדריך, ארגון הקוד מחדש ואימות הבדיקה: כשמבקשים מהסוכן לשדרג, הוא מריץ את npx modern-web-guidance retrieve <guide-id> כדי לאחזר את המדריך המתאים. הוא מבצע את ה-refactoring של הקוד בהתאם לתבניות התאימות של Baseline במדריך, ומריץ מחדש את legacy-scan <path> בקבצים ששונו לצד חבילת המקרים לבדיקה של הפרויקט כדי לאשר את הפתרון.

רוצה לנסות?

לא משנה אם אתם מריצים legacy-scan חד-פעמי במסוף או מבקשים מסוכן התכנות שלכם לשדרג מודול ישן, תהליך העבודה של השדרוג עוזר לכם לשלם את החוב של פלטפורמת האינטרנט הקודמת בלי הרעש של ה-linters המסורתיים.

כדי לעבור ממודרניזציה של קוד סטטי לאימות, השוואה לשוק וניפוי באגים בדפדפן בזמן אמת, אתם יכולים לשלב את Modern Web Guidance עם כלי הפיתוח ל-Chrome לסוכני AI.

השלבים הבאים ומשאבים