api-audit
/api-audit
Audytuje spójność powierzchni API i bezpieczeństwo typów: ocena projektów API, interfejsów i elegancji projektu.
- Autor
- nrdxp ↗
- Repozytorium
- predicate ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 31.08.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 31.08.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Audytuje spójność powierzchni API i bezpieczeństwo typów: ocena projektów API, interfejsów i elegancji projektu.
Oryginalny opis (EN)
Protocol for auditing API surface coherence and type safety. Trigger when: - Evaluating API designs, interface type safety, or design elegance. - Prompt contains: /api-audit, API surface, API coherence, type safety.
Jak działa
- Phase 0: Scope Definition
- Checkpoint: Present scope to user for approval before proceeding.
- Phase 1: Surface Discovery (Full Codebase Ingestion)
- Phase 2: Iterative Component Audit
- For each component, evaluate against all dimensions. Rate each: [PASS | WARN | FAIL]
- Checkpoint: Present findings for this component. Await acknowledgment before proceeding.
- Phase 3: Cross-Cutting Analysis
- Phase 4: Remediation Plan
- Checkpoint: Present remediation plan for user approval before any code changes.
- Appendix: Language-Specific Checklists
Podgląd SKILL.md
--- name: api-audit description: | Protocol for auditing API surface coherence and type safety. Trigger when: - Evaluating API designs, interface type safety, or design elegance. - Prompt contains: /api-audit, API surface, API coherence, type safety. --- # API Coherence Audit Protocol A thorough, piecemeal framework for auditing code API surfaces. Designed to maintain agent coherence by working iteratively through the codebase with explicit human checkpoints. > **Adversarial path anchor.** This lens is invoked on the Verification Dual's adversarial path ([rules.md](../../rules.md) §2 Invariant 1): when no deterministic evaluator can close an API-surface correctness condition, context-free agents using this protocol supply the decorrelated review. See [skills/refine/SKILL.md](../refine/SKILL.md) AUDIT §"Sibling Skills Consultation" for the wiring point. > **Guiding Principle:** An ideal API is minimal, well-scoped, type-safe, elegantly composable, and monosemic. It leverages language features to make error states unrepresentable. --- ## Phase 0: Scope Definition Before beginning, establish the audit scope with the user. Confirm: target language and version; type system strength; public API entry points; explicit exclusions (generated code, vendored deps); user-defined constraints (e.g., no breaking changes, no-std compatibility). ## **Checkpoint:** Present scope to user for approval before proceeding. ## Phase 1: Surface Discovery (Full Codebase Ingestion) **Objective:** Build a complete mental model of the public API surface before any analysis. ### 1.1 Enumerate Public Surface For each entry point, catalog: - [ ] **Exported Types:** Structs, enums, classes, interfaces, type aliases - [ ] **Exported Functions:** Free functions, associated functions, methods - [ ] **Exported Constants:** Public constants, static values - [ ] **Re-exports:** Items re-exported from internal modules - [ ] **Traits/Interfaces:** Abstractions meant for external implementation ### 1.2 Generate Surface Map Produce a structured inventory: ``` ## Module: `crate::auth` ### Types - `Principal` (struct) — L23-L45 - `AuthState` (enum) — L47-L62 ### Functions - `Principal::verify(&self, sig: &Signature) -> Result<()>` — L67 - `validate_token(token: &str) -> Result<Claims>` — L89 ### Traits - `Authenticator` — L12-L21 - `fn authenticate(&self, credentials: &Credentials) -> Result<Session>` ``` **Checkpoint:** Present surface map to user. Ask: 1. Is this complete? Are there missing entry points? 2. Are there items here that should NOT be public? --- ## Phase 2: Iterative Component Audit **Objective:** Audit each logical component systematically, one at a time. > **Coherence Strategy:** Analyze ONE component per iteration. Present findings. Await user acknowledgment before proceeding to the next. ### Audit Dimensions ## For each component, evaluate against all dimensions. Rate each: `[PASS | WARN | FAIL]` #### Dimension A: Minimal Surface (Encapsulation) The API should expose only what external consumers need. | Check | Description | Anti-Pattern | |:------|:------------|:-------------| | A.1 | Internal implementation details are hidden | `pub` on helper functions; `_internal` prefixes on public items | | A.2 | Configuration uses sensible defaults | Requiring 10 parameters when 2 would suffice | | A.3 | No "god objects" with excessive responsibility | Single type with 50+ methods across unrelated concerns | | A.4 | Private fields with controlled accessors where appropriate | All fields `pub` when mutation should be constrained | **Remediation Patterns:** - Use visibility modifiers (`pub(crate)`, `internal`, `private`) - Builder pattern for complex construction - Facade pattern to simplify overly complex subsystems --- #### Dimension B: Type Safety & Error Unrepresentability Leverage the type system to make invalid states impossible to construct. | Check | Description | Anti-Pattern | |:------|:------------|:-------------| | B.1 | Domain values use newtypes, not primitives | `user_id: String` instead of `UserId(String)` | | B.2 | Enums are exhaustive over valid states | Magic strings like `status: "pending"` vs `Status::Pending` | | B.3 | Result/Option used properly; no null/nil abuse | Returning `null` for "not found" vs `Option<T>` | | B.4 | Builder/factory patterns prevent invalid construction | Partially-constructed objects allowed to exist | | B.5 | Phantom types or typestate for protocol enforcement | State machine transitions not enforced at compile time | | B.6 | Deserialization targets concrete types | Deserializing to `Map<String, Any>` then validating at runtime | **Language-Specific Checks:** - **Rust:** Proper `#[non_exhaustive]` usage; no unwrap in library code; correct `Send`/`Sync` bounds - **Go:** Proper error wrapping; unexported fields for invariants; meaningful zero values - **TypeScript:** Strict mode; no `any`; discriminated unions over string literals - **Python:** Type hints on public API; @dataclass for structured data; no Dict[str, Any] leakage **Remediation Patterns:** - Parse, don't validate (deserialize to concrete types) - Newtype pattern for domain primitives - Typestate pattern for state machines - `#[must_use]` on Result-returning functions --- #### Dimension C: Composability & Self-Reuse Higher-level APIs should compose lower-level primitives, not duplicate logic. | Check | Description | Anti-Pattern | |:------|:------------|:-------------| | C.1 | Higher abstractions compose lower ones | Convenience function re-implements core logic | | C.2 | Common patterns extracted to reusable utilities | Same validation logic in 5 different functions | | C.3 | Trait/interface hierarchies are coherent | Trait with 20 methods when 3 would compose | | C.4 | Extension points via composition, not inheritance | Deep inheritance hierarchies | **Remediation Patterns:** - Extract shared logic to internal helpers, call from public API - Use decorator/wrapper types for cross-cutting concerns - Prefer trait composition (`+ OtherTrait`) over monolithic traits --- #### Dimension D: Monosemicity (One Path Per Concern) Each concern should have exactly one canonical path through the API. | Check | Description | Anti-Pattern | |:------|:------------|:-------------| | D.1 | No redundant methods with overlapping functionality | `get()`, `fetch()`, `retrieve()` all doing the same thing | | D.2 | Clear canonical path for common operations | 5 ways to create an instance, none obviously "correct" | | D.3 | Deprecated paths actively marked and documented | Old API coexisting with new, neither marked deprecated | | D.4 | No "stringly typed" APIs where enums would work | `method: "GET"` instead of `Method::Get` | **Remediation Patterns:** - Consolidate redundant methods; deprecate legacy paths - Document the "happy path" prominently - Use `#[deprecated]` or equivalent with migration guidance --- #### Dimension E: Naming & Cognitive Load Names should be precise, consistent, and minimize mental overhead. | Check | Description | Anti-Pattern | |:------|:------------|:-------------| | E.1 | Consistent naming conventions throughout | `getUserById` vs `fetch_user` vs `user.get` | | E.2 | Names reflect precise semantics | `process()` instead of `validateAndTransformInput()` | | E.3 | No abbreviations without project-wide glossary | `crnt_req_hdlr` instead of `current_request_handler` | | E.4 | Boolean methods/fields use predicate naming | `valid` instead of `is_valid` or `has_permission` | **Remediation Patterns:** - Establish and document naming conventions in CONTRIBUTING.md - Rename for precision; use refactoring tools for safe migration --- #### Dimension F: Error Handling Coherence Errors should be informative, typed, and recoverable where possible. | Check | Description | Anti-Pattern | |:------|:------------|:-------------| | F.1 | Error types are domain-specific, not stringly-typed | `Error::Generic(String)` for everything | | F.2 | Errors contain sufficient context for debugging | `"failed"` vs `"failed to parse config at line 42: expected integer"` | | F.3 | Recoverable errors distinct from fatal panics | Panicking on user input validation failure | | F.4 | Error variants map to distinct recovery paths | Single error type with no way to discriminate cause | **Remediation Patterns:** - Define enum error types per module/subsystem - Use `thiserror`/`anyhow` (Rust), `errors.Is/As` (Go), custom error classes (TS/Python) - Include structured context (file paths, line numbers, input values) --- ### Iteration Template For each component, produce: ``` ## Audit: `module::Component` ### Summary Brief description of the component's purpose and surface. ### Findings | Dimension | Rating | Notes | |:----------|:-------|:------| | A. Minimal Surface | PASS | — | | B. Type Safety | WARN | Uses `String` for user_id; newtype recommended | | C. Composability | PASS | — | | D. Monosemicity | FAIL | Redundant `create` and `new` methods | | E. Naming | PASS | — | | F. Error Handling | WARN | Generic error type; consider domain errors | ### Recommended Changes 1. **[D.1]** Consolidate `create` and `new` into single `new` constructor 2. **[B.1]** Introduce `UserId(String)` newtype 3. **[F.1]** Define `ComponentError` enum with specific variants ### Open Questions for User 1. Is backwards compatibility required for the `create` method? 2. Should `UserId` validation happen at construction time? ``` ## **Checkpoint:** Present findings for this component. Await acknowledgment before proceeding. ## Phase 3: Cross-Cutting Analysis After completing component audits, assess systemic patterns. ### 3.1 Consistency Audit - [ ] Naming conventions consistent across all modules - [ ] Error handling strategy uniform - [ ] Common patterns (e.g., builders, result types) applied uniformly - [ ] Documentation style consistent ### 3.2 Layering Audit - [ ] Clear dependency direction (lower layers don't import higher) - [ ] No circular dependencies between modules - [ ] Abstractions at appropriate levels (not too leaky, not too opaque) ### 3.3 Coherence Score Rate the overall API coherence: | Criterion | Score (1-5) | Notes | |:----------|:------------|:------| | Minimal Surface | | | | Type Safety | | | | Composability | | | | Monosemicity | | | | Naming Coherence | | | | Error Handling | | | | **Overall** | | | --- ## Phase 4: Remediation Plan Synthesize findings into prioritized action items. ### Priority Levels - **P0 (Critical):** Type safety gaps enabling invalid states; unhandled error conditions - **P1 (High):** Encapsulation violations; significant duplication - **P2 (Medium):** Naming inconsistencies; documentation gaps - **P3 (Low):** Style preferences; minor redundancies ### Remediation Template ``` ## Remediation Plan: [Project Name] ### P0 — Critical 1. [ ] [Module] Brief description — Links to finding ### P1 — High 1. [ ] [Module] Brief description — Links to finding ### P2 — Medium 1. [ ] [Module] Brief description — Links to finding ### P3 — Low 1. [ ] [Module] Brief description — Links to finding ``` ## **Checkpoint:** Present remediation plan for user approval before any code changes. ## Appendix: Language-Specific Checklists ### Rust - [ ] Public items have doc comments (`///`) - [ ] `#[must_use]` on Result-returning functions - [ ] `#[non_exhaustive]` on enums for future-proofing - [ ] No `unwrap()`/`expect()` in library code paths - [ ] Correct `Send`/`Sync` bounds on public types - [ ] `pub(crate)` for internal-only items - [ ] Feature flags documented with cfg_attr ### Go - [ ] Exported types have doc comments - [ ] Error types implement `Error` and support `Is`/`As` - [ ] Unexported fields for invariant protection - [ ] Meaningful zero values or require constructors - [ ] Context propagation for cancellation - [ ] Options pattern for configurable constructors ### TypeScript - [ ] Strict mode enabled; no `any` in public API - [ ] Discriminated unions over string literals - [ ] Readonly types for immutable data - [ ] Branded types for domain primitives - [ ] Proper error class hierarchy - [ ] Zod/io-ts for runtime validation of external input ### Python - [ ] Type hints on all public functions and classes - [ ] `@dataclass` or `pydantic` for structured data - [ ] `Enum` for finite sets of values - [ ] `__all__` defined in `__init__.py` - [ ] No `Dict[str, Any]` in public signatures - [ ] Docstrings follow consistent format (Google/NumPy/Sphinx) --- ## Workflow Execution Summary ``` ┌─────────────────────────────────────────────────────────────────┐ │ Phase 0: Scope Definition │ │ → User approves scope │ ├─────────────────────────────────────────────────────────────────┤ │ Phase 1: Surface Discovery │ │ → Full codebase ingestion │ │ → Surface map generated │ │ → User confirms completeness │ ├─────────────────────────────────────────────────────────────────┤ │ Phase 2: Iterative Component Audit │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ For each component: │ │ │ │ → Analyze against 6 dimensions │ │ │ │ → Present findings │ │ │ │ → Await user acknowledgment │ │ │ │ → Proceed to next component │ │ │ └──────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ Phase 3: Cross-Cutting Analysis │ │ → Consistency audit │ │ → Layering audit │ │ → Coherence scoring │ ├─────────────────────────────────────────────────────────────────┤ │ Phase 4: Remediation Plan │ │ → Prioritized action items │ │ → User approves before implementation │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Final Directive This protocol enforces iterative human engagement to maintain agent coherence. **Never skip checkpoints.** If context becomes unclear or findings accumulate beyond what can be tracked, pause and summarize progress before continuing. The goal is not merely to identify issues, but to cultivate a shared understanding of API quality between the auditor and the user.
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · nrdxp/predicate | 100 | MIT |
| briiirussell/cybersecurity-skills | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki c5115cb8daed (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100api-review
Ocenia projekt powierzchni API, spójność i zgodność ze wzorcami przy przeglądzie zmian w publicznym API lub przed wydaniem nowej powierzchni. - 100api-and-interface-design
Opisuje wzorce projektowania stabilnych interfejsów: endpointy REST i GraphQL, granice modułów, kontrakty typów i zmiany interfejsów publicznych. - 100api-and-interface-design
Podaje wzorce stabilnych API: endpointy REST i GraphQL, granice modułów, kontrakty typów i zmiany publicznych interfejsów. - 100api-and-interface-design
Prowadzi projektowanie stabilnego API i interfejsów: granice modułów, kontrakty typów, endpointy REST lub GraphQL. - 100python-type-safety
Zapewnia bezpieczeństwo typów w Python: adnotacje, generyki, protokoły i ścisłe sprawdzanie typów, w tym konfiguracja mypy i pyright. - 100api-and-interface-design
Prowadzi stabilne projektowanie API i interfejsów: granice modułów, endpointy REST i GraphQL oraz kontrakty typów między frontendem a backendem.