From 8f708adb075e7dd7059b776725eb5ed804f34032 Mon Sep 17 00:00:00 2001 From: Sad Lang Dev Date: Tue, 1 Sep 2026 10:12:47 +0300 Subject: [PATCH 1/2] =?UTF-8?q?=D8=AF=D9=84=D9=8A=D9=84:=20=D8=AD=D8=A7?= =?UTF-8?q?=D8=B1=D8=B3=D9=8C=20=D9=8A=D9=82=D9=8A=D8=B3=D9=8F=20=D9=83?= =?UTF-8?q?=D9=84=D9=8E=D9=91=20=D9=81=D8=B5=D9=84=D9=8D=D8=8C=20=D9=88?= =?UTF-8?q?=D9=81=D8=AD=D8=B5=D9=8C=20=D9=8A=D9=82=D9=8A=D8=B3=D9=8F=20?= =?UTF-8?q?=D9=85=D8=B1=D8=AC=D8=B9=D9=8E=20=D8=A7=D9=84=D9=82=D9=81=D9=84?= =?UTF-8?q?=D9=90=20=D9=84=D8=A7=20=D9=88=D8=B3=D9=85=D9=8B=D8=A7=20=D8=B3?= =?UTF-8?q?=D9=88=D8=A7=D9=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit عطبان في أداةِ المزامنةِ نفسِها — لا في الفصول: ١) `cmd_guard_lock` كان يمرّرُ بصمةً تقدّمت إن عُدِّل **أيُّ** فصلٍ يستشهدُ بمصدرها. فمفتاحٌ مشتركٌ (أربعةٌ اليوم: `scripts/codegen` · `_schemas` · `language-truth/grammar` · `ast_visitor.h`) كان يَسِمُ الفصلَ الثانيَ طازجًا وما قرأه أحد — أي أنّ الحارسَ يكتمُ ما بُنيَ لِيَكشِفَه. صار يشترطُ **كلَّ** الفصول، ويسمّي المتروكَ منها والمشتركَ معه. ٢) `sync-check` الأسبوعيُّ كان يقيسُ الانجرافَ عند «آخرِ وسمِ إصدار» بينما القفلُ مبصومٌ عند `dev`. وv1.0.0 وسمُ ٢٠٢٦-٠٣-٠٩، سابقٌ لـ`language-truth/` و`scripts/codegen`، فأعلنَ التقريرُ حذفَ ٣٠ مسارًا وتعذُّرَ ٤٧ (القضيّة #1) وكلُّها قائمةٌ سليمةٌ على dev — إنذارٌ دائمٌ لا يُقرأ، وتحته تعفّنَت أحدَ عشرَ فصلًا بلا كاشف. صار الافتراضيُّ مرجعَ القفلِ نفسَه، ويُرفَعُ تحفّظٌ صريحٌ — على المعيار وفي جسمِ القضيّة — كلّما اختلفَ المرجعان. برهانان (خارج المستودع): مفتاحٌ مشتركٌ بفصلٍ واحدٍ يُرَدُّ وبفصلَيه يمرّ · لافتةُ المرجعِ تظهرُ عند الاختلافِ وتغيبُ عند التطابق. `--validate` سليم. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/sync-check.yml | 29 +++++++++++++-------- scripts/check_sync.py | 43 +++++++++++++++++++++++++++----- 2 files changed, 56 insertions(+), 16 deletions(-) diff --git a/.github/workflows/sync-check.yml b/.github/workflows/sync-check.yml index 6ed7b62..78285e4 100644 --- a/.github/workflows/sync-check.yml +++ b/.github/workflows/sync-check.yml @@ -1,8 +1,13 @@ # ============================================================================ -# فحص مزامنة الدليل مع كود اللغة (drift detection) — مربوطٌ بإصدارات اللغة. -# يقيس الانجراف تجاه **آخر وسم إصدار** للغة (لا تجاه dev المتقلّب)، فتعكس النتيجة -# «هل يطابق الدليلُ الإصدارَ المنشور؟». يعمل: عند إصدار لغة جديد (repository_dispatch -# من مستودع اللغة)، أسبوعيًّا، ويدويًّا. عند الانجراف يفتح/يحدّث قضيّة بالفصول المتأثّرة. +# فحص مزامنة الدليل مع كود اللغة (drift detection). +# يقيس الانجراف تجاه **مرجع القفل نفسِه** (`sources.lock.json`.ref)، لأنّ البصمات أُخذت +# عنده، فقياسُها عند مرجعٍ سواه يقارن شيئًا بغيره. كان الافتراضُ «آخر وسم إصدار»، +# وv1.0.0 وسمُ 2026-03-09 سابقٌ لـ`language-truth/` و`scripts/codegen`، فكان التقريرُ يعلن +# حذفَ 30 مسارًا وتعذّرَ 47 (القضيّة #1)، وكلّها قائمةٌ سليمةٌ على dev — فصار الإنذارُ ضجيجًا +# لا يُقرأ. ولقياس الدليل تجاه إصدارٍ منشور: أعِد البصم عند وسمِه +# (`--ref vX --update --set-version X`)، ثمّ يصير هو مرجعَ القفل تلقائيًّا. +# يعمل: عند إصدار لغة جديد (repository_dispatch)، أسبوعيًّا، ويدويًّا. +# عند الانجراف يفتح/يحدّث قضيّة بالفصول المتأثّرة. # ============================================================================ name: sync-check @@ -12,7 +17,7 @@ on: workflow_dispatch: inputs: ref: - description: "ref/وسم لقياس الانجراف تجاهه (افتراضيًّا آخر إصدار)" + description: "ref/وسم لقياس الانجراف تجاهه (افتراضيًّا مرجعُ القفل)" required: false repository_dispatch: types: [language-release] # يطلقه مستودع اللغة عند نشر إصدار @@ -32,16 +37,15 @@ jobs: python-version: "3.12" - run: pip install pyyaml - - name: تحديد الـref (وسم الإصدار > مُدخَل يدويّ > آخر إصدار > dev) + - name: تحديد الـref (وسم الإصدار > مُدخَل يدويّ > مرجع القفل > dev) id: ref - env: - GH_TOKEN: ${{ github.token }} run: | REF="${{ github.event.client_payload.tag }}" [ -z "$REF" ] && REF="${{ github.event.inputs.ref }}" + # (AR) الافتراضيّ: المرجعُ الذي أُخذت عنده البصماتُ نفسُه — وحده + # يجعل «تغيّر/حُذف» تعفّنًا فعليًّا لا فرقَ مرجعين. if [ -z "$REF" ]; then - REF=$(gh api repos/sadlang/s-programming-language/releases/latest \ - --jq .tag_name 2>/dev/null || true) + REF=$(python -c "import json;print(json.load(open('sync/sources.lock.json',encoding='utf-8')).get('ref',''))" || true) fi [ -z "$REF" ] && REF="dev" echo "ref=$REF" >> "$GITHUB_OUTPUT" @@ -69,6 +73,11 @@ jobs: L = [f"رصد فحص المزامنة انجرافًا بين الدليل وكود اللغة عند **`{ref}`** " f"(النسخة المُغطّاة في الدليل: `{r.get('covers_version')}`).\n", "أي أن مصادر تغيّرت في اللغة وقد لا يطابقها الدليل بعد.\n"] + lock_ref = r.get("lock_ref") + if lock_ref and lock_ref != ref: + L.append(f"> ⚠️ البصماتُ المخزّنة أُخذت عند `{lock_ref}` لا عند " + f"`{ref}`؛ فـ«حُذف» و«متعذّر الوصول» أدناه تعنيان «غير " + f"موجودٍ عند `{ref}`» لا «أُزيل من اللغة».\n") def sec(t, items): if items: L.append(f"### {t}") diff --git a/scripts/check_sync.py b/scripts/check_sync.py index 0609f69..5f946cc 100644 --- a/scripts/check_sync.py +++ b/scripts/check_sync.py @@ -14,6 +14,10 @@ --json تقرير JSON للأتمتة. --update يثبّت البصمات الحاليّة (بعد مراجعة الدليل). --ref REF يتجاوز ref البيان (مثلًا وسم إصدار: v1.2.0) — لربط المزامنة بالإصدارات. + تنبيه: البصماتُ المخزّنة أُخذت عند `lock.ref`، فقياسُها عند مرجعٍ سواه + يجعل «حُذف/متعذّر» تعني «غير موجودٍ عند ذلك المرجع» لا «أُزيل من اللغة»؛ + لذا يرفع الفحصُ لافتةً على المعيار حين يختلف المرجعان. ولربط الدليل + بإصدارٍ منشور: أعِد البصم عنده (--ref vX --update --set-version X). --set-version V مع --update: يكتب covers_version=V في القفل (ارفعه عند مراجعة إصدار). --validate حارس بلا شبكة: يتحقّق من سلامة البيان (مسارات الفصول، تكرار المفاتيح، صيغة الأسطر، وأن كل فصل تقنيّ في SUMMARY مسجَّل). @@ -238,21 +242,33 @@ def cmd_guard_lock(manifest: dict, base_path: str, changed_path: str) -> int: changed_files = {l.strip().replace("\\", "/") for l in Path(changed_path).read_text(encoding="utf-8").splitlines() if l.strip()} + # (AR) القاعدة: **كلّ** فصلٍ يستشهد بالمصدر يجب أن يُعدَّل، لا أيّ فصلٍ منها. + # المفتاحُ المشترك (`scripts/codegen` بين codegen.md وphilosophy.md مثلًا) + # كان يمرّ بتعديل أحدهما فَيَسِمُ الآخرَ طازجًا دون أن يقرأه أحد — أي أنّ الحارسَ + # نفسَه كان يكتم ما بُني لِيَكشِفَه. (أربعة مفاتيحَ مشتركةٍ اليوم.) offenders = [] for key in advanced + added: chapters = chapters_for_key(manifest, key) - if not any(c in changed_files for c in chapters): - offenders.append((key, chapters)) + untouched = [c for c in chapters if c not in changed_files] + if untouched or not chapters: + offenders.append((key, chapters, untouched)) if offenders: print("❌ كتمٌ صامت مرصود: تقدّمت بصماتٌ في القفل دون تعديل فصولها:\n") - for key, chapters in offenders: - print(f" • المصدر `{key}` تقدّم، لكن لم يُعدَّل أيّ من: " - f"{', '.join(chapters) or '(لا فصل!)'}") + for key, chapters, untouched in offenders: + if not chapters: + print(f" • المصدر `{key}` تقدّم، ولا فصلَ يستشهد به أصلًا!") + continue + shared = [c for c in chapters if c not in untouched] + print(f" • المصدر `{key}` تقدّم، ولم يُعدَّل: " + f"{', '.join(untouched)}") + if shared: + print(f" (مشتركٌ مع فصولٍ عُدّلت: " + f"{', '.join(shared)} — تعديلُ أحدها لا يُبرّئُ البقية)") print("\nالقاعدة: لا تثبّت بصمةً جديدة (`--update`) إلّا بعد مراجعة الفصل " "المرتبط وتعديله فعليًّا. راجع الفصل، عدّله، ثم أعِد --update.") return 1 print(f"✅ الحارس مرّ: كل بصمةٍ تقدّمت ({len(advanced)+len(added)}) رافقها " - "تعديلُ فصلها.") + "تعديلُ **كلّ** فصلٍ يستشهد بها.") return 0 @@ -266,6 +282,20 @@ def cmd_check(manifest: dict, ref: str, as_json: bool) -> int: lock = json.loads(LOCKFILE.read_text(encoding="utf-8")) old = lock.get("sources", {}) + # (AR) البصماتُ المخزّنة أُخذت عند `lock["ref"]`. قياسُها عند مرجعٍ آخر + # يقارن شيئًا بشيءٍ سواه: مسارٌ لم يكن قد وُجد بعدُ عند وسمٍ قديم + # يُقرأ «حُذف». (قِيس: v1.0.0 وسمُ 2026-03-09، وهو قبل `language-truth/` + # و`scripts/codegen`، فكان التقريرُ الأسبوعيّ يعلن حذفَ 30 مسارًا + # وتعذّرَ 47، وكلّها قائمةٌ سليمةٌ على dev. القضيّة #1 شاهدُها.) + lock_ref = lock.get("ref") + if lock_ref and lock_ref != ref: + print(f"⚠️ المرجع المقيس `{ref}` يخالف مرجع القفل `{lock_ref}`.\n" + f" «حُذف» و«متعذّر الوصول» أدناه تعني «غير موجودٍ عند `{ref}`» " + f"لا «أُزيل من اللغة».\n" + f" لقياس تعفّنٍ حقيقيّ: قِس عند مرجع القفل (--ref {lock_ref})، " + f"أو أعِد البصم عند `{ref}` (--ref {ref} --update).\n", + file=sys.stderr) + changed = [k for k, s in shas.items() if k in old and old[k] != s] added = [k for k in shas if k not in old] removed = [k for k in old if k not in shas] @@ -275,6 +305,7 @@ def cmd_check(manifest: dict, ref: str, as_json: bool) -> int: report = { "drift": bool(drift_keys or missing or added), "ref": ref, + "lock_ref": lock_ref, "changed": sorted(changed), "added": sorted(added), "removed": sorted(removed), From 79dbec66cec6ca638b9253626242a653ddc33662 Mon Sep 17 00:00:00 2001 From: Sad Lang Dev Date: Tue, 1 Sep 2026 10:34:46 +0300 Subject: [PATCH 2/2] =?UTF-8?q?=D8=AF=D9=84=D9=8A=D9=84:=20=D9=85=D9=88?= =?UTF-8?q?=D8=AC=D8=A9=D9=8C=20=D8=AB=D8=A7=D9=86=D9=8A=D8=A9=D9=8C=20?= =?UTF-8?q?=D8=AA=D9=8F=D8=BA=D9=84=D9=82=D9=8F=20=D8=A7=D9=84=D8=A7=D9=86?= =?UTF-8?q?=D8=AC=D8=B1=D8=A7=D9=81=D9=8E=20=E2=80=94=20=D9=88=D8=AA=D8=B1?= =?UTF-8?q?=D8=A8=D8=B7=D9=8F=20=D9=83=D9=84=D9=8E=D9=91=20=D8=AF=D8=B9?= =?UTF-8?q?=D9=88=D9=8B=D9=89=20=D8=AD=D8=A7=D9=85=D9=84=D8=A9=D9=8D=20?= =?UTF-8?q?=D8=A8=D9=85=D8=B5=D8=AF=D8=B1=D9=8D=20=D9=85=D8=A8=D8=B5=D9=88?= =?UTF-8?q?=D9=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ستّةُ فصولٍ رُوجعت (llvm · interpreter · ast · grammar-sot · crypto-unification · sadui-layout)، وعشرون بصمةً تقدّمت أو أُضيفت، فبلغ الانجرافُ **صفرًا**: أربعةٌ وستّون مصدرًا كلُّها مبصومةٌ ومطابقةٌ لـdev لأوّل مرّة. و`covers_version` صار `dev@1138f5e1` لا `1.0.0` — الدليلُ يصفُ dev لا إصدارَ آذار. ما كان يكذبُ في الفصول: • `SIRBuilder` ليس زائرًا — يرثُ SIRBuilderContext ويوزّعُ بـdynamic_cast، والمخطّطُ كان يرسمُه فرعًا من ASTVisitor. أثرُه عمليّ: دالّةُ visit وحدَها لا تصلُ المترجم، فتسقطُ العقدةُ صامتةً. • `--emit-llvm` علمٌ لا وجودَ له — القانونيُّ `--أظهر-llvm` (لا مرادفات). • `ClassManager` مُفرَدٌ عابرٌ للمحرّكين، يقفلُ إنشاءَه لا خريطتَه — فوعدُ عزلِ الـgoroutines لا يشملُه. • `execute` لا يبدأُ بالتنفيذ: طورٌ ساكنٌ يمسحُ البرنامجَ كلَّه، وفاحصُ الأنواعِ فيه **مطفأٌ افتراضيًّا**، والثلاثةُ محجوبةٌ على wasm وأندرويد. • `sadc.exe` اسمٌ متقاعدٌ لا يُنتجه هدف — وsetup.md كان يوصي بنسخِ الثنائيّ إليه، أي يوصي بعطب. الهدفُ `sad-build`، والمفسّرُ `sad-run`. • أعدادٌ تباعدت: ٨٢←١٠٤ مفتاحَ خاصّيّة · «أربعةُ ملفّات»←٢٠ · ٩٥ دالّةَ زيارة منها ٥ بجسمٍ فارغ لا صرفة · ثمانيةُ مجلّداتِ بُناة. • `sadinfo` أداةٌ متقاعدةٌ بقيت في أربعةِ فصول. والأهمُّ بنيويًّا: سبعةُ مصادرَ تحملُ الدعاوى المركزيّةَ لهذه الفصول لم تكن مسجَّلةً في البيان أصلًا (sir_builder.h · interpreter_core.cpp · class_manager · cli_flags.yaml · …)، فانجرافُها لا يُرصَد. سُجّلت وبُصمت، و`pipeline.md` سُجّل فصلًا (٢٢ فصلًا لا ٢١). البوّابات: --validate ٠ · الحارسُ الأصرمُ مرّ بعشرين بصمةً كلٌّ بكلّ فصولها · الانجراف صفر · mdbook نظيف · ٧٣٢ رابطًا محلّيًّا بلا كسر. Co-Authored-By: Claude Opus 5 (1M context) --- src/SUMMARY.md | 4 +- src/architecture/overview.md | 2 +- src/architecture/pipeline.md | 6 +- src/backend/crypto-library-expansion.md | 8 +- src/backend/crypto-unification.md | 33 ++++--- src/backend/interpreter.md | 101 ++++++++++++++++++---- src/backend/llvm.md | 32 +++++-- src/backend/native.md | 2 +- src/contributing/definition-of-done.md | 2 +- src/contributing/freshness.md | 8 +- src/frontend/ast.md | 74 +++++++++++++--- src/getting-started/first-contribution.md | 4 +- src/getting-started/repo-map.md | 2 +- src/getting-started/setup.md | 22 +++-- src/glossary.md | 6 +- src/introduction.md | 2 +- src/sot/grammar-sot.md | 32 +++++++ src/sot/philosophy.md | 2 +- src/status.md | 2 +- src/systems/builtins.md | 2 +- src/systems/sadui-layout.md | 13 ++- sync/sources.lock.json | 27 ++++-- sync/sources.yaml | 16 +++- 23 files changed, 311 insertions(+), 91 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index c40c89b..9b31225 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -35,9 +35,9 @@ - [المفسّر الشجري (Interpreter)](backend/interpreter.md) - [التمثيل الوسيط SIR](backend/sir.md) -- [توليد LLVM (المترجم sadc)](backend/llvm.md) +- [توليد LLVM (المترجم sad-build)](backend/llvm.md) - [الخلفيّة الأصليّة بلا LLVM (SIR → ELF64)](backend/native.md) -- [دراسة حالة: توحيد هاش/شفّر/فك_تشفير](backend/crypto-unification.md) +- [دراسة حالة: توحيد هاش/شفر/فك_تشفير](backend/crypto-unification.md) - [دراسة حالة: توسيع مكتبة التشفير (٥ مراحل + Argon2id)](backend/crypto-library-expansion.md) # الجزء السادس · أنظمة اللغة diff --git a/src/architecture/overview.md b/src/architecture/overview.md index 7ec943f..0d6d26f 100644 --- a/src/architecture/overview.md +++ b/src/architecture/overview.md @@ -12,7 +12,7 @@ | الخلفيّة الأصليّة | `compiler/include/backend/native/` | SIR → شيفرة آلة → ELF64 ساكن بلا LLVM ولا رابطٍ أجنبيّ — [الفصل](../backend/native.md) | | ~~الآلة الافتراضية~~ | — | `vm/` أُزيل من الشجرة بالإيداع `bcf0a746` («ستُعاد كتابتها من الصفر») — لا فصل له حتّى تُكتب | | المكتبة القياسية | `stdlib/` | وحدات عربية: core/io/math/string/network/graphics | -| الأدوات | `tools/` | lsp · formatter · pkg · repl · sadc CLI · sadinfo | +| الأدوات | `tools/` | ١٥ مجلّدًا على `dev`: analyze · apk_builder · build · check · compiler (واجهة `sad-build`) · formatter · hub (موزِّع `sad`) · installers · lsp · pkg · profiler · repl · security-scanner · shared · wasm | | مصدر الحقيقة | `language-truth/` | YAML SoT لكل بيانات اللغة + القواعد | ## القاعدة الطبقيّة (CW-02) diff --git a/src/architecture/pipeline.md b/src/architecture/pipeline.md index d23d94e..5b0d1f5 100644 --- a/src/architecture/pipeline.md +++ b/src/architecture/pipeline.md @@ -33,16 +33,16 @@ flowchart LR `InterpreterCore` يزور AST مباشرةً: يدير النطاقات والمتغيّرات والدوال، ويقيّم التعابير، وينفّذ الجمل. سريع للتطوير والاختبار. -## المرحلة 4ب — الترجمة (sadc) +## المرحلة 4ب — الترجمة (`sad-build`) 1. **`SIRBuilder`**: AST → **SIR** (تمثيل وسيط بتعليمات ملكية، `sir_types.h`). 2. **`SIROptimizer`**: تمريرات على SIR. 3. **`LLVMCodeGen`**: SIR → LLVM IR، ثم LLVM يُنتج كائنًا يُربَط لملفّ تنفيذيّ. -> **لماذا SIR وسيط؟** يفصل دلالة الملكية/الأنواع عن تفاصيل LLVM، ويسهّل التحسين والتشخيص (`--emit-llvm`, SIR dumps). +> **لماذا SIR وسيط؟** يفصل دلالة الملكية/الأنواع عن تفاصيل LLVM، ويسهّل التحسين والتشخيص (`--أظهر-llvm`، وتفريغات SIR). ## نقاط تشخيص مفيدة - اختلاف سلوك المفسّر عن المترجم ⇒ المشكلة في `SIRBuilder` أو `LLVMCodeGen` (BF-08). -- ولّد LLVM IR بـ`--emit-llvm` وافحص: الكتلة الأولى، تطابق أنواع الحقول، ترتيب التعليمات، `getelementptr`. +- ولّد LLVM IR بـ`--أظهر-llvm` وافحص: الكتلة الأولى، تطابق أنواع الحقول، ترتيب التعليمات، `getelementptr`. --- **اقرأ بعده:** [الأنظمة المتشابكة](interconnected.md). diff --git a/src/backend/crypto-library-expansion.md b/src/backend/crypto-library-expansion.md index 8447236..2030b17 100644 --- a/src/backend/crypto-library-expansion.md +++ b/src/backend/crypto-library-expansion.md @@ -1,6 +1,6 @@ # دراسة حالة: توسيع مكتبة التشفير (٥ مراحل + Argon2id) -بعد [توحيد هاش/شفّر](crypto-unification.md) (`هاش`/`شفّر`/`فك_تشفير` في وحدة `تأكيدات`)، وُسِّعت +بعد [توحيد هاش/شفر](crypto-unification.md) (`هاش`/`شفر`/`فك_تشفير` في وحدة `تأكيدات`)، وُسِّعت اللغة بمكتبة تشفير حديثة كاملة في وحدة منفصلة `تشفير` — عبر RFC كامل (`sadlang-rfcs/text/0000-توسيع-مكتبة-التشفير.md`) نُفِّذ على ٥ مراحل + مرحلة إضافيّة (Argon2id) بطلب صريح من المالك رغم تأجيلها في نصّ RFC الأصليّ. المرجع @@ -21,7 +21,7 @@ | ٤ | `ولّد_مفتاح_خاص_x25519` وعائلتها (7 دوال) | X25519 (RFC 7748) + Ed25519 (RFC 8032) + SHA-512 ذاتيّ | #221 | كل الدوال ذاتيّة التنفيذ (self-rolled، بلا OpenSSL/libsodium) حفاظًا على قابليّة -العمل على هدف الوضع الحرّ (نفس قيد [[crypto-unification|توحيد هاش/شفّر]])، وسطح +العمل على هدف الوضع الحرّ (نفس قيد [[crypto-unification|توحيد هاش/شفر]])، وسطح اللغة لكل دالّة **سلسلة تدخل ⇒ سلسلة تخرج** حصرًا على كلا المحرِّكين — لا كائنات مركَّبة عابرة للحدود. @@ -124,12 +124,12 @@ AEAD في **نفس** القطعة بعد حلّ التعارض أعاد تجاو كل مرحلة أضافت ملفّات إلى `tests/behavior/sections/09_المكتبة_القياسية/04_تشفير/` (**20 ملفًّا** في `dev` اليوم؛ كانت 14 عند كتابة الفصل)، -كلّ واحد يُشغَّل عبر `sad-run.exe` **و**`sadc.exe` ويُقارَن الناتج حرفيًّا — +كلّ واحد يُشغَّل عبر `sad-run.exe` **و**`sad-build.exe` ويُقارَن الناتج حرفيًّا — شعاعات RFC/مسابقة رسميّة لكل معيار (BLAKE3-team، RFC 2898/5869/7748/8032/8439/ 9106)، إضافة إلى حالات رفض صريحة (سرّ مشترك كلّه أصفار في X25519، توقيع/مفتاح مُعبَث بهما في Ed25519، بارامترات خارج الحدود الآمنة في KDFs). --- -**اقرأ بعده:** [توحيد هاش/شفّر/فك_تشفير](crypto-unification.md) · +**اقرأ بعده:** [توحيد هاش/شفر/فك_تشفير](crypto-unification.md) · [دوال مضمنة ووحدات](../systems/builtins.md) · [نظام معالجة الأخطاء](../systems/errors.md). diff --git a/src/backend/crypto-unification.md b/src/backend/crypto-unification.md index b857ef7..aea2bf8 100644 --- a/src/backend/crypto-unification.md +++ b/src/backend/crypto-unification.md @@ -1,7 +1,7 @@ -# دراسة حالة: توحيد هاش/شفّر/فك_تشفير بين المحرّكين +# دراسة حالة: توحيد هاش/شفر/فك_تشفير بين المحرّكين مثال متكامل على **إزالة تباعُد** بين المفسّر والمترجم (لا إضافة ميزة جديدة): دالّتا -`هاش`/`شفّر`/`فك_تشفير` في وحدة `تأكيدات` كانتا مُنفَّذتين مرّتين بخوارزميّتين +`هاش`/`شفر`/`فك_تشفير` في وحدة `تأكيدات` كانتا مُنفَّذتين مرّتين بخوارزميّتين مختلفتين تمامًا — والمترجم كان يملك **نسخة ثالثة** منفصلة لهدف Android لم يمسّها أحد. المرجع اللغويّ للمستخدم في [sadlang-docs](https://github.com/sadlang/sadlang-docs/blob/main/src/language/security.md)؛ @@ -15,7 +15,7 @@ ```mermaid flowchart TD - MOD["وحدة تأكيدات: هاش / شفّر / فك_تشفير"] + MOD["وحدة تأكيدات: هاش / شفر / فك_تشفير"] MOD --> INT["المفسّر
builtin_module_assertions.cpp
SHA-256 + SHA-256-CTR حقيقيّ"] MOD --> CMP["المترجم (سطح مكتب/Windows/Linux)
sad_embedded_runtime.c
FNV-1a + XOR بسيط"] MOD --> AND["المترجم (هدف Android)
compiler_driver_android_linker.cpp
نسخة ثالثة منفصلة: FNV-1a"] @@ -25,8 +25,8 @@ flowchart TD ثلاث حقائق متزامنة سبّبت الالتباس: 1. **`هاش("نفس النص")` يُعطي قيمتين مختلفتين** حسب المحرّك المُشغِّل — FNV-1a (عدد صحيح) في المترجم مقابل SHA-256 حقيقيّ (نصّ ست عشريّ) في المفسّر. -2. **`شفّر`/`فك_تشفير` غير متبادلين عبر المحرّكين** — XOR بسيط في المترجم لا - يفكّه SHA-256-CTR الذي شفّر به المفسّر، والعكس. +2. **`شفر`/`فك_تشفير` غير متبادلين عبر المحرّكين** — XOR بسيط في المترجم لا + يفكّه SHA-256-CTR الذي شفر به المفسّر، والعكس. 3. **`stdlib/crypto/` كانت تبدو الحلّ الصحيح** (OpenSSL كامل: Hash/HMAC/AES/ Base64) لكن بلا أيّ مستهلك في المفسّر أو المترجم — بُنِيت واختُبِرت (هدف CMake `crypto_tests`) دون أن تُربَط بأيّ مسار تنفيذ فعليّ. @@ -52,13 +52,21 @@ SHA-256/SHA-256-CTR **الذاتيّة التنفيذ** (self-rolled، بلا ا | **مولِّد LLVM** ([`security_builtins_ops.cpp`](https://github.com/sadlang/s-programming-language/blob/dev/compiler/src/backend/llvm/builders/builtins/security_builtins_ops.cpp)) | توقيع `sad_security_hash`: `(i8*) -> i64` | `(i8*) -> i8*` | | **مُصدِّر Android** ([`compiler_driver_android_linker.cpp`](https://github.com/sadlang/s-programming-language/blob/dev/tools/compiler/compiler_driver_android_linker.cpp)) | نسخة ثالثة FNV-1a منفصلة تمامًا | نفس SHA-256 (`sad_sha256_rotr`/`sad_sha256_raw`/`sad_security_hash`) — هذا الهدف لا يملك `sad_security_encrypt`/`decrypt` أصلًا | +> 📎 **الاسم القانونيّ `شفر` بلا شدّة.** مصدرُ الحقيقة +> [`assertions.yaml`](https://github.com/sadlang/s-programming-language/blob/dev/language-truth/builtins/assertions.yaml) +> يسجّل `canonical: شفر`، وكذلك `builtin_registry_generated.h`. وتُكتَب في اختبارات +> السلوك `شفّر` بشدّةٍ فتعمل، لأنّ المعجميّ **يتخطّى علامات التشكيل العربيّة +> (U+064B–U+065F)** داخل المعرِّفات +> ([`lexer_core.cpp`](https://github.com/sadlang/s-programming-language/blob/dev/shared/lexer/src/lexer_core.cpp#L1281)). +> فالشدّةُ زينةُ كتابةٍ لا فرقُ اسم — والقانونيُّ للتوثيق والأدوات هو المجرَّد. + `sad_security_encrypt`/`decrypt` نُقِلا بنفس بنية المفسّر: مقطع `nonce` عشوائيّ 8 بايت في بداية الناتج، وكل كتلة 32 بايت تُخفى بـ`SHA-256(مفتاح ‖ nonce ‖ عدّاد)` كتيّار مفاتيح XOR. ```mermaid flowchart LR - SRC["هاش(نص) / شفّر(نص، مفتاح)"] --> INTP["المفسّر: تقييم مباشر
sha256 lambda"] + SRC["هاش(نص) / شفر(نص، مفتاح)"] --> INTP["المفسّر: تقييم مباشر
sha256 lambda"] SRC --> SIR["المترجم: CALL sad_security_*
(SadTypeKind::String الآن)"] SIR --> RT["sad_embedded_runtime.c
sad_sha256_raw مطابق للمفسّر"] INTP -.->|"تكافؤ حرفيّ + تبادليّة عابرة للمحركين"| RT @@ -96,11 +104,14 @@ flowchart LR ## الاختبار (تكافؤ مزدوج) -`tests/behavior/sections/09_المكتبة_القياسية/04_تشفير/` — أربعة ملفّات: -شعاعات FIPS 180-4 الرسميّة لـ`هاش("")`/`هاش("abc")`، تبادليّة `شفّر`/`فك_تشفير` -عبر نصوص عربيّة/مختلطة/متعدّدة الكتل، شعاع ثابت مُسجَّل يدويًّا كمرساة انحدار، -واختبار مفتاح أطول من 256 بايت (يرصد رجوع باغ الاقتطاع الصامت). كلّ ملفّ يُشغَّل -عبر `sad-run.exe` **و**`sadc.exe` ويُقارَن الناتج حرفيًّا (ADR-03) — هذا ما +`tests/behavior/sections/09_المكتبة_القياسية/04_تشفير/` — **٢٠ ملفًّا اليوم**، +وُلد من هذا التوحيد أربعةٌ منها (`150`–`153`): شعاعات FIPS 180-4 الرسميّة +لـ`هاش("")`/`هاش("abc")`، تبادليّة `شفر`/`فك_تشفير` عبر نصوص عربيّة/مختلطة/متعدّدة +الكتل، شعاع ثابت مُسجَّل يدويًّا كمرساة انحدار، واختبار مفتاح أطول من 256 بايت (يرصد +رجوع باغ الاقتطاع الصامت). أمّا البقيّة (`154`–`168`) فمن +[حملة توسيع مكتبة التشفير](crypto-library-expansion.md) اللاحقة: BLAKE3 · PBKDF2 · +HKDF · AEAD · Argon2id · X25519 · Ed25519 وحدودُها القصوى. كلّ ملفّ يُشغَّل +عبر `sad-run.exe` **و**`sad-build.exe` ويُقارَن الناتج حرفيًّا (ADR-03) — هذا ما يضمن ألّا يعود التباعُد. --- diff --git a/src/backend/interpreter.md b/src/backend/interpreter.md index 9104993..4a47d29 100644 --- a/src/backend/interpreter.md +++ b/src/backend/interpreter.md @@ -2,7 +2,8 @@ > **ماذا ستتعلّم:** كيف يزور `Interpreter` شجرة AST ويقيّمها فورًا (tree‑walking) — > نمط الزائر بحامل النتيجة، تنسيق المدراء (نطاقات · متغيّرات · دوال · كائنات · ملكيّة)، -> دورة التقييم من البرنامج إلى القيمة، ونموذج التزامن (goroutines). +> **الطور الساكن الذي يسبق أوّل جملة**، دورة التقييم من البرنامج إلى القيمة، ونموذج +> التزامن (goroutines) وحدودُ عزله. > 📎 المصدر: [`interpreter/include/core/interpreter_core.h`](https://github.com/sadlang/s-programming-language/blob/dev/interpreter/include/core/interpreter_core.h) · [`visitors/expression_evaluator.h`](https://github.com/sadlang/s-programming-language/blob/dev/interpreter/include/visitors/expression_evaluator.h) · [`shared/ast/include/ast_visitor.h`](https://github.com/sadlang/s-programming-language/blob/dev/shared/ast/include/ast_visitor.h) @@ -31,25 +32,33 @@ flowchart TB INT["Interpreter
execute · executeStatement · evaluateExpression"] INT --> SE["StatementExecutor
(تنفيذ الجمل)"] INT --> EE["ExpressionEvaluator
(تقييم التعابير)"] - subgraph MGR["المدراء (Data::*)"] + subgraph MGR["مدراء المفسّر (interpreter/include/managers/)"] SM["ScopeManager — النطاقات"] VM["VariableManager — المتغيّرات"] FM["FunctionManager — الدوال"] - CM["ClassManager — الأصناف"] OM["ObjectManager — الكائنات"] OW["OwnershipManager — الملكيّة"] end SE --> MGR EE --> MGR + SE -.->|"getInstance()"| CM["ClassManager
(مُفرَدٌ في shared/types — خارج المفسّر)"] ``` -| المدير | يدير | -|--------|------| -| `ScopeManager` | سلسلة النطاقات (دخول/خروج، البحث الهرميّ) | -| `VariableManager` | ربط الأسماء بالقيم داخل النطاق | -| `FunctionManager` | تعريفات الدوال (مشترَكٌ **للقراءة فقط** بين الخيوط) | -| `ClassManager` / `ObjectManager` | الأصناف ومثيلاتها (OOP) | -| `OwnershipManager` | تتبّع الملكيّة/الاستعارة — يربط [نظام الذاكرة](../systems/memory.md) | +| المدير | يدير | أين | +|--------|------|-----| +| `ScopeManager` | سلسلة النطاقات (دخول/خروج، البحث الهرميّ) | `managers/scope_manager.h` | +| `VariableManager` | ربط الأسماء بالقيم داخل النطاق | `managers/variable_manager.h` | +| `FunctionManager` | تعريفات الدوال (مشترَكٌ **للقراءة فقط** بين الخيوط) | `managers/function_manager.h` | +| `ObjectManager` | مثيلات الكائنات (OOP) | `managers/object_manager.h` | +| `OwnershipManager` | تتبّع الملكيّة/الاستعارة — يربط [نظام الذاكرة](../systems/memory.md) | `managers/ownership_manager.h` | +| `GoroutineManager` | دورة حياة الخيوط المتزامنة | `interpreter/include/channel.h` | +| `UIStateManager` | حالة عناصر الواجهة أثناء التفسير | `interpreter/include/ui/ui_state_manager.h` | + +> ⚠️ **`ClassManager` ليس من مدراء المفسّر.** هو **مُفرَدٌ (singleton)** يعيش في +> [`shared/types/include/class_manager.h`](https://github.com/sadlang/s-programming-language/blob/dev/shared/types/include/class_manager.h#L128) +> ويُنادى بـ`ClassManager::getInstance()` من المحلّل والمفسّر والمترجم جميعًا — +> فسجلُّ الأصناف **عابرٌ للمحرّكين وعمليّةٌ واحدة**، لا حالةٌ مملوكةٌ لمثيل `Interpreter`. +> راجع أثرَ ذلك على التزامن في §⑤. ## ② نمط الزائر بحامل النتيجة @@ -73,16 +82,58 @@ sequenceDiagram > 💡 **الإرسال المزدوج (double dispatch):** العقدة تعرف نوعها، فتستدعي `visitBinaryExpr` > الصحيحة دون `switch` على نوعٍ مُعدَّد — إضافة عقدةٍ جديدة = دالة `visit` جديدة في الزائر. -الزائر مقسَّمٌ على ملفّات حسب العائلة (تخفيفًا للترجمة): `expression_evaluator_binary_ops`، -`..._calls_*`، `..._members_*`، `..._oop_*`، `..._overloads`، `..._ui`. ومثلها للجمل: -`statement_executor`، `..._control`، `..._control_exceptions`، `..._functions*`، -`..._modules`، `..._oop*`. +الزائران مقسَّمان على **٣٠ ملفًّا** في `interpreter/src/visitors/` (تخفيفًا لزمن الترجمة): +`expression_evaluator_core` · `..._binary_ops`/`..._binary_logic` · +`..._calls`/`..._calls_dispatch`/`..._calls_invoke`/`..._calls_user_func`/`..._calls_macro` · +`..._members`/`..._members_advanced`/`..._members_assign` · +`..._oop`/`..._oop_new`/`..._oop_array_methods`/`..._oop_string_map_methods`/`..._oop_concurrency` · +`..._overloads` · `..._ui`. ومثلها للجمل: `statement_executor` · `..._control` · +`..._control_exceptions` · `..._functions`/`..._functions_templates` · `..._modules` · +`..._oop`/`..._oop_types`/`..._oop_struct_test`. ومعها `sem045_report` +(تقرير SEM045 — عقد الغياب) وجسرا الواجهة `ui_eval_bridge_core` و`ui_widget_expr_dispatch`. -## ③ دورة التقييم الكاملة +## ③ الطور الساكن: `execute` لا يبدأ بالتنفيذ + +> 🔑 **المفسّر ليس «مشيًا على الشجرة» فقط.** قبل تنفيذ أوّل جملة يمسح +> [`execute()`](https://github.com/sadlang/s-programming-language/blob/dev/interpreter/src/core/interpreter_core.cpp) +> **البرنامجَ كلَّه** — **مرّتين افتراضيًّا، وثلاثًا إن فُعِّل فحصُ الأنواع** (فهو مطفأٌ +> افتراضيًّا، انظر أدناه) — ويشمل المسحُ الدوالَّ غيرَ المُنادَاة والفروعَ الميّتة. +> مَن ظنّه محضَ مُقيِّمٍ كسولٍ فوجئ بتشخيصٍ يخرج من كودٍ لا يُنفَّذ أبدًا. + +```mermaid +flowchart TD + S0["execute(program)"] --> S1["مسحٌ عن الدالّة «رئيسية»"] + S1 --> S2{"قاعدة الدالّة الرئيسيّة
checkMainFunctionRule"} + S2 -->|"كودٌ تنفيذيٌّ خارج الدوال مع وجود رئيسية"| ERR1["SEM_MAIN_FUNCTION_RULE ⇒ توقّف"] + S2 --> S3{"options_.enableTypeCheck؟"} + S3 -->|"false (الافتراضيّ)"| S4 + S3 -->|"true"| TC["TypeChecker على كلّ جملة ⇒ فشلٌ عند أيّ خطأ"] + TC --> S4["NullSafetyAnalyzer — دائمًا"] + S4 --> CLR["ErrorManager::clear()"] + CLR --> P1["الطور الأوّل: تنفيذ كلّ الجمل العلويّة
(تسجيل الدوال والأصناف والعوامّ)"] + P1 --> P2["الطور الثاني: تنفيذ «رئيسية» إن وُجدت"] +``` + +| الطور | متى يعمل | إن فشل | +|---|---|---| +| قاعدة الدالّة الرئيسيّة | حين توجد `رئيسية` | `SEM_MAIN_FUNCTION_RULE` وتوقّفٌ قبل التنفيذ | +| فحص الأنواع (`TypeChecker`) | **مطفأٌ افتراضيًّا**: `enableTypeCheck = false` | توقّفٌ بعدّ الأخطاء | +| تحليل أمان العدم | **دائمًا**، وصرامتُه مشتقّةٌ من سياسة الذاكرة عبر `strictnessFromOwnershipMode` | تحذيراتٌ دائمًا؛ وتوقّفٌ عند الصرامة القاتلة | + +> ⚠️ **العَلَمُ الافتراضيّ يكذبُ على القارئ.** +> [`enableTypeCheck = false`](https://github.com/sadlang/s-programming-language/blob/dev/interpreter/include/core/interpreter_core.h#L78) +> — فالمفسّر يعمل بفاحصِ الأنواع **مُطفأً** ما لم يُطلَب صراحةً. فإن جرى برنامجٌ على +> `sad-run` وسقط على `sad-build`، فليس بالضرورة تباعُدَ محرّكين: قد يكون طورًا ساكنًا +> شغّله المترجمُ ولم يشغّله المفسّر. + +> ⚠️ الأطوارُ الساكنة كلُّها محجوبةٌ بـ`#if !defined(__EMSCRIPTEN__) && !defined(SAD_PLATFORM_ANDROID)` +> — فبناءُ wasm أو أندرويد **لا يفحص شيئًا** قبل التنفيذ. لا تَقِس دلالةَ اللغة على أيٍّ منهما. + +## ④ دورة التقييم الكاملة ```mermaid flowchart TD - P["execute(program: جمل)"] --> LOOP{"لكلّ جملة"} + P["الطور الأوّل/الثاني: تنفيذ الجمل"] --> LOOP{"لكلّ جملة"} LOOP --> ES["executeStatement → StatementExecutor"] ES --> KIND{"نوع الجملة"} KIND -->|تعبيريّة| EVAL["evaluateExpression → accept → getResult"] @@ -101,7 +152,7 @@ flowchart TD `(left, TokenType op, right, Position)` وتتشاور مع [نظام الأنواع](../systems/types.md) للتحميل الزائد والإكراه. -## ④ التزامن (Goroutines) +## ⑤ التزامن (Goroutines) نموذج التزامن يقوم على **العزل**: كلّ goroutine يعمل بـ`StatementExecutor` مستقلّ مع `ScopeManager` / `VariableManager` / `OwnershipManager` خاصّةٍ به، ويُشارَك `FunctionManager` @@ -122,13 +173,25 @@ flowchart LR > نطاق المنشئ. `FunctionManager` مشترَكٌ لكنّه للقراءة فقط، والقنوات (`SadChannel`) آمنةٌ > بـmutex داخليّ. +> 🔑 **حدُّ العزل: `ClassManager` خارجه.** العزلُ أعلاه يغطّي مدراءَ المفسّر، لا المُفرَدَ +> العابرَ للمحرّكين. وقياسُ [`class_manager.cpp`](https://github.com/sadlang/s-programming-language/blob/dev/shared/types/src/class_manager.cpp) +> يقول: **`getInstance` و`resetInstance` وحدهما يقفلان `instanceMutex_`** — أمّا +> `registerClass` و`getClass` و`hasClass` و`registerTrait` وسائرُ الخريطة **فبلا قفل**. +> فالتعليقُ الذي يصف الصنفَ بأنّه «آمنٌ للخيوط المتعدّدة» يصفُ **إنشاءَ المُفرَد** لا +> **محتواه**. عمليًّا: `أطلق` على شيفرةٍ تُصرِّح صنفًا (أو تحمِّل وحدةً تُصرِّحه) يكتبُ +> في خريطةٍ عامّةٍ غيرِ متزامنة. هذا **عقدٌ معلَنٌ لا يقيسه أحد**، لا حكمٌ بأنّه عطبٌ +> مرصود — قِسه قبل أن تبنيَ عليه. + ## ملاحظات للمطوّر - القيم كلّها `Value` (`std::variant` على `ValueType`)؛ `OBJECT` يحمل `shared_ptr` ⇒ **تمرير الكائنات بالمرجع** → [نظام الأنواع](../systems/types.md). -- شغّل `.ص` مباشرةً بـ`sad.exe` لاختبارٍ سريع — لا حاجة لخطوة ترجمة. +- شغّل `.ص` مباشرةً بـ`sad-run` لاختبارٍ سريع — لا حاجة لخطوة ترجمة. - إن طابق المفسّر وخالف المترجم ⇒ المشكلة في SIR/LLVM لا في الدلالة (BF‑08). -- لإضافة عقدة AST جديدة: أضف `visit` إلى `BaseASTVisitor` ونفّذها في الزائرَين. +- لإضافة عقدة AST جديدة: أضف `visit` الصرفة إلى `ASTVisitor` وتطبيقًا فارغًا في + `BaseASTVisitor`، ثمّ نفّذها في الزائرَين → [شجرة AST](../frontend/ast.md). +- الأصنافُ تُسجَّل في `ClassManager::getInstance()` (مُفرَدُ `shared/types`)، لا في مديرٍ + يملكه المفسّر. --- **اقرأ بعده:** [التمثيل الوسيط SIR](sir.md). diff --git a/src/backend/llvm.md b/src/backend/llvm.md index 1658c9f..85afdc3 100644 --- a/src/backend/llvm.md +++ b/src/backend/llvm.md @@ -1,18 +1,38 @@ -# توليد LLVM (المترجم sadc) +# توليد LLVM (المترجم `sad-build`) > **ماذا ستتعلّم:** كيف يحوّل `LLVMCodeGen` تمثيل SIR إلى LLVM IR ثم ملفّ تنفيذيّ أصليّ. ## الدور `compiler/src/backend/llvm/` يأخذ SIR المحسَّن ويُنتج LLVM IR، ثم يستخدم LLVM لتوليد -كائن ثم ربطه في ملفّ تنفيذيّ. هذا قلب المترجم `sadc`. +كائن ثم ربطه في ملفّ تنفيذيّ. هذا قلب المترجم `sad-build`. ## الاعتماد على LLVM - **LLVM 18** — مفعّل بشرط `ENABLE_LLVM_BACKEND=ON`؛ راجع `cmake/llvm.cmake` و`#ifdef HAS_LLVM`. -- واجهة `sadc` تعيش في `tools/compiler/` (`compiler_driver_*.cpp`). +- واجهة المترجم تعيش في `tools/compiler/` (`compiler_driver_*.cpp`)، وهدفُها `sad-build` + (`sad-build.exe`). أمّا `sadc.exe` فاسمٌ متقاعد لا يُنتجه أيّ هدف. + +> ⚠️ **علَمٌ عربيٌّ قانونيٌّ وحيد — لا مرادف لاتينيّ.** أعلامُ المترجم الطويلة كلُّها +> في [`language-truth/cli_flags.yaml`](https://github.com/sadlang/s-programming-language/blob/dev/language-truth/cli_flags.yaml)، +> ونصُّه صريح: «اسمٌ عربيٌّ قانونيٌّ وحيد، بلا مرادفات ولا توافقٍ خلفيّ». فمخرجاتُ +> LLVM الوسيطة هي `--أظهر-llvm` و`--أظهر-bc` — و`--emit-llvm` **لا تُقبَل**. تبقى +> الأعلامُ القصيرة الموروثة من سلسلة الأدوات (`-o -c -S -g -O* -L -l -Werror -T -h`) +> أعرافًا في المحلِّل، خارجَ هذا المصدر — بنصّ المصدر نفسِه: «النطاق = الأعلام الطويلة فقط». + +> 📎 **لا سقوطَ صامتًا حين تغيب LLVM.** إلى جانب `sad-build` يُبنى **دائمًا** هدفٌ +> ثانٍ نحيلٌ بلا LLVM البتّة: `sad-build-native`. وهو لا يفترق عن أخيه إلّا في ملفٍّ +> واحد — [`compiler_driver_backend_llvm_absent.cpp`](https://github.com/sadlang/s-programming-language/blob/dev/tools/compiler/compiler_driver_backend_llvm_absent.cpp) +> بدل `compiler_driver_backend.cpp` — الذي **يرفض** صراحةً كلّ طلبٍ لأثرٍ من صنع +> LLVM برمز الكتالوج `INT_LLVM_PATH_ABSENT`، بدل تسليم أثرٍ من +> [الخلفيّة الأصليّة](native.md) وكأنّه هو. مَن طلب أثرًا بعينه يُعطاه أو يُرَدّ. +> +> ولاحظ **لماذا وحدةُ ترجمةٍ كاملةٌ لا فرعُ `#ifdef`**: الفرعُ الذي لا يُصرَّف في أكثر +> الخانات ينجرف صامتًا عن أخيه — وهو عطبٌ مقيسٌ في هذا المستودع من قبل. فكلُّ سطرٍ +> هنا يُصرَّف على المنصّات الثلاث وفي التكوينَين. ## البناة (builders) -`compiler/src/backend/llvm/builders/` — مولّدات لكل بنية (تعابير، تحكّم، دوال، -كائنات، الدوال المضمنة في `builders/builtins/`). +`compiler/src/backend/llvm/builders/` — **ثمانية مجلّداتٍ** مقيسةٍ على `dev`، مولِّدٌ +لكلّ عائلة: `core` · `arithmetic` · `collections` · `oop` · `memory` · `directives` +(توجيهات `@`) · `platform` · `builtins` (الدوالّ المضمنة). ## مخطّط ```mermaid @@ -25,7 +45,7 @@ flowchart LR ``` ## التشخيص (BF-07) -عند خطأ في المترجم، ولّد IR بـ`--emit-llvm` وافحص: +عند خطأ في المترجم، ولّد IR بـ`--أظهر-llvm` وافحص: - هل الكتلة الأولى (entry block) صحيحة؟ - هل أنواع الحقول والمعاملات متّسقة؟ - هل ترتيب التعليمات يحترم تبعيّات البيانات؟ diff --git a/src/backend/native.md b/src/backend/native.md index 377219c..1485672 100644 --- a/src/backend/native.md +++ b/src/backend/native.md @@ -273,6 +273,6 @@ flowchart TB | تفهم لماذا فشل تخفيضٌ عندك | وسمُ السياق في `native_diagnostics.yaml` + رسالةُ الكتالوج | --- -**اقرأ بعده:** [دراسة حالة: توحيد هاش/شفّر/فك_تشفير](crypto-unification.md) — +**اقرأ بعده:** [دراسة حالة: توحيد هاش/شفر/فك_تشفير](crypto-unification.md) — الفصلُ التالي في الفهرس، وهو أخفُّ ويُري التوحيدَ نفسَه من زاويةِ مكتبةٍ لا خلفيّة · أو اقفز إلى [نظام الأنواع وفاحص الأنواع](../systems/types.md). diff --git a/src/contributing/definition-of-done.md b/src/contributing/definition-of-done.md index 8bd1e75..154c971 100644 --- a/src/contributing/definition-of-done.md +++ b/src/contributing/definition-of-done.md @@ -14,7 +14,7 @@ - [ ] **اختبار `.ص`** جديد (إيجابيّ + سلبيّ) بصيغة `@expected` الصحيحة. - [ ] `runner.py --level P0` (وقسم الميزة) يمرّ **100%**. - [ ] `runner.py --level P1` يمرّ **قبل أي PR** — لا تراجع (BF-29). -- [ ] `sadc` يبني بلا أخطاء، و`sad-run` يعمل بلا تراجع. +- [ ] `sad-build` يبني بلا أخطاء، و`sad-run` يعمل بلا تراجع. ## الجودة والتوافق - [ ] تعليقات **مزدوجة اللغة** على كل API عام (CW-08). diff --git a/src/contributing/freshness.md b/src/contributing/freshness.md index a96203d..9c76746 100644 --- a/src/contributing/freshness.md +++ b/src/contributing/freshness.md @@ -23,8 +23,12 @@ chapters: المصدر إمّا **مسارٌ كامل** (ملف أو مجلد، يُرصد أيّ تغيّر تحته) أو **كائن `{path, lines}`** يبصم **نطاقًا بعينه** فقط. النطاق يقلّل **الإنذارات الكاذبة** في الملفّات الكبيرة (تعديلٌ خارج المنطقة الموثَّقة لا يُطلِق إنذارًا) ويرصد **تعفّن** المنطقة المقصودة تحديدًا. -الحقل `covers_version` يوثّق نسخة اللغة التي رُوجِع الدليل تجاهها (يُرفَع آليًّا عند -مراجعة إصدار: `--update --set-version`). +الحقل `covers_version` يوثّق **حالة اللغة التي رُوجِع الدليل تجاهها**. ولمّا كان +`ref: dev` — لا وسمَ إصدارٍ — فصيغتُه اليوم `dev@<إيداع مختصر>` (مثلًا +`dev@1138f5e1`)، أدقُّ من رقم semver لأنّها تسمّي **الإيداع** الذي قِيست عنده +البصمات لا إصدارًا مُتخيَّلًا. يُكتَب في البيان والقفل معًا: `--update --set-version` +ينسخه إلى القفل، و`--update` وحدَه يأخذه من البيان. لا يقيّده مخطّطٌ ولا يقرؤه حارس؛ +مستهلِكُه الوحيد نصُّ قضيّة `sync-check.yml` الذي يطبعه كما هو. ## 2) كاشف الانجراف — `scripts/check_sync.py` يجلب **بصمة (sha)** كل مصدرٍ من المستودع الرئيسيّ عبر `gh api` (لا يلزم استنساخ)، diff --git a/src/frontend/ast.md b/src/frontend/ast.md index f036d92..79e7e1e 100644 --- a/src/frontend/ast.md +++ b/src/frontend/ast.md @@ -1,35 +1,81 @@ # شجرة AST -> **ماذا ستتعلّم:** كيف تُمثَّل البرامج كشجرة، ونمط الزائر (Visitor) الذي يستهلكها. +> **ماذا ستتعلّم:** كيف تُمثَّل البرامج كشجرة، ونمط الزائر (Visitor) الذي يستهلكها — +> ومَن يطبّقه فعلًا ومَن لا يطبّقه رغم أنّه يستهلك الشجرة. + +> 📎 المصدر: [`shared/ast/include/ast_visitor.h`](https://github.com/sadlang/s-programming-language/blob/dev/shared/ast/include/ast_visitor.h) ## الدور `shared/ast/` يُعرّف عقد الشجرة المجرّدة التي يبنيها المحلل النحوي ويستهلكها المفسّر والمترجم. القاعدة `ASTNode`، ومنها `Statement` (جمل) و`Expression` (تعابير). -## أنواع العقد (أمثلة) -- **جمل:** `IfStmt`, `WhileStmt`, `ForRangeStmt`, `ReturnStmt`, `BlockStmt`, `TryStmt`, `SwitchStmt`, `MatchStmt`, `ExprStmt`، تصريحات (`FunctionDecl`, `ClassDecl`, `VarDeclStmt`, `EnumDecl`, `StructDecl`, …). -- **تعابير:** `BinaryExpr`, `UnaryExpr`, `CallExpr`, `MethodCallExpr`, `MemberExpr`, `IndexExpr`, `LiteralExpr`, `VariableExpr`, `LambdaExpr`, `TernaryExpr`, `RangeExpr`, `ArrayExpr`, `MapExpr`, `NewExpr`, `ThisExpr`/`SuperExpr`, `AwaitExpr`، … +## أنواع العقد +الواجهة [`ASTVisitor`](https://github.com/sadlang/s-programming-language/blob/dev/shared/ast/include/ast_visitor.h#L158) +تصرّح **٩٥ دالّة زيارة** — واحدةً لكلّ نوع عقدة. فهذا العدد هو **إحصاء أنواع العقد +نفسه**، لا تقديرًا: العقدة التي لا دالّةَ لها لا تُزار. + +> ⚠️ **٩٠ صرفة و٥ لها جسمٌ فارغ.** ليست الخمسُ والتسعون كلُّها `= 0`: خمسٌ منها +> (`visitEnumVariantExpr` · `visitAsmBlockStmt` · `visitUIStateDecl` · +> `visitUIConditional` · `visitUILoop`) صُرِّحت بجسمٍ فارغ `{}` داخل `ASTVisitor` +> نفسِها. فالزائرُ الذي يُهملها **يُصرَّف بلا شكوى** — وهذا بالضبط بابُ السلوك +> الصامت الذي يحرسُه `= 0` في الباقي. + +| العائلة | أمثلة | +|---|---| +| **تعابير** | `BinaryExpr` · `UnaryExpr` · `TernaryExpr` · `LiteralExpr` · `VariableExpr` · `AssignExpr` · `CallExpr` · `IndexExpr` · `MemberExpr` · `ArrayExpr` · `MapExpr` · `LambdaExpr` · `RangeExpr` · `SliceExpr` · `TupleExpr` | +| **ملكيّة وتزامن** | `BorrowExpr` (استعارة) · `AwaitExpr` · `WalrusExpr` | +| **أمان العدم** | `OptionalChainExpr` (`?.`) · `NullCoalesceExpr` (`??`) · `ErrorPropagateExpr` (`انشر`) | +| **استيعابات** | `ListComprehensionExpr` · `DictComprehensionExpr` · `SetComprehensionExpr` · `GeneratorExpr` | +| **توجيهات `@`** | `UnsafeBlockStmt` (`@غير_آمن`) · `ComptimeBlockStmt` (`@وقت_الترجمة`) · `SizeofExpr` (`@حجم`) · `AtomicExpr` (`@ذري`) · `VolatileVarDeclStmt` (`@متطاير`) · `AsmBlockStmt` (كتلة «تجميع … نهاية») · `InlineAsmExpr` | +| **كائنيّة** | `NewExpr` · `MemberAccessExpr` · `MemberAssignExpr` · `IndexAssignExpr` · `MethodCallExpr` · `ThisExpr` · `SuperExpr` · `ClassDeclStmt` | +| **جمل** | `ExprStmt` · `VarDeclStmt` · `IfStmt` · `WhileStmt` · `ForStmt` · `ForRangeStmt` · `SwitchStmt` · `MatchStmt` · `ReturnStmt` · `YieldStmt` · `BreakStmt` · `ContinueStmt` · `BlockStmt` · `TryStmt` · `RaiseStmt` · `WithStmt` · `DeferStmt` (تنظيفٌ مضمون) · `GoStmt` · `SelectStmt`/`SelectCase` | +| **تصريحات** | `FunctionDecl` · `ClassDecl` · `FieldDecl` · `MethodDecl` · `PropertyDecl` · `ConstructorDecl` · `DestructorDecl` · `EnumDecl` · `StructDecl` · `TestDecl` · `ImportStmt`/`FromImportStmt` · `ExportStmt`/`ExportDecl`/`ReExportStmt` | +| **قوالب وعموميّات** | `TemplateFunctionDecl` · `TemplateClassDecl` · `TemplateInstantiation` · `NamespaceDecl` · `OperatorDecl` · `TraitDecl` · `ImplDecl` · `ExtensionDecl` · `MacroDecl` · `TypeAliasDecl` · `TupleDestructureStmt` | +| **تعدادٌ بحمولة** | `EnumVariantExpr` — بناء عضو تعداد بحمولة (ADT) | +| **واجهة SadUI** | `UIDeclaration` · `UIWidgetExpr` · `UIModifier` · `UIEventHandler` · `UIStateDecl` · `UIConditional` · `UILoop` | +| **مزخرِفات** | `DecoratorExpr` | > العقدة المُنتَجة لكل قاعدة نحويّة مُوثَّقة في حقل `ast_node` بمصدر القواعد. → [grammar SoT](../sot/grammar-sot.md). ## نمط الزائر (Visitor) -العقد تُستهلَك عبر `ASTVisitor` (في `shared/ast/include/ast_visitor.h`): كل مستهلِك -(مفسّر، `SIRBuilder`، منسّق، LSP) يطبّق الزائر. هذا يحقّق **مبدأ المفتوح/المغلق**: -أضف مستهلِكًا جديدًا دون تعديل العقد. +العقد تُستهلَك عبر `ASTVisitor` (الواجهة الصرفة) و`BaseASTVisitor` (يرثها ويعطي +تطبيقًا فارغًا لكلّ دالّة، فيَشتقّ منه الزائرُ ويعيد تعريف ما يحتاجه فقط). هذا يحقّق +**مبدأ المفتوح/المغلق**: أضف مستهلِكًا جديدًا دون تعديل العقد. ```mermaid flowchart LR - AST["عقد AST"] --> V{"ASTVisitor"} - V --> INT["InterpreterVisitor (تقييم)"] - V --> SIR["SIRBuilder (→ SIR)"] - V --> FMT["Formatter / LSP"] + AST["عقد AST"] --> V{"ASTVisitor / BaseASTVisitor"} + V --> EE["ExpressionEvaluator
StatementExecutor
(المفسّر)"] + V --> TC["TypeChecker
(shared/semantic)"] + V --> AN["AstAnalysisVisitor
(tools/analyze)"] + V --> PR["ASTPrinter"] + AST -.->|"لا يمرّ بالزائر"| SB["SIRBuilder
(dynamic_cast + بُناةٌ فرعيّة)"] ``` +**مَن يطبّق الزائر فعلًا** (مقيسٌ على `dev`): +`interpreter/include/visitors/expression_evaluator.h` · `.../statement_executor.h` · +`shared/semantic/include/semantic/type_checker.h` · `tools/analyze/include/ast_analysis_visitor.h` · +`ast_printer.h`. + +> ⚠️ **`SIRBuilder` ليس زائرًا.** الواجهةُ الأماميّة للمترجم تستهلك الشجرة، لكنّها لا +> ترثُ `ASTVisitor`: [`class SIRBuilder : public SIRBuilderContext`](https://github.com/sadlang/s-programming-language/blob/dev/compiler/include/frontend/sir_builder.h#L182)، +> مدخلُها `buildModule(ProgramNode*)`، وتوزيعُها على أنواع العقد بـ`dynamic_cast` +> (٦٨٠ سطرًا تحوي `dynamic_cast` في ٣٧ ملفًّا تحت `compiler/src/frontend/`) +> عبر بُناةٍ فرعيّةٍ `friend` +> (`StatementBuilder` · `ExpressionBuilder` · `ClassBuilder` · `CallBuilder` · …). +> ولا يطبّقه منسّقٌ ولا LSP اليوم. أثرُ ذلك عمليٌّ: إضافةُ دالّة `visit` **لا** تصل +> المترجمَ من تلقائها — لا مترجمَ يشكو، وإنّما تسقط العقدةُ في `dynamic_cast` غيرِ +> مطابقٍ ⇒ سلوكٌ صامت. + ## إضافة عقدة AST 1. عرّف الصنف في `shared/ast/include/` (ورث من `Statement`/`Expression`). -2. أضف تصريحها في `ast_visitor.h` ودالة الزيارة. -3. نفّذ الزيارة في المفسّر (`interpreter/include/visitors/`) و`compiler/src/frontend/`. -4. **التوافق الخلفيّ:** إضافة عقدة مسموحة — تغيير معنى عقدة موجودة ممنوع (CW-24). +2. أضف تصريحها المسبق ودالّة `visit` **الصرفة** في `ASTVisitor`، وتطبيقًا فارغًا + في `BaseASTVisitor` — وإلّا كسرتَ كلّ الزوّار دفعةً واحدة. ولا تُقلِّدها بالخمسِ + ذواتِ الجسمِ الفارغ: هنّ استثناءٌ قائم، لا قدوة. +3. نفّذ الزيارة في زائرَي المفسّر (`interpreter/include/visitors/`) وفي `TypeChecker`. +4. أضف فرعَ `dynamic_cast` في بُناة `compiler/src/frontend/` — **يدويًّا**، فالمترجمُ + لا يذكّرك بها (انظر التحذير أعلاه). +5. **التوافق الخلفيّ:** إضافة عقدة مسموحة — تغيير معنى عقدة موجودة ممنوع (CW-24). ## ملاحظات - مرّر العقد الكبيرة بمرجع/مؤشّر ذكيّ؛ لا نسخ عميق إلا عبر `clone()` صريح (CW-29). diff --git a/src/getting-started/first-contribution.md b/src/getting-started/first-contribution.md index f8b6d92..9d2b1aa 100644 --- a/src/getting-started/first-contribution.md +++ b/src/getting-started/first-contribution.md @@ -31,8 +31,8 @@ python scripts/codegen/gen_all_builtins_yaml.py # أو المولّد المع ## 6) ابنِ وشغّل (تنفيذ مزدوج) ```bash -cmake --build build --config Debug --target sad -cmake --build build --config Release --target sadc +cmake --build build --config Debug --target sad-run +cmake --build build --config Release --target sad-build python runner.py --level P1 # يجب أن يمرّ 100% بلا تراجع ``` diff --git a/src/getting-started/repo-map.md b/src/getting-started/repo-map.md index d28a392..0373ca5 100644 --- a/src/getting-started/repo-map.md +++ b/src/getting-started/repo-map.md @@ -16,7 +16,7 @@ s-programming-language/ │ └── src/backend/llvm/ ← LLVMCodeGen + builders ├── stdlib/ ← المكتبة القياسية (core/io/math/string/network/graphics) ├── runtime/ ← ABI/FFI المستقلّ + الوضع الحرّ (freestanding) -├── tools/ ← sadinfo · lsp · formatter · pkg · repl · compiler(sadc CLI) +├── tools/ ← analyze · build · check · compiler(واجهة sad-build) · formatter · hub · lsp · pkg · profiler · repl · security-scanner · wasm · apk_builder ├── language-truth/ ← ⭐ مصدر الحقيقة الموحّد (YAML) │ ├── keywords.yaml · operators.yaml · types.yaml · directives.yaml │ ├── builtins/ · errors/ · grammar/ ← قواعد الإنتاج (SoT) diff --git a/src/getting-started/setup.md b/src/getting-started/setup.md index 9dfd742..ce6ccf5 100644 --- a/src/getting-started/setup.md +++ b/src/getting-started/setup.md @@ -5,7 +5,7 @@ ## المتطلبات - **C++17** ومُصرِّف حديث (MSVC على Windows، أو Clang/GCC). - **CMake ≥ 3.20**. -- **LLVM 18** — *اختياريّ*، للمترجم `sadc` فقط (`ENABLE_LLVM_BACKEND=ON`). +- **LLVM 18** — *اختياريّ*، للمترجم `sad-build` فقط (`ENABLE_LLVM_BACKEND=ON`). - **Python 3** — لمولّدات الكود (`scripts/codegen/gen_*.py`) و`runner.py`. - **Git + GPG** — للمساهمة (الفروع المحميّة تشترط توقيع GPG). @@ -18,19 +18,25 @@ cd s-programming-language ## البناء (PowerShell على Windows) ```powershell cmake -S . -B build # تهيئة أولى -cmake --build build --config Debug --target sad # المفسّر (أسرع) -cmake --build build --config Release --target sadc # المترجم (LLVM) +cmake --build build --config Debug --target sad-run # المفسّر (أسرع) +cmake --build build --config Release --target sad-build # المترجم (LLVM) cmake --build build --config Debug # كل شيء ``` -> ⚠️ **فخّان مهمّان** (مذكوران في تعليمات المشروع): -> - هدف `sadc` قد يُنتج `sad-build.exe` — انسخه إلى `sadc.exe` قبل `runner.py` وإلا فنتائج المترجم بائتة. -> - الـrunner يقرأ مفسّر **Debug** ومترجم **Release** — أعد بناء التهيئتين معًا. +> ⚠️ **ثلاثة فخاخ:** +> - **`sadc.exe` اسمٌ متقاعد — لا يُنتجه أيّ هدف.** اسمُ الهدف مُوحَّدٌ مع اسم +> المُخرَج: `sad-run` ⇒ `sad-run.exe`، و`sad-build` ⇒ `sad-build.exe` +> ([`tests/config.yaml`](https://github.com/sadlang/s-programming-language/blob/dev/tests/config.yaml)). +> فلا تنسخ ثنائيًّا باسمٍ آخر لأجل `runner.py` — فهو يقرأ المسارَين من ذلك الملفّ. +> - `sad.exe` ليس المفسّر بل **موزِّع أوامرٍ (hub)** يُشغّل الأدواتِ عمليّاتٍ فرعيّة؛ +> المفسّرُ الفعليّ `sad-run.exe`، فاستدعِه مباشرةً. +> - الـrunner يقرأ تهيئتَي الثنائيَّين من `tests/config.yaml` — أعد بناءهما معًا +> حتّى لا تقيس ثنائيًّا بائتًا. ## التشغيل ```powershell -.\build\bin\Debug\sad.exe examples\test_simple.ص # تفسير -.\build\bin\Release\sadc.exe examples\test_simple.ص # ترجمة لملف تنفيذيّ +.\build\bin\Debug\sad-run.exe examples\test_simple.ص # تفسير +.\build\bin\Release\sad-build.exe examples\test_simple.ص # ترجمة لملف تنفيذيّ ``` ## الاختبارات diff --git a/src/glossary.md b/src/glossary.md index a59383f..af6a842 100644 --- a/src/glossary.md +++ b/src/glossary.md @@ -18,8 +18,10 @@ | **DoD** | Definition of Done — معيار اعتبار التغيير منجَزًا. | | **worktree** | فرع git في مجلد منفصل يشارك نفس المستودع (`C:/s_lang/temp-brunch/`). | | **CW-NN / BF-NN / GR-NN** | قواعد كتابة الكود / إصلاح الأخطاء / الحوكمة (مراجع معياريّة). | -| **sadc** | مُترجِم لغة ص (AST → SIR → LLVM → تنفيذيّ). | -| **sad / sad-run** | المفسّر الشجريّ. | +| **sad-build** | مُترجِم لغة ص (AST → SIR → LLVM → تنفيذيّ). هدفُ CMake ومُخرَجُه `sad-build.exe`. | +| **sad-run** | المفسّر الشجريّ (`sad-run.exe`). | +| **sad** | موزِّع الأوامر (hub) — يُشغّل الأدوات عمليّاتٍ فرعيّة، وليس المفسّر. | +| **~~sadc~~** | اسمٌ **متقاعد**: لا هدفَ يُنتجه اليوم. المترجم هو `sad-build`. | --- [العودة للمقدّمة](introduction.md) diff --git a/src/introduction.md b/src/introduction.md index beaaf0b..09457ad 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -4,7 +4,7 @@

كيف تعمل لغة ص من الداخل، وكيف تُسهم في تطويرها بثقة: معجمي → نحوي → AST → مفسّر/مترجم، فوق مصدر حقيقة موحّد.

-> **لمن هذا الدليل؟** لمن يطوّر **لغة ص نفسها** (المفسّر، المترجم `sadc`، الأنظمة الداخلية) — +> **لمن هذا الدليل؟** لمن يطوّر **لغة ص نفسها** (المفسّر، المترجم `sad-build`، الأنظمة الداخلية) — > لا لمن يكتب برامج *بها*. إن كنت تكتب `.ص` فهذا الدليل ليس لك. ## ابدأ من هنا diff --git a/src/sot/grammar-sot.md b/src/sot/grammar-sot.md index 3dd1612..b640e97 100644 --- a/src/sot/grammar-sot.md +++ b/src/sot/grammar-sot.md @@ -28,6 +28,38 @@ flowchart LR | `60_advanced.yaml` | `gr.adv.*` | أنواع/قوالب/عمر/تزامن/استيعاب/ماكرو/FFI/واجهة | | `70_lexical.yaml` | `gr.lex.*` | الطرفيات (جسر للمعجمي) | +ومعها في المجلّد نفسِه ستّةُ ملفّاتٍ ليست قواعدَ إنتاج: + +| ملفّ | دوره | +|-----|------| +| `_notation.yaml` | **الميتا-قواعد**: كيف تُقرأ ملفّات القواعد (علاقة `ebnf` بـ`alternatives`) | +| `lowers_to.yaml` | ربطُ كلّ قاعدةٍ بأوپكودات SIR — **مُشتقٌّ بالتشغيل** (انظر أدناه) | +| `README.md` | دليلُ المجلّد | +| `CONFORMANCE_REPORT.md` · `CONFORMANCE_REPORT_detail.md` · `DISCOVERED_ISSUES.md` | مخرجاتُ فحص المطابقة وما كشفه | + +## `lowers_to.yaml` — الجسر إلى الخلفيّات + +لا يكفي أن تُوثَّق القاعدةُ نحويًّا؛ السؤالُ العمليّ: **إلى أيّ أوپكودات تنزل، وأيّ +معماريّةٍ تخفضها كلَّها؟** يجيب [`lowers_to.yaml`](https://github.com/sadlang/s-programming-language/blob/dev/language-truth/grammar/lowers_to.yaml)، +وهو مُولَّدٌ آليًّا بـ`gen_grammar_lowers_to.py` — والاشتقاقُ **تجريبيّ لا تحليليّ**: +تُترجَم اختباراتُ القاعدة بـ`--أظهر-sir` وتُجمَع أوپكوداتُها الفعليّة. + +| الحقل | معناه | +|---|---| +| `lowers_to` | كلّ أوپكودات القاعدة (عليها يقوم الحكم) | +| `beyond_baseline` | ما تضيفه القاعدةُ فوق سقالةِ أيّ دالّة | +| `native_ok` | المعماريّات التي تخفض أوپكوداتِها كلَّها في [الخلفيّة الأصليّة](../backend/native.md) | +| `native_missing_<قوس>` | الأوپكودات المانعة لكلّ معماريّة | +| `evidence` | ملفّات الاختبار التي اشتُقّ منها | +| `status: not_derived` | **لم يُترجَم — لا يُفترَض نجاحه** | + +الإحصاء المسجَّل في الملفّ: **١٠٧ قواعد**، منها **١٠٥ مشتقّةٌ** و**٢ `not_derived`**؛ +والتغطية الأصليّة **١٠٢ لـx86-64 و١٠٢ لـarm64 و٢٦ لـriscv64** (٣ عيّناتٍ لكلّ قاعدة). +فهذا الملفّ هو المكان الذي تُقرأ فيه فجوةُ RISC-V كمًّا، لا انطباعًا. + +> 🔑 **`not_derived` إعلانٌ لا صمت.** القاعدةُ التي لم تُترجَم تُوسَم صراحةً بدل أن +> تسقط من الإحصاء — فغيابُ البرهان مذكورٌ، لا مسكوتٌ عنه. + ## شكل قاعدة الإنتاج كل قاعدة (مخطّط `_schemas/grammar_production.schema.json`): - `id` بصيغة `gr..` (فريد، مرجِع). diff --git a/src/sot/philosophy.md b/src/sot/philosophy.md index 510a4a7..2bb271d 100644 --- a/src/sot/philosophy.md +++ b/src/sot/philosophy.md @@ -16,7 +16,7 @@ flowchart LR Y["language-truth/*.yaml
(المصدر الوحيد)"] --> GEN["scripts/codegen/gen_*.py
(المولّد)"] GEN --> CPP["shared/*/generated/*.{h,cpp}
(مُولَّد — لا يُحرَّر)"] GEN --> DOC["توثيق + مخطّطات مُولَّدة"] - Y --> TOOLS["LSP · formatter · sadinfo · pkg"] + Y --> TOOLS["LSP · formatter · pkg · analyze"] CPP --> BUILD["بناء C++"] ``` diff --git a/src/status.md b/src/status.md index a5301b3..0524d51 100644 --- a/src/status.md +++ b/src/status.md @@ -21,7 +21,7 @@ - [ ] **إعادة توثيق VM:** يُكتب الفصل من الكود عند إعادة كتابة الطبقة، لا قبلها. - [x] **مزامنة الدليل مع اللغة:** بيان ربط + كاشف انجراف + فحص أسبوعيّ → [Freshness](contributing/freshness.md). - [ ] **جسر آليّ لقواعد المحلل:** تضمين/مزامنة `docs/parser_rule/_generated/` داخل الدليل. -- [ ] **فصل الأدوات:** LSP · المنسّق · مدير الحزم (pkg) · sadinfo. +- [ ] **فصل الأدوات:** LSP · المنسّق · مدير الحزم (pkg) · المحلّل (analyze) · المُشخِّص (profiler). - [ ] **فصل stdlib:** بنية المكتبة القياسية ووحداتها. - [ ] **فصل runtime/FFI:** ABI المستقلّ (`runtime/`) والوضع الحرّ (freestanding). - [ ] **أمثلة «دراسة حالة»:** تتبّع ميزة كاملة عبر كل الطبقات (نهاية-لنهاية). diff --git a/src/systems/builtins.md b/src/systems/builtins.md index 826284e..008c1d8 100644 --- a/src/systems/builtins.md +++ b/src/systems/builtins.md @@ -40,5 +40,5 @@ shared/builtins/generated/builtin_registry_generated.h ← مُولَّد > التفاصيل في مهارة `sad-lang-dev` (`references/builtins-system.md`). --- -**اقرأ بعده:** [دراسة حالة: توحيد هاش/شفّر/فك_تشفير](../backend/crypto-unification.md) · +**اقرأ بعده:** [دراسة حالة: توحيد هاش/شفر/فك_تشفير](../backend/crypto-unification.md) · [سير عمل الفروع](../contributing/workflow.md). diff --git a/src/systems/sadui-layout.md b/src/systems/sadui-layout.md index 627529f..1c0b545 100644 --- a/src/systems/sadui-layout.md +++ b/src/systems/sadui-layout.md @@ -43,9 +43,11 @@ ## مصدر حقيقة مفاتيح الخصائص (SoT) كلّ مفتاح خاصّيّة (نحو «محاذاة»/«حشو»/«عرض») معرَّف في -`language-truth/ui_props.yaml` (٨٢ مفتاحًا)، يُولَّد منه -`sad_ui/prop_keys.h` (ثوابت `sad::ui::props::`) عبر `x.py gen`. **لا سلسلة -مفتاح خام في كود الرسوميّات** — يُقرأ المفتاح دائمًا عبر الثابت المولَّد: +[`language-truth/ui_props.yaml`](https://github.com/sadlang/s-programming-language/blob/dev/language-truth/ui_props.yaml) +— **١٠٤ مفاتيحَ على `dev`** — يُولَّد منه `sad_ui/prop_keys.h` (ثوابت +`sad::ui::props::`، وعددُها ١٠٤ أيضًا: تكافؤٌ عدديٌّ بين المصدر والمولَّد) عبر +`x.py gen`. **لا سلسلة مفتاح خام في كود الرسوميّات** — يُقرأ المفتاح دائمًا عبر +الثابت المولَّد: ```cpp node.findProperty(props::ALIGN) // ✓ لا findProperty("محاذاة") @@ -54,5 +56,10 @@ node.findProperty(props::ALIGN) // ✓ لا findProperty("محاذاة") يحرسه `check_no_raw_props.py` + `check_ui_props_consistency.py` ضمن `x.py gen --check` (محلّيًّا + CI)، وworkflow `props-literals-lint.yml`. +> ⚠️ **`latin_alias` ليس اسمًا قانونيًّا.** بعضُ المفاتيح يحمل حقلًا اختياريًّا +> `latin_alias` — نصُّ المصدر يحدّه: «بديلٌ احتياطيٌّ لاتينيّ يقرؤه المُرسِّم فقط، لا +> قانونيّ». فلا يُكتَب في `IRNode` ولا يُوثَّق للمستخدم؛ القانونيُّ هو `canonical` +> العربيُّ وحده. + > التفصيل المعماريّ الكامل (مع الأمثلة والرسوم) في مستودع اللغة: > `docs/architecture/sadui-layout-alignment.md`. diff --git a/sync/sources.lock.json b/sync/sources.lock.json index dee81bb..f51c16a 100644 --- a/sync/sources.lock.json +++ b/sync/sources.lock.json @@ -1,5 +1,5 @@ { - "covers_version": "1.0.0", + "covers_version": "dev@1138f5e1", "ref": "dev", "repo": "sadlang/s-programming-language", "sources": { @@ -9,24 +9,33 @@ "compiler/include/backend/native/sir_lowering_common.h": "259cceb18f6b2fc4ef0e978ee6e9c32ed406903e", "compiler/include/backend/native/sir_native_lowering.h#L1-30": "sha256:9a217df04a7742ee", "compiler/include/backend/native/x86_variable_encoder.h": "09ae23ed09b452c8802c7e1ca87852ed72f00d7e", + "compiler/include/frontend/sir_builder.h": "180218ed3728b56b79e70619edfc9a1b58b274a2", "compiler/include/frontend/sir_constants.h": "a194d187bc7c4298d07a1340adfc68ce9877b297", "compiler/include/frontend/sir_types.h": "d7adf45f13c2aa9071f7a8bd36550abeeb5f0fcb", - "compiler/src/backend/llvm": "32d6a3cc07ebf51e3f2fa2933afb92f99143d06f", + "compiler/src/backend/llvm": "525f452df4773db03c579b2b2f84454361920cbf", "compiler/src/backend/llvm/builders/builtins/io_builtins_ops.cpp": "169fdb572efd32d02919dc09c5e94b4a621d3468", + "compiler/src/backend/llvm/builders/builtins/security_builtins_ops.cpp": "96616d075384d3b2a1cff7773ba63ed721c5b1cb", "compiler/src/backend/llvm/builders/collections/map_ops.cpp": "40b02975f418d9db94ba3314f06a07d539c46472", "compiler/src/frontend/builders/builtins_core.cpp": "d8de39cd2ec664fee6c13bbfb66ddedfa9ef79f4", + "compiler/src/frontend/builders/builtins_security.cpp": "f4ca53edeb256d1d6c6492018819091b75cc0b0a", "compiler/src/frontend/builders/expression_comp2.cpp": "a857b9752d53eaa9a36c8a9f4ef4d4e03f5c260d", "compiler/src/frontend/builders/expression_comprehensions.cpp": "48284a8c8ceea0663dbd250bbb9b0efa8ac787d8", "compiler/src/frontend/builders/statement_for_range.cpp": "6345f89e25b5f426a8ea4f6a4ca836a50f1b28e4", - "interpreter/include/core/interpreter_core.h": "031ec8bc4b77e628b67615c7680897387fe821cc", - "interpreter/include/visitors/expression_evaluator.h": "a6e90c03cb75de00525fd7888bb61c91d57aa2fc", + "features/graphics/core/include/sad_ui/prop_keys.h": "149ca3c9abcd815c662f446fff0c9c0d64d6e85a", + "features/graphics/core/src/layout.cpp": "b02fcd06d7a1ebfd98904c411cc633043714a45d", + "interpreter/include/channel.h": "119dc0e9cfea1b7e1b514a7d2b49614c1e499860", + "interpreter/include/core/interpreter_core.h": "10ed076702d3d20491c953c5047b7421f615370c", + "interpreter/include/visitors/expression_evaluator.h": "1aa1eaecd41908e921e08919c902e3b71e5f2d60", "interpreter/src/builtins": "fd3f67280e1e90ba6f9aa680ea28896e9db14bde", + "interpreter/src/builtins/builtin_module_assertions.cpp": "1cf037f1f5ffb75e9c13aa3709b23e20967f50ef", "interpreter/src/builtins/builtin_module_crypto.cpp": "7bb771626147ce04f7e43a715beec99bafeefc44", + "interpreter/src/core/interpreter_core.cpp": "a6d3445646d9843e4b26bba1ef5e95f72600ec7f", "interpreter/src/visitors/expression_evaluator_members_advanced.cpp": "bd2003b66b8be9c340e4650b2b851c9348765191", "language-truth": "c96c2155d17c2cae855b72b5ad371b583ea80ecc", "language-truth/_schemas": "113cd3948583dfb130fe4169f18e4ff6c7e16cd7", "language-truth/backend": "db97d27d4cc2407c977e6ff1b451040e03c62012", "language-truth/builtins": "9ffea44f0a878cf2cb57d5ec6757ea973a1a7247", + "language-truth/builtins/assertions.yaml": "c10ee3e417b8cd2eee7e376b70585c0cfb3edb5b", "language-truth/builtins/crypto.yaml": "16862db43a802396baa7559521c6fd801c63a7bb", "language-truth/cli_flags.yaml": "7694b926b12657541ccf3c4e3788223441d5dd92", "language-truth/errors": "cae7885b8c004934ddde3e59fe0bfb6d7b6ac1b1", @@ -34,12 +43,15 @@ "language-truth/keywords.yaml": "930d96448d776f20b1c7f75e96145e67e362de1d", "language-truth/operators.yaml": "99c005878a137ceeb387de34bf937ad7ab2e0f22", "language-truth/types.yaml": "73b5c1d165ec83f73b819c4d6af52333e2c217e4", + "language-truth/ui_props.yaml": "89cbf23a799f309698e97b29ecc595c293798963", "scripts/codegen": "54744b199f588b1a93b08ad677a069b263c21233", "scripts/codegen/gen_error_messages.py": "3a70f260e525f133b9a93f9919b3622e9056e871", + "scripts/codegen/gen_grammar_lowers_to.py": "3c7466870b2218d12089eea65d2b3361123b11b1", "scripts/codegen/gen_native_diagnostics.py": "f0accb963fc8f296e38c1f1d4226c0c5a5edee29", - "scripts/codegen/gen_parser_grammar_docs.py": "aaba9f37bd6d31cf0fcb190190c49fe742ad41c3", + "scripts/codegen/gen_parser_grammar_docs.py": "7b9f7a8a87252ee4599b4fa6da79cb18bbb05120", + "scripts/codegen/gen_ui_props.py": "5f750bc52cbe4e85bb67f087a94d67a840fcc6fe", "scripts/native_backend/run_native_proofs.sh": "84069b1cd325573c7336b131d37997788a4d1885", - "shared/ast/include/ast_visitor.h": "cee84846d4097724c8d62c13f036d6fc1686ee6f", + "shared/ast/include/ast_visitor.h": "6a19219711e62321697a041044962642888091f5", "shared/ast/include/expressions.h": "8c8ffe93587aa833c10890b9c4e12c2e9855825d", "shared/errors/include/error_codes.h": "893d39e3bf05aaeb798d9ff46f64e347fb46dff1", "shared/errors/include/error_manager.h": "63c70109de759eaedf809642d11681a1453db5d3", @@ -54,9 +66,12 @@ "shared/parser/src/core/parser_main.cpp#L40-1600": "sha256:61a72e3d3187d028", "shared/parser/src/statements/parser_advanced.cpp": "870578af5f28eaf1e013b6f1940eb3f3277e9764", "shared/types/generated/sad_type_kind_generated.h": "66a2e25e89fe3a3fc2d782fc79cbc86cab75b9bb", + "shared/types/include/class_manager.h": "da0673b71cd2ea5a51447d5d8065bd35d2aa4c15", "shared/types/include/sad_type_system.h": "abc0ace4395e26799a23ff5346efbe0714515d4b", "shared/types/include/value.h": "4d16c5e5f6c17fd4393f1d1da32716582d15750d", + "shared/types/src/class_manager.cpp": "3afe4d8387045573f7ae9d1c19b54eee7bb1226f", "tools/compiler/compiler_driver_android_linker.cpp": "86c4974e713923f47c0f16077b4db8ede94eef28", + "tools/compiler/compiler_driver_backend_llvm_absent.cpp": "7ea38eea2362fccc22e6d5d6666a9b4d55e09ac2", "tools/compiler/compiler_driver_native.cpp": "74676054c3660ec7ac0df65a1da9aa8d3baab0dd", "tools/compiler/runtime/sad_embedded_runtime.c": "c4465bac5594536e01b41f099a6dddf9fc80999d" } diff --git a/sync/sources.yaml b/sync/sources.yaml index de20e0c..ab8b444 100644 --- a/sync/sources.yaml +++ b/sync/sources.yaml @@ -7,7 +7,7 @@ repo: sadlang/s-programming-language ref: dev # نسخة اللغة التي يغطّيها الدليل (تُرفَع آليًّا عند مراجعة إصدار: --update --set-version) -covers_version: "1.0.0" +covers_version: "dev@1138f5e1" # صيغة المصدر: إمّا مسار نصّيّ (يُرصد أيّ تغيّر في الملف/المجلد كاملًا)، # أو كائن {path, lines: "بداية-نهاية"} لبصم نطاقٍ بعينه فقط — يقلّل الإنذارات @@ -27,8 +27,14 @@ chapters: - shared/parser/include/parser_core.h - language-truth/operators.yaml + - file: src/architecture/pipeline.md + sources: + - compiler/include/frontend/sir_types.h # SIR: المرحلة 4ب + - language-truth/cli_flags.yaml # --أظهر-llvm (نقاط التشخيص) + - file: src/frontend/ast.md sources: + - compiler/include/frontend/sir_builder.h # SIRBuilder : SIRBuilderContext (ليس زائرًا) + buildModule - shared/ast/include/ast_visitor.h - file: src/frontend/comprehensions.md @@ -47,6 +53,10 @@ chapters: - file: src/backend/interpreter.md sources: + - interpreter/src/core/interpreter_core.cpp # execute(): الطور الساكن (قاعدة الرئيسية · فحص الأنواع · أمان العدم) + - shared/types/include/class_manager.h # المُفرَد العابر للمحرّكين (خارج مدراء المفسّر) + - shared/types/src/class_manager.cpp # القفل على getInstance/resetInstance وحدهما + - interpreter/include/channel.h # GoroutineManager + SadChannel - interpreter/include/core/interpreter_core.h - interpreter/include/visitors/expression_evaluator.h - shared/ast/include/ast_visitor.h @@ -57,6 +67,8 @@ chapters: - file: src/backend/llvm.md sources: + - language-truth/cli_flags.yaml # --أظهر-llvm / --أظهر-bc: اسم عربيّ وحيد بلا مرادفات + - tools/compiler/compiler_driver_backend_llvm_absent.cpp # هدف sad-build-native: رفض صريح INT_LLVM_PATH_ABSENT - compiler/src/backend/llvm - file: src/backend/native.md @@ -105,6 +117,7 @@ chapters: - file: src/backend/crypto-unification.md sources: + - { path: shared/lexer/src/lexer_core.cpp, lines: "100-1770" } # تخطّي التشكيل U+064B–U+065F ⇒ «شفّر» تعمل و«شفر» هو القانونيّ - compiler/src/frontend/builders/builtins_security.cpp - compiler/src/backend/llvm/builders/builtins/security_builtins_ops.cpp - interpreter/src/builtins/builtin_module_assertions.cpp @@ -133,6 +146,7 @@ chapters: - file: src/sot/grammar-sot.md sources: + - scripts/codegen/gen_grammar_lowers_to.py # مولِّد lowers_to.yaml (اشتقاق تجريبيّ بـ--أظهر-sir) - language-truth/grammar - scripts/codegen/gen_parser_grammar_docs.py