Node.js مناسب للأدوات التي تتعامل مع الملفات والمجلدات لأن JavaScript نفسها تصبح متاحة خارج المتصفح. توثيق Node الرسمي يضم APIs للملفات والمسارات والعمليات، لكن جودة الأداة تعتمد على تصميم الأمر وحدود صلاحياته أكثر من عدد الأسطر.
حدد نطاق الأداة
لنصنع أمرًا اسمه scan-assets يقرأ مجلد assets ويخرج قائمة بالملفات الكبيرة. لا تحذف ولا تعيد تسمية أي ملف في الإصدار الأول. الأداة التي تقرأ فقط أسهل في الاختبار وأقل خطورة.
import { readdir, stat } from 'node:fs/promises';
import path from 'node:path';
async function listFiles(folder) {
const names = await readdir(folder, { withFileTypes: true });
const rows = [];
for (const entry of names) {
if (!entry.isFile()) continue;
const full = path.join(folder, entry.name);
const info = await stat(full);
rows.push({ name: entry.name, bytes: info.size });
}
return rows.sort((a,b) => b.bytes - a.bytes);
}المدخلات لا تثق بها
حتى الأداة المحلية تحتاج تحققًا. امنع المسار الفارغ، اعرض رسالة إذا لم يكن مجلدًا، ولا تسمح بتمرير flags غير معروفة بصمت. إذا ستضيف خيارًا للحذف لاحقًا، اجعله explicit مثل --apply ولا تجعله السلوك الافتراضي.
اجعل الناتج مفيدًا للإنسان والآلة
اعرض جدولًا بسيطًا للإنسان، وأضف --json للسكربتات. لا تخلط رسائل التشخيص مع JSON في stdout؛ استخدم stderr للتنبيهات حتى يستطيع برنامج آخر قراءة الناتج.
const json = process.argv.includes('--json');
const rows = await listFiles(process.argv[2] || '.');
if (json) console.log(JSON.stringify(rows, null, 2));
else for (const row of rows) console.log(`${row.bytes} ${row.name}`);التشغيل والتوزيع
ضع الأمر في package.json، وثبّت نسخة Node في README، وأضف اختبارًا لمجلد فارغ ومسار غير موجود. لا تضع token أو مسارًا خاصًا داخل الكود. لو احتاجت الأداة إعدادًا، اقرأه من arguments أو environment variables موثقة.
مراجع رسمية
هذه الروابط الرسمية هي نقطة الرجوع عند اختلاف إصدار الأداة أو تغيّر سلوك المتصفح.