Begona repoda orientatsiya: 15 daqiqada loyihani config fayllaridan o'qish

Qisqacha: Notanish loyihani ochganda kodni o'qishdan boshlamang. Avval ildiz fayllari: lock-fayl paket menejerini aytadi, package.json — skriptlar va asboblarni, .nvmrc/engines va CI — Node versiyasini, config fayllar — lint, format va build qoidalarini. 15 daqiqalik tartibli ko'rik loyihaning "pasportini" beradi. Shundan keyin birinchi ishga tushirish va, kerak bo'lsa, "ishlamayapti" tergovi.

Bu darsda

• Begona repoga birinchi 15 daqiqalik ko'rik tartibini qo'llaysiz.
• Lock-fayldan paket menejerini aniqlaysiz va noto'g'ri menejer nima buzishini ko'rasiz.
• package.json skriptlari va config fayllardan loyihaning asboblar zanjirini chizasiz.
• CI workflow'idan "loyiha qanday tekshiriladi" degan savolga javob olasiz.
• "Menda ishlamayapti" holatida qayerdan boshlashni bilasiz.

Oldin bilishingiz kerak: Platforma va kutubxona config fayllari, tsconfig app va node, ESLint II: plaginlar.

1. Nega bu kerak?

Sardor stajirovkaning ikkinchi oyida. Jasur aka yangi topshiriq berdi: "Biz nanoid kutubxonasidan foydalanamiz. Uning reposiga kichik tuzatish yuborish kerak — ko'rib chiq".

Sardor reponi ochdi va... src/ papkasi yo'q, pnpm-lock.yaml, oxlint.config.ts, oxfmt.config.ts, .devcontainer.json — bularning yarmini birinchi ko'rishi. Qayerdan boshlash kerak?

Bu holat har dasturchining hayotida doimiy: yangi ish joyi, ochiq kodga hissa, mijozning eski loyihasi. Kodni boshidan o'qishga urinish — kitobni lug'atsiz o'qish kabi. Avval "mundarija" kerak. Loyiha ildizidagi fayllar — aynan mundarija: 16-qism davomida ularning deyarli hammasini o'rgandingiz. Bugun shu bilimni bitta ko'nikmaga yig'amiz.

Darsdagi hamma kuzatuv — haqiqiy ochiq repo: github.com/ai/nanoid, commit c0d01e30b0ecf1add4ae860937445924f078188e (2026-10-10, "Remove JSR since Deno is dead"). Repo kichik (310 KB), lekin zamonaviy asboblar bilan to'la. Siz o'qiyotganda u o'zgargan bo'lishi mumkin — shuning uchun commit aniq ko'rsatilgan. npm buyruqlari darsida nanoid ni paket sifatida o'rnatgan edingiz — endi uning ichkarisini ko'ramiz.

2. 15 daqiqalik ko'rik tartibi

flowchart TB
  A["1. README<br/>(2 daq)"] --> B["2. Lock-fayl:<br/>paket menejeri"]
  B --> C["3. package.json:<br/>scripts, type, engines"]
  C --> D["4. Config fayllar<br/>xaritasi"]
  D --> E["5. CI workflow:<br/>qanday tekshiriladi"]
  E --> F["6. Birinchi<br/>ishga tushirish"]

Har qadam bitta savolga javob beradi. Tartib muhim: oldingi qadam keyingisini osonlashtiradi.

2.1 README — ikki daqiqa

Reponi yuklab olamiz — butun tarixsiz, faqat kerakli commit:

git clone --depth 1 https://github.com/ai/nanoid.git

--depth 1 — faqat oxirgi commit (Remote: clone). Biz aniq commitni olish uchun git fetch --depth 1 origin c0d01e3… ishlatdik — mashqda.

README'dan faqat ikki narsani qidiramiz: "bu nima?" va "qanday ishga tushiriladi / qanday hissa qo'shiladi?". nanoid README boshi:

A tiny, secure, URL-friendly, unique string ID generator for JavaScript.
…
- **Small.** 117 bytes (minified and brotlied). No dependencies.
  [Size Limit] controls the size.

"JavaScript uchun kichik, xavfsiz, URL'ga mos noyob ID yasovchi. 117 bayt, bog'liqliksiz. Hajmni Size Limit nazorat qiladi". Uchinchi gap — asboblar haqida birinchi ishora: loyihada hajm tekshiruvi bor.

