feat: add hook reflection to SuiteReflection

Before / After / BeforeSuite / AfterSuite are top-level sibling
statements of Feature in CodeceptJS, so the existing suite-range
walker already visits them — it just used to ignore them.

New surface on SuiteReflection:
- hooks: list of { kind, line, range }, in source order, scoped to
  this Feature (never bleeds into the next Feature in the same file)
- findHook(kind): filter helper
- addHook(kind, code, { position }): append after existing hooks or
  right after Feature(); rejects unknown hook kinds
- removeHook(kind, { index }): delete by kind, throws
  AmbiguousLocateError when multiple match and no index is given
- replaceHook(kind, code, { index }): replace with the same
  disambiguation semantics

Implementation extends collectSuiteStatements to return hooks[]
alongside scenarios[]; the JS and TS engines both classify
ExpressionStatements whose callee is one of the four hook names.

15 new unit tests covering listing, scoping, insertion into empty
and populated suites, cross-suite isolation, ambiguity detection,
index-based disambiguation, and replacement.

Removed hook reflection from the v2 "deferred" list in limitations.md.

Totals: 213 tests across 23 files.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: DavertMik

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.5.0 — Unreleased
+
+Added hook reflection to `SuiteReflection` for `Before`, `After`, `BeforeSuite`, and `AfterSuite`.
+
+- `sur.hooks` — list of `{ kind, line, range }` entries scoped to the current suite.
+- `sur.findHook(kind)` — filter by kind.
+- `sur.addHook(kind, code, { position })` — append after existing hooks (or right after `Feature(...)` if none); scoped to the current suite.
+- `sur.removeHook(kind, { index })` — delete a hook; throws `AmbiguousLocateError` when multiple match and no index is given.
+- `sur.replaceHook(kind, code, { index })` — replace a hook body with the same disambiguation semantics.
+
 ## 0.4.0 — Unreleased
 
 Added `ProjectReflection` — a project-level discovery layer that reads a CodeceptJS config and enumerates suites, tests, steps, and page objects without running anything.

docs/api/suite-reflection.md

@@ -21,6 +21,7 @@ Reflection.forSuite(suite)
 | `tags` | `string[]` | |
 | `meta` | `object` | |
 | `tests` | `Array<{ title, range }>` | Scenarios that belong to this suite, in source order. `title` is the first string argument of each `Scenario(...)`. `range` is the byte range of the full statement. |
+| `hooks` | `Array<{ kind, line, range }>` | `Before` / `After` / `BeforeSuite` / `AfterSuite` calls that belong to this suite, in source order. `kind` is the hook function name. |
 | `dependencies` | `string[]` | Unique destructured parameter names across all scenarios in this suite (e.g. `['I', 'loginPage']`). Non-destructured params appear as `*name` so you can tell them apart. |
 
 ## Methods
