progcode/editorial/reviews/2024-03-draft.md

P73 · 2024-03 · Границы пакетов — три прохода саморевью

Рамка sidecar-пакета

• Slug: editorial-2024-03-practice-package-boundaries, editorial-2024-03-mechanism-package-boundaries, editorial-2024-03-field-package-boundaries.
• Голос: M7, март 2024. Автор говорит коротко и предметно: сначала цена скрытой зависимости, затем «симптом → причина → проверка → действие», контракт, граница инструмента и следующий шаг. Это не рассказ о личном production-инциденте.
• Созданы ровно пять sidecar-файлов: этот review, import-safe script и три локальные SVG. Overlay, README, articles.json, очередь, Git, staging, commit/push и чужие файлы не менялись; пакет не интегрирован.
• Fixture хранит только fixed synthetic JS records в памяти Node. Он не читает repository, source files, package.json, tsconfig, eslint config, lockfile, environment, часы, CI output, сеть, HTTP, SDK или реальный import graph. Его PASS не доказывает существование пакетов, dependency graph, lint result, bundle, release или production effect.

Проход 1 — факты, источники и модель

• Источники перепроверены 31.07.2026 и существовали к марту 2024. Node.js v20.11.1: Modules: Packages документирует exports: entry points package import-а можно задать явно, а неэкспортируемые subpath становятся недоступны обычному package import. Там же явно сказано, что это не strong encapsulation против прямого абсолютного пути. Поэтому статья не называет exports security boundary и не утверждает, что оно строит архитектуру монорепозитория.
• TypeScript 4.7 release notes опубликованы в мае 2022: node16 и nodenext поддерживают Node-oriented ESM/CJS resolution, package.json exports, imports и self-reference. В статьях это ограничено корректностью module/type resolution; TypeScript не объявлен средством решить, имеет ли utility право знать InvoiceStatus.
• ESLint v8.55.0 release notes, 01.12.2023 подтверждают доступность importNamePattern в no-restricted-imports до марта 2024. Это используется как пример статического route guard после решения команды, а не как обещание полного dependency graph, обработки dynamic import или business-semantics analysis.
• inspectSyntheticPackageBoundary() принимает только input v1 c marker synthetic, scope synthetic-package-boundary-demo, режимом fixed-memory-only и одним из трёх embedded case id. Она отвергает non-synthetic input, лишнее project-like поле, чужой scope, scan-project и неизвестный case. Модель не получает произвольный graph из файлов или сети.
• В трёх фиксированных записях различены: чистый root import, utility-imports-domain (platform-formatting → billing-domain/InvoiceStatus) и consumer-bypasses-public-api (consumer → platform-formatting/internal/*). Это две разные причины с разными draft action, а не один размытый verdict «плохая архитектура».
• planSyntheticBoundaryRemediation() принимает только отчёт fixture, повторно сверяет его с fixed record и возвращает лишь decision draft. Он не пишет package.json или lint config, не запускает lint/CI и возвращает realConfiguration=not-written, realLint=not-run, realCi=not-run, productionEffect=not-attempted. rollbackSyntheticBoundaryDraft() удаляет только этот synthetic draft и не трогает repository, files, network или CI.
• На техническом ревью найдены и исправлены границы модели. inspect требует точный набор own-полей, а не только отсутствие незнакомых; report и plan требуют полную ожидаемую форму и плотные массивы. plan сравнивает полный canonical report с fixed record, а rollback воспроизводит canonical plan для case id и отвергает лишнее поле, подменённый draftAction и разрежённый список действий. Это сохраняет связь результата и embedded case, не превращая fixture в доверчивый parser произвольных данных.

Проход 2 — редактура, объём и голос

• Три материала отвечают на разные вопросы. Practice строит минимальный контракт shared utility и порядок миграции. Mechanism различает public API record, Node exports, TypeScript resolution и static route guard. Field разбирает один synthetic case, где domain type попал в utility, а consumer обошёл root API через internal.
• В первых двух абзацах каждого текста названы ситуация и цена: скрытая доменная связность расширяет поверхность изменения, делает enum и internal cache чужими рисками, повышает стоимость review, миграции и обратного хода. Ни одна статья не придумывает реальный production-инцидент, bundle measurement, scan или запуск CI.
• В каждой ревизии есть figure с meaningful alt и подписью, доступная таблица, исполнимый synthetic example, порядок «симптом → причина → проверка → действие», явные ограничения и конкретный следующий шаг. Public API раскрыт как specifier + names + input/output + owner, а запрещённый импорт — как маршрут и правило, а не общий лозунг.
• audit:draft фиксирует основной текст без списка источников: practice — 9 960, mechanism — 9 999, field — 9 969 знаков. Все три текста попадают в целевой коридор 8–10 тыс. и обязательный диапазон 5–15 тыс. знаков.
• Речь вычитана против шаблонных оценок. Термины public API, root specifier, exports, node16, internal subpath, static import, domain owner либо привязаны к примеру, либо ограничены источником. Нет обещания универсальной архитектуры, «магической» изоляции и подмены прогона fixture реальной проверкой проекта.

Проход 3 — визуал, безопасность и выпуск

• SVG разделяют три задачи: направление dependency edge, границу public API и маршрут принятия решения. В них нет script, foreignObject, внешних URL, data:image, event-handler-атрибутов или пользовательского ввода.
• Для мобильного чтения схемы выполнен Sharp-render шириной 375 px и ручное открытие каждого PNG. Крупные карточки, контрастные подписи, короткие стрелки и отдельная нижняя строка ограничения остаются читаемы; элементы не перекрываются и не обрезаются. Визуал не выдаёт synthetic package names за сведения о реальном проекте.
• Финальные проверки: node --check web/scripts/upgrade-2024-03.mjs — PASS; fixture — PASS 24/24; cd web && npm run audit:draft -- scripts/upgrade-2024-03.mjs — PASS для трёх slug; import-safe export без date/author — PASS; xmllint --noout всех трёх SVG — PASS; SVG safety scan — чисто (нет script, foreignObject, external URL, data:image или event handler); Sharp-render 375 px и ручной просмотр — PASS.
• До интеграции пакет не меняет overlay, README, articles.json, очередь, Git или чужие файлы. Реальная проверка import graph и настройка production tooling находятся за границей P73.

Выпуск после трёх проходов

• Главный редактор подключил ровно три мартовские ревизии в web/data/editorial-revisions.mjs, не меняя архивный articles.json, и обновил счётчик производства до 223 из 358 материалов.
• После подключения npm run audit:articles -- <три slug> подтвердил объём, figure, таблицу и пример каждой статьи; registry содержит 214 уникальных ревизий без повторов slug.
• npm run build завершился успешно: Next.js сгенерировал 374 статические страницы. В выпуск не включены пользовательские правки и sidecar-пакеты апреля, мая, июня и июля.