README'da "Install" bo'limi bor, lekin u foydalanuvchi uchun (npm install nanoid). Dasturchi uchun yo'riqnoma (CONTRIBUTING.md) nanoid'da yo'q. Bunday holat ko'p uchraydi — keyingi qadamlar shuning uchun kerak.

2.2 Lock-fayl — paket menejeri

ls -a

Ildizda pnpm-lock.yaml bor, package-lock.json yo'q. Demak, loyiha pnpm da (pnpm darsi). Bu birinchi va eng muhim xulosa.

Yana ikki dalil: pnpm-workspace.yaml fayli va CI'dagi pnpm ci buyrug'i. package.json da "packageManager" maydoni yo'q — versiyani CI'dan olamiz: pnpm/setup qadamida version: 12.

2.3 Tuzoq: noto'g'ri menejer

Sardor odati bo'yicha npm install qildi:

added 54 packages, and audited 55 packages in 17s

13 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Xato yo'q! Lekin git status da yangi fayl: ?? package-lock.json. npm pnpm-lock.yaml ni o'qimaydi — u versiyalarni package.json dagi chegaralardan qaytadan tanladi. Taqqoslaymiz:

Muallif bir versiyalar bilan tekshirgan, Sardor esa boshqalari bilan ishlayapti. Xato chiqsa, "menda boshqacha" bahsi boshlanadi. Lock-fayl aynan shunga qarshi edi (Lock-fayllar). Va eng yomoni — package-lock.json tasodifan commitga tushsa, repoda ikkita lock-fayl paydo bo'ladi.

To'g'ri yo'l — loyihaning menejeri, lock'ga qat'iy amal qilib. pnpm o'rnatilmagan bo'lsa, global o'rnatmasdan npx orqali:

npx -y pnpm@12.10.1 install --frozen-lockfile

…
Progress: resolved 54, reused 12, downloaded 42, added 54, done

devDependencies:
+ @logux/oxc-configs 1.2.0
…
+ oxlint 1.86.0
+ oxlint-tsgolint 7.0.2003
…
+ vite 8.3.2

Done in 13.4s using pnpm v12.10.1

--frozen-lockfile — npm ci ning pnpm'dagi o'xshashi: lock'dan bir qadam ham chetga chiqmaydi. Versiyalar — lock'dagidek.

Tekshirib ko'ring: Ildizda ham package-lock.json, ham yarn.lock bor. Qaysi menejerni ishlatasiz?

3. package.json — asboblar ro'yxati

3.1 Skriptlar

{
  "scripts": {
    "clean": "rm -rf coverage",
    "start": "vite --host 0.0.0.0 test/demo/",
    "test:coverage": "bnt --coverage 100 --coverage-exclude 'test/*'",
    "test:lint": "oxlint",
    "test:size": "pnpm clean && size-limit",
    "test:prebuild": "node ./test/check-prebuild.js",
    "test": "pnpm run /^test:/"
  }
}

Har skript — bitta asbob:

pnpm run /^test:/ — pnpm'ning imkoniyati: skript nomi o'rniga regex. npm buni bilmaydi. Bitta qator — va siz loyihada nima tekshirilishini bilasiz: testlar (100 % qamrov bilan), lint, hajm va "prebuild" fayl.

3.2 Pasport maydonlari

dependencies umuman yo'q — README'dagi "No dependencies" va'dasi shu yerda tasdiqlanadi.

4. Config fayllar xaritasi

4.1 Ildizni guruhlaymiz

Ildiz fayllari darsidagi guruhlar bo'yicha:

Notanish fayllarni bittalab ochamiz.

4.2 oxlint.config.ts — Oxlint, lekin .ts da

import loguxOxlintConfig from '@logux/oxc-configs/lint'
import { defineConfig } from 'oxlint'

export default defineConfig({
  options: {
    typeCheck: false
  },
  extends: [loguxOxlintConfig],
  ignorePatterns: ['test/demo/dist'],
  // The generated CDN build uses `var` for smaller Rolldown output.
  overrides: [
    {
      files: ['nanoid.js'],
      rules: {
        'block-scoped-var': 'off',
        'no-var': 'off',
        'prefer-let/prefer-let': 'off'
      }
    }
  ],
  rules: {
    'unicorn/no-array-sort': 'off'
  }
})

