Image: AI generated
إذا كنت تريد تبني SSOT في مشروع قائم لكن لا تستطيع إعادة الكتابة من الصفر، إذا كنت تريد استخلاص OpenAPI وDDL تلقائياً من واجهة خلفية قديمة بلغة Go أو TypeScript أو Python أو Java أو C# أو Rust أو PHP — codistill يعصر المواصفات من الكود الموجود.
“لدينا بالفعل 200 نقطة نهاية”
شخص يقرأ مقال yongol ويسأل: “جيد، لكن مشروعنا لديه بالفعل عشرات الآلاف من الأسطر. هل نحتاج لكتابة SSOT من الصفر؟”
البدء من الصفر سيكون مثالياً، لكنه مستحيل عملياً. لا يستطيع أي فريق إيقاف خدمة تعمل وكتابة المواصفات من الصفر.
لذلك صُنع codistill. يستخلص SSOT من الكود الموجود.
ضع الفاكهة كاملة، يخرج العصير
codistill يحلل كود إطار العمل الويب بشكل ساكن لاستخلاص المواصفات التصريحية تلقائياً.
codist scan --openapi ./my-project
سطر واحد ينتج مواصفات OpenAPI 3.0 من الكود الموجود. ما كان يستغرق أياماً من العمل اليدوي ينتهي في ثوانٍ.
إذا كان المشروع يتضمن بالفعل openapi.yaml، يكتشفه codist ويدمجه — البنية تأتي من الكود (تسجيل الموجِّه هو مرجع الحقيقة)، والأوصاف من المواصفات الموجودة، وتُسقط المواصفات الميتة التي لم تعد موصولة بأي مسار.
صفر حمل على وقت التشغيل. لا حاجة للقياس. تحليل ساكن بحت. كما جرى تصليبه على قواعد كود ضخمة من العالم الواقعي — Immich وGhost وNocoDB وPlane وAppFlowy وغيرها — بإصلاح عيوب الاستخلاص التي لا تظهر إلا في مصادر بحجم الإنتاج (changelog).
ستة عشر إطاراً، ثماني لغات
| اللغة | أطر العمل |
|---|---|
| Go | Gin, Fiber, Echo |
| TypeScript | NestJS, Fastify, Hono, Express |
| Python | FastAPI, Flask, Django |
| Java | Spring Boot, Quarkus |
| C# | ASP.NET Core |
| Rust | Actix Web |
| PHP | Laravel |
| Deno TypeScript | Supabase Edge Functions |
ما بدأ بثلاثة أطر — Gin وNestJS وFastAPI — يغطي الآن ستة عشر عبر ثماني لغات. يُكتشف إطار العمل تلقائياً من go.mod أو package.json أو requirements.txt أو pom.xml أو *.csproj أو Cargo.toml أو composer.json أو supabase/functions/، أو يُحدَّد بـ --framework. تُحلَّل معظم الواجهات الخلفية عبر tree-sitter؛ أما Go+Gin فيستخدم go/ast + go/types مباشرة.
تجميع DDL
codist ddl ./migrations -o ./schema
يقرأ تاريخ الترحيل بالكامل ويخرج لقطة CREATE TABLE نظيفة لكل جدول.
يعالج CREATE/ALTER/DROP TABLE وADD/DROP/ALTER COLUMN والقيود والفهارس. أما في المشاريع المعتمدة على Prisma، فإن codist prisma يقرأ schema.prisma مباشرة — بما في ذلك المفاتيح الأجنبية المركّبة وأنواع enum وأنواع pgvector — ويُخرج DDL مرتباً حسب المفاتيح الأجنبية يُطبَّق بنظافة على قاعدة بيانات حيّة.
هيكلة استعلامات sqlc
codist sql next --repo ./repository --queries ./db/query
next – سير عمل السقاطة. يعرض طريقة Repository التالية بدون استعلام.
الدخول إلى خط أنابيب yongol
خرج codistill هو دخل yongol. codistill يستخلص SSOT من الكود الموجود؛ yongol يتحقق من الاتساق ويولّد الكود. التحول من brownfield إلى greenfield يحدث تدريجياً.
ليس أساسات بل تعزيز مقاوم للزلازل. نمط Strangler Fig لـ Fowler (2004).
ابدأ
npx skills add park-jun-woo/codistill
codist scan --openapi ./my-project
الكود الموجود يصبح عصيراً.
الكود: github.com/park-jun-woo/codistill
مقالات ذات صلة
- yongol — عارضة السفينة للـ SaaS بالذكاء الاصطناعي – أداة التحقق وتوليد الكود من SSOT المستخلص بواسطة codistill.
- Ratchet Pattern — كيف تجعل الوكلاء ينهون العمل – خلفية سير عمل السقاطة في
codist sql next. - Reins Engineering — ذكاء اصطناعي بلجام – الإطار الهندسي الذي ينتمي إليه codistill.
المراجع
- Huang, R. et al. (2024). Generating REST API Specifications through Static Analysis. ICSE 2024. ACM
- Perry, D. E. & Wolf, A. L. (1992). Foundations for the Study of Software Architecture. ACM
- Fowler, M. (2004). StranglerFigApplication. Link
- Lercher, A. et al. (2024). Generating Accurate OpenAPI Descriptions. arXiv
- Chauhan, S. et al. (2026). OpenAI for OpenAPI. arXiv
- De Silva, L. & Balasubramaniam, D. (2012). Controlling software architecture erosion. ScienceDirect
- Fritzsch, J. et al. (2019). Microservices Migration in Industry. arXiv
- Curino, C. A. et al. (2008). Graceful database schema evolution. VLDB
- Nghiem, D. et al. (2023). REST API Design Practices. IEEE
سجل التغييرات
- 2026-06-19: توسيع التغطية إلى 16 إطاراً عبر 8 لغات؛ دعم DDL ALTER COLUMN ومخطط Prisma؛ تصليب على قواعد كود من العالم الواقعي (codistill v0.1.11)
- 2026-05-26: الإصدار الأول