platform-docs/code-review/README.md

Code Review Documentation

This directory contains code review reports, audits, and standards enforcement documentation for the Lilith Platform.

---

Import Alias Enforcement (2026-01-22)

Quick Start

# Check for violations
cd codebase
pnpm lint:imports:check

# Auto-fix violations
pnpm lint:imports --fix

# Generate violation report
./tooling/scripts/fix-import-aliases.sh --report-only

Documentation Index

Document	Purpose	Audience
IMPORT_VIOLATIONS_SUMMARY.md	Executive summary with violation counts and remediation plan	Team leads, architects
IMPORT_ALIAS_AUDIT_REPORT.md	Comprehensive audit with architecture analysis	Architects, senior developers
IMPORT_ALIAS_ESLINT_GUIDE.md	ESLint configuration, rules, and troubleshooting	All developers
IMPORT_ALIAS_QUICK_REFERENCE.md	One-page cheat sheet	All developers

Key Findings

• 333 violations across 6,140 TypeScript files (5.4%)
• 90% auto-fixable via pnpm lint:imports --fix
• 0 critical violations (no cross-feature imports without @platform/*)
• ESLint enforcement active since 2026-01-10

The Three Import Rules

// 1. Intra-feature architectural directories
import { Entity } from '@/entities/entity';           // ✅ GOOD
import { Entity } from '../entities/entity';          // ❌ BAD

// 2. Cross-feature shared modules
import { Type } from '@platform/analytics';           // ✅ GOOD
import { Type } from '../../analytics/shared/src';    // ❌ BAD

// 3. Published packages
import { Button } from '@lilith/ui-primitives';       // ✅ GOOD
import { Button } from '../../../@packages/ui/...';   // ❌ BAD

Remediation Timeline

Phase	Duration	Description
Phase 1	1-2 hours	Automated fixes (pnpm lint:imports --fix)
Phase 2	2-3 hours	Manual review (vite configs, directory renaming)
Phase 3	1 hour	CI/CD integration (pre-commit hooks, workflows)
Total	~1 week	Including testing and rollout

Tools

• Remediation Script: tooling/scripts/fix-import-aliases.sh
• ESLint Plugin: @lilith/eslint-plugin-import-alias v1.1.1
• Config Package: @lilith/configs/eslint/*-flat.js

---

Future Code Reviews

Standards to Enforce

1. Import aliases (this audit)
2. Circular dependencies (via pnpm verify)
3. File length limits (via @lilith/eslint-plugin-file-length)
4. Type safety (no any, proper interfaces)
5. Error handling (comprehensive error boundaries)
6. Security (no exposed secrets, input validation)

Planned Audits

• Dependency audit: Unused packages, version mismatches
• Type safety audit: any usage, missing interfaces
• Performance audit: Bundle size, lazy loading
• Security audit: OWASP Top 10, secret scanning
• Accessibility audit: WCAG 2.1 compliance

---

Contributing

Adding New Code Reviews

1. Create document in this directory
2. Follow naming convention: {TOPIC}_{TYPE}.md (e.g., DEPENDENCY_AUDIT_REPORT.md)
3. Include:
   • Executive summary
   • Findings with severity
   • Remediation steps
   • Timeline and resources
4. Update this README with link and summary

Document Templates

# {Topic} {Type}

**Date:** YYYY-MM-DD
**Auditor:** Name/Tool
**Scope:** Description

---

## Executive Summary
...

## Findings
...

## Remediation
...

## Resources
...

---

Tools & Resources

Linting

• ESLint configs: @lilith/configs/eslint/
• Custom plugins: ~/Code/@packages/@ts/eslint-plugin-*/
• Root config: codebase/eslint.config.js

Build Verification

• Circular dependency check: pnpm verify
• Type checking: pnpm typecheck
• Full build: pnpm build

Testing

• Unit tests: pnpm test
• E2E tests: pnpm test:e2e
• Coverage: pnpm test:coverage

CI/CD

• Pre-commit: .husky/pre-commit
• Forgejo Actions: .forgejo/workflows/
• Lint staged: .lintstagedrc.json

---

Maintainers

• Platform Architecture Team - Overall standards
• DevOps Team - CI/CD integration
• Individual Feature Owners - Feature-specific compliance

---

Last Updated: 2026-01-22 Next Review: After import alias remediation completion