Dawn Code Master

Dawn Code Master — hardened coding standards distilled from code-quality, python, typescript, python-testing, and code-smell-analyzer. Write, review, and refactor code with consistent quality across Python and TypeScript. Follow this skill for every new file, every review, every PR.

5 skills → 1. Integrated coding standards for Python & TypeScript.

Pocket Checklist (every commit)

text

[ ] py_compile / tsc — syntax clean
[ ] pytest pass
[ ] Type hints on all public functions
[ ] No bare except / no `any`
[ ] No hardcoded secrets
[ ] f-strings / template literals — never format() or %
[ ] pathlib / fs paths — never os.path
[ ] Docstrings on all public APIs
[ ] No function > 30 lines

---

1. Universal Principles (all languages)

Naming

Construct	Convention	Example
variables / functions	snake_case / camelCase⁽¹⁾	etf_rotator() / getEtfData()
classes / types	PascalCase	class EtfPortfolio
constants	UPPER_CASE	MAX_WEIGHT = 0.40
private	_ prefix	_validate()

⁽¹⁾ Python → snake_case, TypeScript → camelCase.

Comment & Docstring Standard

python

# Python docstring (Google-style)
def rebalance(code: str, target_pct: float) -> dict:
    """Rebalance ETF position to target weight.

    Args:
        code: ETF code, e.g. "515790".
        target_pct: Target allocation as decimal 0-1.

    Returns:
        {order_id, filled_qty, avg_price}

    Raises:
        ValueError: If target_pct > max_single_weight.
    """

typescript

// TypeScript JSDoc
/** Rebalance ETF position to target weight. */
export function rebalance(code: string, targetPct: number): OrderResult

Error Handling

✅ except Exception: — never bare except: (catches SystemExit, KeyboardInterrupt) ✅ Always log or re-raise — never silent except: pass ✅ Type-specific errors: ValueError / TypeError / custom exceptions

python

# ❌ Bad
try:
    result = api.buy(code, qty)
except:
    pass

# ✅ Good
try:
    result = api.buy(code, qty)
except ApiError as e:
    log(f"Buy failed: {e}")
    raise

Security Guardrails

• No secrets in code. Use env vars or .env files.
• Validate inputs. Never trust user/external data.
• Least privilege. Only request permissions you actually use.
• No credentials in logs, screenshots, or test fixtures.

---

2. Python (PEP 8 + Modern Patterns)

Style

• 4-space indent, 88-char line limit (Black default)
• Imports: stdlib → third-party → local, alphabetized
• Two blank lines before top-level defs, one within class

Pythonic Patterns

python

# ✅ Comprehensions over loops
squares = [x**2 for x in range(10)]
lookup = {item.id: item for item in items}

# ✅ Context managers for I/O
with open(path, encoding="utf-8") as f:
    data = f.read()

# ✅ Unpacking & walrus
first, *rest = items
if match := re.search(pattern, text):
    print(match.group())

# ✅ EAFP (Easier to Ask Forgiveness than Permission)
try:
    value = d[key]
except KeyError:
    value = default

# ✅ f-strings
msg = f"{name} has {count} items"

# ✅ pathlib
from pathlib import Path
config = Path.home() / ".config" / "app.json"

# ✅ dataclasses
@dataclass
class Position:
    code: str
    qty: int
    cost: float

# ✅ enumerate, zip, itertools
for i, item in enumerate(items):
    ...
for a, b in zip(xs, ys, strict=True):
    ...

Anti-patterns to Avoid

python

# ❌ Mutable defaults
def bad(items=[]):      # Shared across calls!

def good(items=None):
    items = items or []

# ❌ Bare except
try:
    ...
except:  # Catches SystemExit, KeyboardInterrupt

# ❌ from module import *
# ❌ == None  (use `is None`)
# ❌ len(x) == 0  (use `not x`)
# ❌ String concat in loops  (use join)
# ❌ Global mutable state

Python Version

