@yaawn/workflow 0.0.0-stage → 0.3.1

package/agents/skills/yaawn-clean-code/references/error-handling.md

@@ -0,0 +1,151 @@
+# Error Handling
+
+Error handling is important, but if it obscures logic, it's wrong.
+
+> Source: Robert C. Martin, _Clean Code_ — Chapter 7: Error Handling
+
+## Rules
+
+### Use exceptions rather than return codes
+
+Returning error codes leads to deeply nested structures and forces callers to handle errors immediately.
+
+```typescript
+// Bad — error codes force nested handling
+function login(dto: AuthDto): ResponseCode {
+  if (!dto.email || !dto.password) return ResponseCode.BadRequest;
+  const user = userRepository.get(dto);
+  if (!user) return ResponseCode.UserNotFound;
+  if (!matchPassword(user.password, dto.password)) return ResponseCode.WrongPassword;
+  setUserSession(user);
+  return ResponseCode.Success;
+}
+
+// Good — exceptions separate the happy path from error handling
+function login(dto: AuthDto): void {
+  if (!dto.email || !dto.password) {
+    throw new BadRequestError('Email and password are required');
+  }
+  const user = userRepository.get(dto);
+  if (!user) {
+    throw new UserNotFoundError('Invalid username or password');
+  }
+  if (!matchPassword(user.password, dto.password)) {
+    throw new AuthError('Invalid username or password');
+  }
+  setUserSession(user);
+}
+```
+
+### Extract try/catch bodies
+
+If `try` exists in a function, it should be the first keyword. Extract the body into a separate function. Nothing should follow the catch/finally block.
+
+```typescript
+// Bad
+function performLogin(dto: AuthDto): void {
+  try {
+    login(dto);
+  } catch (error) {
+    logger.error(error);
+  }
+  redirect(); // should be inside the try block
+}
+
+// Good
+function performLogin(dto: AuthDto): void {
+  try {
+    login(dto);
+    redirect();
+  } catch (error) {
+    logger.error(error);
+  }
+}
+```
+
+### Provide context with exceptions
+
+Each exception should provide enough context to determine the source and location of the error. Include the root cause when wrapping errors.
+
+```typescript
+// Bad — loses the original stack trace
+catch (error) {
+  throw new AuthError('Cannot get user');
+}
+
+// Good — preserves the cause chain
+catch (error) {
+  throw new AuthError('Cannot get user', { cause: error });
+}
+```
+
+### Define exception classes by the caller's needs
+
+Wrap third-party API errors into a single common exception type. This minimizes dependencies, makes it easier to switch libraries, and simplifies mocking in tests.
+
+```typescript
+// Bad — caller must handle every specific error
+try {
+  port.open();
+} catch (error) {
+  if (error instanceof DeviceResponseError) {
+    /* ... */
+  }
+  if (error instanceof UnlockedError) {
+    /* ... */
+  }
+  if (error instanceof GMXError) {
+    /* ... */
+  }
+}
+
+// Good — wrapper normalizes the error surface
+class PortDeviceFailure extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+  }
+}
+
+// Inside the port module
+try {
+  // low-level operations
+} catch (error) {
+  throw new PortDeviceFailure('Device communication failed', { cause: error });
+}
+```
+
+### Don't return null
+
+Returning `null` leads to null-check cascades. Prefer throwing an exception or returning a special-case object (empty array, empty object, `Optional`/`Result` types).
+
+```typescript
+// Bad
+function getEmployees(): Employee[] | null {
+  return null;
+}
+
+const employees = getEmployees();
+if (employees !== null) {
+  for (const e of employees) {
+    /* ... */
+  }
+}
+
+// Good
+function getEmployees(): Employee[] {
+  return [];
+}
+
+const employees = getEmployees();
+for (const e of employees) {
+  /* ... */
+}
+```
+
+### Don't pass null
+
+Passing `null` into methods is worse than returning it. Forbid passing `null` by default. Use TypeScript's `strictNullChecks` to enforce this at compile time.
+
+### Fail fast
+
+Detect problems as early as possible. Validate inputs at system boundaries. When something is wrong, fail immediately with a clear error rather than propagating corrupted state.

package/agents/skills/yaawn-clean-code/references/formatting.md