@@ -61,6 +62,57 @@ The lookup is scoped: if another suite in the same file has a scenario with the
 sur.removeTest('flaky login').apply()
 ```
 
+## Hook editing
+
+CodeceptJS suite hooks — `BeforeSuite`, `Before`, `After`, `AfterSuite` — are top-level sibling statements of `Feature` / `Scenario`. `SuiteReflection` locates them by walking the same suite range used for `tests`, so each hook operation is scoped to the current Feature.
+
+### `findHook(kind)`
+Returns all hooks of a given kind in this suite (in source order). Useful before calling `removeHook` / `replaceHook` to check for ambiguity.
+
+```js
+sur.findHook('Before')   // [{ kind: 'Before', line: 5, range: {...} }]
+```
+
+### `addHook(kind, code, opts?)`
+Inserts a new hook and returns an [`Edit`](./edit.md).
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `position` | `'afterHooks' \| 'afterFeature'` | `'afterHooks'` | `'afterHooks'` appends after the last existing hook in this suite, or after `Feature(...)` if none exist. `'afterFeature'` always inserts right after `Feature(...)`. |
+
+```js
+sur.addHook(
+  'BeforeSuite',
+  `BeforeSuite(async ({ I }) => { I.amOnPage('/seed') })`,
+).apply()
+```
+
+Insertion is scoped — the hook will never land past the next `Feature(...)` in the same file. Throws `ReflectionError` if `kind` is not one of the four supported hook names.
+
+### `removeHook(kind, opts?)`
+Deletes a hook of a given kind, scoped to this suite.
+
+| Option | Type | Description |
+|---|---|---|
+| `index` | `number?` | Disambiguate when this suite has multiple hooks of the same kind. 0-based index into `findHook(kind)`. |
+
+```js
+sur.removeHook('Before').apply()
+sur.removeHook('Before', { index: 1 }).apply()  // remove the second of two Before hooks
+```
+
+Throws `NotFoundError` if no hook of that kind exists (or `index` is out of range). Throws `AmbiguousLocateError` when there are multiple matching hooks and no `index` was given.
+
+### `replaceHook(kind, code, opts?)`
+Replaces the body of a hook. Accepts the same `{ index }` option as `removeHook` for disambiguation.
+
+```js
+sur.replaceHook(
+  'Before',
+  `Before(async ({ I }) => { I.amOnPage('/login') })`,
+).apply()
+```
+
 ## Gherkin
 
 Gherkin `.feature` files are not supported: `read()` throws `UnsupportedSourceError`. For BDD-style CodeceptJS projects, reflect the step-definition JS/TS file instead.

docs/getting-started.md

@@ -104,6 +104,22 @@ sur.removeTest('flaky login').apply()
 
 Insertion is scoped to the current suite, so the new Scenario will not land after a later `Feature(...)` in the same file.
 
+### Edit suite hooks
+
+`BeforeSuite`, `Before`, `After`, and `AfterSuite` are editable too:
+
+```js
+sur.hooks                        // [{ kind: 'BeforeSuite', line: 3, range: {...} }, ...]
+sur.findHook('Before')           // just the Before hooks
+
+sur.addHook('BeforeSuite', `BeforeSuite(async ({ I }) => { I.amOnPage('/seed') })`).apply()
+sur.replaceHook('Before', `Before(async ({ I }) => { I.clearCookie() })`).apply()
+sur.removeHook('After').apply()
+
+// Multiple hooks of the same kind? Disambiguate with { index }
+sur.removeHook('Before', { index: 1 }).apply()
+```
+
 ## List dependencies
 
 Both `TestReflection` and `SuiteReflection` expose a `dependencies` accessor that reads the destructured parameter list from the scenario callback:

docs/limitations.md

@@ -41,4 +41,3 @@
 - Worker-safe concurrent edits (file locking)
 - `.replace()` validating the new code parses
 - `.replace()` accepting a function callback `(node) => newCode`
-- Hook reflection (`Before`, `After`, `BeforeSuite`, `AfterSuite`)

src/locate/suite.js

@@ -35,6 +35,13 @@ function isScenarioCallee(name) {
   return false
 }
 
+export const HOOK_KINDS = ['BeforeSuite', 'Before', 'After', 'AfterSuite']
+const HOOK_SET = new Set(HOOK_KINDS)
+
+function isHookCallee(name) {
+  return !!name && HOOK_SET.has(name)
+}
+
 export function locateSuiteByTitle(parsed, { title, lineHint }) {
   if (parsed.engine === 'acorn') return locateSuiteJS(parsed, title, lineHint)
   return locateSuiteTS(parsed, title, lineHint)
@@ -88,8 +95,9 @@ function collectSuiteStatementsJS(parsed, featureNode) {
   )
   const featureStmt = idx !== -1 ? body[idx] : null
   const scenarios = []
+  const hooks = []
   let suiteEnd = parsed.source.length
-  if (idx === -1) return { featureStmt, scenarios, suiteEnd }
+  if (idx === -1) return { featureStmt, scenarios, hooks, suiteEnd }
 
   for (let i = idx + 1; i < body.length; i++) {
     const stmt = body[i]
@@ -109,9 +117,17 @@ function collectSuiteStatementsJS(parsed, featureNode) {
         title: firstStringArgJS(expr),
         range: { start: stmt.start, end: stmt.end },
       })
+    } else if (isHookCallee(name)) {
+      hooks.push({
+        stmt,
+        call: expr,
+        kind: name,
+        line: stmt.loc.start.line,
+        range: { start: stmt.start, end: stmt.end },
+      })
     }
   }
-  return { featureStmt, scenarios, suiteEnd }
+  return { featureStmt, scenarios, hooks, suiteEnd }
 }
 
 function collectSuiteStatementsTS(parsed, featureNode) {
@@ -123,8 +139,9 @@ function collectSuiteStatementsTS(parsed, featureNode) {
   )
   const featureStmt = idx !== -1 ? stmts[idx] : null
   const scenarios = []
+  const hooks = []
   let suiteEnd = parsed.source.length
-  if (idx === -1) return { featureStmt, scenarios, suiteEnd }
+  if (idx === -1) return { featureStmt, scenarios, hooks, suiteEnd }
 
   for (let i = idx + 1; i < stmts.length; i++) {
     const stmt = stmts[i]
@@ -144,9 +161,18 @@ function collectSuiteStatementsTS(parsed, featureNode) {
         title: firstStringArgTS(ts, expr),
         range: { start: stmt.getStart(sourceFile), end: stmt.getEnd() },
       })
+    } else if (isHookCallee(name)) {
+      const start = stmt.getStart(sourceFile)
+      hooks.push({
+        stmt,
+        call: expr,
+        kind: name,
+        line: sourceFile.getLineAndCharacterOfPosition(start).line + 1,
+        range: { start, end: stmt.getEnd() },
+      })
     }
   }
-  return { featureStmt, scenarios, suiteEnd }
+  return { featureStmt, scenarios, hooks, suiteEnd }
 }
 
 function locateSuiteTS(parsed, title, lineHint) {

src/suite.js

@@ -1,9 +1,11 @@
 import { parseFile } from './parser.js'
 import { resolveSourceFile } from './source-path.js'
-import { locateSuiteByTitle, collectSuiteStatements } from './locate/suite.js'
+import { locateSuiteByTitle, collectSuiteStatements, HOOK_KINDS } from './locate/suite.js'
 import { extractScenarioDepsJS, extractScenarioDepsTS } from './locate/deps.js'
 import { Edit } from './edit.js'
-import { ReflectionError, NotFoundError } from './errors.js'
+import { ReflectionError, NotFoundError, AmbiguousLocateError } from './errors.js'
+
+export { HOOK_KINDS }
 
 export class SuiteReflection {
   constructor(suite) {
@@ -61,6 +63,19 @@ export class SuiteReflection {
     }))
   }
 
+  get hooks() {
+    const { hooks } = this._statements()
+    return hooks.map(h => ({
+      kind: h.kind,
+      line: h.line,
+      range: h.range,
+    }))
+  }
+
+  findHook(kind) {
+    return this.hooks.filter(h => h.kind === kind)
+  }
+
   get dependencies() {
     const parsed = this._parsed()
     const { scenarios } = this._statements()
@@ -132,19 +147,108 @@ export class SuiteReflection {
         { filePath: parsed.filePath },
       )
     }
+    return this._buildRemoveEdit(parsed, match)
+  }
+
+  addHook(kind, code, { position = 'afterHooks' } = {}) {
+    if (!HOOK_KINDS.includes(kind)) {
+      throw new ReflectionError(
+        `addHook: unknown hook kind "${kind}". Expected one of: ${HOOK_KINDS.join(', ')}`,
+      )
+    }
+    const parsed = this._parsed()
+    const { featureStmt, hooks, suiteEnd } = this._statements()
+    const eol = parsed.eol
+
+    let insertPos
+    if (position === 'afterFeature' || hooks.length === 0) {
+      insertPos = featureStmt ? featureStmt.end : this._locate().range.end
+    } else {
+      insertPos = hooks[hooks.length - 1].range.end
+    }
+    if (insertPos > suiteEnd) insertPos = suiteEnd
+
+    const trimmed = code.replace(/[\r\n]+$/, '')
+    const replacement = eol + eol + trimmed + eol
+
+    return new Edit({
+      filePath: parsed.filePath,
+      source: parsed.source,
+      parsedAtHash: parsed.hash,
+      start: insertPos,
+      end: insertPos,
+      replacement,
+      eol,
+    })
+  }
+
+  removeHook(kind, { index } = {}) {
+    const parsed = this._parsed()
+    const match = this._pickHook(kind, index, parsed.filePath)
+    return this._buildRemoveEdit(parsed, match)
+  }
+
+  replaceHook(kind, code, { index } = {}) {
+    const parsed = this._parsed()
+    const match = this._pickHook(kind, index, parsed.filePath)
+    return new Edit({
+      filePath: parsed.filePath,
+      source: parsed.source,
+      parsedAtHash: parsed.hash,
+      start: match.range.start,
+      end: match.range.end,
+      replacement: code.replace(/[\r\n]+$/, ''),
+      eol: parsed.eol,
+    })
+  }
+
+  _pickHook(kind, index, filePath) {
+    if (!HOOK_KINDS.includes(kind)) {
+      throw new ReflectionError(
+        `Unknown hook kind "${kind}". Expected one of: ${HOOK_KINDS.join(', ')}`,
+        { filePath },
+      )
+    }
+    const { hooks } = this._statements()
+    const matches = hooks.filter(h => h.kind === kind)
+    if (matches.length === 0) {
+      throw new NotFoundError(
+        `No ${kind} hook found in suite "${this.title}" in ${filePath}`,
+        { filePath },
+      )
+    }
+    if (index != null) {
+      if (index < 0 || index >= matches.length) {
+        throw new NotFoundError(
+          `${kind} hook index ${index} out of range (0..${matches.length - 1})`,
+          { filePath },
+        )
+      }
+      return matches[index]
+    }
+    if (matches.length > 1) {
+      throw new AmbiguousLocateError(
+        `Multiple ${kind} hooks in suite "${this.title}". Pass { index } to disambiguate.`,
+        {
+          filePath,
+          candidates: matches.map(m => ({ start: m.range.start, end: m.range.end, line: m.line })),
+        },
+      )
+    }
+    return matches[0]
+  }
+
+  _buildRemoveEdit(parsed, match) {
     const eol = parsed.eol
     let start = match.range.start
     let end = match.range.end
-    // Eat one trailing newline so the surrounding blank line becomes the new separator
     if (parsed.source.slice(end, end + eol.length) === eol) end += eol.length
-    // If there was a preceding blank line, eat that too
     if (
       parsed.source.slice(start - eol.length, start) === eol &&
       parsed.source.slice(start - 2 * eol.length, start - eol.length) === eol
     ) {
       start -= eol.length
     }
-
     return new Edit({
       filePath: parsed.filePath,
       source: parsed.source,

src/types.d.ts

@@ -88,22 +88,43 @@ export interface SuiteTestEntry {
   range: Range
 }
 
+export type HookKind = 'BeforeSuite' | 'Before' | 'After' | 'AfterSuite'
+
+export interface SuiteHookEntry {
+  kind: HookKind
+  line: number
+  range: Range
+}
+
 export interface AddTestOptions {
   position?: 'start' | 'end'
 }
 
+export interface AddHookOptions {
+  position?: 'afterFeature' | 'afterHooks'
+}
+
+export interface HookIndexOption {
+  index?: number
+}
+
 export declare class SuiteReflection {
   constructor(suite: SuiteLike)
   readonly fileName: string
   readonly title: string
   readonly tags: string[]
   readonly meta: Record<string, unknown>
   readonly tests: SuiteTestEntry[]
+  readonly hooks: SuiteHookEntry[]
   readonly dependencies: string[]
   read(): string
   replace(newCode: string): Edit
   addTest(code: string, opts?: AddTestOptions): Edit
   removeTest(title: string): Edit
+  findHook(kind: HookKind): SuiteHookEntry[]
+  addHook(kind: HookKind, code: string, opts?: AddHookOptions): Edit
+  removeHook(kind: HookKind, opts?: HookIndexOption): Edit
+  replaceHook(kind: HookKind, code: string, opts?: HookIndexOption): Edit
 }
 
 export interface ReflectionConfigureOptions {