Repository navigation
Expand file tree
/
Copy pathfile_description.py
More file actions
317 lines (276 loc) · 21.5 KB
/
Copy pathfile_description.py
File metadata and controls
317 lines (276 loc) · 21.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
"""התיאור של קובץ — הגיל שלו ותקרת האורך שלו, כל אחד מקור אמת יחיד.
ב-Ck כל "גרסה" של קובץ היא מסמך חדש באוסף, וה-``description`` מועתק
מהגרסה הקודמת לחדשה. זו ברירת מחדל נכונה — עריכת שורת קוד אינה מבטלת את
התיאור — אבל התוצאה שלה היא שתיאור שנכתב בגרסה 1 נראה בגרסה 11 בדיוק כמו
תיאור שנכתב אתמול. המודול הזה נותן לו **חותמת**: מספר הגרסה שבה התיאור
נקבע או השתנה לאחרונה, ומתוכה את **הגיל** — כמה גרסאות עברו מאז.
שני חצאי הכלל יושבים כאן יחד בכוונה. :func:`description_stamp_for_new_version`
היא צד הכתיבה ו-:func:`description_age_versions` הוא צד הקריאה; פיצול
שלהם לשני מודולים היה מאפשר לשניים לסטות, וסטייה כזאת לא הייתה מתגלה
בשגיאה אלא במספר שנראה סביר.
**ותקרת האורך יושבת כאן מאותה סיבה** (#3489): :data:`FILE_DESCRIPTION_MAX_CHARS`
ו-:func:`description_length_error`. האכיפה יושבת בשכבת המסד
(``update_file_metadata_in``) ובשכבת ה-MCP (``handlers.save_file``), והתיאורים של
כלי ה-MCP נבנים מאותו קבוע — שלוש שכבות שקוראות הגדרה אחת. ``mcp_server/handlers``
בנוי להיות ניתן לייבוא בלי שכבת המסד, ולכן הקבוע לא יכול היה להישאר ב-
``database.repository``.
המודול טהור בכוונה — ``typing`` ותו לא, בלי Flask, בלי מסד ובלי
``bson``. זה מה שמאפשר גם ל-``database/repository``, גם ל-``webapp/app``
וגם ל-``mcp_server/backend`` לייבא אותו ישירות ברמת המודול, בלי
``try/except`` ובלי עותק fallback. אותה תבנית שכבר עובדת עם
``file_dates``, ``file_deletion`` ו-``user_roles`` — ובוובאפ היא לא
נוחות אלא תנאי: ייבוא מ-``database.repository`` ברמת המודול מפיל את
``import webapp.app`` בסביבה בלי ``MONGODB_URL``, ויש טסט שאוכף את זה.
"""
from __future__ import annotations
from typing import Any
#: שם השדה המאוחסן שנושא את מספר הגרסה שבה התיאור נקבע לאחרונה.
#:
#: מוגדר פעם אחת כי הוא נכתב בשישה מסלולי יצירת גרסה ובמסלול עדכון אחד,
#: ונקרא בשלושה מסלולי קריאה — מחרוזת מודפסת בכל אחד מהם הייתה עשרה
#: מקומות שאפשר לשגות בהם בלי ששום בדיקת טיפוסים תיפול. אותו נימוק בדיוק
#: כמו ``VERSION_CREATED_AT_FIELD`` ב-``file_dates``.
DESCRIPTION_SET_AT_VERSION_FIELD = "description_set_at_version"
#: שם השדה ה**מחושב** שמוחזר ללקוחות ה-MCP. אינו נשמר באף מסמך.
DESCRIPTION_AGE_FIELD = "description_age_versions"
#: התקרה המעשית לאורך ``description`` של קובץ, **בתווים**.
#:
#: המספר עצמו אינו חדש — הראוט ``quick-update`` בוובאפ חתך ב-500 מאז שנכתב.
#: מה שחדש הוא שיש לו שם אחד: משנוסף ``codekeeper_update_file_description``
#: ב-MCP, ``500`` קשיח בשני קבצים היה נעשה מספר שרק אחד משני המקומות יקבל
#: את העדכון הבא שלו, ותיאור שנכתב דרך הכלי היה נחתך בשקט ברגע שמישהו
#: עורך אותו בדפדפן.
#:
#: **תווים ולא בייטים, וזה מכוון.** ``len()`` בפייתון סופר תווים, ובעברית
#: כל אות היא שני בייטים ב-UTF-8 — תקרה שנמדדת בבייטים הייתה חותכת תיאור
#: עברי בחצי האורך, ובגבול עצמו באמצע אות. ראו H6 ב-``BY-STACK/hebrew-source.md``
#: שבריפו ``amir-bug-patterns`` (לא בריפו הזה). מכאן גם ``max_chars`` ו-``actual_chars``
#: בתשובות: עד #3489 הסירוב נשא רק ``max``, וסוכן עם 413 תווים עבריים (625 בתים)
#: לא יכול היה לדעת ממנו אם הטקסט שלו נכנס.
#:
#: **איפה הוא נאכף, ומה כל ערוץ עושה איתו — בכוונה לא אותו דבר.** הוא נאכף
#: רק על תיאור **שנמסר מבחוץ**, ולעולם לא על תיאור שמועתק לגרסה חדשה
#: (:func:`description_length_error`):
#:
#: - ``codekeeper_update_file_description`` — סירוב ``description_too_long``,
#: כי שם התיאור הוא כל הבקשה (``update_file_metadata_in``).
#: - ``codekeeper_save_file`` — הקובץ נשמר והתיאור לא, עם ``description_saved:
#: false`` (``mcp_server/handlers.py``): סירוב היה שולח את הסוכן לשלוח שוב את
#: כל התוכן בגלל מטא-דאטה.
#: - הראוט ``quick-update`` בוובאפ **חותך** לפני הכתיבה, כי שם אדם רואה את
#: הטקסט בתיבה לפני השליחה ואחריה — ולכן לעולם אינו מגיע לסירוב.
#: - **הבוט, טפסי הוובאפ שכותבים גרסה, ומסלולי ההעתקה אינם אוכפים** — הבוט
#: והטפסים עוד לא (#3489, חלק שלא בסבב הזה), וההעתקות בכוונה. קובץ יכול
#: לכן לשאת תיאור ארוך מהתקרה, וזה מצב שהקוד חייב להמשיך לתמוך בו.
FILE_DESCRIPTION_MAX_CHARS = 500
def description_stamp_for_new_version(
previous: Any,
description: Any,
new_version: Any,
) -> int | None:
"""החותמת ל**גרסה חדשה** שנכתבת עכשיו: באיזו גרסה התיאור הזה נקבע.
**הכלל יושב כאן ולא בכל כותב בנפרד, וזה כל העניין.** כתיבת גרסה חדשה
של קובץ מתרחשת בשישה מקומות: ``Repository.save_code_snippet`` (הבוט,
כל כלי הכתיבה של ה-MCP, הפסאדות, שחזור מגיבוי) וחמישה ``insert_one``
נפרדים ב-``webapp/app.py`` — עריכה, העלאה, שחזור גרסה, שמירת מדריך
משותף וייצוא Incident Story. ``description`` **כבר** מועתק מהגרסה
הקודמת בכל ששת המקומות, כל אחד בנוסח משלו; חותמת שהייתה מועתקת באותה
צורה הייתה נשמטת במקום הראשון שמישהו יוסיף, והשדה היה מדווח "עדכני"
על תיאור בן אחת-עשרה גרסאות — כלומר בדיוק הכשל שהוא בא לחשוף.
``description`` והחותמת שלו הם שני שדות מקושרים שחייבים לזוז יחד
(``bugbot-rules/linked-field-atomicity.md``).
**הפונקציה טהורה ואינה כותבת כלום.** היא מחזירה מספר, והכותב מחליט
איפה להניח אותו. זה מה שמאפשר לשני החיבורים למונגו שבפרויקט —
ה-``DatabaseManager`` הגלובלי וזה שהוובאפ פותח בעצמו
(``webapp.app.get_db``) — להזין את אותה לוגיקה.
**הכללים:**
- תיאור ריק או שאינו מחרוזת ← ``None``. קובץ בלי תיאור אינו מקבל
חותמת, ובהתאם גם לא יקבל גיל.
- אין גרסה קודמת ← הגרסה החדשה. התיאור נקבע עכשיו.
- התיאור זהה לקודם ← החותמת של הקודם **עוברת כמות שהיא**. זה הענף
היחיד שמונע איפוס של הגיל בכל עריכה.
- התיאור שונה ← הגרסה החדשה.
- גרסה קודמת בלי חותמת תקינה (קובץ מלפני השדה, כזה שהמיגרציה לא
הצליחה לחשב, או חותמת שאינה תקפה ביחס למסמך שהיא יושבת עליו) ←
``None``. עריכה אינה יודעת מתי התיאור נכתב, ושתיקה עדיפה על מספר
שנשמע כמו ידיעה.
**``None`` פירושו "אל תכתוב את השדה"** ולא "כתוב ``None``": שדה חסר
הוא מה ש-:func:`description_age_versions` מתרגם ל-``null``, ושדה
שנושא ``None`` היה מגיע לאותו מקום בדרך ארוכה יותר.
**``previous`` חסר נחשב "קובץ חדש" ולא "לא ידוע", וזו החלטה.** הוא
חסר גם כששמירה נוחתת על שם שכל גרסאותיו בסל המיחזור — ושם התיאור
באמת נקבע עכשיו, ואפס הוא התשובה הנכונה. הוא יכול להיות חסר גם
כשקריאת הגרסה הקודמת נכשלה, וזה כבר ניחוש; אבל באותו מסלול בדיוק גם
``created_at`` וסימון הנעיצה כבר נלקחים כאילו אין קודם
(``save_code_snippet``), ומספור הגרסה עצמו מפיל את השמירה כשהוא לא
מצליח לברר. הפרדה בין שני המצבים אינה זמינה בשכבה הזו.
``isinstance`` ולא ``str(...)``: ``description`` מגיע מגוף JSON של
כלי MCP או משדה טופס, כלומר מחוץ לתהליך, והמרה שקטה של ``42``
למחרוזת ``"42"`` הייתה קוברת קלט פגום במקום לדחות אותו
(``bugbot-rules/external-input-isinstance.md``).
"""
if not isinstance(description, str) or not description:
return None
version = normalized_version(new_version)
if version is None:
return None
if not isinstance(previous, dict):
return version
previous_description = previous.get("description")
if not isinstance(previous_description, str):
previous_description = ""
if previous_description != description:
return version
previous_stamp = normalized_version(previous.get(DESCRIPTION_SET_AT_VERSION_FIELD))
previous_version = normalized_version(previous.get("version"))
# **החותמת נבדקת מול המסמך שהיא יושבת עליו**, ולא רק מול הגרסה
# החדשה. היא תכונה של הגרסה הקודמת — "בגרסה הזו התיאור נקבע" — ולכן
# מסגרת ההתייחסות הנכונה היא ``previous["version"]``.
#
# בדיקה מול הגרסה החדשה בלבד מחמיצה בדיוק את המקרה הגרוע: מסמך גרסה
# 5 שנושא חותמת 6 הוא נתון פגום, אבל בשמירה הבאה (גרסה 6) ה-6 עובר
# את הסף ויורש — והגרסה החדשה יוצאת עם חותמת ששווה למספר שלה, כלומר
# **גיל 0**. זה הערך היחיד שאסור להמציא, ואי-ידיעה הייתה מתחפשת
# ל"התיאור נכתב עכשיו".
#
# ``previous_version is None`` נכנס לאותו ענף מאותה סיבה: בלי לדעת
# על איזו גרסה החותמת יושבת אי אפשר לאמת אותה, ושתיקה עדיפה על
# מספר שנשמע כמו ידיעה. שני התנאים על ``version`` נשמרים גם יחד,
# כי מסמך "קודם" שמספרו גבוה מהחדש הוא בעצמו נתון פגום.
if (
previous_stamp is None
or previous_version is None
or previous_stamp > previous_version
or previous_stamp > version
):
return None
return previous_stamp
def description_age_versions(doc: Any) -> int | None:
"""כמה גרסאות עברו מאז שהתיאור נקבע — או ``None`` כשלא ידוע.
**מחושב בזמן קריאה ואינו נשמר.** ערך שמור היה חייב להתעדכן בכל
שמירה, והשמירה שתשכח אותו הייתה מייצרת בדיוק את השקר שהשדה בא
לחשוף. חיסור של שני מספרים אינו שווה את הסיכון הזה.
**``None`` ולעולם לא ``0`` כשלא ידוע.** אפס הוא טענה — "התיאור נכתב
לגרסה הזו" — ומי שאין לו חותמת אינו יודע אותה. שלושת המסלולים
שמחזירים ``None``: מסמך בלי מספר גרסה (קובץ גדול ב-``large_files``
אינו ממוספר כלל), מסמך בלי חותמת (נכתב לפני השדה, או שהמיגרציה לא
הצליחה לשחזר), וחותמת שגבוהה ממספר הגרסה.
מחזירה ``None`` גם לקובץ **בלי תיאור** — ושם הקורא אמור לא להחזיר את
השדה בכלל, כי אין תיאור שאפשר לבדוק את גילו. ההבחנה בין שני סוגי
ה-``None`` שייכת לקורא ולא לכאן: כאן יש רק שאלה אחת, "מה הגיל",
ולשתיהן אין לה תשובה.
**הגיל הוא הפרש של מספרי גרסה, לא מניין עריכות שקרו.** מספור הגרסאות
רץ על כל המסמכים של אותו שם קובץ כולל אלה שבסל המיחזור
(``_max_version_any_state``), ולכן גרסאות שנמחקו משאירות חורים ברצף
והגיל יוצא גדול במקצת ממספר העריכות בפועל. זה לא משנה את מה שהשדה
משמש לו — סדר גודל, לא ספירה מדויקת.
"""
if not isinstance(doc, dict):
return None
version = normalized_version(doc.get("version"))
if version is None:
return None
stamp = normalized_version(doc.get(DESCRIPTION_SET_AT_VERSION_FIELD))
if stamp is None or stamp > version:
return None
return version - stamp
def description_age_field(doc: Any) -> dict:
"""מה שמסלולי הקריאה מוסיפים לתשובה — ``{}`` או ``{השדה: גיל-או-None}``.
**ההחלטה אם השדה מופיע בכלל שייכת לכאן ולא לכל קורא בנפרד**, כי היא
ההבחנה שהכי קל לטעות בה: ``null`` ו"אין שדה" אינם אותו דבר. ``null``
אומר *"יש כאן תיאור ואיני יודע בן כמה הוא — לך תבדוק"*, ולכן הוא
קריאה לפעולה; היעדר השדה אומר *"אין כאן מה לבדוק"*, ולכן הוא שקט.
לשפוך את שניהם ל-``null`` היה מייצר התראה על כל קובץ בלי תיאור.
שני מקרים מחזירים ``{}``:
- **קובץ בלי תיאור.** אין טקסט שאפשר לשאול על גילו.
- **מסמך בלי מספר גרסה.** קובץ גדול (``large_files``) נשמר בדריסה
ולא בגרסאות ואין לו ``version`` כלל — "גיל בגרסאות" אינו מושג
שקיים שם, ו-``null`` היה שולח את הסוכן לבדוק משהו שאין בו מה
לבדוק.
``null`` נשאר למקרה שהוא באמת מתאר: קובץ **ממוספר** שיש לו תיאור
ואין לו חותמת — נכתב לפני שהשדה קיים, או שהמיגרציה לא הצליחה
לשחזר את שרשרת הגרסאות שלו.
"""
if not isinstance(doc, dict):
return {}
description = doc.get("description")
if not isinstance(description, str) or not description:
return {}
if normalized_version(doc.get("version")) is None:
return {}
return {DESCRIPTION_AGE_FIELD: description_age_versions(doc)}
def description_length_error(
description: str,
previous_description: Any = None,
) -> dict[str, int] | None:
"""``None`` כשהתיאור מותר; אחרת ``{"max_chars": ..., "actual_chars": ...}``.
**מותר** פירושו אחד משניים: באורך של עד :data:`FILE_DESCRIPTION_MAX_CHARS`
תווים, **או זהה לתיאור הקודם** — בכל אורך. הכלל השני הוא מה שמבדיל תיאור
שנמסר מבחוץ מתיאור שמועתק: קובץ שנשמר עם תיאור ארוך (לפני שהתקרה נאכפה,
או בערוץ שעוד אינו אוכף אותה — מי אוכף ואיך, ליד :data:`FILE_DESCRIPTION_MAX_CHARS`)
חייב להישאר ניתן לעריכה, לשחזור,
ולסימון "נבדק" ב-``codekeeper_update_file_description`` עם אותו טקסט.
אותה הבחנה כבר קיימת בכלל החותמת — ראו :func:`description_stamp_for_new_version`,
"התיאור זהה לקודם".
**הפונקציה טהורה ואינה קוראת כלום.** ``previous_description`` מגיע מהקורא,
כי רק הקורא יודע מאיזה מסמך הוא נקרא — וכשהוא צריך שההשוואה תהיה אטומית
עם הכתיבה, היא חייבת לשבת בתוך הכתיבה ולא כאן (``update_file_metadata_in``
עושה בדיוק את זה, ומשתמש בפונקציה כדי לקבוע אם לכתוב בתנאי ואם הכתיבה
חלה). ``None`` או ערך שאינו מחרוזת פירושו "אין תיאור קודם שאפשר להשוות
אליו", ולא "זהה".
**המספרים הם תווים ולא בתים** (``len``), ושמות השדות אומרים זאת — אותו
אוצר מילים של ``path_too_long`` ו-``section_too_long`` בכלי ה-MCP. המדידה
היא על הערך שייכתב, כלומר אחרי כל נרמול שהקורא עושה (``strip`` ב-MCP).
``TypeError`` על תיאור שאינו מחרוזת, ולא ``None``: הקוראים בודקים טיפוס
לפני כן ומחזירים קוד שגיאה משלהם (``invalid_description``), ולכן ערך כזה
כאן הוא באג אצל קורא — ורשימה של מחרוזת אחת ארוכה הייתה עוברת את
``len`` בשקט כ"קצרה" (``bugbot-rules/external-input-isinstance.md`` ב-``amir-bug-patterns``).
"""
if not isinstance(description, str):
raise TypeError(f"description must be str, not {type(description).__name__}")
if len(description) <= FILE_DESCRIPTION_MAX_CHARS:
return None
if isinstance(previous_description, str) and description == previous_description:
return None
return {"max_chars": FILE_DESCRIPTION_MAX_CHARS, "actual_chars": len(description)}
def normalized_version(value: Any) -> int | None:
"""מספר גרסה חיובי, או ``None`` לכל דבר אחר.
**ציבורית, כי זו התשובה לשאלה "מה נחשב מספר גרסה" וכל מי ששואל
אותה חייב לקבל את אותה תשובה.** ``scripts/migrate_description_set_at_version.py``
שואל אותה על כל מסמך בשרשרת; קודם היה לו עותק משלו, וכשהעותק הזה
היה קיים רק בחצי אחד מהסקריפט — הבנייה סיננה מספר פגום והבחירה
של הגרסה האחרונה קרסה עליו. עותק שני של כלל הוא עותק שיסטה.
``bool`` נפסל מפורשות: הוא תת-מחלקה של ``int`` בפייתון, ו-``True``
היה עובר כ-1 ונקרא כ"התיאור נקבע בגרסה הראשונה".
``int(value)`` על מחרוזת נעשה בכוונה ולא נדחה — מסמכים ישנים במונגו
נושאים לעיתים מספרים כמחרוזות, וזה אותו ``int(...)`` שכבר מריצים
``_max_version_any_state`` והראוטים בוובאפ על אותו שדה בדיוק.
**``ArithmeticError`` נתפס, וזה לא הרחבה ליתר ביטחון.** BSON יודע
לאחסן ``double`` אינסופי, ו-``int(float("inf"))`` זורק
``OverflowError`` — שאינו ``ValueError`` ואינו ``TypeError``. נמדד:
``NaN`` דווקא עובר בשלום (הוא כן ``ValueError``), ולכן הפער היה
נראה מכוסה. ``OverflowError`` ו-``InvalidOperation`` של ``Decimal``
הם שניהם ``ArithmeticError``, כלומר שם אחד מכסה את כל הצורות של
"``int()`` לא הצליח להמיר".
זה חשוב כאן במיוחד מפני שהפונקציה רצה בכל מסלול קריאה של קובץ
(``_clean`` ב-``mcp_server/backend.py``): מסמך פגום יחיד היה מפיל
את כל הרשימה, לא רק את עצמו.
"""
if isinstance(value, bool) or value is None:
return None
try:
number = int(value)
except (TypeError, ValueError, ArithmeticError):
return None
# **ערך שברי נדחה ואינו מקוצר.** ``int(1.5)`` הוא ``1``, כלומר מספר
# גרסה שהומצא: הוא יכול להתנגש בגרסה 1 אמיתית, והגיל שייגזר ממנו
# ייראה סביר לגמרי. זו אותה הכרעה בדיוק שנעשתה על ``Infinity`` שורה
# למעלה — נתון פגום הוא אי-ידיעה, לא ערך לעגל.
#
# ההשוואה מדלגת על מחרוזות כי ``3 != "3"`` תמיד, ושם ``int()`` כבר
# עשה את העבודה: ``int("3.5")`` זורק ``ValueError`` מעצמו. למספרים
# ``3 == 3.0 == Decimal("3")`` מחזיר ``True``, ולכן ערך שלם שנשמר
# כ-``double`` — הצורה הרגילה במונגו — ממשיך לעבור.
if not isinstance(value, str) and number != value:
return None
return number if number >= 1 else None