Handle @include tags on entry point project

Resolves #2800

CHANGELOG.md

@@ -4,9 +4,14 @@ title: Changelog
 
 ## Unreleased
 
+### Features
+
+-   API: Introduced new `Converter.EVENT_CREATE_PROJECT` event which fires when a project is created by the converter, #2800.
+
 ### Bug Fixes
 
 -   Switch from gzip to deflate for compressing assets to make output consistent across different operating systems, #2796.
+-   `@include` and `@includeCode` now work for comments on the entry point for projects with a single entry point, #2800.
 -   Cascaded modifier tags will no longer be copied into type literals, #2802.
 
 ## v0.27.3 (2024-12-04)

src/lib/converter/converter-events.ts

@@ -1,6 +1,7 @@
 export const ConverterEvents = {
     BEGIN: "begin",
     END: "end",
+    CREATE_PROJECT: "createProject",
     CREATE_DECLARATION: "createDeclaration",
     CREATE_DOCUMENT: "createDocument",
     CREATE_SIGNATURE: "createSignature",

src/lib/converter/converter.ts

@@ -67,6 +67,7 @@ import { MergeModuleWithPlugin } from "./plugins/MergeModuleWithPlugin.js";
 export interface ConverterEvents {
     begin: [Context];
     end: [Context];
+    createProject: [Context, ProjectReflection];
     createDeclaration: [Context, DeclarationReflection];
     createDocument: [undefined, DocumentReflection];
     createSignature: [
@@ -175,6 +176,13 @@ export class Converter extends AbstractComponent<Application, ConverterEvents> {
      * Factory events
      */
 
+    /**
+     * Triggered when the converter has created a project reflection.
+     * The listener will be given {@link Context} and a {@link Models.ProjectReflection}.
+     * @event
+     */
+    static readonly EVENT_CREATE_PROJECT = ConverterEvents.CREATE_PROJECT;
+
     /**
      * Triggered when the converter has created a declaration reflection.
      * The listener will be given {@link Context} and a {@link Models.DeclarationReflection}.
@@ -459,6 +467,14 @@ export class Converter extends AbstractComponent<Application, ConverterEvents> {
                 : !!(context.scope as ProjectReflection).documents;
         }
 
+        if (createModuleReflections) {
+            this.trigger(
+                ConverterEvents.CREATE_PROJECT,
+                context,
+                context.project,
+            );
+        }
+
         entries.forEach((e) => {
             context.setActiveProgram(e.entryPoint.program);
             e.context = this.convertExports(
@@ -499,6 +515,11 @@ export class Converter extends AbstractComponent<Application, ConverterEvents> {
                 ? context.getComment(symbol, context.project.kind)
                 : context.getFileComment(node);
             this.processDocumentTags(context.project, context.project);
+            this.trigger(
+                ConverterEvents.CREATE_PROJECT,
+                context,
+                context.project,
+            );
             moduleContext = context;
         } else {
             const reflection = context.createDeclarationReflection(

src/lib/converter/plugins/IncludePlugin.ts

@@ -19,6 +19,7 @@ export class IncludePlugin extends ConverterComponent {
     constructor(owner: Converter) {
         super(owner);
         const onCreate = this.onCreate.bind(this);
+        owner.on(ConverterEvents.CREATE_PROJECT, onCreate);
         owner.on(ConverterEvents.CREATE_DOCUMENT, onCreate);
         owner.on(ConverterEvents.CREATE_DECLARATION, onCreate);
         owner.on(ConverterEvents.CREATE_PARAMETER, onCreate);

src/test/converter2/issues/gh2800.ts

@@ -0,0 +1,6 @@
+/**
+ * Module docs
+ * {@includeCode ./gh2800.ts}
+ * @module
+ */
+export const bug = true;

src/test/issues.c2.test.ts

@@ -1943,6 +1943,20 @@ describe("Issue Tests", () => {
         equal(type.type?.toString(), "any");
     });
 
+    it("#2800 handles @include tags on project", () => {
+        const project = convert();
+        const includeTag = project.comment?.summary.find(
+            (t) => t.kind === "inline-tag",
+        );
+        equal(includeTag, undefined);
+
+        ok(
+            Comment.combineDisplayParts(project.comment?.summary).includes(
+                "const bug",
+            ),
+        );
+    });
+
     it("#2802 preserves @alpha tags on signature types", () => {
         const project = convert();
         const alpha1 = query(project, "AlphaOk");