@mirta/package 0.0.1 → 0.4.0

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -1,45 +1,181 @@
-# @mirta/package
+# `@mirta/package`
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+[![en](https://img.shields.io/badge/lang-en-olivedrab.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-package/README.md)
+[![ru](https://img.shields.io/badge/lang-ru-dimgray.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-package/README.ru.md)
+[![NPM Version](https://img.shields.io/npm/v/@mirta/package?style=flat-square)](https://npmjs.com/package/@mirta/package)
+[![NPM Downloads](https://img.shields.io/npm/dm/@mirta/package?style=flat-square&logo=npm)](https://npmjs.com/package/@mirta/package)
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+> A simple and reliable way to read `package.json` in Mirta tools.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+`@mirta/package` is a utility for safely reading `package.json` in the development environment. It supports:
+- TypeScript typing
+- Clear error handling
+- Reading only required fields: `name`, `exports`, `workspaces`
+- Synchronous and asynchronous APIs
 
-## Purpose
+Used internally by `@mirta/workspace`, `@mirta/rollup`, and other Mirta tools for project structure analysis.<br/>
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@mirta/package`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+**Not intended for execution in the Duktape environment on Wiren Board controllers.**
 
-## What is OIDC Trusted Publishing?
+## 📦 Installation
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+```bash
+# Not required directly — used internally by Mirta
+pnpm add -D @mirta/package
+```
+⚠️ This package is part of Mirta's internal infrastructure. It is typically not used directly.
 
-## Setup Instructions
+## 🚀 Quick Start
 
-To properly configure OIDC trusted publishing for this package:
+```ts
+import { readPackage, readPackageAsync, PackageError } from '@mirta/package'
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+// Synchronous reading
 
-## DO NOT USE THIS PACKAGE
+try {
+  const pkg = readPackage('packages/mirta-testing')
+  console.log(pkg.name)
+} catch (err) {
+  if (err instanceof PackageError)
+    console.error('Error:', err.message)
+}
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+// Asynchronous reading
 
-## More Information
+try {
+  const pkg = await readPackageAsync('packages/mirta-testing')
+  console.log(pkg.name)
+} catch (err) {
+  if (err instanceof PackageError)
+    console.error('Error:', err.message)
+}
+```
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+## 🧰 API
+
+`readPackage(path: string): Package`
+
+Synchronously reads and parses `package.json` from the given path.
+
+Supports:
+- Path to file: `'package.json'`, `'packages/mirta-testing/package.json'`
+- Path to package directory: `'.'`, `'packages/mirta-testing'`
+
+Returns: an object of type `Package`.<br/>
+Throws: `PackageError` with one of the error codes listed in the "[Possible error codes](#possible-error-codes)" section.
+
+---
+
+`readPackageAsync(path: string): Promise<Package>`
+
+Asynchronously reads and parses `package.json` from the specified path.
+
+Fully equivalent to `readPackage`, but works asynchronously. Recommended for use in async contexts (e.g. bundler plugins).
+
+Returns: a Promise resolving to a `Package` object.<br/>
+Throws: `PackageError` with one of the error codes listed in the "[Possible error codes](#possible-error-codes)" section.
 
 ---
 
-**Maintained for OIDC setup purposes only**
+`parsePackageJson(content: string): Package`
+
+Parses a string containing `package.json` content into a `Package` object.
+
+Use if the file content is already loaded (e.g. from cache or test).
+
+---
+
+`PackageError`
+
+Error class with clear messages and codes. Helps quickly identify what went wrong.
+
+<a name="#possible-error-codes"></a>
+Possible error codes:
+- `notFound`: the package.json file was not found,
+- `accessDenied`: permission denied to read the file,
+- `invalidPath`: the path does not point to a package.json file or package directory,
+- `invalidJson`: the file contains invalid or malformed JSON,
+- `invalidJsonRoot`: the JSON root is not an object,
+- `failedToRead`: failed to read the file.
+
+Example usage:
+
+```ts
+if (err.code === 'notFound') {
+  console.error('File not found:', err.message)
+}
+```
+## 🧩 Supported Fields
+
+The package reads only the `package.json` fields required by the framework:
+
+`name`
+
+Package name, e.g.: `"@mirta/testing"`
+
+`exports`
+
+Simplified format with import is supported:
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs"
+    },
+    "./setup-global": "./dist/setup/global.mjs"
+  }
+}
+```
+Or with types:
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  }
+}
+```
+Ignored: `require`, `node`, `browser`, and other conditions.
+
+`workspaces`
+
+Only array of strings is allowed: `["packages/*"]`</br>
+Object format (`{ packages: [...] }`) is not supported.
+
+## ✅ Testing
+
+The package is fully tested:
+
+- Successful `package.json` reading
+- Handling all error types: file not found, no access, invalid JSON
+- Support for various paths
+- Correct error mapping to `PackageError`
+
+Uses Vitest, dependency mocks, and isolated tests.
+
+⚠️ Limitations
+
+- Works only in Node.js (not in Duktape).
+- Supports only `import` in `exports`.
+- The `workspaces` field must be an array of strings.
+- Use `readPackageAsync` in asynchronous environments.
+- Synchronous operations are not recommended in async contexts (use `readPackageAsync`).
+
+## 🔄 Usage in `@mirta/workspace`
+
+This package is used in `@mirta/workspace` to:
+- Read `package.json` of the root project and individual packages.
+- Validate the `workspaces` field.
+- Collect metadata from every package in the monorepo.
+
+Example:
+```ts
+const pkg = await readPackageAsync(`${rootDir}/packages/mirta-testing/package.json`)
+```
+Ensures a consistent and reliable way to access package metadata.

package/README.ru.md

@@ -0,0 +1,180 @@
+# `@mirta/package`
+
+[![en](https://img.shields.io/badge/lang-en-dimgray.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-package/README.md)
+[![ru](https://img.shields.io/badge/lang-ru-olivedrab.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-package/README.ru.md)
+[![NPM Version](https://img.shields.io/npm/v/@mirta/package?style=flat-square)](https://npmjs.com/package/@mirta/package)
+[![NPM Downloads](https://img.shields.io/npm/dm/@mirta/package?style=flat-square&logo=npm)](https://npmjs.com/package/@mirta/package)
+
+> Простой и надёжный способ чтения `package.json` в инструментах Mirta.
+
+`@mirta/package` — это утилита для безопасного чтения `package.json` в среде разработки. Она поддерживает:
+- TypeScript-типизацию
+- Чёткую обработку ошибок
+- Работу только с нужными полями: `name`, `exports`, `workspaces`
+- Синхронный и асинхронный API
+
+Используется внутри `@mirta/workspace`, `@mirta/rollup` и других инструментов Mirta для анализа структуры проекта.<br/>
+
+**Не предназначен для выполнения в среде Duktape на контроллерах Wiren Board.**
+
+## 📦 Установка
+
+```bash
+# Не требуется напрямую — используется внутри Mirta
+pnpm add -D @mirta/package
+```
+⚠️ Этот пакет — часть внутренней инфраструктуры фреймворка Mirta. Обычно он не используется напрямую.
+
+## 🚀 Быстрый старт
+
+```ts
+import { readPackage, readPackageAsync, PackageError } from '@mirta/package'
+
+// Синхронное чтение
+
+try {
+  const pkg = readPackage('packages/mirta-basics')
+  console.log(pkg.name)
+} catch (err) {
+  if (err instanceof PackageError)
+    console.error('Ошибка:', err.message)
+}
+
+// Асинхронное чтение
+
+try {
+  const pkg = await readPackageAsync('packages/mirta-basics')
+  console.log(pkg.name)
+} catch (err) {
+  if (err instanceof PackageError)
+    console.error('Ошибка:', err.message)
+}
+```
+
+## 🧰 API
+
+`readPackage(path: string): Package`
+
+Синхронно читает и парсит `package.json` по указанному пути.
+
+Поддерживает:
+- Путь к файлу: `'package.json'`, `'packages/core/package.json'`
+- Путь к директории пакета: `'.'`, `'packages/core'`
+
+Возвращает: объект типа `Package`.<br/>
+Выбрасывает: `PackageError` с одним из кодов ошибок, перечисленных в разделе "[Возможные коды ошибок](#possible-error-codes)".
+
+---
+
+`readPackageAsync(path: string): Promise<Package>`
+
+Асинхронно читает и парсит `package.json` по указанному пути.
+
+Полностью аналогичен `readPackage`, но работает асинхронно. Рекомендуется для использования в асинхронных контекстах (например, в плагинах сборщиков).
+
+Выбрасывает: `PackageError` с одним из кодов ошибок, перечисленных в разделе "[Возможные коды ошибок](#possible-error-codes)".
+Возвращает: промис с объектом типа Package.<br/>
+
+---
+
+`parsePackageJson(content: string): Package`
+
+Парсит строку с содержимым `package.json` в объект `Package`.
+
+Используйте, если содержимое файла уже загружено (например, из кэша или теста).
+
+---
+`PackageError`
+
+Класс ошибок с понятными сообщениями и кодами. Помогает быстро выяснить, что пошло не так.
+
+<a name="#possible-error-codes"></a>
+Возможные коды ошибок:
+- `notFound` — файл `package.json` не найден,
+- `accessDenied` — нет прав на чтение файла,
+- `invalidPath` — путь не ведёт к `package.json` или к папке пакета,
+- `invalidJson` — повреждённый или невалидный JSON,
+- `invalidJsonRoot` — корень JSON-файла не является объектом,
+- `failedToRead` — не удалось прочитать файл.
+
+Пример использования:
+
+```ts
+if (err.code === 'notFound') {
+  console.error('Файл не найден:', err.message)
+}
+```
+## 🧩 Поддерживаемые поля
+
+Пакет читает только те поля `package.json`, которые нужны фреймворку:
+
+`name`
+
+Имя пакета, например: "@mirta/basics"
+
+`exports`
+
+Поддерживается упрощённый формат с `import`:
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs"
+    },
+    "./setup-global": "./dist/setup/global.mjs"
+  }
+}
+```
+Или с типами:
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  }
+}
+```
+Игнорируются: `require`, `node`, `browser` и другие условия.
+
+`workspaces`
+
+Разрешён только массив строк: `["packages/*"]`<br/>
+Объектный формат (`{ packages: [...] }`) не поддерживается.
+
+## ✅ Тестирование
+
+Пакет полностью покрыт тестами:
+- Успешное чтение `package.json`
+- Обработка всех типов ошибок: файл не найден, нет доступа, невалидный JSON
+- Поддержка разных путей
+- Корректная миграция ошибок в `PackageError`
+
+Используется Vitest, моки зависимостей, изолированные тесты.
+
+## ⚠️ Ограничения
+
+- Работает только в Node.js (не в Duktape).
+- Поддерживает только `import` в `exports`.
+- Поле `workspaces` должно быть массивом строк.
+- Для асинхронных операций используйте `readPackageAsync`.
+- Синхронные операции не рекомендуются в асинхронных средах (используйте `readPackageAsync`).
+
+## 🔄 Использование в `@mirta/workspace`
+
+Этот пакет используется в `@mirta/workspace` для:
+- Чтения `package.json` корневого проекта.
+- Проверки поля `workspaces`.
+- Сбора информации о каждом пакете в монорепозитории.
+
+Пример:
+
+```ts
+const pkg = await readPackageAsync(`${rootDir}/packages/mirta-basics`)
+```
+Это обеспечивает единый, надёжный способ доступа к метаданным пакетов.

package/dist/index.d.mts

@@ -0,0 +1,409 @@
+/**
+ * Путь внутри поля `exports` (например, `"./dist/index.mjs"`).
+ *
+ * Может быть строкой, `null` или `undefined`.
+ *
+ * @since 0.4.0
+ *
+ **/
+type ExportsPath = string | null | undefined;
+/**
+ * Объект с `types` и `default` внутри поля `exports`.
+ *
+ * Определяет альтернативные пути для условия `import`.
+ *
+ * @example
+ *
+ * ```json
+ * {
+ *   "import": {
+ *     "types": "./dist/index.d.mts",
+ *     "default": "./dist/index.mjs"
+ *   }
+ * }
+ *
+ * ```
+ * @since 0.4.0
+ *
+ **/
+interface ExportsObject {
+    /** Путь к файлу типов (`.d.mts`). */
+    types?: ExportsPath;
+    /** Основной путь экспорта. */
+    default?: ExportsPath;
+}
+/**
+ * Упрощённая форма условного экспорта, поддерживаемая фреймворком Мирта.
+ *
+ * Поддерживается только условие `import`.
+ * Другие условия (`require`, `node`, `browser`) игнорируются.
+ *
+ * @example
+ *
+ * ```json
+ * {
+ *   "exports": {
+ *     ".": {
+ *       "import": "./dist/index.mjs"
+ *     }
+ *   }
+ * }
+ *
+ * ```
+ * @example
+ *
+ * ```json
+ * {
+ *   "exports": {
+ *     ".": {
+ *       "import": {
+ *         "types": "./dist/index.d.mts",
+ *         "default": "./dist/index.mjs"
+ *       }
+ *     }
+ *   }
+ * }
+ *
+ * ```
+ *
+ * @since 0.4.0
+ *
+ **/
+interface ExportsConditional {
+    /**
+     * Путь или объект экспорта для условной загрузки.
+     *
+     * @remarks
+     * Условие `import` — единственный поддерживаемый вариант в Мирте.
+     *
+     **/
+    import: ExportsPath | ExportsObject;
+}
+/**
+ * Любой допустимый тип в записи поля `exports`.
+ * Может быть строкой, объектом или условным экспортом.
+ *
+ * @since 0.4.0
+ *
+ **/
+type ExportsEntry = ExportsPath | ExportsConditional | ExportsObject;
+/**
+ * Упрощённая форма поля `exports` из package.json, поддерживаемая фреймворком Мирта.
+ *
+ * Поддерживает:
+ * - Простые пути: `"import": "./dist/index.mjs"`;
+ * - Объекты с `types` и `default`;
+ * - Дополнительные точки входа (например, `./setup-global`, `./context`).
+ *
+ * @example
+ *
+ * ```json
+ * {
+ *   "exports": {
+ *     ".": {
+ *       "import": "./dist/index.mjs"
+ *     }
+ *   }
+ * }
+ * ```
+ * @since 0.4.0
+ *
+ **/
+type PackageExports = ExportsPath | ExportsConditional | Record<string, ExportsEntry>;
+/**
+ * Минимальный контракт `package.json`, необходимый для работы фреймворка Мирта.
+ *
+ * @since 0.4.0
+ *
+ **/
+interface Package {
+    /**
+     * Имя пакета (например, `"@mirta/package"`).
+     *
+     **/
+    name?: string;
+    /**
+     * Семантическая версия пакета (SemVer).
+     *
+     * Обязательна при публикации в реестр. Рекомендуется указывать
+     * даже в приватных пакетах, для отслеживания изменений.
+     *
+     * Имеет формат `major.minor.patch` (например, `1.2.3`), где каждый
+     * сегмент обозначает разные уровни изменений:
+     * - `major` — крупные изменения, возможны breaking changes,
+     * - `minor` — добавление новых возможностей без нарушения совместимости,
+     * - `patch` — исправление ошибок.
+     *
+     * Версии до `1.0.0` (например, `0.4.0`) считаются экспериментальными:
+     * любое обновление может включать breaking changes.
+     *
+     * @example
+     * "0.4.0"
+     * "1.0.0-alpha.1"
+     *
+     **/
+    version?: string;
+    /**
+     * Признак того, что пакет не предназначен для публикации.
+     *
+     * Если значение `true`, пакет нельзя опубликовать в реестре (например, npm).
+     * Используется для защиты от случайной публикации внутренних или служебных пакетов.
+     *
+     **/
+    private?: boolean;
+    /**
+     * Именованные команды для автоматизации задач (сборка, тесты, форматирование и т.п.).
+     *
+     **/
+    scripts?: Record<string, string>;
+    /**
+     * Конфигурация экспорта модуля.
+     *
+     * Поддерживается упрощённый формат с условием `import`.
+     *
+     **/
+    exports?: PackageExports;
+    /**
+     * Список шаблонов рабочих пространств (workspaces).
+     * Используется для определения структуры монорепозитория.
+     *
+     **/
+    workspaces?: string[];
+    /**
+     * Зависимости, необходимые для работы пакета.
+     *
+     * Устанавливаются вместе с пакетом при его добавлении в проект.
+     *
+     * @since 0.4.0
+     *
+     **/
+    dependencies?: Record<string, string>;
+    /**
+     * Зависимости, необходимые при разработке пакета.
+     *
+     * Не устанавливаются вместе с пакетом при его добавлении в проект.
+     *
+     **/
+    devDependencies?: Record<string, string>;
+    /**
+     * Зависимости, которые ожидаются в основном проекте.
+     *
+     * Не устанавливаются автоматически, но требуются для корректной работы.
+     * Позволяют избежать дублирования пакетов.
+     *
+     **/
+    peerDependencies?: Record<string, string>;
+    /**
+     * Опциональные зависимости, которые устанавливаются, если возможно.
+     *
+     * Ошибки при их установке игнорируются. Используются, когда:
+     * - Зависимость работает только на определённых платформах (например, macOS, Windows);
+     * - Пакет может предоставить fallback-реализацию или работать с ограниченной функциональностью.
+     *
+     **/
+    optionalDependencies?: Record<string, string>;
+}
+
+/**
+ * Синхронно читает и парсит `package.json` по указанному пути.
+ *
+ * Поддерживается:
+ * - Прямой путь к файлу — `'package.json'`, `'packages/core/package.json'`
+ * - Путь к корневой директории пакета — `'.'`, `'..'`, `'../../shared'`, `'packages/core'`
+ *
+ * Не поддерживается:
+ * - Передача пути к произвольному файлу — `'src/index.ts'`
+ *
+ * При ошибках чтения файла или невалидном JSON выбрасывается {@link PackageError}
+ * с подробным описанием и контекстом.
+ *
+ * @param path - Путь к `package.json` или к корневой директории пакета.
+ * @returns  Объект типа {@link Package}, представляющий минимальный контракт,
+ *           необходимый для разрешения структуры монорепозитория и сборки проектов.
+ * @throws {PackageError} Если файл не найден, нет доступа или JSON повреждён.
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function readPackage(path: string): Package;
+/**
+ * Асинхронно читает и парсит `package.json` по указанному пути.
+ *
+ * Поддерживается:
+ * - Прямой путь к файлу — `'package.json'`, `'packages/core/package.json'`
+ * - Путь к корневой директории пакета — `'.'`, `'..'`, `'../../shared'`, `'packages/core'`
+ *
+ * Не поддерживается:
+ * - Передача пути к произвольному файлу — `'src/index.ts'`
+ *
+ * При ошибках чтения файла или невалидном JSON выбрасывается {@link PackageError}
+ * с подробным описанием и контекстом.
+ *
+ * @param path - Путь к `package.json` или к корневой директории пакета.
+ * @returns Объект типа {@link Package}, представляющий минимальный контракт.
+ * @throws {PackageError} Если файл не найден, нет доступа или JSON повреждён.
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function readPackageAsync(path: string): Promise<Package>;
+
+/**
+ * Парсит строку JSON и возвращает объект типа {@link Package}.
+ *
+ * Не выполняет чтение из файловой системы.
+ *
+ * @param content - Строка в формате JSON
+ * @returns Объект типа {@link Package}
+ * @throws {SyntaxError} Если JSON некорректен.
+ *                       Сообщение содержит детали: позицию, причину.
+ *
+ * @throws {PackageError} Если JSON не является объектом.
+ *
+ * @example
+ *
+ * ```ts
+ * parsePackageJson('{ "name": "my-package" }')
+ *
+ * ```
+ * @since 0.4.0
+ *
+ **/
+declare function parsePackageJson(content: string): Package;
+
+/**
+ * Резолвит путь к `package.json` на основе входного пути.
+ *
+ * Правила:
+ * - Если `path` заканчивается на `package.json` → возвращается как есть
+ * - Если `path` указывает на директорию (включая `.` и `..`) → возвращается `path/package.json`
+ * - Если `path` указывает на файл с расширением (например, `src/index.ts`), но не на `package.json` → ошибка
+ *
+ * Не выполняет проверку существования файла.
+ *
+ * @param path - Путь к `package.json` или к директории пакета.
+ *               Может быть абсолютным или относительным.
+ * @returns Абсолютный или относительный путь к `package.json`
+ * @throws {PackageError} С кодом `invalidPath`, если путь указывает на файл с расширением,
+ *                        но не является `package.json`.
+ *
+ * @example
+ *
+ * ```ts
+ * resolvePackagePath('.')             // → './package.json'
+ * resolvePackagePath('..')            // → '../package.json'
+ * resolvePackagePath('packages/core') // → 'packages/core/package.json'
+ * resolvePackagePath('package.json')  // → 'package.json'
+ * resolvePackagePath('src/index.ts')  // → ошибка
+ *
+ * ```
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function resolvePackagePath(path: string): string;
+
+/**
+ * Преобразует путь из формата Windows в формат POSIX.
+ *
+ * Заменяет все обратные слеши (`\`) на прямые (`/`), что необходимо для кросс-платформенной
+ * совместимости, особенно при сравнении путей или работе с инструментами сборки,
+ * которые ожидают стандартизированный формат пути.
+ *
+ * @param path - Входной путь, который может содержать разделители Windows (`\`).
+ * @returns Путь, в котором все разделители заменены на `/`.
+ *
+ * @example
+ * ```ts
+ * toPosix('C:\\projects\\app\\src\\index.ts')
+ * // Результат: 'C:/projects/app/src/index.ts'
+ * ```
+ *
+ * @remarks
+ * Функция использует {@link nodePath.win32.sep} и {@link nodePath.posix.sep} для получения
+ * платформенно-зависимых разделителей, что делает её надёжной независимо от ОС,
+ * на которой выполняется код.
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function toPosix(path: string): string;
+declare function toPosix(path: string | undefined): string | undefined;
+
+/**
+ * Специализированный класс для обработки ошибок, связанных с чтением и парсингом файла `package.json`.
+ *
+ * Предоставляет структурированные и типизированные ошибки с использованием кодов, что упрощает
+ * программную обработку исключений в инструментах, работающих с пакетами.
+ *
+ * @example
+ * ```ts
+ * throw PackageError.get('notFound', '/path/to/package.json');
+ * ```
+ * @since 0.4.0
+ *
+ **/
+declare class PackageError extends Error {
+    /**
+     * Код ошибки для программной идентификации.
+     *
+     * Позволяет точно определить причину ошибки в обработчиках `try/catch`.
+     *
+     **/
+    readonly code: string;
+    /**
+     * Приватный конструктор, используемый только внутри
+     * класса для создания экземпляров ошибки.
+     *
+     * @param message - Полное сообщение об ошибке.
+     * @param code - Код ошибки для идентификации.
+     * @param scope - Пространство имён или модуль, в котором возникла ошибка.
+     *                По умолчанию — {@link THIS_PACKAGE_NAME}.
+     *
+     **/
+    private constructor();
+    /** Карта кодов ошибок с соответствующими сообщениями. */
+    private static readonly codeMappings;
+    /**
+     * Фабричный метод для создания экземпляра ошибки по её коду.
+     *
+     * Автоматически подставляет сообщение из `codeMappings` и формирует ошибку с заданными параметрами.
+     *
+     * @template T - Ограниченный ключами `codeMappings` тип, гарантирующий корректность кода.
+     * @param code - Код ошибки (например, `'notFound'`, `'invalidJson'`).
+     * @param args - Аргументы, соответствующие параметрам функции сообщения из `codeMappings`.
+     * @returns Новый экземпляр {@link PackageError} с шаблонным сообщением.
+     *
+     * @example
+     * ```ts
+     * const error = PackageError.get('notFound', '/src/package.json');
+     * ```
+     */
+    static get<T extends keyof typeof PackageError['codeMappings']>(code: T, ...args: Parameters<typeof PackageError['codeMappings'][T]>): PackageError;
+    /**
+     * Фабричный метод, аналогичный `get`, но с возможностью указать
+     * пользовательское пространство имён (scope).
+     *
+     * Полезно при использовании в других модулях, где нужно указать
+     * иной контекст ошибки.
+     *
+     * @template TKey - Тип кода ошибки, аналогично `get`.
+     *
+     * @param scope - Пространство имён ошибки (например, `'@mirta/cli'`).
+     * @param code - Код ошибки.
+     * @param args - Аргументы для формирования сообщения.
+     *
+     * @returns Новый экземпляр {@link PackageError} с пользовательским
+     *          префиксом и шаблонным сообщением.
+     *
+     * @example
+     *
+     * ```ts
+     * const error = PackageError.getScoped('@mirta/cli', 'invalidPath', '/invalid/path');
+     * ```
+     **/
+    static getScoped<TKey extends keyof typeof PackageError['codeMappings']>(scope: string, code: TKey, ...args: Parameters<typeof PackageError['codeMappings'][TKey]>): PackageError;
+}
+
+export { PackageError, parsePackageJson, readPackage, readPackageAsync, resolvePackagePath, toPosix };
+export type { ExportsConditional, ExportsEntry, ExportsObject, ExportsPath, Package, PackageExports };

package/dist/index.mjs

@@ -0,0 +1,341 @@
+import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import nodePath, { basename, posix } from 'node:path';
+
+/**
+ * Имя текущего пакета в формате, используемом в npm-реестре.
+ *
+ * Используется для логирования, формирования сообщений об ошибках,
+ * а также в диагностических и пользовательских интерфейсах,
+ * чтобы явно указывать источник операций.
+ *
+ * Централизованное определение позволяет избежать жёсткой привязки
+ * к строковому значению в разных частях кода и упрощает поддержку
+ * при возможном переименовании пакета.
+ *
+ * @example
+ * ```ts
+ * console.log(`[${THIS_PACKAGE_NAME}] Запуск сборки...`);
+ * ```
+ *
+ * @since 0.4.0
+ *
+ **/
+const THIS_PACKAGE_NAME = '@mirta/package';
+
+/**
+ * Специализированный класс для обработки ошибок, связанных с чтением и парсингом файла `package.json`.
+ *
+ * Предоставляет структурированные и типизированные ошибки с использованием кодов, что упрощает
+ * программную обработку исключений в инструментах, работающих с пакетами.
+ *
+ * @example
+ * ```ts
+ * throw PackageError.get('notFound', '/path/to/package.json');
+ * ```
+ * @since 0.4.0
+ *
+ **/
+class PackageError extends Error {
+    /**
+     * Код ошибки для программной идентификации.
+     *
+     * Позволяет точно определить причину ошибки в обработчиках `try/catch`.
+     *
+     **/
+    code;
+    /**
+     * Приватный конструктор, используемый только внутри
+     * класса для создания экземпляров ошибки.
+     *
+     * @param message - Полное сообщение об ошибке.
+     * @param code - Код ошибки для идентификации.
+     * @param scope - Пространство имён или модуль, в котором возникла ошибка.
+     *                По умолчанию — {@link THIS_PACKAGE_NAME}.
+     *
+     **/
+    constructor(message, code, scope) {
+        super(`[${scope ?? THIS_PACKAGE_NAME}] ${message}`);
+        this.name = 'PackageError';
+        this.code = code;
+        // Захватываем стек вызовов, исключая фабричный метод `get`,
+        // чтобы улучшить читаемость трассировки.
+        //
+        if ('captureStackTrace' in Error)
+            Error.captureStackTrace(this, scope
+                // eslint-disable-next-line @typescript-eslint/unbound-method
+                ? PackageError.getScoped
+                // eslint-disable-next-line @typescript-eslint/unbound-method
+                : PackageError.get);
+    }
+    /** Карта кодов ошибок с соответствующими сообщениями. */
+    static codeMappings = {
+        /**
+         * Ошибка, возникающая, когда файл `package.json`
+         * не найден по указанному пути.
+         *
+         * @param filePath - Абсолютный или относительный путь к отсутствующему файлу.
+         *
+         **/
+        notFound: (filePath) => `File not found: "${filePath}"`,
+        /**
+         * Ошибка, возникающая при отсутствии прав на чтение файла.
+         *
+         * @param filePath - Путь к файлу, доступ к которому запрещён.
+         *
+         **/
+        accessDenied: (filePath) => `Access denied to file "${filePath}"`,
+        /**
+         * Ошибка, возникающая при передаче невалидного пути.
+         *
+         * @param path - Переданный путь, не соответствующий ожидаемому формату.
+         *
+         **/
+        invalidPath: (path) => `Invalid path "${path}": expected a path to "package.json" or a package directory`,
+        /**
+         * Ошибка парсинга JSON в файле `package.json`.
+         *
+         * @param filePath - Путь к файлу с некорректным JSON.
+         * @param message - Сообщение об ошибке от парсера (например, `Unexpected token }`).
+         *
+         **/
+        invalidJson: (filePath, message) => `Invalid JSON in file "${filePath}": ${message}`,
+        /**
+         * Ошибка, возникающая, если корневой элемент JSON не является объектом.
+         * Согласно спецификации, `package.json` должен начинаться с `{}`.
+         *
+         **/
+        invalidJsonRoot: () => 'Invalid JSON: root must be an object, not an array or primitive value',
+        /**
+         * Общая ошибка чтения файла с неуточнённой причиной.
+         * @param filePath - Путь к файлу.
+         * @param message - Возможное описание ошибки от файловой системы.
+         *
+         **/
+        failedToRead: (filePath, message) => `Failed to read "${filePath}": ${message ?? 'unknown reason'}`,
+        /**
+         * Ошибка, возникающая, если в `package.json` отсутствует поле `version`.
+         *
+         **/
+        noVersionField: () => 'No version field found in package.json',
+    };
+    /**
+     * Фабричный метод для создания экземпляра ошибки по её коду.
+     *
+     * Автоматически подставляет сообщение из `codeMappings` и формирует ошибку с заданными параметрами.
+     *
+     * @template T - Ограниченный ключами `codeMappings` тип, гарантирующий корректность кода.
+     * @param code - Код ошибки (например, `'notFound'`, `'invalidJson'`).
+     * @param args - Аргументы, соответствующие параметрам функции сообщения из `codeMappings`.
+     * @returns Новый экземпляр {@link PackageError} с шаблонным сообщением.
+     *
+     * @example
+     * ```ts
+     * const error = PackageError.get('notFound', '/src/package.json');
+     * ```
+     */
+    static get(code, ...args) {
+        const messageFn = this.codeMappings[code];
+        const message = messageFn(...args);
+        return new PackageError(message, code);
+    }
+    /**
+     * Фабричный метод, аналогичный `get`, но с возможностью указать
+     * пользовательское пространство имён (scope).
+     *
+     * Полезно при использовании в других модулях, где нужно указать
+     * иной контекст ошибки.
+     *
+     * @template TKey - Тип кода ошибки, аналогично `get`.
+     *
+     * @param scope - Пространство имён ошибки (например, `'@mirta/cli'`).
+     * @param code - Код ошибки.
+     * @param args - Аргументы для формирования сообщения.
+     *
+     * @returns Новый экземпляр {@link PackageError} с пользовательским
+     *          префиксом и шаблонным сообщением.
+     *
+     * @example
+     *
+     * ```ts
+     * const error = PackageError.getScoped('@mirta/cli', 'invalidPath', '/invalid/path');
+     * ```
+     **/
+    static getScoped(scope, code, ...args) {
+        const messageFn = this.codeMappings[code];
+        const message = messageFn(...args);
+        return new PackageError(message, code, scope);
+    }
+}
+
+function toPosix(path) {
+    if (path === '' || path === undefined)
+        return path;
+    return path.replaceAll(nodePath.win32.sep, nodePath.posix.sep);
+}
+
+/**
+ * Резолвит путь к `package.json` на основе входного пути.
+ *
+ * Правила:
+ * - Если `path` заканчивается на `package.json` → возвращается как есть
+ * - Если `path` указывает на директорию (включая `.` и `..`) → возвращается `path/package.json`
+ * - Если `path` указывает на файл с расширением (например, `src/index.ts`), но не на `package.json` → ошибка
+ *
+ * Не выполняет проверку существования файла.
+ *
+ * @param path - Путь к `package.json` или к директории пакета.
+ *               Может быть абсолютным или относительным.
+ * @returns Абсолютный или относительный путь к `package.json`
+ * @throws {PackageError} С кодом `invalidPath`, если путь указывает на файл с расширением,
+ *                        но не является `package.json`.
+ *
+ * @example
+ *
+ * ```ts
+ * resolvePackagePath('.')             // → './package.json'
+ * resolvePackagePath('..')            // → '../package.json'
+ * resolvePackagePath('packages/core') // → 'packages/core/package.json'
+ * resolvePackagePath('package.json')  // → 'package.json'
+ * resolvePackagePath('src/index.ts')  // → ошибка
+ *
+ * ```
+ *
+ * @since 0.4.0
+ *
+ **/
+function resolvePackagePath(path) {
+    const normalizedPath = toPosix(path);
+    if (normalizedPath.endsWith('package.json'))
+        return normalizedPath;
+    const base = basename(normalizedPath);
+    // Проверяем последний фрагмент пути, не допуская файлы.
+    if (base !== '.' && base !== '..' && base.includes('.'))
+        throw PackageError.get('invalidPath', normalizedPath);
+    return posix.join(normalizedPath, 'package.json');
+}
+
+/**
+ * Парсит строку JSON и возвращает объект типа {@link Package}.
+ *
+ * Не выполняет чтение из файловой системы.
+ *
+ * @param content - Строка в формате JSON
+ * @returns Объект типа {@link Package}
+ * @throws {SyntaxError} Если JSON некорректен.
+ *                       Сообщение содержит детали: позицию, причину.
+ *
+ * @throws {PackageError} Если JSON не является объектом.
+ *
+ * @example
+ *
+ * ```ts
+ * parsePackageJson('{ "name": "my-package" }')
+ *
+ * ```
+ * @since 0.4.0
+ *
+ **/
+function parsePackageJson(content) {
+    const parsed = JSON.parse(content);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        throw PackageError.get('invalidJsonRoot');
+    return parsed;
+}
+
+/**
+ * Обрабатывает ошибку, возникшую при чтении или парсинге файла `package.json`,
+ * и преобразует её в соответствующую ошибку типа {@link PackageError}.
+ *
+ * @param e - Неизвестное исключение, которое необходимо обработать.
+ * @param path - Путь к файлу `package.json`, на котором произошла ошибка.
+ * @returns Экземпляр {@link PackageError}, соответствующий типу исключения.
+ *
+ * @since 0.4.0
+ *
+ **/
+function handleError(e, path) {
+    if (e instanceof PackageError)
+        return e;
+    if (e instanceof SyntaxError)
+        return PackageError.get('invalidJson', path, e.message);
+    if (e && typeof e === 'object' && 'code' in e) {
+        const code = e.code;
+        switch (code) {
+            case 'ENOENT':
+                return PackageError.get('notFound', path);
+            case 'EACCES':
+            case 'EPERM':
+                return PackageError.get('accessDenied', path);
+        }
+    }
+    const message = e instanceof Error
+        ? e.message
+        : String(e);
+    return PackageError.get('failedToRead', path, message);
+}
+/**
+ * Синхронно читает и парсит `package.json` по указанному пути.
+ *
+ * Поддерживается:
+ * - Прямой путь к файлу — `'package.json'`, `'packages/core/package.json'`
+ * - Путь к корневой директории пакета — `'.'`, `'..'`, `'../../shared'`, `'packages/core'`
+ *
+ * Не поддерживается:
+ * - Передача пути к произвольному файлу — `'src/index.ts'`
+ *
+ * При ошибках чтения файла или невалидном JSON выбрасывается {@link PackageError}
+ * с подробным описанием и контекстом.
+ *
+ * @param path - Путь к `package.json` или к корневой директории пакета.
+ * @returns  Объект типа {@link Package}, представляющий минимальный контракт,
+ *           необходимый для разрешения структуры монорепозитория и сборки проектов.
+ * @throws {PackageError} Если файл не найден, нет доступа или JSON повреждён.
+ *
+ * @since 0.4.0
+ *
+ **/
+function readPackage(path) {
+    const resolvedPath = resolvePackagePath(path);
+    let content;
+    try {
+        content = readFileSync(resolvedPath, 'utf-8');
+        return parsePackageJson(content);
+    }
+    catch (e) {
+        throw handleError(e, resolvedPath);
+    }
+}
+/**
+ * Асинхронно читает и парсит `package.json` по указанному пути.
+ *
+ * Поддерживается:
+ * - Прямой путь к файлу — `'package.json'`, `'packages/core/package.json'`
+ * - Путь к корневой директории пакета — `'.'`, `'..'`, `'../../shared'`, `'packages/core'`
+ *
+ * Не поддерживается:
+ * - Передача пути к произвольному файлу — `'src/index.ts'`
+ *
+ * При ошибках чтения файла или невалидном JSON выбрасывается {@link PackageError}
+ * с подробным описанием и контекстом.
+ *
+ * @param path - Путь к `package.json` или к корневой директории пакета.
+ * @returns Объект типа {@link Package}, представляющий минимальный контракт.
+ * @throws {PackageError} Если файл не найден, нет доступа или JSON повреждён.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function readPackageAsync(path) {
+    const resolvedPath = resolvePackagePath(path);
+    let content;
+    try {
+        content = await readFile(resolvedPath, 'utf-8');
+        return parsePackageJson(content);
+    }
+    catch (e) {
+        throw handleError(e, resolvedPath);
+    }
+}
+
+export { PackageError, parsePackageJson, readPackage, readPackageAsync, resolvePackagePath, toPosix };

package/package.json

@@ -1,10 +1,48 @@
 {
   "name": "@mirta/package",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @mirta/package",
+  "version": "0.4.0",
+  "sideEffects": false,
+  "description": "Internal type-safe reader & parser for package.json, used by Mirta Framework",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "mirta",
+    "package.json",
+    "read",
+    "parse",
+    "exports",
+    "monorepo",
+    "typescript",
+    "config",
+    "utility"
+  ],
+  "license": "Unlicense",
+  "homepage": "https://github.com/wb-mirta/core#readme",
+  "bugs": {
+    "url": "https://github.com/wb-mirta/core/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wb-mirta/core.git",
+    "directory": "packages/mirta-package"
+  },
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "imports": {
+    "#src/*": "./src/*.js"
+  },
+  "engines": {
+    "node": ">=24.12.0"
+  }
+}