[codex] document architecture compliance audit #425
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| # Architecture compliance audit | ||
|
|
||
| Дата аудита: 2026-06-18 | ||
|
|
||
| Источник требований: [ProverCoderAI/architecture-skills#1](https://github.com/ProverCoderAI/architecture-skills/issues/1). | ||
|
|
||
| ## Summary | ||
|
|
||
| Текущая кодовая база частично соответствует требованиям. В проекте уже есть сильная | ||
| база: monorepo, CI с build/typecheck/lint/test/e2e, Effect lint profile, | ||
| property-based tests и jscpd в части пакетов. По строгой трактовке issue | ||
| репозиторий пока нельзя считать соответствующим: есть крупные нарушения по | ||
| размеру модулей, файлов и функций; OpenAPI/generated client отсутствует; | ||
| mutation testing отсутствует; coverage не enforced в CI; API `lint:effect` не | ||
| подключён в CI; остаются прямые `fetch`, `unknown` и casts. | ||
|
|
||
| Строгость оценки: strict with documented exceptions. Boundary `unknown` | ||
| допустим только при явном schema decoding и без утечки в domain API. | ||
|
|
||
| ## Audit matrix | ||
|
|
||
| | Требование | Статус | Evidence | | ||
| | --- | --- | --- | | ||
| | File size <= 400 lines | Fail | 33 tracked TS code files exceed 400 lines. Largest: `packages/api/src/http.ts` 2121, `packages/api/src/services/federation.ts` 1916, `packages/api/src/services/terminal-sessions.ts` 1836. | | ||
| | Function size <= 50 lines | Fail | 270 functions exceed 50 lines. Largest: `makeRouter` in `packages/api/src/http.ts` starts at line 942 and spans about 1179 lines. | | ||
| | Parameters <= 5 | Partial | 7 functions exceed the limit. Worst: `packages/api/src/services/terminal-sessions.ts:1203` has 7 params. | | ||
| | Nesting depth <= 4 | Partial | 2 functions exceed the limit: `packages/api/src/services/auth-menu.ts:114` depth 7 and `packages/api/src/services/auth-menu.ts:165` depth 5. | | ||
| | Cyclomatic complexity <= 8 | Fail | 35 functions exceed the limit. Worst: `packages/api/src/services/projects.ts:449` complexity 36. | | ||
| | Suppression comments blocked | Partial | Only 4 `eslint-disable` / TS suppression hits, but they are config-level comments allowing test disables. jscpd suppression is broad: 40 `jscpd:ignore-start` blocks. | | ||
| | `any`, `unknown`, dynamic blocked | Partial | Explicit `any`: 0 AST occurrences. `unknown`: 163 AST occurrences; some are legitimate boundary values, but literal policy is not globally enforced. | | ||
| | Casts / `as` blocked | Fail | 59 TypeScript casts/type assertions in TS-only audit; broader JS/TS scope found 74. | | ||
| | Monorepo modules <= 5000 LOC | Fail | Top packages exceed the limit: app about 48k lines, lib about 28k, api about 26k, terminal about 10k, container about 8k. | | ||
| | Folder <= 10 code files | Fail | Top flat folders: `packages/app/src/web` 149 files, `packages/app/src/docker-git` 100, `packages/lib/src/usecases` 77, `packages/api/src/services` 42. | | ||
| | No unused dependencies | Partial | `dist-deps-prune` exists for packaged app dependency pruning, but there is no workspace-wide `knip`, `depcheck`, or equivalent unused dependency gate. | | ||
| | No unused modules | Partial | TypeScript and ESLint catch local unused symbols, but no workspace-wide unused export/module gate such as `knip` or `ts-prune` was found. | | ||
| | No duplicate code | Partial | `.jscpd.json` exists for app/lib/terminal and jscpd dependencies exist in app/lib/terminal/container. API and session-sync lack jscpd config, and many files use `jscpd:ignore`. | | ||
| | ORM or typed query layer for DB | Fail / not currently applicable | No Prisma/Drizzle/Kysely/TypeORM/Knex/Effect SqlClient usage was found. Existing DB-related code mainly handles typed database profile/proxy configuration, not database persistence. | | ||
| | Swagger/OpenAPI generated client | Fail | No OpenAPI/Swagger files or generated API client pipeline found. API schemas and clients appear handwritten with Effect Schema. | | ||
| | CI safe `lint --fix` bot flow | Fail | CI runs lint, but no deterministic auto-fix commit/fixed-point workflow was found. | | ||
| | Test coverage >= 10% | Partial | Vitest coverage thresholds exist in app/lib/container/terminal configs, but package test scripts and CI run plain `vitest run` without `--coverage`; API and session-sync lack coverage thresholds. | | ||
| | Property-based testing for invariants | Pass | `fast-check` is used broadly: 42 files and 77 `fc.property` usages were found. | | ||
| | E2E testing | Pass | CI runs 7 E2E jobs in `.github/workflows/check.yml`: local package, browser command, opencode, clone cache, login context, runtime volumes + SSH, clone auto-open SSH. | | ||
| | 100% changed code covered in PR | Fail | No diff coverage gate was found. | | ||
| | Mutation testing on PR changes | Fail | No Stryker or equivalent mutation testing config/tooling was found. | | ||
|
Comment on lines
+7
to
+44
There was a problem hiding this comment. Документ не содержит явного Story + Prove блока, требуемого SDD. Согласно
Текущий документ содержит only Audit matrix (WHAT) и Top blockers (почему), но не содержит явного Story (WHO/WHY) и не привязывает каждый инвариант к способу его проверки. Рекомендация: добавить перед Audit matrix раздел вида: ## Story
Как архитектор проекта, я хочу убедиться, что кодовая база соответствует
функциональной парадигме с чистыми функциями и контролируемыми эффектами,
чтобы обеспечить воспроизводимость, типовую безопасность и математическую
доказуемость решений.
### Prove (инварианты проверяемости)
- INV-1: ∀ файл ∈ TS-files: lines(файл) ≤ 400
Проверка: `bun run audit:lines` (read-only скрипт)
- INV-2: ∀ функция ∈ функции: lines(функция) ≤ 50
Проверка: `bun run audit:functions` (read-only скрипт)
... и т.д. для каждого требованияЭто обеспечит:
🤖 Prompt for AI Agents |
||
|
|
||
| ## Top blockers | ||
|
|
||
| 1. `packages/api` is the biggest architectural risk: large files, large functions, | ||
| direct `fetch`, remaining Effect migration warnings, and weak regular ESLint | ||
| enforcement compared with app/lib/container/terminal. | ||
| 2. OpenAPI/generated-client workflow is absent. | ||
| 3. Mutation testing and diff coverage are absent. | ||
| 4. Coverage thresholds exist only partially and are not enforced by CI. | ||
| 5. Module and folder size limits are not satisfied by current package/folder | ||
| boundaries. | ||
| 6. Duplication checks are partial and heavily bypassed in copied frontend-lib | ||
| code. | ||
|
|
||
| ## Recommended PR sequence | ||
|
|
||
| 1. Enforcement PR: add a read-only architecture audit script for LOC, folder | ||
| width, function size, params, nesting, complexity, casts and direct `fetch`; | ||
| connect API `lint:effect` to CI. | ||
| 2. Coverage PR: add `test:coverage` scripts, thresholds for API/session-sync, | ||
| and a CI coverage job. | ||
| 3. Duplication and unused-code PR: add workspace-wide jscpd coverage plus a | ||
| `knip` or equivalent unused dependency/export gate. | ||
| 4. API contract PR: choose and introduce OpenAPI as source of truth, then | ||
| generate client/types and block handwritten internal API access. | ||
| 5. Refactor PR series: split the largest API files first: | ||
| `http.ts`, `federation.ts`, `terminal-sessions.ts`, `skiller.ts`. | ||
| 6. Mutation PR: add mutation testing on changed files after the test/coverage | ||
| baseline is stable. | ||
|
Comment on lines
+59
to
+73
There was a problem hiding this comment. Рекомендуемая PR sequence не привязана к инвариантам Audit matrix. Раздел "Recommended PR sequence" содержит 6 PR'ов, но не указывает, какие требования из Audit matrix (строки 20–44) каждая PR закрывает. Это затрудняет:
Рекомендация: добавить трассировку вида: ## Recommended PR sequence
1. **Enforcement PR** (closes: File size, Function size, Parameters, Cyclomatic complexity, Casts)
- Description: add read-only architecture audit script...
2. **Coverage PR** (closes: Test coverage >= 10%, 100% diff coverage)
- Description: add `test:coverage` scripts...
3. **Duplication and unused-code PR** (closes: No duplicate code, No unused modules, No unused dependencies)
- Description: add workspace-wide jscpd coverage...
... и т.д.Это позволит быстро найти в матрице, какие требования решает каждая PR, и проверить их выполнение. 🤖 Prompt for AI Agents |
||
|
|
||
| ## Verification commands | ||
|
|
||
| The audit used read-only checks only: | ||
|
|
||
| ```bash | ||
| rtk gh issue view 1 --repo ProverCoderAI/architecture-skills --json title,body,comments | ||
| rtk rg --files -g 'package.json' -g '*eslint*' -g '*biome*' -g '*jscpd*' -g '*openapi*' -g '*swagger*' -g '*stryker*' -g '*vitest*' | ||
| rtk bun run lint:effect | ||
| rtk rg -n 'fast-check|fc\\.property|fc\\.assert' packages -g '*.ts' -g '*.tsx' | ||
| rtk rg -n '\\bfetch\\(|\\.fetch\\(' packages scripts -g '*.ts' -g '*.tsx' -g '*.mjs' | ||
| ``` | ||
|
Comment on lines
+75
to
+85
There was a problem hiding this comment. Команды верификации используют неизвестный префикс Строки 80–85 ссылаются на утилиту На основе context snippets (package.json:49 и # Проверка lint:effect
bun run lint:effect
# Или по отдельным пакетам:
bun run --cwd packages/container lint:effect
bun run --cwd packages/api lint:effect
# Поиск fast-check использований
rg -n 'fast-check|fc\.property|fc\.assert' packages -g '*.ts' -g '*.tsx'
# Поиск прямых fetch вызовов
rg -n '\bfetch\(|\.fetch\(' packages scripts -g '*.ts' -g '*.tsx' -g '*.mjs'Рекомендация: заменить все вхождения 🤖 Prompt for AI Agents |
||
|
|
||
| The AST metrics were computed with the TypeScript compiler API against tracked | ||
| files under `packages/` and `scripts/`, excluding generated build output. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Summary недооценивает серьёзность несоответствий матрицы.
Summary утверждает: «репозиторий пока нельзя считать соответствующим» и перечисляет «крупные нарушения», но матрица показывает более суровую картину:
Итого: 19 из 20 требований не полностью выполнены (11 Fail + 8 Partial).
Рекомендация: усилить выводы Summary, чтобы явно указать процент несоответствия и критичность (например, 55% требований полностью не выполнено, 40% выполнено частично). Это поднимет осведомленность о масштабе работ.
🤖 Prompt for AI Agents