add-ktnip-collector

name	add-ktnip-collector
description	Adds a new collector to the ktnip KSP processor. Use when implementing a new handler type (e.g. new annotation like @MyHandler), adding a collector for a new activity pattern, or extending the ktnip processor to collect additional annotated functions.

Add Ktnip Collector

Workflow

1. Create Annotation (if new)

• Define annotation in telegram-bot module (annotations package)
• Ensure it can be discovered via findAnnotationRecursively (meta-annotations supported)

2. Add Annotation Parser (if new annotation)

• In AnnotationParser.kt: add parseMyAnnotation(arguments) returning parsed data
• Use parseValueList, parseScopes patterns from existing parsers

3. Create Collector Class

• Place in ktnip/src/jvmMain/kotlin/eu/vendeli/ktnip/collectors/
• Extend BaseCollector (for activity-based handlers) or implement Collector directly
• Override collect(resolver: Resolver, ctx: CollectorsContext)

4. Collector Implementation

• Discovery: resolver.getAnnotatedFnSymbols(ctx.pkg, MyAnnotation::class)
• Parse: function.annotations.findAnnotationRecursively(MyAnnotation::class)?.arguments
• Metadata: extractActivityMetadata(function) (from BaseCollector)
• Generate: generateAndRegisterActivity(function, metadata, ctx, parameters, updateType)
• Register: ctx.loadFun.addStatement("registerX(%S, %L.id)", id, activityId)

5. Register in ActivityProcessor

• Add to collectors list in ActivityProcessor.kt processPackage:
  • Order matters: BotCtxCollector, CommandCollector, InputCollector, CommonCollector, UpdateHandlerCollector, UnprocessedHandlerCollector, WizardCollector

6. ResolverExtensions (if needed)

• getAnnotatedFnSymbols(pkg, MyAnnotation::class) works for any annotation (generic)
• Custom discovery logic only if collecting non-function symbols

7. Add KSP Tests

• Add test data in ktnip/src/jvmTest/resources/test-data/ (or extend DefaultHandlers.kt, WizardHandlers.kt, etc.)
• Add runTest("test-data/YourFile.kt") in ProcessorTest.kt
• Use /* G-EXPECT ... */ block for golden output checks (see add-ktnip-ksp-tests skill)

Reference

• InputCollector.kt - simple collector
• CommandCollector.kt - multiple annotations, parameters, updateType