@@ -0,0 +1,146 @@
+# Formatting
+
+Code formatting is important. It is about **communication**, and communication is the professional developer's first order of business.
+
+> Source: Robert C. Martin, _Clean Code_ — Chapter 5: Formatting
+
+## Rules
+
+### Vertical openness between concepts
+
+Use blank lines to separate distinct concepts: imports, property blocks, methods. Each blank line is a visual cue identifying a new concept.
+
+```typescript
+import { Injectable } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+
+@Injectable({ providedIn: 'root' })
+export class UserService {
+  readonly apiUrl = '/api/users';
+  readonly defaultPageSize = 20;
+
+  constructor(private http: HttpClient) {}
+
+  getUsers(): Observable<User[]> {
+    // ...
+  }
+
+  getUser(id: string): Observable<User> {
+    // ...
+  }
+}
+```
+
+### Use vertical density for tightly related concepts
+
+Lines of code that are tightly related should appear vertically dense — don't separate them with blank lines or useless comments.
+
+```typescript
+// Bad — comments break the association
+/** The class name of the reporter listener */
+private className: string;
+
+/** The properties of the reporter listener */
+private properties: Property[] = [];
+
+// Good — tightly related, no visual noise
+private className: string;
+private properties: Property[] = [];
+```
+
+### Place dependent functions vertically close
+
+If one function calls another, they should be vertically close. The **caller should appear above the callee** (stepdown rule).
+
+```typescript
+// Good — createUser calls validateUser and sendNotification, which follow it
+createUser(dto: UserDto): void {
+  this.validateUser(dto);
+  this.userRepository.save(dto);
+  this.sendNotification(dto);
+}
+
+private validateUser(dto: UserDto): void { /* ... */ }
+
+private sendNotification(dto: UserDto): void { /* ... */ }
+```
+
+### Declare variables close to their usage
+
+Don't declare all variables at the top of a function. Declare them where they are first used.
+
+```typescript
+// Bad — response declared too early
+function userStatistics(users: User[]): UserStatisticResponse {
+  const response = new UserStatisticResponse();
+  const admins: User[] = [];
+  const guests: User[] = [];
+  // ... loop ...
+  response.admins = admins;
+  response.guests = guests;
+  return response;
+}
+
+// Good — response declared where first needed
+function userStatistics(users: User[]): UserStatisticResponse {
+  const admins: User[] = [];
+  const guests: User[] = [];
+
+  for (const user of users) {
+    if (isAdmin(user)) admins.push(user);
+    else guests.push(user);
+  }
+
+  const response = new UserStatisticResponse();
+  response.admins = admins;
+  response.guests = guests;
+  return response;
+}
+```
+
+### Use horizontal whitespace to show association
+
+- **No** space between function name and opening parenthesis (they are closely related)
+- **Yes** space around assignment operators (left and right sides are distinct)
+- **Yes** space after commas in argument lists (arguments are separate entities)
+
+### Avoid horizontal alignment
+
+Don't align variable names or types into columns — it draws the eye to the wrong thing and is hard to maintain.
+
+```typescript
+// Bad
+private socket:          Socket;
+private input:           InputStream;
+private output:          OutputStream;
+
+// Good
+private socket: Socket;
+private input: InputStream;
+private output: OutputStream;
+```
+
+### Don't break indentation
+
+Never collapse short functions or if statements onto one line. Use proper block formatting.
+
+```typescript
+// Bad
+constructor(parent: ParentWidget) { super(parent); }
+render(): string { return ''; }
+
+// Good
+constructor(parent: ParentWidget) {
+  super(parent);
+}
+
+render(): string {
+  return '';
+}
+```
+
+### Follow team rules
+
+Individual style preferences give way to team conventions. The codebase should look like it was written by one person, not a committee of disagreeing individuals.
+
+> **Project convention:** This codebase enforces formatting via `.editorconfig` and ESLint. Follow the established conventions.

package/agents/skills/yaawn-clean-code/references/functions.md

