@nitra/ci-docs 0.0.2 → 1.0.1

package/CHANGELOG.md

@@ -4,9 +4,35 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
-## [0.0.2] - 2026-05-12
+## [1.0.1] - 2026-05-13
+
+### Changed
+
+- `writeGithubOutput()` тепер бере `GITHUB_OUTPUT` через `env` з `node:process` (вимога `n-js-run`).
+- JSDoc-описи для helper-функцій у тестах (`setupTmpDocs`, `setupBareDocs`, `startMockGraphql`) — повний набір `@param`/`@returns`.
+- `cli.mjs` рефакторено з `process.exit()` на `process.exitCode` (вимога `n-no-process-exit`).
+
+### Added
+
+- `tsconfig.emit-types.json` для генерації `.d.mts` без штучного `src/index.js` (Variant B з `n-npm-module`).
+- Локальні регулярки у тестах винесено в module-scope константи (вимога `e18e/prefer-static-regex`).
+
+## [1.0.0] - 2026-05-12
 
 ### Added
 
-- CLI `ci-docs` з subcommand `sync-schema` — синкає GraphQL-схему в споживацький `npm/`-пакет (bump + CHANGELOG + копіювання SDL).
-- Аргументи (тільки `--key value`, без env-vars): `--new-schema <path>` (обовʼязковий), `--docs <path>` (default `./docs`), `--schema-name <file>` (default `maya.graphql`), `--db-sha <sha>` (default `unknown`).
+- CLI `ci-docs sync-schema` — інтроспектить **будь-який** GraphQL-ендпоінт, рахує SemVer-bump через `graphql-inspector`, оновлює CHANGELOG і пише SDL у `npm/schema/`.
+  - `--endpoint <url>` (обовʼязковий) — GraphQL-ендпоінт.
+  - `--header "K: V"` (повторюваний) — будь-які HTTP-заголовки (Hasura admin secret, Bearer token тощо).
+  - `--docs <path>` (default `./docs`), `--schema-name <file>` (default `maya.graphql`), `--source-ref <text>` (default `unknown`).
+- CLI `ci-docs commit-push` — git add/commit/push для перелічених файлів.
+  - `--repo <path>`, `--message <msg>`, `--file <path>` (повторюваний), `--author-name`, `--author-email` — обовʼязкові.
+  - `--branch <name>` (default `main`), `--remote <name>` (default `origin`) — опціональні.
+  - Якщо staged-зміни відсутні, ні коміту, ні push не буде.
+
+### Changed
+
+- (BREAKING) Перейменовано CLI-аргументи `sync-schema`: `--hasura-url` → `--endpoint`, `--hasura-secret` → `--header`, `--db-sha` → `--source-ref`.
+- (BREAKING) Текст CHANGELOG, що генерується, більше не згадує Hasura: "Оновлено GraphQL-схему (`<ref>`)." та "Початкове додавання GraphQL-схеми.".
+- (BREAKING) `main()` та `formatChangelogBlock()` приймають `sourceRef` замість `dbSha`. `fetchSdl(endpoint, headers)` — headers як обʼєкт замість окремого `adminSecret`.
+- Видалено CLI-аргумент `--new-schema` зі `sync-schema` (живий ендпоінт — єдина точка входу).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/ci-docs",
-  "version": "0.0.2",
+  "version": "1.0.1",
   "description": "Nitra CI tooling: sync GraphQL schema to a docs npm package (and more to come).",
   "homepage": "https://github.com/nitra/ci-docs",
   "bugs": {
@@ -12,15 +12,18 @@
     "type": "git",
     "url": "git+https://github.com/nitra/ci-docs.git"
   },
+  "bin": {
+    "ci-docs": "./src/cli.mjs"
+  },
   "files": [
     "src",
     "types",
     "CHANGELOG.md"
   ],
   "type": "module",
-  "types": "./types/index.d.ts",
-  "bin": {
-    "ci-docs": "./src/cli.mjs"
+  "types": "./types/cli.d.mts",
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
     "@graphql-inspector/core": "^6.2.1",
@@ -29,11 +32,5 @@
   "engines": {
     "bun": ">=1.3",
     "node": ">=24"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "@nitra/cursor": "^1.9.4"
   }
 }

package/src/cli.mjs

@@ -5,11 +5,13 @@
  * Запуск: `npx -y @nitra/ci-docs <subcommand> [args...]`
  *
  * Доступні subcommands:
- *   sync-schema  — інтроспект Hasura → bump → CHANGELOG → копіювання SDL
+ *   sync-schema  — інтроспект GraphQL-ендпоінта → bump → CHANGELOG → запис SDL
+ *   commit-push  — git add/commit/push для оновлених файлів
  */
 
 const SUBCOMMANDS = {
-  'sync-schema': () => import('./sync-schema/main.mjs').then(m => m.cli)
+  'sync-schema': () => import('./sync-schema/main.mjs').then(m => m.cli),
+  'commit-push': () => import('./commit-push/main.mjs').then(m => m.cli)
 }
 
 const [subcommand, ...rest] = process.argv.slice(2)
