DEV Community: Tarek

ما الذي تدين به رسالة الفشل لقارئها؟

Tarek — Thu, 22 Oct 2026 11:00:52 +0000

ما الذي تدين به رسالة الفشل لقارئها؟

متى كانت آخر مرة قرأت فيها — فعلاً قرأت — رسالة فشل اختبار؟

في الغالب كانت الثانية صباحاً، والسجل مفتوح أمامك، وكل ما لديك سطر واحد:

Expected True, but found False.

أيّ True؟ في أيّ استدعاء؟ في هذا الاختبار تسعة تأكيدات، وأيُّها كان يمكن أن ينتج هذا السطر نفسه. الرسالة لا تستبعد شيئاً.

وعامل البناء الذي نفّذ الاختبار اختفى أصلاً. والفرع قد يُحذف الأسبوع المقبل. لكن السطر يبقى — ملصقاً في محادثة، مقتبساً في تذكرة، مرفقاً بتقرير ما بعد الحادث. رسالة الفشل هي الجزء الوحيد من مجموعة اختباراتك المضمون قراءته خارج المحرر، على يد من لم يرَ الكود أبداً. لهذا القارئ كُتبت هذه المقالة.

هنا تتوقف مكتبة الاختبارات عن كونها واجهة برمجية وتصبح وثيقة. نحن نختار المكتبة بواجهتها المرنة — Should() و.Be() و.And — لكن ما نقرأه فعلاً، ونحن تحت الضغط، بعد شهور، وبلا سياق، هو نص الفشل. سمِّ الشيء باسمه: هذا هو سطح التشخيص لمجموعة الاختبارات كلها. ومع ذلك قلّ من سأل: ما الذي يجب أن يدين به هذا السطح لقارئه؟

جرّبها في ستين ثانية. الادعاء المركزي لهذه المقالة قابل للفحص، فافحصه بنفسك:

dotnet add package Jeninnet.Assertions

using Jeninnet.Assertions;

[TestMethod]
public void Username_matches_expected()
{
    string username = "dennis";
    username.Should().Be("jonas");
}

Expected username to be 'jonas', but found 'dennis'.

الحزمة لا تعتمد على أي إطار اختبار، فتعمل أسطر التوكيد الثلاثة نفسها تحت MSTest أو xUnit أو NUnit. أعد تسمية username إلى login فيتسمّى معه نص الفشل؛ ونفّذه على جهاز آخر فلا يتحرك النص.

هذه المقالة أول ست ملاحظات عن هذا السطح — وكلمة عن كيفية قراءتها. هذه الملاحظات لن تُعلّمك واجهة المكتبة؛ فالكتاب والمرجع يفعلان ذلك. إنها تشرح منطق التصميم الذي وراءها: لماذا يبدو كل سطح على ما هو عليه، وما ثمنه، وأين يتوقف. كل واحدة تقف وحدها؛ ومجتمعةً تصف تصميماً واحداً.

وخط السير ثابت. بعد هذا العقد: رسائل الفشل بالعربية — ماذا يتغير حين لا يقرأ القارئ الواقع تحت الضغط الإنجليزية. ثم الزمن: كيف تختبر ما يحدث لاحقاً دون أن تنام أثناء تنفيذ مجموعتك. ثم الذاكرة: لماذا تنتمي ميزانيات التخصيص إلى اختبارات الوحدة. ثم الانتظار: اختبارات تستطلع حقيقة لم تصل بعد بدل أن تؤكد كذبة على مؤقّت. وأخيراً: تحقق لا يرمي أبداً — الأفعال نفسها حيث لا يُسمح بالاستثناءات. ابدأ من هنا، من العقد.

سمِّ المتغيّر. أول واجبات رسالة الفشل أن تقول ماذا فشل، لا أن تقول إن شيئاً قد فشل. قارن:

Expected True, but found False.
Expected username to be 'jonas', but found 'dennis'.