• Minimum: Python 3.10+ (3.9 EOL Oct 2025)
• Target: 3.11-3.13 for new code
• Use modern features: match statements, | union syntax, type hints

---

3. TypeScript (Strict Mode)

Core Rules

• Stop using any — unknown forces narrowing, any silently breaks safety
• Prefer const over let — enables literal inference
• as const on config objects / tuples to preserve literals
• satisfies over type annotation when you need both checking + literal preservation

Narrowing

typescript

// ❌ filter(Boolean) doesn't narrow type
items.filter(Boolean)

// ✅ Use type predicate
items.filter((x): x is T => Boolean(x))

// ❌ Object.keys returns string[]
const keys = Object.keys(obj)  // string[], not (keyof typeof obj)[]

// ✅ Exhaustive discriminated union
switch (event.kind) {
  case "buy": return handleBuy(event);
  case "sell": return handleSell(event);
  default: const _exhaustive: never = event;
}

Null Safety

• ?. returns undefined (not null) — matters for APIs
• ?? catches null/undefined only — || catches all falsy
• ! non-null assertion is last resort — prefer narrowing / early return

Module Boundaries

• import type for type-only imports — stripped at runtime
• Re-export types: export type { X } — prevents accidental runtime dep
• .d.ts augmentation: declare module with exact module path

---

4. Testing (pytest)

Quickstart

bash

pytest -v                                    # run all, verbose
pytest test_guardrails.py -k "blacklist"     # filter tests
pytest --cov=scripts --cov-report=term        # coverage
pytest -x --tb=short                          # stop on first fail

Patterns

python

import pytest
from unittest.mock import patch

# Parametrize
@pytest.mark.parametrize("code,expected", [
    ("688001", False), ("600519", True),
])
def test_blacklist(code, expected):
    assert check_blacklist(code)[0] == expected

# Mock
@patch("module.api_buy")
def test_buy_fails_gracefully(mock_buy):
    mock_buy.side_effect = ApiError("timeout")
    result = execute_trade("515790", 100)
    assert result["status"] == "error"

# Fixture
@pytest.fixture
def sample_state():
    return {"holdings": {}, "cash": 100000}

def test_empty_portfolio(sample_state):
    assert total_weight(sample_state) == 0

Coverage Targets

• Core logic: 90%+ (guardrails, strategy decisions, scoring)
• I/O wrappers: 70%+ (API calls, file I/O with mocking)
• UI / scripts: 50%+ (integration-style)

---

5. Code Smell & Refactoring

Every PR Review: Smell Checklist

Smell	Fix
Function > 30 lines	Extract smaller functions
Nested if > 3 deep	Early return / guard clauses
Magic numbers	Named constants
Duplicate code	Extract helper / DRY
Long param list (>3)	Dataclass / config object
Mixed error handling	Consistent try/except pattern
No tests for new logic	Add pytest parametrize
Hardcoded config	Move to config file / env var

Refactoring Process

1. Read the function — understand what it does
2. Write tests to lock current behavior
3. Extract coherent chunks into named functions
4. Rename variables/helpers to be self-documenting
5. Verify — tests still pass, output unchanged
6. Commit — one atomic change per refactor

SOLID (Simple version)

• S — One reason to change per module
• O — Extend with new code, not by modifying working code
• L — Subtypes must be substitutable for base types
• I — Small, focused interfaces over one big one
• D — Depend on abstractions, not concrete implementations

---

Reference Files

File	Source Skill
references/python-guide.md	Full PEP 8 + Pythonic patterns reference
references/typescript-guide.md	Generics, utility types, declaration files
references/pytest-guide.md	Mocking, fixtures, async tests, coverage
references/security-checklist.md	Security validation, threat modeling

---

Changelog

v1.0.0 (2026-07-06)

• Integrated 5 skills: code-quality + python + typescript + python-testing + code-smell-analyzer
• Universal principles across Python and TypeScript
• Pocket checklist for every commit
• Refactoring process with smell checklist