Refactor and document guard resolution system

[UniquePixels]

Context

Audit IDs: ARCH-2, SIMP-1, SIMP-2, SIMP-4

The guard system in `guards/index.ts` has several related improvements that should be done together since they all touch the same file:

ARCH-2: Document guard resolution algorithm

The `collectDeps()` / `resolveDeps()` / `resolveGuards()` pipeline is 168 lines of graph traversal with cycle detection. Add high-level JSDoc explaining the algorithm (depth-first traversal, deduplication, topological ordering). Analyze whether the algorithm can be simplified.

SIMP-1: Simplify resolveDeps dual-Set pattern

`resolveDeps` maintains two separate Sets (`seen` and `resolvedSet`) plus an array (`resolved`). A single `added` Set and the `resolved` array should be sufficient.

SIMP-2: Simplify createGuard metadata copy

Four separate `if` branches manually copy each optional field from `meta`. A filtered spread with `Object.freeze` would be more concise and maintainable.

SIMP-4: Remove or internalize runGuard

`runGuard` is exported but never imported by production code. It's a trivial passthrough (`return guard(input)`). Remove from public API or mark as internal.

Files

• `src/core/guards/index.ts` (all changes)
• `src/core/guards/index.test.ts` (test updates)

[coderabbitai]

Coding Plan

Summary

• Consolidate the dual-Set pattern in resolveDeps into a single tracking Set that serves both traversal deduplication and output deduplication purposes
• Replace verbose conditional branches in createGuard with idiomatic conditional spread syntax while preserving freeze semantics
• Remove runGuard entirely rather than marking internal, since it provides no value over direct guard invocation
• Add algorithm-focused JSDoc that explains the "why" (topological ordering, cycle detection) rather than restating the "what" visible in code

Implementation Steps

Phase 1: Simplify Guard Functions

This phase consolidates three simplification items that reduce code complexity without changing external behavior. All changes are internal refactoring with test updates to maintain coverage.

Task 1: Simplify resolveDeps Dual-Set Pattern

Refactor resolveDeps to eliminate redundant tracking by merging seen and resolvedSet into a single added Set.

• Rename resolvedSet to added and remove the separate seen Set in src/core/guards/index.ts
• Pass added to collectDeps instead of seen — this single Set now serves both purposes: preventing re-traversal during dependency collection AND preventing duplicate entries in the output array
• Update collectDeps parameter name from seen to added for clarity
• Remove the redundant iteration pattern where all items in seen are checked against resolvedSet — instead, check added directly when processing each dependency
• Existing tests in index.test.ts for resolveGuards should pass without modification since the behavior is unchanged

Task 2: Simplify createGuard Metadata Copy

Replace the four separate if-branches with a conditional spread pattern for more concise metadata construction.

• Refactor createGuard in src/core/guards/index.ts to use conditional object spread syntax
• Construct the frozen object in a single object literal using ...(condition && { field: value }) pattern for requires, incompatibleWith, and channelResolver
• Maintain the same freezing behavior: spread and freeze arrays for requires and incompatibleWith, direct assignment for channelResolver
• Apply Object.freeze to the entire metadata object as before
• No test changes required — existing createGuard with metadata tests verify the same behavior

Task 3: Remove runGuard Export

Remove the unused runGuard function from the public API since it's never called in production code.

• Delete the runGuard function (lines 160-165) from src/core/guards/index.ts
• Remove runGuard from the module exports
• Remove the runGuard import and entire describe('runGuard', ...) block from src/core/guards/index.test.ts
• The tested behavior (calling a guard function) is trivial (return guard(input)) and already covered by runGuards tests which exercise guard invocation directly

🤖 Prompt for AI agents

This phase simplifies three areas of `src/core/guards/index.ts` through internal
refactoring without changing external behavior.

**Task 1: Simplify `resolveDeps` Dual-Set Pattern**
- In `src/core/guards/index.ts`, remove the separate `seen` Set from
`resolveDeps` and rename `resolvedSet` to `added`
- Update the call to `collectDeps` to pass `added` in place of `seen`
- In `collectDeps`, rename the `seen` parameter to `added`
- Remove the redundant iteration that checks items in `seen` against
`resolvedSet`; instead, check `added` directly when processing each dependency
- No changes needed in `index.test.ts` — behavior is unchanged