الجملة الثانية تنجو حين تُلصق في محادثة فريق بلا أي كود حولها. والاسم هنا مأخوذ من نص التعبير نفسه لحظة التصريف — عبر سمة CallerArgumentExpression في المصرّف (C# 10) — لا من وسم يدوي يفلت من المتغيّر خلال أسبوع، ولا من تتبّع مكدّس يعتمد على ملف PDB قد لا يكون منشوراً أصلاً. وللحكاية وجه ثانٍ يستحق الذكر صراحة: أعد تسمية المتغيّر فيتسمّى معه نص الفشل تلقائياً. الأوسمة اليدوية تتعفن؛ والتعبيرات الملتقطة لا يسعها ذلك.

وبلا الاسم يبدأ كل فشل بالطريقة نفسها: افتح الكود، وعُدّ التوكيدات، وضيّق الدائرة. تسعة مشتبهين وسطر دليل واحد. اسم المتغيّر يختصر هذا البحث إلى الصفر — قبل أن تفتح أي شيء، تعرف أي قيمة، من أي تعبير، أخفقت في أي فحص.

اذكر المتوقَّع والفعلي، وبهذا الترتيب. القارئ يعقد مقارنة؛ سلّمه طرفيها بترتيب القراءة. "فشل التأكيد" حكمٌ بلا ملف قضية.

كن ثابتة. نفس الفشل يجب أن يُنتج النص نفسه على جهازك وجهاز زميلك وعامل البناء — عبر أنظمة التشغيل وثقافات الواجهة. التنسيق الثابت (invariant) ليس لمسة تجميل؛ إنه ما يجعل نص الفشل قابلاً للبحث والمقارنة بين التشغيلات، وآمناً لأن يُؤكَّد عليه داخل اختبارات تختبر الاختبارات. مجموعة اختبارات هذه المكتبة نفسها — 1242 اختباراً كلها خضراء — تؤكد رسائلها كنصوص حرفية حيث تكون مستقرة، وهذا ممكن فقط لأن الرسائل صُممت مستقرة أصلاً. الثبات خاصية قابلة للاختبار، وهي مُختبَرة فعلاً.

وتأمل البديل الذي تعيش عليه معظم المجموعات: رسائل تتغير بتغير ثقافة واجهة الجهاز، فيقرأ الفشل نفسه على حاسوبك بصيغة وعلى عامل البناء بصيغة أخرى. لا يمكنك البحث في سجل لا تستطيع إعادة إنتاجه، ولا التأكيد على نص يتحرك. الثبات هو ما يجعل رسالة الفشل تتصرف كبيانات — قابلة للمقارنة والبحث والاقتباس — لا كأحوال طقس.

تصاغَرْ بأناقة. رسالة الفشل ملخّص لا تفريغ بيانات. حين تتجاوز النصوص المقارَنة مئتي حرف أو تعبر الأسطر، طبعُها كاملة يدفن الفرق؛ ما ينفع هو الفرق نفسه: diff موحّد بثلاثة أسطر سياق، والقيم مقتطعة عند مئة حرف. وحين تكون القيمة وحدها طويلة، اقتطعها ودع القارئ يعيد الإنتاج بنفسه. الرسالة تجيب عن سؤال واحد: هل تحتاج إلى إعادة الإنتاج، أم أنك ترى الخلل أصلاً؟

أشِر إلى الخطوة التالية. بعض الإخفاقات بحثٌ أخطأ العنوان — مفتاح قاموس، خاصية JSON، سطر في مجموعة نصوص. سرد الموجود، مرتباً بالقرب ومحدوداً بثلاثة، يحوّل الطريق المسدود إلى خطوة عملية:

Did you mean 'name'?

اخدم القارئين معاً. الإنسان يقرأ نصاً، وخط الأنابيب يقرأ JSON. المكتبة الجدّية في سطح التشخيص تعامل الاثنين كصياغتين لبنية واحدة: كل فشل مجموع يحمل تعبير الموضوع وفئته ورسالته، والقيمتين الفعلية والمتوقعة حيث يبلّغ عنهما الفعل — يُسلسل للآلة ويُصاغ للإنسان. ابنِ السطحين منفصلين فيتباعدا مع الزمن؛ وابنِهما من مصدر واحد فيبقيا صادقين.

وعملياً، تسافر الصياغة الآلية أبعد مما يتوقع معظم المهندسين: مُرفقة بتشغيلات التكامل، مخزنة إلى جوار تقارير التشغيل الجاف، تُقارن عبر البناءات الليلية. تقرير JSON يحمل التعبير والفئة والقيمتين هو ما يجعل الفشل مقروءاً للأدوات بعد عام، حين لا يذكر أحد الاختبار.

قل "لماذا" حين يسأل القارئ لماذا. فشلٌ يصف الحالة فقط هو نصف تشخيص. من أرفق because: "the connection dropped" يحصل على جملة تفكير مترابطة، لا على معلومتين متجاورتين. جملة السبب تُلحَق — بأسلوب الجملة نفسها — بما بلّغ عنه الفعل أصلاً؛ فيركب السبب مع الدليل بدل أن يحلّ محله.

لا شيء من هذا يغني عن المصفّح، ولا قيمة لأي منه إن كان الاختبار لا يؤكد شيئاً. رسالة الفشل آخر الملاذ — ولهذا تحديداً تستحق تصميماً من الدرجة الأولى. فآخر الملاذ هو حيث ينتهي بنا الجميع.

ويبقى قارئ واحد لم يخدمه هذا العقد بعد: المهندس الذي ليست الإنجليزية لغته العاملة. نص الفشل من الأسطح النادرة التي نضمن أن قارئها تحت ضغط — ومكتبات هذا المجال تكاد تُجمع على لغة واحدة، وما عداها يصل مترجَماً. ما الذي يدين به سطح التشخيص لهذا القارئ؟ هذا موضوع المقالة التالية.

التالي: حين يجب أن تتكلم رسالة الفشل بالعربية

عن هذه السلسلة: هذه الملاحظات من بناء Jeninnet.Assertions — مكتبة تأكيدات مرنة ومستقلة عن أطر الاختبار، بترخيص MIT وبلا أي اعتماديات خارجية. هذه المقالة 01 من 06.

تجد المستودع هنا: Jeninnet.Assertions(GitHub).
تجد الحزم هنا:
- Jeninnet.Assertions (NuGet).
- Jeninnet.Assertions.Analyzer (NuGet).
- Jeninnet.Assertions.MSTest (NuGet).

What a Failure Message Owes Its Reader

Tarek — Thu, 22 Oct 2026 10:57:20 +0000

A test fails at 2 AM. You open the CI log, and the entire story of the failure is one line:

Expected True, but found False.

Which True? In which call? The test holds nine assertions, and a line written this way rules none of them out.

The build agent that ran it is already gone. The branch may be deleted next week. But the line stays — pasted into a chat thread, quoted in a ticket, screenshotted into a postmortem. A failure message is the only part of your test suite guaranteed to be read outside the editor, by people who never saw the code. That is the audience this piece is written for.

This is the moment a test library stops being an API and becomes a document. We choose libraries by their fluent surface — Should(), .Be(), .And — but the artifact most of us actually read, under pressure, months later, without context, is the failure text. Call it what it is: the diagnostic surface of the test suite. Most of us have never asked what that surface owes its reader.

Try it in sixty seconds. The central claim of this piece is checkable, so check it:

dotnet add package Jeninnet.Assertions

using Jeninnet.Assertions;

[TestMethod]
public void Username_matches_expected()
{
    string username = "dennis";
    username.Should().Be("jonas");
}

Expected username to be 'jonas', but found 'dennis'.

The package depends on no test framework, so the same three assertion lines work under MSTest, xUnit, or NUnit. Rename username to login and the message renames itself; run it on another machine and the message does not move.

This piece is the first of six notes on that surface — and a word on how to read them. These notes will not teach you the library's API; the book and the reference do that. They argue for the design behind it: why each surface looks the way it does, what it costs, and where it stops. Each note stands alone; together they describe one design.

The arc is fixed. After this contract: failure messages in Arabic — what changes when the reader under stress does not read English. Then time: how to test what happens later without sleeping through your own suite. Then memory: why allocation budgets belong inside unit tests. Then waiting: tests that poll for a truth that has not arrived yet instead of asserting a lie on a timer. Finally, validation that never throws — the same verbs, usable where exceptions are not allowed. Start here, with the contract.

Name the subject. A failure should say what failed, not only that something did. Compare:

Expected True, but found False.
Expected username to be 'jonas', but found 'dennis'.

The second sentence survives being pasted into a chat thread with no code around it. The subject is named because the assertion captured the expression text at compile time — the compiler's CallerArgumentExpression attribute (C# 10) — not because someone hand-wrote a label that drifts from the variable within a sprint, and not because a stack walk consulted a PDB file that is not guaranteed to be deployed. There is a second-order effect worth stating plainly: rename the variable and the message renames itself. Hand-written labels rot; captured expressions cannot.

Without the subject, every failure begins the same way: open the code, count the assertions, bisect. Nine suspects, one line of evidence. The subject name collapses that search to zero — before you have opened anything, you already know which value, from which expression, failed which check.

State expected and actual, in that order. The reader is performing a comparison; hand them both operands in reading order. "Assertion failed" is a verdict with no case file.

Be stable. The same failure should produce the same text on your machine, a colleague's machine, and a build agent — across operating systems and UI cultures. Invariant formatting is not a cosmetic detail; it is what makes failure output searchable, comparable across runs, and safe to assert on in tests that test tests. This library's own suite — 1,242 tests, all green — asserts its messages as exact strings wherever they are stable, which is only possible because the messages were designed to be stable in the first place. Stability is a testable property, and it is tested.

Consider the alternative most suites live with: messages that change with the machine's UI culture, so the same failure reads one way on your laptop and another on the build agent. You cannot search history you cannot reproduce, and you cannot assert on text that moves. Invariance is what lets a failure message behave like data — diffable, greppable, quotable — instead of weather.

Scale down gracefully. A failure message is a summary, not a data dump. When the compared strings grow past two hundred characters or span lines, printing both in full buries the difference; the useful artifact is the difference itself — a unified diff with three lines of context, values truncated to a hundred characters. When a value is merely long, truncate it and let the reader reproduce the rest. The message answers one question: do you need to reproduce this, or do you already see it?

Point at the next move. Some failures are lookups that missed — a dictionary key, a JSON property, a line in a string collection. Listing what does exist, ordered by closeness and capped at three, turns a dead end into a next step:

Did you mean 'name'?

Serve both readers. The human reads prose; the pipeline reads JSON. A library serious about the diagnostic surface treats these as two renderings of one structure: each collected failure carries its subject expression, its category, its message, and the actual and expected values where the verb reports them — serialized for machines, worded for people. Build the two surfaces separately and they drift; build them from one source and they stay honest.

In practice the machine rendering travels further than most engineers expect: attached to CI runs, stored beside dry-run reports, compared across nightly builds. A JSON report with the expression, the category, and both values is what makes a failure legible to tooling a year later, when nobody remembers the test.

Say why, when the reader asks why. A failure that describes only the state is half a diagnosis. The reader who attached because: "the connection dropped" gets one sentence of reasoning, not two unrelated facts. The because clause is appended, sentence-style, to whatever the verb already reported — the reason rides with the evidence instead of replacing it.

None of this replaces the debugger, and none of it matters if the test asserts nothing. The failure message is a last resort — which is precisely why it deserves first-class design. The last resort is where we all end up.

There is one more reader this contract has not served yet: the engineer whose working language is not English. Failure text is one of the rare surfaces whose reader is guaranteed to be under stress — and almost every library in this space speaks exactly one language, with anything else arriving as a translation. What the diagnostic surface owes that reader is the subject of the next piece.

Next: When the Failure Message Must Speak Arabic

About this series: These notes come from building Jeninnet.Assertions — a fluent, framework-agnostic assertion library, *MIT-licensed, with no test-framework dependency. This is article 1 of 6.

You can find the repository here: Jeninnet.Assertions(GitHub).
You can find the packages here:
- Jeninnet.Assertions (NuGet).
- Jeninnet.Assertions.Analyzer (NuGet).
- Jeninnet.Assertions.MSTest (NuGet).

AI-Assisted Professional Engineering with .NET [1]

Tarek — Fri, 31 Jul 2026 21:58:50 +0000

From Writing a Technical Book to Building an Engineering Ecosystem

Most technical books begin with an outline.

Mine began with a question.

How can Artificial Intelligence help professional software engineers without replacing engineering discipline?

At first, my goal was simple.

Write a high-quality technical book about AI-assisted software engineering with .NET.

But something unexpected happened.

Every chapter introduced new engineering problems that had nothing to do with writing itself.

How should documentation be organized?

How can architectural decisions remain traceable?

How can a bilingual manuscript stay synchronized?

How should Markdown become the single source of truth?

How can professional DOCX and PDF documents be generated automatically?

How should publishing become reproducible rather than manual?

One by one, solving these problems produced new tools, new documentation, new workflows, and new engineering practices.

Eventually I realized I wasn't building a manuscript anymore.

I was building an engineering ecosystem.

Today the repository contains much more than the book.

It contains a publishing platform, automation tooling, engineering documentation, community standards, architectural decisions, and an evolving knowledge base.

The manuscript is still important.

But it is now one component of a much larger project.

Perhaps the most important decision I made was to build everything in public.

Every improvement.

Every release.

Every architectural decision.

Every lesson learned.

Instead of publishing only the final result, I chose to document the complete engineering journey.

The first public release publishes only the Introduction of the manuscript.

That may seem like a small milestone.

In reality, it marks the beginning of a project that I expect to evolve for many years.

If this journey helps another engineer design a better workflow, document a better architecture, or publish knowledge more effectively, then the project has already achieved one of its goals.

This is only the beginning.

Engineering Series

002-Why I Built My Own Markdown Publishing Platform →

Continue the Journey

If you'd like to explore the project, follow its progress, or read future releases, you can find everything here:

GitHub Repository

https://github.com/TarekNajem04/AI-Assisted-Professional-Engineering-with-.NET

First Public Release

https://github.com/TarekNajem04/AI-Assisted-Professional-Engineering-with-.NET/releases/tag/v0.0.1

AI-Assisted Professional Engineering with .NET [1]

Tarek — Fri, 31 Jul 2026 21:51:09 +0000

من تأليف كتاب تقني إلى بناء منظومة هندسية متكاملة

تبدأ معظم الكتب التقنية بفهرس.

أما هذا المشروع فقد بدأ بسؤال.

كيف يمكن للذكاء الاصطناعي أن يساعد مهندس البرمجيات دون أن يحل محل التفكير الهندسي؟

في البداية كان هدفي بسيطًا.

تأليف كتاب احترافي حول الهندسة البرمجية بمساعدة الذكاء الاصطناعي باستخدام .NET.

لكن مع مرور الوقت بدأت تظهر تحديات لم تكن مرتبطة بالكتابة نفسها.

كيف يمكن تنظيم التوثيق؟

كيف نحافظ على تتبع القرارات الهندسية؟

كيف يمكن إدارة مخطوطة بلغتين دون فقدان التزامن؟

كيف تصبح ملفات Markdown المصدر الوحيد للحقيقة؟

كيف يمكن إنتاج ملفات DOCX وPDF بجودة احترافية بصورة آلية؟

وكيف تتحول عملية النشر من عمل يدوي إلى عملية هندسية قابلة للتكرار؟

كل سؤال كان يقود إلى حل جديد.

ومع كل حل ظهر مكون جديد داخل المشروع.

أدوات.

توثيق.

عمليات أتمتة.

معايير.

قرارات هندسية.

حتى أدركت في مرحلة ما أنني لم أعد أبني كتابًا فقط.

بل أبني منظومة هندسية متكاملة.

اليوم يضم المشروع أكثر من مجرد مخطوطة.

إنه يضم منصة نشر احترافية، ووثائق هندسية، وأدوات أتمتة، ومعايير للمجتمع، وسجلًا للقرارات الهندسية، وقاعدة معرفة تتوسع مع كل إصدار.

ما زال الكتاب يمثل قلب المشروع.

لكنه لم يعد المشروع كله.

ولعل أهم قرار اتخذته هو أن تُبنى هذه الرحلة أمام الجميع.

كل إصدار.

كل تحسين.

كل قرار هندسي.

وكل درس مستفاد.

فبدلًا من نشر النتيجة النهائية فقط، قررت توثيق الرحلة كاملة.

الإصدار الأول لا ينشر سوى مقدمة الكتاب.

وقد يبدو ذلك إنجازًا صغيرًا.

لكنه بالنسبة لي يمثل أول خطوة في مشروع أتمنى أن يستمر في التطور لسنوات طويلة.

وإذا ساعدت هذه الرحلة مهندسًا واحدًا على بناء مشروع أفضل، أو توثيق معرفة بصورة أفضل، أو تطوير سير عمل أكثر احترافية، فسأعتبر أن المشروع بدأ يحقق رسالته.

وما هذه إلا البداية.

Engineering Series

002-Why I Built My Own Markdown Publishing Platform →

تابع الرحلة

إذا أعجبتك فكرة المشروع وترغب في متابعة تطوره أو قراءة الإصدارات القادمة، يمكنك زيارة المستودع من خلال الرابط التالي.

المستودع

https://github.com/TarekNajem04/AI-Assisted-Professional-Engineering-with-.NET

الإصدار الأول

https://github.com/TarekNajem04/AI-Assisted-Professional-Engineering-with-.NET/releases/tag/v0.0.1

AI-Assisted Professional Engineering with .NET

Tarek — Tue, 28 Jul 2026 21:44:45 +0000

بداية الرحلة

لفترةٍ طويلة كنت أعتقد أنني أؤلف كتابًا تقنيًا.

لكن في مرحلة ما من الرحلة، أدركت أن ما أبنيه أكبر من كتاب.

في كل مرة كنت أحل مشكلة في النشر، أو أوثق قرارًا هندسيًا، أو أؤتمت مهمة متكررة، أو أحسن سير العمل، كان المشروع يكبر في اتجاه لم أخطط له منذ البداية.

اليوم لم يعد AI-Assisted Professional Engineering with .NET مجرد مخطوطة كتاب.

بل أصبح مشروعًا هندسيًا مفتوحًا يجمع بين:

كتاب تقني باللغتين العربية والإنجليزية.
منصة احترافية لتحويل Markdown إلى DOCX وPDF بجودة عالية.
توثيق هندسي ومعماري.
أدوات أتمتة.
معايير لتنظيم المستودع.
توثيق علني للقرارات الهندسية.

كل شيء في هذا المشروع يُبنى في العلن.

كل إصدار يمثل تقدمًا هندسيًا حقيقيًا.

وكل وثيقة تضيف لبنة جديدة إلى قاعدة معرفة تتوسع مع مرور الوقت.

اليوم أنشر أول محطة عامة في هذه الرحلة.

يتضمن الإصدار مقدمة الكتاب، لكنه يمثل قبل ذلك الأساس الهندسي الذي سيُبنى عليه المشروع خلال السنوات القادمة.

أتمنى أن يجد مطورو البرمجيات، والمهندسون، وكتّاب المحتوى التقني، وكل المهتمين بالذكاء الاصطناعي والهندسة البرمجية، ما يفيدهم في هذه الرحلة.

المستودع

https://github.com/TarekNajem04/AI-Assisted-Professional-Engineering-with-.NET

الإصدار الأول

https://github.com/TarekNajem04/AI-Assisted-Professional-Engineering-with-.NET/releases/tag/v0.0.1

يسعدني كثيرًا سماع آرائكم، وملاحظاتكم، وأفكاركم حول المشروع ورحلته.

AI-Assisted Professional Engineering with .NET

Tarek — Tue, 28 Jul 2026 21:40:40 +0000

The journey begins

For a long time, I believed I was writing a technical book.

At some point, I realized I was actually building something much bigger.

Every time I solved a publishing problem, automated a repetitive task, documented an architectural decision, or improved my engineering workflow, I wasn't just writing chapters anymore—I was building an engineering ecosystem.

That realization completely changed the direction of the project.

Today, AI-Assisted Professional Engineering with .NET is no longer just a manuscript.

It has grown into an open engineering project that brings together:

• A bilingual technical manuscript (English & Arabic)
• A professional Markdown publishing platform capable of producing high-quality DOCX and PDF documents

• Engineering documentation
• Automation tooling
• Repository standards
• Public engineering decisions

Everything is developed in public.

Every release represents measurable engineering progress.
Every document contributes to a continuously growing knowledge base.

Today I'm publishing the project's first public milestone.

It contains the complete Introduction of the manuscript, but more importantly, it establishes the engineering foundation for everything that follows.

This project will continue to evolve for years.

The manuscript will grow.

The publishing platform will mature.

The engineering knowledge base will expand.

I hope that by documenting the entire journey openly, other engineers, authors, and development teams will find ideas they can reuse in their own projects.

Repository

https://github.com/TarekNajem04/AI-Assisted-Professional-Engineering-with-.NET

First Public Release

https://github.com/TarekNajem04/AI-Assisted-Professional-Engineering-with-.NET/releases/tag/v0.0.1

I'm looking forward to your thoughts, feedback, and engineering discussions.

Jeninnet.FileQuery

Tarek — Wed, 03 Jun 2026 06:22:43 +0000

Building a Deterministic File Query Engine for .NET

How Jeninnet.FileQuery Combines GitIgnore, Glob, and Regex Into a Predictable High-Performance Query Engine

Building a Deterministic File Query Engine for .NET
Technical Whitepaper
Version 1.0
Author: Tarek Najem
GitHub: https://github.com/TarekNajem04/Jeninnet.FileQuery
NuGet: https://www.nuget.org/packages/Jeninnet.FileQuery
License: MIT

Jeninnet.FileQuery
- Table of Contents
- 1. Introduction
- 2. The Problem With Traditional File Matching
- 2.1 Glob-only libraries
- 2.2 Regular expression libraries
- 2.3 GitIgnore-inspired libraries
- 3. Deterministic Rule Evaluation
- 4. The Pattern Language
- 4.1 GitIgnore Patterns
- 4.2 Glob Patterns
- 4.3 Regular Expression Patterns
- 4.4 POSIX Character Classes
- 5. Architecture
- 5.1 Separation of Concerns
- 5.2 The Compilation Pipeline
- 5.3 The HybridPathMatcher
- 5.4 Traversal
- 5.5 Path Normalization
- 6. Performance
- 6.1 Zero-Allocation Hot Path
- 6.2 Benchmark Results
- 6.3 Compilation Pipeline Allocations
- 7. Getting Started
- 7.1 Installation
- 7.2 Basic Usage
- 7.3 Pattern-Based Filtering
- 7.4 Hybrid Pattern Mixing
- 7.5 Async Enumeration
- 7.6 Dependency Injection
- 7.7 Command-Line Integration
- 8. Package Reference
- Supported Targets
- 9. Design Goals and Non-Goals
- Goals
- Non-Goals
- 10. Conclusion

1. Introduction

Every non-trivial software system eventually encounters the same deceptively simple task: finding files.
Build systems search for source files. Backup tools scan directories to determine what has changed.
Code analyzers walk entire repositories. Log processors filter terabytes of archived data.

At first glance, file discovery appears trivial. Operating systems provide directory enumeration APIs, and many environments include globbing utilities.
But once a project grows, developers discover deeper issues:

Pattern languages behave inconsistently.
Traversal becomes expensive at scale.
Rule ordering is unclear.
Pattern syntaxes cannot easily coexist.

These challenges led to the creation of Jeninnet.FileQuery, a library that treats file discovery as a first-class architectural problem.

2. The Problem With Traditional File Matching

Most libraries approach file matching from one of three directions.

2.1 Glob-only libraries

Glob patterns are simple and familiar.
However, limitations appear when rule sets grow:

No rule ordering
No negation
No mixing with regex
No hierarchical semantics

2.2 Regular expression libraries

Regex is expressive but not suited for hierarchical filesystem rules.
Patterns become unreadable and difficult to maintain.

2.3 GitIgnore-inspired libraries

GitIgnore introduces:

Rule ordering
Negation
Directory-aware semantics

But these libraries rarely allow mixing GitIgnore, Glob, and Regex in the same rule set.

The deeper issue is not syntax but evaluation order.
Ambiguities lead to unpredictable results.

3. Deterministic Rule Evaluation

Jeninnet.FileQuery adopts a simple and explicit rule model:

Patterns are evaluated sequentially, and the last matching rule determines the final result.

Example rule set:

**           # Exclude everything
!*.log       # Include all .log files
data.log     # Exclude this specific file again

Evaluation:

Rule 1: exclude all files
Rule 2: include files ending in .log
Rule 3: exclude data.log specifically

Final result:

data.log is excluded
all other .log files are included
all other files remain excluded

This deterministic model eliminates ambiguity and ensures predictable behavior.

4. The Pattern Language

Jeninnet.FileQuery supports three pattern dialects that can coexist in the same rule set:

GitIgnore patterns
Glob patterns
Regular expressions

The engine automatically classifies each pattern and routes it to the correct matcher.

4.1 GitIgnore Patterns

GitIgnore patterns are the default and most expressive for hierarchical rules.

Syntax	Meaning
**	Match zero or more path segments
*	Match any characters within one segment
?	Match exactly one character
!	Negate the pattern
/pattern	Anchor to root
pattern/	Directory-only
[abc]	Character set
[a-z]	Character range
[!abc]	Negated set
[[:digit:]]	POSIX digit class

Example:

**               # exclude everything
!src/**/.cs      # include C# files under src
src/obj/**       # exclude obj
src/bin/**       # exclude bin

4.2 Glob Patterns

Glob patterns follow classical Unix rules and are always anchored.

Examples:

*.cs
**/*.cs
data/??.log
report.[0-9].txt

Negation is not supported in glob patterns.

4.3 Regular Expression Patterns

Regex patterns are prefixed with r: and evaluated against the full normalized path.

Examples:

r:^src/.*\.cs$
r:^data_\d{4}\.log$
r:^(?!.*test).*\.dll$

4.4 POSIX Character Classes

Supported inside [: :]:

Class	Matches
[:digit:]	0–9
[:alpha:]	a–z, A–Z
[:alnum:]	digits and letters
[:space:]	whitespace
[:upper:]	A–Z
[:lower:]	a–z
[:xdigit:]	hex digits
[:punct:]	punctuation

Example:

**
![[:digit:]]*.txt

5. Architecture

5.1 Separation of Concerns

The engine separates:

Pattern compilation
Filesystem traversal
Matching execution

Each layer is isolated and enforced by architecture tests.

5.2 The Compilation Pipeline

Patterns pass through four phases:

Phase	Responsibility
Lexical invariant	Validate raw text
PatternScanner	Tokenize into tokens
Structural invariants	Validate token structure
Semantic invariants	Apply dialect transforms

The scanner is purely lexical; semantics are applied later for clarity and testability.

5.3 The HybridPathMatcher

The matcher coordinates three sub-matchers:

GitIgnoreInstructionMatcher
GlobInstructionMatcher
RegexInstructionMatcher

Routing is precomputed, so evaluation is fast and allocation-free.

5.4 Traversal

Supports:

Depth-first traversal
Breadth-first traversal

Options include recursion depth, symlink policy, case sensitivity, and error handling.

5.5 Path Normalization

All paths are normalized:

Forward slashes
Collapsed duplicates
Preserved UNC roots
Uppercased drive letters

This ensures cross-platform consistency.

6. Performance

Jeninnet.FileQuery is designed for high performance, especially in large directory trees and complex rule sets.

6.1 Zero-Allocation Hot Path

The engine ensures that pattern matching produces zero heap allocations in the hot path.

Before optimization:

foreach (var pattern in patterns)
{
    ...
}

This caused boxing of the enumerator (~40 bytes per evaluation).

After optimization:

for (var i = 0; i < patterns.Count; i++)
{
    var pattern = patterns[i];
    ...
}

This eliminates all allocations during matching.

6.2 Benchmark Results

Environment:
Intel Core i7-8850H 2.60 GHz
.NET 10.0.5
Windows 11
BenchmarkDotNet v0.15.8

Component	Mean	Allocated
PatternClassifier	64 ns	0 B
GlobMatcher	261 ns	0 B
RegexMatcher	85 ns	0 B
GitIgnoreMatcher	771 ns	0 B
HybridMatcher	742 ns	0 B
PatternTokenizer	4.85 µs	~9 KB (one-time)
Traversal (QueryFiles)	2.0 ms	~30 KB

Most allocations come from returning actual file paths, not from the engine itself.

6.3 Compilation Pipeline Allocations

When the caller specifies a PatternKind explicitly, the engine skips classification and reduces allocations by ~400–500 bytes per pattern.

Sub-lists for pattern kinds are allocated lazily.
If only GitIgnore patterns are used, no Glob or Regex lists are created.

7. Getting Started

7.1 Installation

Install the core package:

dotnet add package Jeninnet.FileQuery

Optional packages:

dotnet add package Jeninnet.FileQuery.CommandLine
dotnet add package Jeninnet.FileQuery.DependencyInjection

7.2 Basic Usage

var engine = FileQueryRuntime.Create();

var query = FileQuery.From(@"C:\repo")
                     .Build();

foreach (var file in engine.Execute(query))
{
    Console.WriteLine(file);
}

7.3 Pattern-Based Filtering

var query = FileQuery.From(@"C:\repo")
                     .Where(
                         "**",
                         "!src/**/*.cs",
                         "src/obj/**",
                         "src/bin/**"
                     )
                     .Build();

var results = engine.Execute(query).ToList();

7.4 Hybrid Pattern Mixing

var query = FileQuery.From(@"C:\repo")
                     .UsingHybrid()
                     .Where(
                         "**",
                         "!*Global*.cs",
                         "r:^src/.*Engine.*"
                     )
                     .IgnoreCase()
                     .Build();

7.5 Async Enumeration

await foreach (var file in engine.ExecuteAsync(query, cancellationToken))
{
    await ProcessFileAsync(file, cancellationToken);
}

7.6 Dependency Injection

builder.Services.AddFileQuery();

public class FileScanner(IFileQueryEngine engine)
{
    public IEnumerable<string> Scan(string root)
        => engine.Execute(FileQuery.From(root).Build());
}

7.7 Command-Line Integration

// Usage: myapp --patterns "**;!*.exe" --gitignore "bin/;obj/"

var options = new CommandLinePatternOptions();
var rootCmd = new RootCommand("File scanner");

foreach (var opt in options.GetCommandOptions())
    rootCmd.Add(opt);

rootCmd.SetAction(result =>
{
    var patterns = PatternBuilder.Build(result, options);
    var query = FileQuery.From(root).Where(patterns).Build();

    foreach (var file in engine.Execute(query))
        Console.WriteLine(file);
});

8. Package Reference

Package	Description
Jeninnet.FileQuery	Core engine. GitIgnore, Glob, Regex. Zero-allocation matching.
Jeninnet.FileQuery.CommandLine	Maps System.CommandLine results to pattern options.
Jeninnet.FileQuery.DependencyInjection	Registers IFileQueryEngine for DI containers.

Supported Targets

All packages target:

net10.0

Symbol packages and Source Link are enabled.

9. Design Goals and Non-Goals

Goals

Deterministic behavior
Composable pattern dialects
Zero-allocation hot path
Streaming traversal
Cross-platform normalization
Strong architectural boundaries
Extensible compiler and matcher pipeline

Non-Goals

File content inspection
Parallel traversal (planned for v1.1)
Mutable filesystem operations
Pattern caching across queries (planned for v1.1)

10. Conclusion

File discovery becomes complex at scale.
Jeninnet.FileQuery solves this by:

Providing deterministic rule evaluation
Supporting mixed pattern dialects
Ensuring high performance with zero allocations
Offering a clean, extensible architecture

Try it:

dotnet add package Jeninnet.FileQuery

GitHub: github.com/TarekNajem04/Jeninnet.FileQuery
NuGet: nuget.org/packages/Jeninnet.FileQuery
License: MIT

DEV Community: Tarek

ما الذي تدين به رسالة الفشل لقارئها؟

ما الذي تدين به رسالة الفشل لقارئها؟

What a Failure Message Owes Its Reader

AI-Assisted Professional Engineering with .NET [1]

From Writing a Technical Book to Building an Engineering Ecosystem

Engineering Series

Continue the Journey

GitHub Repository

First Public Release

AI-Assisted Professional Engineering with .NET [1]

من تأليف كتاب تقني إلى بناء منظومة هندسية متكاملة

Engineering Series

تابع الرحلة

المستودع

الإصدار الأول

AI-Assisted Professional Engineering with .NET

بداية الرحلة

AI-Assisted Professional Engineering with .NET

The journey begins

Jeninnet.FileQuery

Building a Deterministic File Query Engine for .NET

How Jeninnet.FileQuery Combines GitIgnore, Glob, and Regex Into a Predictable High-Performance Query Engine

Table of Contents

1. Introduction

2. The Problem With Traditional File Matching

2.1 Glob-only libraries

2.2 Regular expression libraries

2.3 GitIgnore-inspired libraries

3. Deterministic Rule Evaluation

4. The Pattern Language

4.1 GitIgnore Patterns

4.2 Glob Patterns

4.3 Regular Expression Patterns

4.4 POSIX Character Classes

5. Architecture

5.1 Separation of Concerns

5.2 The Compilation Pipeline

5.3 The HybridPathMatcher

5.4 Traversal

5.5 Path Normalization

6. Performance

6.1 Zero-Allocation Hot Path

6.2 Benchmark Results

6.3 Compilation Pipeline Allocations

7. Getting Started

7.1 Installation

7.2 Basic Usage

7.3 Pattern-Based Filtering

7.4 Hybrid Pattern Mixing

7.5 Async Enumeration

7.6 Dependency Injection

7.7 Command-Line Integration

8. Package Reference

Supported Targets

9. Design Goals and Non-Goals

Goals

Non-Goals

10. Conclusion