@@ -0,0 +1,261 @@
+# Functions
+
+Functions should be small and do one thing.
+
+> Source: Robert C. Martin, _Clean Code_ — Chapter 3: Functions
+
+## Rules
+
+### Small
+
+The first rule of functions is that they should be small. The second rule is that they should be smaller than that. Aim for **15 lines or fewer**. If a function grows beyond that, start asking questions.
+
+### Do one thing
+
+A function should do one thing, do it well, and do it only. If you can extract another function from it with a name that is **not merely a restatement** of its implementation, it's doing more than one thing.
+
+### One level of abstraction per function (SLAP)
+
+Statements within a function should all be at the same level of abstraction. Don't mix high-level orchestration with low-level details.
+
+```typescript
+// Bad — mixed abstraction levels
+function getUserReportDtos(): UserReportDto[] {
+  const users = CsvUtils.read('user.csv', User);
+  const dtos: UserReportDto[] = [];
+  if (users && users.length > 0) {
+    for (const user of users) {
+      const dto: UserReportDto = { name: user.name, email: user.email };
+      dtos.push(dto);
+    }
+  }
+  return dtos;
+}
+
+// Good — each function is at one level of abstraction
+function getUserReportDtos(): UserReportDto[] {
+  const users = readUsersFromCsvFile('user.csv');
+  return mapToUserReportDtos(users);
+}
+
+function readUsersFromCsvFile(fileName: string): User[] {
+  return CsvUtils.read(fileName, User);
+}
+
+function mapToUserReportDtos(users: User[]): UserReportDto[] {
+  if (!isValid(users)) {
+    return [];
+  }
+  return users.map(mapToUserReportDto);
+}
+```
+
+### The stepdown rule
+
+Read code from top to bottom. Every function should be followed by those at the next level of abstraction.
+
+### Avoid nested structures
+
+Use early returns (guard clauses) instead of deeply nested if statements.
+
+```typescript
+// Bad
+function isUserValid(userDto: UserDto): boolean {
+  if (userDto) {
+    if (userDto.password) {
+      if (userDto.email) {
+        return !userService.isEmailExists(userDto.email);
+      }
+    }
+  }
+  return false;
+}
+
+// Good
+function isUserValid(userDto: UserDto): boolean {
+  if (!userDto) return false;
+  if (!userDto.password) return false;
+  if (!userDto.email) return false;
+  return !userService.isEmailExists(userDto.email);
+}
+```
+
+### Avoid negative conditionals
+
+Negatives are harder to understand than positives.
+
+```typescript
+// Bad
+if (!isNotEmpty(users)) {
+}
+
+// Good
+if (isEmpty(users)) {
+}
+```
+
+### Replace switch statements with polymorphism
+
+Switch statements violate SRP and OCP — they grow with every new type. Use polymorphism instead.
+
+```typescript
+// Bad
+function perform(vehicle: Vehicle): void {
+  switch (vehicle.type) {
+    case 'bicycle':
+      vehicle.ride();
+      break;
+    case 'car':
+      vehicle.drive();
+      break;
+    case 'airplane':
+      vehicle.fly();
+      break;
+  }
+}
+
+// Good — each type knows how to perform
+interface VehicleAction {
+  perform(): void;
+}
+
+class Bicycle implements VehicleAction {
+  perform(): void {
+    this.ride();
+  }
+}
+```
+
+### Use descriptive names
+
+A long descriptive name is better than a short enigmatic name. A long descriptive name is better than a long descriptive comment.
+
+```typescript
+// Bad
+function createPrd(): void {} // Create a product
+
+// Good
+function createProduct(): void {}
+```
+
+Be consistent: use the same verbs across the codebase (`get` vs `fetch`, `set` vs `update`, `add` vs `append`).
+
+### Prefer fewer arguments
+
+Zero arguments (niladic) is ideal. One (monadic) and two (dyadic) are fine. Three (triadic) should be avoided. More than three requires strong justification.
+
+When a function needs many arguments, wrap them in an object.
+
+```typescript
+// Bad
+function createUser(username: string, password: string, gender: Gender, roleId: number): void {}
+
+// Good
+function createUser(userDto: CreateUserDto): void {}
+```
+
+### Avoid flag arguments
+
+A boolean argument declares the function does more than one thing. Split into two functions.
+
+```typescript
+// Bad
+function execute(isTestSuite: boolean): void {
+  if (isTestSuite) {
+    /* suite logic */
+  } else {
+    /* single test logic */
+  }
+}
+
+// Good
+function executeTestSuite(): void {}
+function executeSingleTest(): void {}
+```
+
+### Have no side effects
+
+A function promises to do one thing — don't do hidden things.
+
+```typescript
+// Bad — "get" function secretly updates the database
+function getUserByEmail(email: string): User {
+  const user = userRepository.getUserByEmail(email);
+  user.lastAccess = new Date();
+  userRepository.update(user);
+  return user;
+}
+```
+
+### Avoid output arguments
+
+Don't mutate arguments passed to a function. If a function must change state, have it change the state of its owning object.
+
+```typescript
+// Bad
+function appendFooter(report: StringBuffer): void;
+
+// Good
+report.appendFooter();
+```
+
+### Separate command from query
+
+Functions should either **do something** or **answer something**, but not both.
+
+```typescript
+// Bad
+function set(attribute: string, value: string): boolean;
+if (set('username', 'gpcoder')) {
+}
+
+// Good
+if (attributeExists('username')) {
+  setAttribute('username', 'gpcoder');
+}
+```
+
+### Prefer exceptions to returning error codes
+
+Error codes lead to deeply nested structures and violate command-query separation.
+
+```typescript
+// Bad
+function login(dto: AuthDto): ResponseCode {
+  if (!dto.email || !dto.password) return ResponseCode.BadRequest;
+  // ...
+  return ResponseCode.Success;
+}
+
+// Good
+function login(dto: AuthDto): void {
+  if (!dto.email || !dto.password) {
+    throw new BadRequestError('Email and password are required');
+  }
+  // ...
+}
+```
+
+### Extract try/catch bodies
+
+If `try` exists in a function, it should be the first word. Extract the body into its own function.
+
+```typescript
+// Good
+function performLogin(dto: AuthDto): void {
+  try {
+    login(dto);
+    redirect();
+  } catch (error) {
+    logger.error(error);
+  }
+}
+```
+
+### DRY — Don't Repeat Yourself
+
+Duplication is the root of all evil in software. Every piece of knowledge must have a single, unambiguous representation.
+
+### Write, test, and refine
+
+> "When I write functions, they come out long and complicated. But I also have unit tests that cover every one of those clumsy lines of code. So then I massage and refine that code, splitting out functions, changing names, eliminating duplication." — Robert C. Martin