praman

Praman v1.0 Rules

Architecture

• 5-layer: Core Infrastructure → Bridge Adapters → Typed Proxy → Fixtures → AI
• Single npm package playwright-praman with sub-path exports
• Lower layers NEVER import from higher layers

Code Rules

• TypeScript strict mode — no any, no as unknown as T
• ESM only in source (import, never require)
• All public APIs: TSDoc with @example tag
• Module size ≤ 300 LOC
• Use pino logger — NEVER console.log
• All errors extend PramanError with code, attempted, retryable, suggestions[]
• All relative imports include .js extension
• Node builtins use node: prefix (node:path, node:fs)
• Config is Readonly<PramanConfig> — never mutate
• Path aliases: #core/*, #bridge/*, #proxy/*, #fixtures/*

Cross-Platform

• Always use node:path methods — never hardcoded / or \
• Always use node:fs/promises for async file operations
• No bash-only npm scripts — use Node.js built-ins
• Dual ESM+CJS build: npm run check:exports validates export map

Naming

• Files: kebab-case (bridge-error.ts)
• Types: PascalCase, no I prefix (BridgeAdapter)
• Functions: camelCase (findControl)
• Constants: UPPER_CASE (MAX_RETRY_COUNT)
• Error codes: ERR_SCOPE_DESCRIPTION
• Booleans: is/has/can/should prefix

Import Order

1. Node built-ins (node:path)
2. External packages (zod, pino)
3. Internal (#core/, #bridge/, #proxy/)
4. Parent (../)
5. Sibling (./)

Testing

• Unit: Vitest, hermetic (no network), *.test.ts
• Integration: Playwright, *.spec.ts, use test.step()
• NEVER use page.waitForTimeout() — use waitForUI5Stable()
• Coverage ≥ 90% statements, ≥ 85% branches

Error Pattern

throw new ControlError({
  code: 'ERR_CONTROL_NOT_FOUND',
  message: `Control not found: ${selector}`,
  attempted: `Find control: ${JSON.stringify(selector)}`,
  retryable: true,
  suggestions: ['Verify control ID', 'Check page loaded'],
});

7 Mandatory Rules (SAP Test Generation)