@@ -21,15 +23,15 @@ Subcommands:
   ${Object.keys(SUBCOMMANDS).join('\n  ')}
 
 Run \`ci-docs <subcommand> --help\` for subcommand-specific options.`)
-  process.exit(subcommand ? 0 : 2)
+  process.exitCode = subcommand ? 0 : 2
+} else {
+  const loader = SUBCOMMANDS[subcommand]
+  if (loader) {
+    const run = await loader()
+    await run(rest)
+  } else {
+    console.error(`Unknown subcommand: ${subcommand}`)
+    console.error(`Available: ${Object.keys(SUBCOMMANDS).join(', ')}`)
+    process.exitCode = 2
+  }
 }
-
-const loader = SUBCOMMANDS[subcommand]
-if (!loader) {
-  console.error(`Unknown subcommand: ${subcommand}`)
-  console.error(`Available: ${Object.keys(SUBCOMMANDS).join(', ')}`)
-  process.exit(2)
-}
-
-const run = await loader()
-await run(rest)

package/src/commit-push/main.mjs

@@ -0,0 +1,100 @@
+import { execFileSync } from 'node:child_process'
+import { parseArgs } from 'node:util'
+
+/**
+ * Викликає `git` як зовнішній процес з фіксованим CWD.
+ * @param {string} cwd робоча директорія
+ * @param {string[]} args аргументи `git`
+ * @returns {string} stdout (UTF-8, без trailing newline)
+ */
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'inherit'], encoding: 'utf8' }).trimEnd()
+}
+
+/**
+ * Перевіряє чи є хоч якісь стейджовані зміни.
+ * @param {string} repo шлях до робочого дерева git-репо
+ * @returns {boolean} true якщо є staged-зміни (diff --cached не порожній)
+ */
+function hasStagedChanges(repo) {
+  try {
+    execFileSync('git', ['diff', '--cached', '--quiet'], { cwd: repo, stdio: 'ignore' })
+    return false
+  } catch {
+    return true
+  }
+}
+
+/**
+ * Стейджить файли, робить commit + push. Якщо файли не несуть змін — нічого не комітить і не пушить.
+ * @param {{repo: string, files: string[], message: string, authorName: string, authorEmail: string, branch?: string, remote?: string}} params параметри
+ * @returns {{committed: boolean, sha: string|null}} результат: чи був коміт і його SHA
+ */
+export function main({ repo, files, message, authorName, authorEmail, branch = 'main', remote = 'origin' }) {
+  if (!files.length) throw new Error('At least one --file is required')
+
+  git(repo, ['config', 'user.name', authorName])
+  git(repo, ['config', 'user.email', authorEmail])
+
+  git(repo, ['add', '--', ...files])
+
+  if (!hasStagedChanges(repo)) {
+    return { committed: false, sha: null }
+  }
+
+  git(repo, ['commit', '-m', message])
+  const sha = git(repo, ['rev-parse', 'HEAD'])
+  git(repo, ['push', remote, `HEAD:${branch}`])
+
+  return { committed: true, sha }
+}
+
+/**
+ * CLI-обгортка для commit-push. Параметри як `--key value`.
+ *
+ * Обовʼязкові:
+ *   --repo <path>           шлях до git-репо
+ *   --message <msg>         повідомлення коміту
+ *   --file <path>           повторюваний; шлях файлу від кореня репо (мінімум один)
+ *   --author-name <name>    Git user.name
+ *   --author-email <email>  Git user.email
+ *
+ * Необовʼязкові:
+ *   --branch <name>         цільова гілка (default 'main')
+ *   --remote <name>         remote (default 'origin')
+ * @param {string[]} [argv] аргументи. Default — process.argv.slice(2).
+ * @returns {{committed: boolean, sha: string|null}} результат main()
+ */
+export function cli(argv = process.argv.slice(2)) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      repo: { type: 'string' },
+      message: { type: 'string' },
+      file: { type: 'string', multiple: true, default: [] },
+      'author-name': { type: 'string' },
+      'author-email': { type: 'string' },
+      branch: { type: 'string', default: 'main' },
+      remote: { type: 'string', default: 'origin' }
+    },
+    allowPositionals: false,
+    strict: true
+  })
+
+  for (const key of ['repo', 'message', 'author-name', 'author-email']) {
+    if (!values[key]) throw new Error(`--${key} is required`)
+  }
+  if (values.file.length === 0) throw new Error('At least one --file is required')
+
+  const result = main({
+    repo: values.repo,
+    files: values.file,
+    message: values.message,
+    authorName: values['author-name'],
+    authorEmail: values['author-email'],
+    branch: values.branch,
+    remote: values.remote
+  })
+  console.log(JSON.stringify(result, null, 2))
+  return result
+}

package/src/sync-schema/main.mjs

@@ -1,5 +1,6 @@
 import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs'
 import { dirname } from 'node:path'