**Task 2: Simplify `createGuard` Metadata Copy**
- In `createGuard` in `src/core/guards/index.ts`, replace the four separate
if-branches for optional metadata fields with a single object literal using
conditional spread syntax: `...(condition && { field: value })` for `requires`,
`incompatibleWith`, and `channelResolver`
- Preserve freeze semantics: spread-and-freeze arrays for `requires` and
`incompatibleWith`, direct assignment for `channelResolver`
- Apply `Object.freeze` to the entire constructed metadata object as before
- No test changes required

**Task 3: Remove `runGuard` Export**
- Delete the `runGuard` function (around lines 160–165) from
`src/core/guards/index.ts` and remove it from the module exports
- In `src/core/guards/index.test.ts`, remove the `runGuard` import and the
entire `describe('runGuard', ...)` test block

Phase 2: Document Guard Resolution Algorithm

Add comprehensive JSDoc documentation explaining the dependency resolution pipeline's algorithm, design decisions, and invariants.

Task 1: Document collectDeps Function

Add JSDoc explaining the recursive depth-first traversal and cycle detection mechanism.

• Add JSDoc block above collectDeps in src/core/guards/index.ts describing:
  • Purpose: recursively collects transitive dependencies for a guard
  • Algorithm: depth-first traversal that processes dependencies before the dependent (ensuring topological order)
  • Cycle detection: uses visiting Set to track guards currently in the call stack; throws ERR_GUARD_CYCLE if a guard is encountered while already being visited
  • Incompatibility validation: checks each transitive dependency against sparkType and throws ERR_GUARD_INCOMPATIBLE if a dependency is incompatible
• Document the added parameter's dual purpose (prevents re-traversal, tracks what's been collected)

Task 2: Document resolveDeps Function

Add JSDoc explaining the deduplication and ordering guarantees.

• Add JSDoc block above resolveDeps in src/core/guards/index.ts describing:
  • Purpose: flattens guard arrays with their transitive dependencies into execution order
  • Ordering guarantee: dependencies always appear before their dependents in the output
  • Deduplication: each guard appears exactly once in output regardless of how many times it's referenced
  • Process: iterates developer-specified guards left-to-right, collecting deps for each before appending the guard itself

Task 3: Document resolveGuards Function

Add JSDoc explaining the public entry point and spark-type-specific behavior.

• Add JSDoc block above resolveGuards in src/core/guards/index.ts describing:
  • Purpose: public entry point for guard resolution, called at spark define-time
  • Compatibility validation: validates all direct guards against sparkType before processing
  • Spark-type behavior: command/component sparks get full dependency resolution; gateway-event/scheduled-event sparks only get deduplication (no dependency auto-injection)
  • Returns: flat array of guards in execution order with dependencies resolved

🤖 Prompt for AI agents

This phase adds comprehensive JSDoc documentation to three functions in
`src/core/guards/index.ts` that form the dependency resolution pipeline. No
logic changes are made — only documentation is added.

**Task 1: JSDoc for `collectDeps`**
- Add a JSDoc block immediately above the `collectDeps` function covering:
  - Purpose: recursively collects transitive dependencies for a guard
- Algorithm: depth-first traversal that processes dependencies before the
dependent, ensuring topological order
- Cycle detection: the `visiting` Set tracks guards currently on the call stack;
throws `ERR_GUARD_CYCLE` if a guard is re-encountered during traversal
- Incompatibility validation: each transitive dependency is checked against
`sparkType`; throws `ERR_GUARD_INCOMPATIBLE` if incompatible
- The `added` parameter's dual purpose: prevents re-traversal and tracks what
has already been collected

**Task 2: JSDoc for `resolveDeps`**
- Add a JSDoc block immediately above the `resolveDeps` function covering:
- Purpose: flattens guard arrays with their transitive dependencies into
execution order
- Ordering guarantee: dependencies always appear before their dependents in the
output array
- Deduplication: each guard appears exactly once regardless of how many times it
is referenced
- Process: iterates developer-specified guards left-to-right, collecting deps
for each before appending the guard itself

