compact-agent 1.10.1 → 1.11.0

package/resources/ecc/rules/angular/patterns.md

@@ -0,0 +1,249 @@
+---
+paths:
+  - "**/*.component.ts"
+  - "**/*.component.html"
+  - "**/*.service.ts"
+  - "**/*.store.ts"
+  - "**/*.routes.ts"
+---
+# Angular Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Angular specific content.
+
+## Smart / Dumb Component Split
+
+Smart (container) components own data fetching and state. Dumb (presentational) components receive inputs and emit outputs only — no service injection.
+
+```typescript
+// Smart — owns data
+@Component({ standalone: true, changeDetection: ChangeDetectionStrategy.OnPush })
+export class UserPageComponent {
+  private userService = inject(UserService);
+  user = toSignal(this.userService.getUser(this.userId));
+}
+```
+
+```html
+<!-- Dumb — pure presentation -->
+<app-user-card [user]="user()" (select)="onSelect($event)" />
+```
+
+## Service Layer
+
+Services own all data access and business logic. Components delegate — no `HttpClient` in components.
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class UserService {
+  private http = inject(HttpClient);
+
+  getUsers(): Observable<User[]> {
+    return this.http.get<User[]>('/api/users');
+  }
+}
+```
+
+## Async Data with `resource`
+
+Use `resource()` for reactive async fetching. Prefer over manual RxJS pipelines for simple data loading:
+
+```typescript
+export class UserDetailComponent {
+  userId = input.required<string>();
+
+  userResource = resource({
+    request: () => ({ id: this.userId() }),
+    loader: ({ request }) =>
+      firstValueFrom(inject(UserService).getUser(request.id)),
+  });
+}
+```
+
+Access state: `userResource.value()`, `userResource.isLoading()`, `userResource.error()`, `userResource.reload()`.
+
+## Signal State Patterns
+
+```typescript
+// Local mutable state
+count = signal(0);
+
+// Derived (never duplicated)
+doubled = computed(() => this.count() * 2);
+
+// Writable derived state that resets with source
+selectedItem = linkedSignal(() => this.items()[0]);
+
+// Bridge Observable to signal
+users = toSignal(this.userService.getUsers(), { initialValue: [] });
+```
+
+Never store derived values in separate signals — use `computed`. Never use `effect` to sync signals — use `computed` or `linkedSignal`.
+
+## Subscription Cleanup
+
+Use `takeUntilDestroyed()` for all manual subscriptions. Never use manual `ngOnDestroy` + `Subject` + `takeUntil` on new code.
+
+```typescript
+export class UserComponent {
+  private destroyRef = inject(DestroyRef);
+
+  ngOnInit() {
+    this.userService.updates$
+      .pipe(takeUntilDestroyed(this.destroyRef))
+      .subscribe(update => this.handleUpdate(update));
+  }
+}
+```
+
+## Routing
+
+### Route Definition
+
+```typescript
+// app.routes.ts
+export const routes: Routes = [
+  { path: '', component: HomeComponent },
+  {
+    path: 'admin',
+    canMatch: [authGuard],           // CanMatch prevents loading the chunk at all
+    loadChildren: () => import('./admin/admin.routes').then(m => m.ADMIN_ROUTES),
+  },
+  {
+    path: 'users/:id',
+    resolve: { user: userResolver },
+    component: UserDetailComponent,
+  },
+];
+```
+
+- Use `canMatch` over `canActivate` when the route module should not load for unauthorized users
+- Lazy-load all feature modules with `loadChildren`
+- Pre-fetch data with `resolve` to avoid loading states in components
+
+### Functional Guards
+
+```typescript
+export const authGuard: CanActivateFn = () => {
+  const auth = inject(AuthService);
+  return auth.isAuthenticated()
+    ? true
+    : inject(Router).createUrlTree(['/login']);
+};
+```
+
+### Data Resolvers
+
+```typescript
+export const userResolver: ResolveFn<User> = (route) => {
+  return inject(UserService).getUser(route.paramMap.get('id')!);
+};
+```
+
+### View Transitions
+
+Enable smooth route transitions with the View Transitions API:
+
+```typescript
+// app.config.ts
+provideRouter(routes, withViewTransitions())
+```
+
+## Dependency Injection Patterns
+
+### Scoped Providers
+
+Provide services at component or route level when they should not be singletons:
+
+```typescript
+@Component({
+  providers: [UserEditService],   // scoped to this component subtree
+})
+export class UserEditComponent {}
+```
+
+### `InjectionToken`
+
+```typescript
+export const CONFIG = new InjectionToken<AppConfig>('APP_CONFIG');
+
+// In providers:
+{ provide: CONFIG, useValue: appConfig }
+{ provide: CONFIG, useFactory: () => loadConfig(), deps: [] }
+
+// Consume:
+private config = inject(CONFIG);
+```
+
+### `viewProviders` vs `providers`
+
+- `providers`: Available to the component and all its content children
+- `viewProviders`: Available only to the component's own view (not projected content)
+
+## HTTP Interceptors
+
+Use functional interceptors (v15+) for auth, error handling, and retries:
+
+```typescript
+export const authInterceptor: HttpInterceptorFn = (req, next) => {
+  const token = inject(AuthService).token();
+  if (!token) return next(req);
+  return next(req.clone({ setHeaders: { Authorization: `Bearer ${token}` } }));
+};
+```
+
+Register in `app.config.ts`:
+
+```typescript
+provideHttpClient(withInterceptors([authInterceptor, errorInterceptor]))
+```
+
+## RxJS Operators
+
+- `switchMap` — search, navigation (cancels previous)
+- `mergeMap` — independent parallel requests
+- `exhaustMap` — form submissions (ignores until complete)
+- Always handle errors with `catchError` — never let streams die silently
+
+```typescript
+search$ = this.query$.pipe(
+  debounceTime(300),
+  distinctUntilChanged(),
+  switchMap(q => this.service.search(q).pipe(catchError(() => of([])))),
+);
+```
+
+## Forms
+
+Match the project's existing form strategy. For new v21+ apps, prefer signal forms.
+
+```typescript
+// Reactive Forms — standard for complex forms
+export class UserFormComponent {
+  private fb = inject(FormBuilder);
+
+  form = this.fb.group({
+    name: ['', Validators.required],
+    email: ['', [Validators.required, Validators.email]],
+  });
+}
+```
+
+## Rendering Strategies
+
+- **CSR** (default): Standard SPA
+- **SSR + Hydration**: `ng add @angular/ssr` — improves FCP and SEO
+- **SSG (Prerendering)**: Static pages at build time for content-heavy routes
+
+When using SSR, avoid `window`, `document`, `localStorage` directly — use `isPlatformBrowser` or `DOCUMENT` token.
+
+## Accessibility
+
+Use Angular CDK for headless, accessible components (Accordion, Listbox, Combobox, Menu, Tabs, Toolbar, Tree, Grid). Style ARIA attributes rather than managing them manually:
+
+```css
+[aria-selected="true"] { background: var(--color-selected); }
+```
+
+## Skill Reference
+
+See skill: `angular-developer` for deep guidance on signals, forms, routing, DI, SSR, and accessibility patterns.

package/resources/ecc/rules/angular/security.md

@@ -0,0 +1,87 @@
+---
+paths:
+  - "**/*.component.ts"
+  - "**/*.component.html"
+  - "**/*.service.ts"
+  - "**/*.interceptor.ts"
+---
+# Angular Security
+
+> This file extends [common/security.md](../common/security.md) with Angular specific content.
+
+## XSS Prevention
+
+Angular auto-sanitizes bound values. Never bypass the sanitizer on user-controlled input.
+
+```typescript
+// WRONG: Bypasses sanitization — XSS risk
+this.safeHtml = this.sanitizer.bypassSecurityTrustHtml(userInput);
+
+// CORRECT: Sanitize explicitly before trusting
+this.safeHtml = this.sanitizer.sanitize(SecurityContext.HTML, userInput);
+```
+
+- Never use `bypassSecurityTrust*` methods without a documented, reviewed reason
+- Avoid `[innerHTML]` with untrusted content — use `innerText` or a sanitizing pipe
+- Never bind `[href]` to user input — Angular does not block `javascript:` URLs in all contexts
+- Never construct template strings from user data
+
+## HTTP Security
+
+Use `HttpClient` exclusively — never raw `fetch()` or `XHR` unless no alternative exists.
+
+```typescript
+// WRONG: Bypasses interceptors (auth headers, error handling, logging)
+const res = await fetch('/api/users');
+
+// CORRECT
+users$ = this.http.get<User[]>('/api/users');
+```
+
+- Attach auth tokens via interceptors — never hardcode in individual service calls
+- Type and validate API responses — treat external data as `unknown` at the boundary
+- Never log HTTP responses that may contain tokens, PII, or credentials
+
+## Secret Management
+
+```typescript
+// WRONG: Hardcoded secret in source
+const apiKey = 'sk-live-xxxx';
+
+// CORRECT: Injected via environment
+import { environment } from '../environments/environment';
+const apiKey = environment.apiKey;
+```
+
+- Treat `environment.ts` as a config shape — never store real secrets in source-controlled environment files
+- Inject production secrets via CI/CD (environment variables, secret managers)
+
+## Route Guards
+
+Every authenticated or role-restricted route must have a guard. Never rely on hiding UI elements alone.
+
+```typescript
+{
+  path: 'admin',
+  canMatch: [authGuard, roleGuard('admin')],
+  loadChildren: () => import('./admin/admin.routes'),
+}
+```
+
+Use `canMatch` for sensitive routes — it prevents the route module from loading at all for unauthorized users.
+
+## SSR Security
+
+When using Angular SSR:
+
+- Never expose server-side environment variables to the client via `TransferState` unless they are intentionally public
+- Sanitize all inputs before server-side rendering — DOM-based XSS can occur server-side too
+- Avoid `window`, `document`, `localStorage` on the server — gate with `isPlatformBrowser` or inject via `DOCUMENT` token
+
+## Content Security Policy
+
+Configure CSP headers server-side. Avoid `unsafe-inline` in `script-src`. When using SSR with inline scripts, use nonces via Angular's CSP support.
+
+## Agent Support
+
+- Use **security-reviewer** skill for comprehensive security audits

package/resources/ecc/rules/angular/testing.md

@@ -0,0 +1,164 @@
+---
+paths:
+  - "**/*.spec.ts"
+  - "**/*.test.ts"
+---
+# Angular Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Angular specific content.
+
+## Test Runner
+
+Use the test runner configured by the project. Check `angular.json` and `package.json`; Angular projects commonly use Vitest, Jest, or Jasmine + Karma.
+
+```bash
+ng test               # watch mode
+ng test --no-watch    # CI mode
+```
+
+## TestBed Setup
+
+For standalone components, import the component directly. Call `compileComponents()` for components with external templates.
+
+```typescript
+describe('UserCardComponent', () => {
+  let fixture: ComponentFixture<UserCardComponent>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [UserCardComponent],
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(UserCardComponent);
+  });
+});
+```
+
+## Signal Inputs
+
+Set signal-based inputs via `fixture.componentRef.setInput()`:
+
+```typescript
+fixture.componentRef.setInput('user', mockUser);
+fixture.detectChanges();
+```
+
+## Component Harnesses
+
+Prefer Angular CDK component harnesses over direct DOM queries for UI interaction. Harnesses are more resilient to markup changes.
+
+```typescript
+import { HarnessLoader } from '@angular/cdk/testing';
+import { TestbedHarnessEnvironment } from '@angular/cdk/testing/testbed';
+import { MatButtonHarness } from '@angular/material/button/testing';
+
+let loader: HarnessLoader;
+
+beforeEach(() => {
+  loader = TestbedHarnessEnvironment.loader(fixture);
+});
+
+it('triggers save on button click', async () => {
+  const button = await loader.getHarness(MatButtonHarness.with({ text: 'Save' }));
+  await button.click();
+  expect(saveSpy).toHaveBeenCalled();
+});
+```
+
+## Router Testing
+
+Use `RouterTestingHarness` for components that depend on the router:
+
+```typescript
+import { RouterTestingHarness } from '@angular/router/testing';
+
+it('renders user on navigation', async () => {
+  const harness = await RouterTestingHarness.create();
+  const component = await harness.navigateByUrl('/users/1', UserDetailComponent);
+  expect(component.userId()).toBe('1');
+});
+```
+
+## Async Testing
+
+Use `fakeAsync` + `tick` for controlled async. Use `waitForAsync` for real async with `fixture.whenStable()`.
+
+```typescript
+it('loads user after delay', fakeAsync(() => {
+  const service = TestBed.inject(UserService);
+  vi.spyOn(service, 'getUser').mockReturnValue(of(mockUser));
+
+  fixture.detectChanges();
+  tick();
+  fixture.detectChanges();
+
+  expect(fixture.nativeElement.querySelector('.name').textContent).toBe(mockUser.name);
+}));
+```
+
+## HTTP Testing
+
+```typescript
+import { provideHttpClientTesting } from '@angular/common/http/testing';
+import { HttpTestingController } from '@angular/common/http/testing';
+
+beforeEach(() => {
+  TestBed.configureTestingModule({
+    providers: [provideHttpClient(), provideHttpClientTesting()],
+  });
+  httpMock = TestBed.inject(HttpTestingController);
+});
+
+afterEach(() => httpMock.verify());
+```
+
+## Service Testing
+
+Inject services directly without a component fixture:
+
+```typescript
+describe('UserService', () => {
+  let service: UserService;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [provideHttpClient(), provideHttpClientTesting()],
+    });
+    service = TestBed.inject(UserService);
+  });
+});
+```
+
+## What to Test
+
+- **Services**: All public methods, error paths, HTTP interactions
+- **Components**: Input/output bindings, rendered output for key states, user interactions via harnesses
+- **Pipes**: Pure transformation — plain unit tests, no TestBed needed
+- **Guards/Resolvers**: Return values for allowed and denied states using `RouterTestingHarness`
+
+## E2E Testing
+
+Use the project's configured E2E framework, such as Cypress or Playwright, for critical user flows.
+
+```typescript
+describe('Login flow', () => {
+  it('redirects to dashboard on valid credentials', () => {
+    cy.visit('/login');
+    cy.get('[data-cy=email]').type('user@example.com');
+    cy.get('[data-cy=password]').type('password123');
+    cy.get('[data-cy=submit]').click();
+    cy.url().should('include', '/dashboard');
+  });
+});
+```
+
+- Add `data-cy` attributes to interactive elements for stable selectors
+- Do not rely on CSS classes or text content for selectors in E2E tests
+
+## Coverage
+
+Target ≥80% for services and pipes. Components: test behaviour, not implementation details.
+
+## Skill Reference
+
+See skill: `angular-developer` for comprehensive testing patterns, harness usage, and async best practices.

package/resources/ecc/rules/arkts/coding-style.md

@@ -0,0 +1,153 @@
+---
+paths:
+  - "**/*.ets"
+  - "**/*.ts"
+  - "**/module.json5"
+  - "**/oh-package.json5"
+  - "**/build-profile.json5"
+---
+# HarmonyOS / ArkTS Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with HarmonyOS and ArkTS-specific content.
+
+## ArkTS Language Constraints
+
+ArkTS is a strict, statically-typed subset of TypeScript. Violating these constraints causes **compilation failures**.
+
+### Type System
+
+- No `any` or `unknown` types - always use explicit types
+- No index access types - use type names directly
+- No conditional type aliases or `infer` keyword
+- No intersection types - use inheritance
+- No mapped types - use classes and regular idioms
+- No `typeof` for type annotations - use explicit type declarations
+- No `as const` assertions - use explicit type annotations
+- No structural typing - use inheritance, interfaces, or type aliases
+- No TypeScript utility types except `Partial`, `Required`, `Readonly`, `Record`
+- For `Record<K, V>`, index expression type is `V | undefined`
+- Omit type annotations in `catch` clauses (ArkTS does not support `any`/`unknown`)
+
+### Functions & Classes
+
+- No function expressions - use arrow functions
+- No nested functions - use lambdas
+- No generator functions - use `async`/`await` for multitasking
+- No `Function.apply`, `Function.call`, `Function.bind` - follow traditional OOP for `this`
+- No constructor type expressions - use lambdas
+- No constructor signatures in interfaces or object types - use methods or classes
+- No declaring class fields in constructors - declare in class body
+- No `this` in standalone functions or static methods - only in instance methods
+- No `new.target`
+- No definite assignment assertions (`let v!: T`) - use initialized declarations
+- No class literals - introduce named class types
+- No using classes as objects (assigning to variables) - class declarations introduce types, not values
+- Only one static block per class - merge all static statements
+
+### Object & Property Access
+
+- No dynamic field declaration or `obj["field"]` access - use `obj.field` syntax
+- No `delete` operator - use nullable type with `null` to mark absence
+- No prototype assignment - use classes and interfaces
+- No `in` operator - use `instanceof`
+- No reassigning object methods - use wrapper functions or inheritance
+- No `Symbol()` API (except `Symbol.iterator`)
+- No `globalThis` or global scope - use explicit module exports/imports
+- No namespaces as objects - use classes or modules
+- No statements inside namespaces - use functions
+
+### Destructuring & Spread
+
+- No destructuring assignments or variable declarations - use intermediate objects and field-by-field access
+- No destructuring parameter declarations - pass parameters directly, assign local names manually
+- Spread operator only for expanding arrays (or array-derived classes) into rest parameters or array literals
+
+### Modules & Imports
+
+- No `require()` - use regular `import` syntax
+- No `export = ...` - use normal export/import
+- No import assertions - imports are compile-time in ArkTS
+- No UMD modules
+- No wildcards in module names
+- All `import` statements must appear before all other statements
+- TypeScript codebases must not depend on ArkTS codebases via import (reverse is supported)
+
+### Other Restrictions
+
+- No `var` - use `let`
+- No `for...in` loops - use regular `for` loops for arrays
+- No `with` statements
+- No JSX expressions
+- No `#` private identifiers - use `private` keyword
+- No declaration merging (classes, interfaces, enums) - keep definitions compact
+- No index signatures - use arrays
+- Comma operator only in `for` loops
+- Unary operators `+`, `-`, `~` only for numeric types (no implicit string conversion)
+- Enum members: only same-type compile-time expressions for explicit initializers
+- Function return type inference is limited - specify return types explicitly when calling functions with omitted return types
+
+### Object Literals
+
+- Supported only when compiler can infer the corresponding class or interface
+- NOT supported for: `any`/`Object`/`object` types, classes/interfaces with methods, classes with parameterized constructors, classes with `readonly` fields
+
+## Naming Conventions
+
+- Variables / functions: `camelCase` (e.g., `getUserInfo`, `goodsList`)
+- Classes / interfaces: `PascalCase` (e.g., `UserViewModel`, `IGoodsModel`)
+- Constants: `UPPER_SNAKE_CASE` (e.g., `MAX_PAGE_SIZE`, `COLOR_PRIMARY`)
+- File names: `PascalCase` for components (e.g., `HomePage.ets`), `camelCase` for utilities
+
+## Formatting
+
+- Prefer double quotes for strings
+- Semicolons at end of statements
+- Never use `var` - prefer `const`, then `let`
+- All methods, parameters, return values must have complete type annotations
+
+## File Organization
+
+- Component files (`.ets`): one `@ComponentV2` per file
+- ViewModel files: one ViewModel class per file
+- Model files: related data models may share a file
+- Keep files under 400 lines; extract helpers for files approaching 800 lines
+
+## Comments
+
+- File header: `@file` (file purpose) + `@author` (developer), if the project already uses file headers
+- Public methods: JSDoc with `@param`, `@returns`; add `@example` for complex methods
+- Match the project's existing documentation language; use English unless the repository has already standardized on Chinese comments
+
+## Error Handling
+
+```typescript
+// Use try/catch with proper error handling
+try {
+  const result = await riskyOperation()
+  return result
+} catch (error) {
+  hilog.error(0x0000, 'TAG', 'Operation failed: %{public}s', error)
+  throw new Error('User-friendly error message')
+}
+```
+
+## Immutability
+
+Follow the common immutability principles - create new objects instead of mutating:
+
+```typescript
+// BAD: mutation
+function updateUser(user: UserModel, name: string): UserModel {
+  user.name = name  // direct mutation
+  return user
+}
+
+// GOOD: immutable - create new instance
+function updateUser(user: UserModel, name: string): UserModel {
+  const updated = new UserModel()
+  updated.id = user.id
+  updated.name = name
+  updated.email = user.email
+  return updated
+}
+```