Biome va Oxlint darsida .oxlintrc.json ni ko'rgansiz. Bu yerda — o'sha sozlama TypeScript kod-config ko'rinishida (config fayllar): defineConfig, extends, overrides. Tuzilma ESLint flat config ga juda o'xshaydi. extends dagi @logux/oxc-configs — muallifning o'z umumiy qoidalar to'plami (u boshqa loyihalarida ham shuni ishlatadi). Izohdagi sabab ("CDN build var ishlatadi") — yaxshi config'ning belgisi.

Uslubiga e'tibor bering: nuqtali vergul yo'q, qo'shtirnoq — bittalik. Bu loyiha uslubi, uni oxfmt belgilaydi.

4.3 oxfmt.config.ts va .prettierrc.js

import loguxOxfmtConfig from '@logux/oxc-configs/fmt'

export default loguxOxfmtConfig

oxfmt — Oxc loyihasining formatlagichi (Prettier o'rnida). Qiziq tomoni: .prettierrc.js ning mazmuni aynan bir xil. Nega? Ehtimol, muharrirlardagi Prettier kengaytmasi ham shu uslubni olsin deb. Bu bizning taxminimiz — kodda izoh yo'q. Begona repoda bunday "nega?" savollarini yozib boring va keyin muallifdan (issue yoki PR'da) so'rang.

4.4 pnpm-workspace.yaml — kutilmagan mazmun

minimumReleaseAgeExclude:
  - nope-id

Nomi "workspace", ichida esa — xavfsizlik sozlamasi. pnpm'da minimumReleaseAge (Ta'minot zanjiri darsidagi g'oya) yoqilgan va nope-id paketi bu qoidadan istisno. Ya'ni muallif yangi versiyalarni darhol olmaydi, faqat bitta paketga ishonadi. Fayl nomi har doim ham mazmunni aytmaydi — ochib o'qing.

4.5 .npmignore, .editorconfig, .devcontainer.json

• .npmignore — npm'ga chiqadigan arxivdan nimalar chiqarilsin: test/, coverage/, img/, SECURITY.md, pnpm-workspace.yaml. Foydalanuvchiga testlar kerak emas.
• .editorconfig — indent_size = 2, end_of_line = lf; alohida bo'lim [nanoid.js] uchun: insert_final_newline = false — CDN fayli baytma-bayt (VS Code sozlamalari).
• .devcontainer.json — { "image": "ghcr.io/ai/devcontainer:latest" }: tayyor dasturlash muhiti (Docker obrazi) — 33-qismda. Hozircha: "muallif loyihani konteyner ichida ham ochadi".

5. CI — loyiha qanday tekshiriladi

.github/workflows/test.yml dan muhim qismlar:

      - name: Install Node.js & pnpm
        # SHA qisqartirildi: fbda4c85fc2e…f024
        uses: pnpm/setup@fbda4c85…f024 # v3.0.0
        with:
          version: 12
          runtime: node@26
      - name: Install dependencies
        run: pnpm ci
      - name: Run tests
        run: pnpm test

CI ikki xil job'da ishlaydi: Node 26 da to'liq (pnpm test), Node 24 va 22 da — faqat testlar (pnpm bnt). Ya'ni engines dagi va'da CI'da tekshirilgan. Ikki professional odat ham ko'rinadi:

• Action'lar SHA bilan qotirilgan: actions/checkout@3d3c42e5… (yonida # v7.0.1 izohi). Teg (@v7) o'zgarishi mumkin, commit SHA — yo'q. Ta'minot zanjiri himoyasi.
• persist-credentials: false — checkout'dan keyin token diskda qolmaydi.

vazifalar ning pages.yml ida action'lar teg bilan (@v7). Bu farqni bilish — begona repodan o'rganishning foydasi.

Tekshirib ko'ring: CI'da Node 22 uchun pnpm test emas, pnpm bnt ishlatilgan. Nima uchun bo'lishi mumkin?

6. Birinchi ishga tushirish va "ishlamayapti" tergovi

6.1 Natija

Bog'liqliklar o'rnatildi (pnpm install --frozen-lockfile). Endi Windows'da:

npx -y pnpm@12.10.1 test

Chiqish uzun (183 qator). Oxirini ko'ramiz — Failed so'zli qatorlarga qarang:

. test:coverage: ℹ Error: 98.74% line coverage does not meet threshold of 100%.
…
. test:coverage: Failed
[ELIFECYCLE] Command failed with exit code 1.
…
. test:size: Failed
[ELIFECYCLE] Command failed with exit code 1.
. test:lint: Failed
[ELIFECYCLE] Command failed with exit code 1.
[ELIFECYCLE] Test failed. See above for more details.

Uchta "Failed"! CI esa yashil. Vahima qilmaymiz — tergov qilamiz.

6.2 Bittadan ajratish

pnpm run /^test:/ skriptlarni parallel ishga tushiradi. Birinchi qadam — har birini alohida:

Lint va hajm aslida toza edi — ular "Failed" bo'ldi, chunki parallel ishda bitta skript yiqilganda pnpm qolganlarini to'xtatdi. Haqiqiy muammo — bitta: qamrov.

6.3 Sababni topish

Qamrov hisobotida bin.test.js, index.test.js kabi test fayllarining o'zi bor. Lekin skriptda --coverage-exclude 'test/*' — test fayllari hisobdan chiqarilishi kerak edi. Nega chiqmadi?

Sabab — bitta tirnoq ('…'). macOS va Linux'da skriptlarni sh bajaradi va u tirnoqni olib tashlaydi: bnt ga test/* boradi. Windows'da esa skriptni cmd.exe bajaradi — u bitta tirnoqni tanimaydi va bnt ga 'test/*' (tirnoqlari bilan) boradi. Bunday papka yo'q — hech narsa chiqarilmaydi. Tekshiramiz — qo'sh tirnoq bilan, to'g'ridan-to'g'ri:

npx -y pnpm@12.10.1 exec bnt --coverage 100 \
  --coverage-exclude "test/*"

ℹ pass 88
ℹ fail 0
ℹ all files         | 100.00 |   100.00 |  100.00 | 

100 %. Kod to'g'ri — muammo faqat Windows'dagi skript yozuvida. Bu topilma — yaxshi birinchi PR: skriptda qo'sh tirnoq (\"test/*\") hamma tizimda ishlaydi.

6.4 "Ishlamayapti" — qayerdan boshlash

Bu tergovdan umumiy tartib chiqadi:

1. Menejer va lock — loyihaning menejeri, ci/--frozen-lockfile bilan.
2. Node versiyasi — .nvmrc, engines, CI matritsasi bilan solishtiring.
3. Bittadan — parallel yoki zanjir skriptni qismlarga bo'ling; birinchi haqiqiy xatoni toping.
4. Xabarni o'qing — 98.74% … threshold aniq aytdi: testlar emas, qamrov.
5. CI bilan farq — CI Linux'da, siz Windows'da: qator oxiri (ildiz fayllari), tirnoqlar, rm -rf kabi buyruqlar.

7. Ko'p uchraydigan xatolar

8. Mashqlar

1-mashq (oson): nanoid pasporti

nanoid'ni darsdagi commit'da oling (mashq yechimidagi buyruqlar bilan) va to'ldiring:

• Paket menejeri:
• engines.node:
• Lint vositasi:
• npm'ga chiqmaydigan fayllar ro'yxati qaysi faylda:

git init nanoid && cd nanoid
git remote add origin https://github.com/ai/nanoid.git
git fetch --depth 1 origin c0d01e30b0ecf1add4ae860937445924f078188e
git checkout FETCH_HEAD

2-mashq (o'rta): vazifalar — begona ko'z bilan

Tasavvur qiling: vazifalar ni birinchi marta ko'ryapsiz (qism oxiridagi v6 holati). Faqat ildiz fayllardan javob bering: paket menejeri, Node versiyasi, nechta skript, nechta sozlama fayli (*.config.*, tsconfig*, .*rc, .editorconfig, .gitattributes), CI'da qaysi buyruq tekshiradi.

3-mashq (o'rta): Windows tuzog'ini takrorlang

nanoid'da npx -y pnpm@12.10.1 install --frozen-lockfile, keyin npx -y pnpm@12.10.1 run test:coverage. Natija? Keyin exec bnt … ni qo'sh tirnoq bilan ishga tushiring. (macOS/Linux'da birinchi buyruq ham 100 % beradi — bu ham to'g'ri natija.)

4-mashq (qiyin): ko'rik dasturi

korish.mjs yozing: node korish.mjs <papka> — paket menejeri (lock-fayldan), Node (.nvmrc va engines), modul turi, skriptlar va sozlama fayllari ro'yxatini chiqarsin. vazifalar va nanoid'da sinang. Yordam: node:fs — Node'ning fayl moduli (vazifalar dagi skriptlar/qobiq.js ham uni ishlatadi): existsSync — fayl bormi, readdirSync — papkadagi nomlar, readFileSync — o'qish.

// korish.mjs — begona repoga birinchi nazar (16/46, 4-mashq)
// Ishlatish: node korish.mjs <repo-papkasi>
import { existsSync, readdirSync, readFileSync } from "node:fs";
import { join } from "node:path";

const dir = process.argv[2] ?? ".";
const has = (name) => existsSync(join(dir, name));
const read = (name) => readFileSync(join(dir, name), "utf8");
const pkg = JSON.parse(read("package.json"));

const locks = {
  "package-lock.json": "npm",
  "pnpm-lock.yaml": "pnpm",
  "yarn.lock": "Yarn",
  "bun.lock": "Bun",
};
const lock = Object.keys(locks).find(has);
console.log("Paket menejeri:", lock ? locks[lock] : "noma'lum");

const nvmrc = has(".nvmrc") ? read(".nvmrc").trim() : "yo'q";
const engines = pkg.engines?.node ?? "yo'q";
console.log("Node:", `.nvmrc — ${nvmrc}, engines — ${engines}`);
console.log("Modul:", pkg.type ?? "commonjs");
console.log("Skriptlar:", Object.keys(pkg.scripts ?? {}).join(", "));

// Sozlama fayllari: *.config.*, tsconfig*, .*rc, .editorconfig...
const CONFIG = [
  /\.config\./,
  /^tsconfig/,
  /^\.[\w-]*rc(\.\w+)?$/,
  /^\.(editorconfig|gitattributes)$/,
];
const configs = readdirSync(dir).filter((f) =>
  CONFIG.some((re) => re.test(f)),
);
const list = configs.join(", ");
console.log(`Sozlama fayllari (${configs.length}):`, list);

Paket menejeri: pnpm
Node: .nvmrc — yo'q, engines — ^22 || ^24 || >=26
Modul: module
Skriptlar: clean, start, test:coverage, test:lint, test:size, test:prebuild, test
Sozlama fayllari (4): .editorconfig, .prettierrc.js, oxfmt.config.ts, oxlint.config.ts

9. Real ishda

• Yangi ishdagi birinchi hafta shu tartib bilan boshlanadi; ko'p kompaniyalarda "onboarding" hujjati ham aynan shu savollarga javob beradi (Yangi kod bazaga kirish).
• Ochiq kodga birinchi PR — ko'pincha shunday topilmalar: Windows'da ishlamaydigan skript, eskirgan README qatori.
• Kod sharhi va audit — begona loyihani baholashda (Paket tanlash) ham shu ko'rik: CI bormi, testlar bormi, versiyalar qotirilganmi.
• Intervyu: "Notanish loyihani qanday o'rganasiz?" — tartibli javob (README → lock → scripts → config → CI → ishga tushirish) sizni ajratib turadi.

Xulosa

• Kodni emas, ildizni birinchi o'qing: README → lock-fayl → package.json → config fayllar → CI → ishga tushirish.
• Lock-fayl menejerni aytadi; boshqa menejer lock'ni e'tiborsiz qoldiradi (nanoid'da npm boshqa versiyalarni o'rnatdi).
• scripts — asboblar ro'yxati; config fayllar — qoidalar; CI — "haqiqat": qaysi Node, qaysi buyruq.
• Notanish fayl nomi har doim mazmunni aytmaydi (pnpm-workspace.yaml ichida xavfsizlik sozlamasi) — ochib o'qing.
• "Ishlamayapti" — bittadan ajrating, xabarni o'qing, CI bilan OS farqini tekshiring (nanoid'da Windows'dagi bitta tirnoq).

Keyingi dars: Begona kodni va kutubxona manba kodini o'qish — endi nanoid'ning kodini o'qiymiz: node_modules ichidan, .d.ts va testlardan; nanoid() 21 ta belgini qanday yasashini o'zimiz topamiz.

Manbalar

• nanoid reposi: github.com/ai/nanoid (commit c0d01e3, 2026-10-10)
• pnpm: pnpm install --frozen-lockfile, pnpm run — regex
• GitHub: Security hardening for GitHub Actions — pin actions to a full length commit SHA
• EditorConfig, Dev Containers