**Task 3: JSDoc for `resolveGuards`**
- Add a JSDoc block immediately above the `resolveGuards` function covering:
- Purpose: public entry point for guard resolution, called at spark define-time
- Compatibility validation: validates all direct guards against `sparkType`
before any processing
- Spark-type behavior: `command`/`component` sparks receive full dependency
resolution; `gateway-event`/`scheduled-event` sparks receive deduplication only
(no dependency auto-injection)
- Return value: a flat array of guards in execution order with all dependencies
resolved

Research

The guard system (src/core/guards/index.ts, 469 lines) provides validation and type-narrowing for Discord bot interactions. Key functions include createGuard for attaching metadata to guard functions, collectDeps/resolveDeps/resolveGuards for dependency resolution with cycle detection and topological ordering, and processGuards for runtime execution with logging. The runGuard function is exported but only used in tests—production code uses processGuards which internally calls runGuards. Tests in index.test.ts (806 lines) provide comprehensive coverage of all public APIs.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase simplifies three areas of `src/core/guards/index.ts` through internal
refactoring without changing external behavior.

**Task 1: Simplify `resolveDeps` Dual-Set Pattern**
- In `src/core/guards/index.ts`, remove the separate `seen` Set from
`resolveDeps` and rename `resolvedSet` to `added`
- Update the call to `collectDeps` to pass `added` in place of `seen`
- In `collectDeps`, rename the `seen` parameter to `added`
- Remove the redundant iteration that checks items in `seen` against
`resolvedSet`; instead, check `added` directly when processing each dependency
- No changes needed in `index.test.ts` — behavior is unchanged

**Task 2: Simplify `createGuard` Metadata Copy**
- In `createGuard` in `src/core/guards/index.ts`, replace the four separate
if-branches for optional metadata fields with a single object literal using
conditional spread syntax: `...(condition && { field: value })` for `requires`,
`incompatibleWith`, and `channelResolver`
- Preserve freeze semantics: spread-and-freeze arrays for `requires` and
`incompatibleWith`, direct assignment for `channelResolver`
- Apply `Object.freeze` to the entire constructed metadata object as before
- No test changes required

**Task 3: Remove `runGuard` Export**
- Delete the `runGuard` function (around lines 160–165) from
`src/core/guards/index.ts` and remove it from the module exports
- In `src/core/guards/index.test.ts`, remove the `runGuard` import and the
entire `describe('runGuard', ...)` test block
===============================================================================

Task: 2

This phase adds comprehensive JSDoc documentation to three functions in
`src/core/guards/index.ts` that form the dependency resolution pipeline. No
logic changes are made — only documentation is added.

**Task 1: JSDoc for `collectDeps`**
- Add a JSDoc block immediately above the `collectDeps` function covering:
  - Purpose: recursively collects transitive dependencies for a guard
- Algorithm: depth-first traversal that processes dependencies before the
dependent, ensuring topological order
- Cycle detection: the `visiting` Set tracks guards currently on the call stack;
throws `ERR_GUARD_CYCLE` if a guard is re-encountered during traversal
- Incompatibility validation: each transitive dependency is checked against
`sparkType`; throws `ERR_GUARD_INCOMPATIBLE` if incompatible
- The `added` parameter's dual purpose: prevents re-traversal and tracks what
has already been collected

**Task 2: JSDoc for `resolveDeps`**
- Add a JSDoc block immediately above the `resolveDeps` function covering:
- Purpose: flattens guard arrays with their transitive dependencies into
execution order
- Ordering guarantee: dependencies always appear before their dependents in the
output array
- Deduplication: each guard appears exactly once regardless of how many times it
is referenced
- Process: iterates developer-specified guards left-to-right, collecting deps
for each before appending the guard itself

**Task 3: JSDoc for `resolveGuards`**
- Add a JSDoc block immediately above the `resolveGuards` function covering:
- Purpose: public entry point for guard resolution, called at spark define-time
- Compatibility validation: validates all direct guards against `sparkType`
before any processing
- Spark-type behavior: `command`/`component` sparks receive full dependency
resolution; `gateway-event`/`scheduled-event` sparks receive deduplication only
(no dependency auto-injection)
- Return value: a flat array of guards in execution order with all dependencies
resolved

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

🔗 Related PRs

#6 - 🌈 improve(testing): consolidate test utilities [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!