+import { env } from 'node:process'
 import { parseArgs } from 'node:util'
 import { buildSchema, buildClientSchema, printSchema, getIntrospectionQuery } from 'graphql'
 import { diff } from '@graphql-inspector/core'
@@ -49,17 +50,17 @@ export function classifyChanges(changes) {
 
 /**
  * Будує markdown-блок changelog для версії.
- * @param {{version: string, date: string, dbSha: string, sections: {added: string[], removed: string[], changed: string[]}, first?: boolean}} params параметри блоку
+ * @param {{version: string, date: string, sourceRef: string, sections: {added: string[], removed: string[], changed: string[]}, first?: boolean}} params параметри блоку
  * @returns {string} markdown-блок з трейлінговим порожнім рядком
  */
-export function formatChangelogBlock({ version, date, dbSha, sections, first = false }) {
+export function formatChangelogBlock({ version, date, sourceRef, sections, first = false }) {
   const lines = [`## [${version}] - ${date}`, '']
 
   const changed = [...sections.changed]
   if (first) {
-    changed.unshift('Початкове додавання GraphQL-схеми з Hasura.')
+    changed.unshift('Початкове додавання GraphQL-схеми.')
   } else {
-    changed.unshift(`Оновлено GraphQL-схему з Hasura (\`db@${dbSha}\`).`)
+    changed.unshift(`Оновлено GraphQL-схему (\`${sourceRef}\`).`)
   }
 
   if (sections.added.length > 0) {
@@ -178,25 +179,22 @@ export function bumpVersion(npmDir, kind) {
  * @returns {void}
  */
 export function writeGithubOutput(values) {
-  const outPath = process.env.GITHUB_OUTPUT
+  const outPath = env.GITHUB_OUTPUT
   if (!outPath) return
   const lines = Object.entries(values).map(([k, v]) => `${k}=${v}`)
   appendFileSync(outPath, lines.join('\n') + '\n')
 }
 
 /**
- * Шле introspection-запит до Hasura і повертає SDL-рядок.
- * @param {string} hasuraUrl URL ендпоінта GraphQL
- * @param {string} [adminSecret] значення `X-Hasura-Admin-Secret` (опціонально для публічних ендпоінтів)
+ * Шле introspection-запит до GraphQL-ендпоінта і повертає SDL-рядок.
+ * @param {string} endpoint URL GraphQL-ендпоінта
+ * @param {Record<string, string>} [headers] додаткові HTTP-заголовки (наприклад `{ 'X-Hasura-Admin-Secret': '...' }`)
  * @returns {Promise<string>} SDL-схема у вигляді рядка
  */
-export async function fetchSdl(hasuraUrl, adminSecret) {
-  const res = await fetch(hasuraUrl, {
+export async function fetchSdl(endpoint, headers = {}) {
+  const res = await fetch(endpoint, {
     method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      ...(adminSecret ? { 'X-Hasura-Admin-Secret': adminSecret } : {})
-    },
+    headers: { 'Content-Type': 'application/json', ...headers },
     body: JSON.stringify({ query: getIntrospectionQuery() })
   })
   if (!res.ok) throw new Error(`Introspection failed: ${res.status} ${res.statusText}`)
@@ -205,12 +203,23 @@ export async function fetchSdl(hasuraUrl, adminSecret) {
   return printSchema(buildClientSchema(data))
 }
 
+/**
+ * Парсить рядок `Key: Value` у пару `[key, value]`. Помилка, якщо нема `:`.
+ * @param {string} raw сирий header
+ * @returns {[string, string]} key, value (обрізані з обох боків)
+ */
+export function parseHeader(raw) {
+  const idx = raw.indexOf(':')
+  if (idx === -1) throw new Error(`Invalid --header value (expected "Key: Value"): ${raw}`)
+  return [raw.slice(0, idx).trim(), raw.slice(idx + 1).trim()]
+}
+
 /**
  * Оркеструє весь flow: diff схем → bump → CHANGELOG → запис SDL.
- * @param {{newSdl: string, docsRoot: string, dbSha: string, date: string, schemaFilename?: string}} params параметри запуску
+ * @param {{newSdl: string, docsRoot: string, sourceRef: string, date: string, schemaFilename?: string}} params параметри запуску
  * @returns {Promise<{changed: boolean, bump: 'minor'|'patch'|null, version: string|null}>} результат
  */
-export async function main({ newSdl, docsRoot, dbSha, date, schemaFilename = 'maya.graphql' }) {
+export async function main({ newSdl, docsRoot, sourceRef, date, schemaFilename = 'maya.graphql' }) {
   const oldSchemaPath = `${docsRoot}/npm/schema/${schemaFilename}`
   const oldSdl = readSdl(oldSchemaPath)
 
@@ -226,7 +235,7 @@ export async function main({ newSdl, docsRoot, dbSha, date, schemaFilename = 'ma
   const npmDir = `${docsRoot}/npm`
   const version = bumpVersion(npmDir, bump)
 
-  const block = formatChangelogBlock({ version, date, dbSha: dbSha.slice(0, 7), sections, first })
+  const block = formatChangelogBlock({ version, date, sourceRef, sections, first })
   const changelogPath = `${npmDir}/CHANGELOG.md`
   const existingChangelog = readFileSync(changelogPath, 'utf8')
   writeFileSync(changelogPath, prependChangelog(existingChangelog, block))
@@ -241,14 +250,14 @@ export async function main({ newSdl, docsRoot, dbSha, date, schemaFilename = 'ma
  * CLI-обгортка для sync-schema. Приймає параметри як `--key value`.
  *
  * Обовʼязковий:
- *   --hasura-url <url>      URL GraphQL-ендпоінта (введроспект)
+ *   --endpoint <url>        URL GraphQL-ендпоінта для introspection
  *
  * Необовʼязкові:
- *   --hasura-secret <s>     значення `X-Hasura-Admin-Secret`
+ *   --header "K: V"         HTTP-заголовок (повторюваний; наприклад: `--header "X-Hasura-Admin-Secret: ..."`,
+ *                           `--header "Authorization: Bearer ..."`)
  *   --docs <path>           корінь docs-репо (default './docs')
  *   --schema-name <file>    назва файлу в `npm/schema/` (default 'maya.graphql')
- *   --db-sha <sha>          SHA коміту db (default 'unknown')
- *
+ *   --source-ref <ref>      текст, що йде у CHANGELOG як посилання на джерело (default 'unknown')
  * @param {string[]} [argv] аргументи (без 'node' та script path). Default — process.argv.slice(2).
  * @returns {Promise<{changed: boolean, bump: string|null, version: string|null}>} результат main()
  */
@@ -256,27 +265,28 @@ export async function cli(argv = process.argv.slice(2)) {
   const { values } = parseArgs({
     args: argv,
     options: {
-      'hasura-url': { type: 'string' },
-      'hasura-secret': { type: 'string' },
+      endpoint: { type: 'string' },
+      header: { type: 'string', multiple: true, default: [] },
       docs: { type: 'string', default: './docs' },
       'schema-name': { type: 'string', default: 'maya.graphql' },
-      'db-sha': { type: 'string', default: 'unknown' }
+      'source-ref': { type: 'string', default: 'unknown' }
     },
     allowPositionals: false,
     strict: true
   })
 
-  const hasuraUrl = values['hasura-url']
-  if (!hasuraUrl) {
-    throw new Error('--hasura-url is required')
+  const endpoint = values.endpoint
+  if (!endpoint) {
+    throw new Error('--endpoint is required')
   }
 
-  const newSdl = await fetchSdl(hasuraUrl, values['hasura-secret'])
+  const headers = Object.fromEntries(values.header.map(h => parseHeader(h)))
+  const newSdl = await fetchSdl(endpoint, headers)
 
   const result = await main({
     newSdl,
     docsRoot: values.docs,
-    dbSha: values['db-sha'],
+    sourceRef: values['source-ref'],
     date: new Date().toISOString().slice(0, 10),
     schemaFilename: values['schema-name']
   })

package/types/cli.d.mts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {}

package/types/commit-push/main.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Стейджить файли, робить commit + push. Якщо файли не несуть змін — нічого не комітить і не пушить.
+ * @param {{repo: string, files: string[], message: string, authorName: string, authorEmail: string, branch?: string, remote?: string}} params параметри
+ * @returns {{committed: boolean, sha: string|null}} результат: чи був коміт і його SHA
+ */
+export function main({
+  repo,
+  files,
+  message,
+  authorName,
+  authorEmail,
+  branch,
+  remote
+}: {
+  repo: string
+  files: string[]
+  message: string
+  authorName: string
+  authorEmail: string
+  branch?: string
+  remote?: string
+}): {
+  committed: boolean
+  sha: string | null
+}
+/**
+ * CLI-обгортка для commit-push. Параметри як `--key value`.
+ *
+ * Обовʼязкові:
+ *   --repo <path>           шлях до git-репо
+ *   --message <msg>         повідомлення коміту
+ *   --file <path>           повторюваний; шлях файлу від кореня репо (мінімум один)
+ *   --author-name <name>    Git user.name
+ *   --author-email <email>  Git user.email
+ *
+ * Необовʼязкові:
+ *   --branch <name>         цільова гілка (default 'main')
+ *   --remote <name>         remote (default 'origin')
+ * @param {string[]} [argv] аргументи. Default — process.argv.slice(2).
+ * @returns {{committed: boolean, sha: string|null}} результат main()
+ */
+export function cli(argv?: string[]): {
+  committed: boolean
+  sha: string | null
+}

package/types/sync-schema/main.d.mts

@@ -0,0 +1,142 @@
+/**
+ * Класифікує зміни схеми у секції changelog та визначає тип bump.
+ * @param {Array<{type?: string, message: string, criticality?: {level: string}}>} changes масив змін від graphql-inspector
+ * @returns {{bump: 'minor'|'patch'|null, sections: {added: string[], removed: string[], changed: string[]}}} тип bump та секції changelog
+ */
+export function classifyChanges(
+  changes: Array<{
+    type?: string
+    message: string
+    criticality?: {
+      level: string
+    }
+  }>
+): {
+  bump: 'minor' | 'patch' | null
+  sections: {
+    added: string[]
+    removed: string[]
+    changed: string[]
+  }
+}
+/**
+ * Будує markdown-блок changelog для версії.
+ * @param {{version: string, date: string, sourceRef: string, sections: {added: string[], removed: string[], changed: string[]}, first?: boolean}} params параметри блоку
+ * @returns {string} markdown-блок з трейлінговим порожнім рядком
+ */
+export function formatChangelogBlock({
+  version,
+  date,
+  sourceRef,
+  sections,
+  first
+}: {
+  version: string
+  date: string
+  sourceRef: string
+  sections: {
+    added: string[]
+    removed: string[]
+    changed: string[]
+  }
+  first?: boolean
+}): string
+/**
+ * Вставляє новий блок changelog перед першим існуючим записом (або після хедера, якщо записів нема).
+ * @param {string} existing вміст CHANGELOG.md
+ * @param {string} newBlock новий блок версії
+ * @returns {string} оновлений вміст
+ */
+export function prependChangelog(existing: string, newBlock: string): string
+/**
+ * Запускає graphql-inspector diff між двома SDL.
+ * @param {string} oldSdl стара GraphQL-схема (SDL)
+ * @param {string} newSdl нова GraphQL-схема (SDL)
+ * @returns {Promise<Array<{type: string, message: string, criticality: {level: string}}>>} список змін
+ */
+export function runInspector(
+  oldSdl: string,
+  newSdl: string
+): Promise<
+  Array<{
+    type: string
+    message: string
+    criticality: {
+      level: string
+    }
+  }>
+>
+/**
+ * Читає SDL з файлу або повертає null, якщо файл відсутній/порожній.
+ * @param {string} path шлях до SDL
+ * @returns {string|null} вміст або null
+ */
+export function readSdl(path: string): string | null
+/**
+ * Підіймає версію у package.json напряму (без виклику зовнішнього `npm`).
+ * @param {string} npmDir шлях до директорії пакета
+ * @param {'major'|'minor'|'patch'} kind тип bump
+ * @returns {string} нова версія
+ */
+export function bumpVersion(npmDir: string, kind: 'major' | 'minor' | 'patch'): string
+/**
+ * Пише пари key=value у файл, на який вказує `GITHUB_OUTPUT`.
+ * @param {Record<string, string>} values пари для запису
+ * @returns {void}
+ */
+export function writeGithubOutput(values: Record<string, string>): void
+/**
+ * Шле introspection-запит до GraphQL-ендпоінта і повертає SDL-рядок.
+ * @param {string} endpoint URL GraphQL-ендпоінта
+ * @param {Record<string, string>} [headers] додаткові HTTP-заголовки (наприклад `{ 'X-Hasura-Admin-Secret': '...' }`)
+ * @returns {Promise<string>} SDL-схема у вигляді рядка
+ */
+export function fetchSdl(endpoint: string, headers?: Record<string, string>): Promise<string>
+/**
+ * Парсить рядок `Key: Value` у пару `[key, value]`. Помилка, якщо нема `:`.
+ * @param {string} raw сирий header
+ * @returns {[string, string]} key, value (обрізані з обох боків)
+ */
+export function parseHeader(raw: string): [string, string]
+/**
+ * Оркеструє весь flow: diff схем → bump → CHANGELOG → запис SDL.
+ * @param {{newSdl: string, docsRoot: string, sourceRef: string, date: string, schemaFilename?: string}} params параметри запуску
+ * @returns {Promise<{changed: boolean, bump: 'minor'|'patch'|null, version: string|null}>} результат
+ */
+export function main({
+  newSdl,
+  docsRoot,
+  sourceRef,
+  date,
+  schemaFilename
+}: {
+  newSdl: string
+  docsRoot: string
+  sourceRef: string
+  date: string
+  schemaFilename?: string
+}): Promise<{
+  changed: boolean
+  bump: 'minor' | 'patch' | null
+  version: string | null
+}>
+/**
+ * CLI-обгортка для sync-schema. Приймає параметри як `--key value`.
+ *
+ * Обовʼязковий:
+ *   --endpoint <url>        URL GraphQL-ендпоінта для introspection
+ *
+ * Необовʼязкові:
+ *   --header "K: V"         HTTP-заголовок (повторюваний; наприклад: `--header "X-Hasura-Admin-Secret: ..."`,
+ *                           `--header "Authorization: Bearer ..."`)
+ *   --docs <path>           корінь docs-репо (default './docs')
+ *   --schema-name <file>    назва файлу в `npm/schema/` (default 'maya.graphql')
+ *   --source-ref <ref>      текст, що йде у CHANGELOG як посилання на джерело (default 'unknown')
+ * @param {string[]} [argv] аргументи (без 'node' та script path). Default — process.argv.slice(2).
+ * @returns {Promise<{changed: boolean, bump: string|null, version: string|null}>} результат main()
+ */
+export function cli(argv?: string[]): Promise<{
+  changed: boolean
+  bump: string | null
+  version: string | null
+}>

package/src/sync-schema/__fixtures__/new-schema.graphql

@@ -1,10 +0,0 @@
-type Query {
-  hello: String
-  newField: Int
-}
-
-type User {
-  id: ID!
-  name: String
-  email: String
-}

package/src/sync-schema/__fixtures__/old-schema.graphql

@@ -1,9 +0,0 @@
-type Query {
-  hello: String
-  deprecated_field: Int
-}
-
-type User {
-  id: ID!
-  name: String
-}

package/src/sync-schema/main.test.mjs

@@ -1,280 +0,0 @@
-import { describe, it, expect, afterEach } from 'bun:test'
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { buildSchema, graphqlSync } from 'graphql'
-import { classifyChanges, cli, formatChangelogBlock, main, prependChangelog, runInspector } from './main.mjs'
-
-const HEADER = `# Changelog\n\nУсі помітні зміни цього пакета документуються тут.\n\nФормат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).\n\n`
-const OLD_SDL = readFileSync(join(import.meta.dir, '__fixtures__/old-schema.graphql'), 'utf8')
-const NEW_SDL = readFileSync(join(import.meta.dir, '__fixtures__/new-schema.graphql'), 'utf8')
-
-describe('classifyChanges', () => {
-  it('повертає bump=null коли немає змін', () => {
-    expect(classifyChanges([])).toEqual({ bump: null, sections: { added: [], removed: [], changed: [] } })
-  })
-
-  it('повертає bump=patch для NON_BREAKING додавань', () => {
-    const result = classifyChanges([
-      { type: 'FIELD_ADDED', criticality: { level: 'NON_BREAKING' }, message: "Field 'foo' was added to type 'Bar'" }
-    ])
-    expect(result.bump).toBe('patch')
-    expect(result.sections.added).toEqual(["Field 'foo' was added to type 'Bar'"])
-  })
-
-  it('повертає bump=minor для будь-якого BREAKING', () => {
-    const result = classifyChanges([
-      { type: 'FIELD_REMOVED', criticality: { level: 'BREAKING' }, message: "Field 'old' was removed from type 'User'" },
-      { type: 'FIELD_ADDED', criticality: { level: 'NON_BREAKING' }, message: "Field 'new' was added to type 'User'" }
-    ])
-    expect(result.bump).toBe('minor')
-    expect(result.sections.removed).toEqual(["Field 'old' was removed from type 'User'"])
-    expect(result.sections.added).toEqual(["Field 'new' was added to type 'User'"])
-  })
-
-  it('повертає bump=patch для DANGEROUS', () => {
-    const result = classifyChanges([
-      { type: 'FIELD_ARGUMENT_DEFAULT_CHANGED', criticality: { level: 'DANGEROUS' }, message: "Default for arg 'limit' changed" }
-    ])
-    expect(result.bump).toBe('patch')
-    expect(result.sections.changed).toEqual(["Default for arg 'limit' changed"])
-  })
-
-  it('класифікує BREAKING модифікації у `changed`', () => {
-    const result = classifyChanges([
-      { type: 'TYPE_KIND_CHANGED', criticality: { level: 'BREAKING' }, message: "Type 'Foo' changed kind" }
-    ])
-    expect(result.sections.changed).toEqual(["Type 'Foo' changed kind"])
-    expect(result.sections.removed).toEqual([])
-  })
-})
-
-describe('formatChangelogBlock', () => {
-  const baseInput = { version: '0.1.0', date: '2026-05-11', dbSha: 'a1b2c3d', sections: { added: [], removed: [], changed: [] } }
-
-  it('завжди містить "Changed" з посиланням на db-SHA', () => {
-    const out = formatChangelogBlock(baseInput)
-    expect(out).toContain('## [0.1.0] - 2026-05-11')
-    expect(out).toContain('### Changed')
-    expect(out).toContain('Оновлено GraphQL-схему з Hasura (`db@a1b2c3d`)')
-  })
-
-  it('додає секцію Removed для breaking-видалень', () => {
-    const out = formatChangelogBlock({ ...baseInput, sections: { added: [], removed: ["Field 'old' removed"], changed: [] } })
-    expect(out).toContain('### Removed')
-    expect(out).toContain("- Field 'old' removed")
-  })
-
-  it('додає секцію Added для non-breaking додавань', () => {
-    const out = formatChangelogBlock({ ...baseInput, sections: { added: ["Field 'new' added"], removed: [], changed: [] } })
-    expect(out).toContain('### Added')
-    expect(out).toContain("- Field 'new' added")
-  })
-
-  it('не друкує порожні секції', () => {
-    const out = formatChangelogBlock(baseInput)
-    expect(out).not.toContain('### Added')
-    expect(out).not.toContain('### Removed')
-  })
-
-  it('first-run шаблон, коли first=true', () => {
-    const out = formatChangelogBlock({ ...baseInput, first: true })
-    expect(out).toContain('Початкове додавання GraphQL-схеми')
-    expect(out).not.toContain('Оновлено GraphQL-схему')
-  })
-
-  it('закінчується одним порожнім рядком (для коректного prepend)', () => {
-    const out = formatChangelogBlock(baseInput)
-    expect(out.endsWith('\n\n')).toBe(true)
-  })
-})
-
-describe('runInspector', () => {
-  it('повертає порожній масив для ідентичних схем', async () => {
-    const sdl = `type Query { hello: String }`
-    const changes = await runInspector(sdl, sdl)
-    expect(changes).toEqual([])
-  })
-
-  it('детектить BREAKING при видаленні поля', async () => {
-    const oldSdl = `type Query { hello: String, bye: String }`
-    const newSdl = `type Query { hello: String }`
-    const changes = await runInspector(oldSdl, newSdl)
-    const breaking = changes.find(c => c.criticality.level === 'BREAKING')
-    expect(breaking).toBeDefined()
-    expect(breaking.type).toBe('FIELD_REMOVED')
-  })
-
-  it('детектить NON_BREAKING при додаванні поля', async () => {
-    const oldSdl = `type Query { hello: String }`
-    const newSdl = `type Query { hello: String, newField: Int }`
-    const changes = await runInspector(oldSdl, newSdl)
-    const nb = changes.find(c => c.type === 'FIELD_ADDED')
-    expect(nb).toBeDefined()
-    expect(nb.criticality.level).toBe('NON_BREAKING')
-  })
-})
-
-describe('prependChangelog', () => {
-  it('вставляє новий блок між хедером і першим існуючим записом', () => {
-    const existing = HEADER + '## [0.0.2] - 2026-05-11\n\n### Added\n\n- щось.\n'
-    const block = '## [0.0.3] - 2026-05-12\n\n### Changed\n\n- нове.\n\n'
-    const out = prependChangelog(existing, block)
-    expect(out.indexOf('## [0.0.3]')).toBeLessThan(out.indexOf('## [0.0.2]'))
-    expect(out.startsWith('# Changelog')).toBe(true)
-  })
-
-  it('додає блок після хедера, якщо записів ще нема', () => {
-    const block = '## [0.0.1] - 2026-05-11\n\n### Added\n\n- перший запис.\n\n'
-    const out = prependChangelog(HEADER, block)
-    expect(out).toBe(HEADER + block)
-  })
-})
-
-describe('main (e2e via fixtures)', () => {
-  let tmp
-
-  function setupTmpDocs({ withOldSchema = true, schemaFilename = 'maya.graphql' } = {}) {
-    tmp = mkdtempSync(join(tmpdir(), 'sync-schema-'))
-    const npmDir = join(tmp, 'npm')
-    mkdirSync(npmDir, { recursive: true })
-    writeFileSync(join(npmDir, 'package.json'), JSON.stringify({ name: '@nitra/efes-docs', version: '0.0.2' }, null, 2))
-    writeFileSync(join(npmDir, 'CHANGELOG.md'), HEADER + '## [0.0.2] - 2026-05-10\n\n### Added\n\n- Базовий каркас.\n')
-    if (withOldSchema) {
-      mkdirSync(join(npmDir, 'schema'), { recursive: true })
-      writeFileSync(join(npmDir, 'schema', schemaFilename), OLD_SDL)
-    }
-    return { docsRoot: tmp, npmDir }
-  }
-
-  afterEach(() => {
-    if (tmp && existsSync(tmp)) rmSync(tmp, { recursive: true, force: true })
-  })
-
-  it('NON_BREAKING зміна → bump patch, CHANGELOG.Added', async () => {
-    const { docsRoot, npmDir } = setupTmpDocs()
-    const result = await main({ newSdl: NEW_SDL, docsRoot, dbSha: 'abc1234567', date: '2026-05-11' })
-    console.log(JSON.stringify(result, null, 2))
-
-    expect(result.changed).toBe(true)
-    expect(result.version).toBe('0.0.3')
-
-    const changelog = readFileSync(join(npmDir, 'CHANGELOG.md'), 'utf8')
-    expect(changelog).toContain('## [0.0.3] - 2026-05-11')
-    expect(changelog.indexOf('## [0.0.3]')).toBeLessThan(changelog.indexOf('## [0.0.2]'))
-
-    const schema = readFileSync(join(npmDir, 'schema/maya.graphql'), 'utf8')
-    expect(schema).toBe(NEW_SDL)
-  })
-
-  it('однакові схеми → changed=false, нічого не записує', async () => {
-    const { docsRoot, npmDir } = setupTmpDocs()
-    const result = await main({ newSdl: OLD_SDL, docsRoot, dbSha: 'abc1234567', date: '2026-05-11' })
-    console.log(JSON.stringify(result, null, 2))
-
-    expect(result.changed).toBe(false)
-    expect(result.bump).toBeNull()
-
-    const pkg = JSON.parse(readFileSync(join(npmDir, 'package.json'), 'utf8'))
-    expect(pkg.version).toBe('0.0.2')
-  })
-
-  it('first-run (нема старої схеми) → bump patch, CHANGELOG з "Початкове додавання"', async () => {
-    const { docsRoot, npmDir } = setupTmpDocs({ withOldSchema: false })
-    const result = await main({ newSdl: NEW_SDL, docsRoot, dbSha: 'abc1234567', date: '2026-05-11' })
-    console.log(JSON.stringify(result, null, 2))
-
-    expect(result.changed).toBe(true)
-    expect(result.bump).toBe('patch')
-    expect(result.version).toBe('0.0.3')
-
-    const changelog = readFileSync(join(npmDir, 'CHANGELOG.md'), 'utf8')
-    expect(changelog).toContain('Початкове додавання GraphQL-схеми')
-    expect(existsSync(join(npmDir, 'schema/maya.graphql'))).toBe(true)
-  })
-
-  it('кастомний schemaFilename (smart.graphql) — записує саме його', async () => {
-    const { docsRoot, npmDir } = setupTmpDocs({ schemaFilename: 'smart.graphql' })
-    const result = await main({ newSdl: NEW_SDL, docsRoot, dbSha: 'abc1234567', date: '2026-05-11', schemaFilename: 'smart.graphql' })
-
-    expect(result.changed).toBe(true)
-    expect(existsSync(join(npmDir, 'schema/smart.graphql'))).toBe(true)
-    expect(existsSync(join(npmDir, 'schema/maya.graphql'))).toBe(false)
-  })
-})
-
-describe('cli (тільки args)', () => {
-  let tmp
-  let server
-  let receivedHeaders
-
-  function setupBareDocs() {
-    tmp = mkdtempSync(join(tmpdir(), 'sync-schema-cli-'))
-    const npmDir = join(tmp, 'npm')
-    mkdirSync(npmDir, { recursive: true })
-    writeFileSync(join(npmDir, 'package.json'), JSON.stringify({ name: '@nitra/x-docs', version: '0.0.2' }, null, 2))
-    writeFileSync(join(npmDir, 'CHANGELOG.md'), HEADER + '## [0.0.2] - 2026-05-10\n\n### Added\n\n- щось.\n')
-    return tmp
-  }
-
-  function startMockHasura(sdl) {
-    const schema = buildSchema(sdl)
-    server = Bun.serve({
-      port: 0,
-      async fetch(req) {
-        receivedHeaders = req.headers
-        const { query } = await req.json()
-        const result = graphqlSync({ schema, source: query })
-        return Response.json(result)
-      }
-    })
-    return `http://localhost:${server.port}/v1/graphql`
-  }
-
-  afterEach(() => {
-    if (server) {
-      server.stop()
-      server = undefined
-    }
-    receivedHeaders = undefined
-    if (tmp && existsSync(tmp)) rmSync(tmp, { recursive: true, force: true })
-  })
-
-  it('інтроспектить Hasura через --hasura-url і синкає схему', async () => {
-    const docsRoot = setupBareDocs()
-    const url = startMockHasura(NEW_SDL)
-    const result = await cli(['--hasura-url', url, '--docs', docsRoot, '--schema-name', 'test.graphql', '--db-sha', 'abcdef1234'])
-
-    expect(result.changed).toBe(true)
-    expect(result.bump).toBe('patch')
-    expect(existsSync(join(docsRoot, 'npm', 'schema', 'test.graphql'))).toBe(true)
-  })
-
-  it('передає --hasura-secret як X-Hasura-Admin-Secret заголовок', async () => {
-    const docsRoot = setupBareDocs()
-    const url = startMockHasura(NEW_SDL)
-    await cli(['--hasura-url', url, '--hasura-secret', 'super-secret', '--docs', docsRoot])
-
-    expect(receivedHeaders.get('x-hasura-admin-secret')).toBe('super-secret')
-  })
-
-  it('без --hasura-secret заголовок не надсилається', async () => {
-    const docsRoot = setupBareDocs()
-    const url = startMockHasura(NEW_SDL)
-    await cli(['--hasura-url', url, '--docs', docsRoot])
-
-    expect(receivedHeaders.get('x-hasura-admin-secret')).toBeNull()
-  })
-
-  it('схема за замовчуванням — maya.graphql', async () => {
-    const docsRoot = setupBareDocs()
-    const url = startMockHasura(NEW_SDL)
-    await cli(['--hasura-url', url, '--docs', docsRoot])
-
-    expect(existsSync(join(docsRoot, 'npm', 'schema', 'maya.graphql'))).toBe(true)
-  })
-
-  it('викидає якщо не передано --hasura-url', () => {
-    expect(cli(['--docs', '/tmp/nowhere'])).rejects.toThrow('--hasura-url is required')
-  })
-})

package/types/index.d.ts

@@ -1 +0,0 @@
-export {}