From 344d4bf84833eb3dd7a5303151d0aa24f413572a Mon Sep 17 00:00:00 2001
From: Gerrit Birkeland <gerrit@gerritbirkeland.com>
Date: Fri, 6 Dec 2024 10:37:23 -0700
Subject: [PATCH] Handle `@include` tags on entry point project

Resolves #2800
---
 CHANGELOG.md                               |  5 +++++
 src/lib/converter/converter-events.ts      |  1 +
 src/lib/converter/converter.ts             | 21 +++++++++++++++++++++
 src/lib/converter/plugins/IncludePlugin.ts |  1 +
 src/test/converter2/issues/gh2800.ts       |  6 ++++++
 src/test/issues.c2.test.ts                 | 14 ++++++++++++++
 6 files changed, 48 insertions(+)
 create mode 100644 src/test/converter2/issues/gh2800.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 26a42ba73..5ad90d33e 100644
--- a/CHANGELOG.md
+++ b/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)
diff --git a/src/lib/converter/converter-events.ts b/src/lib/converter/converter-events.ts
index df81cbf78..2636684b2 100644
--- a/src/lib/converter/converter-events.ts
+++ b/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",
diff --git a/src/lib/converter/converter.ts b/src/lib/converter/converter.ts
index 7b783899b..2c32276c1 100644
--- a/src/lib/converter/converter.ts
+++ b/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(
diff --git a/src/lib/converter/plugins/IncludePlugin.ts b/src/lib/converter/plugins/IncludePlugin.ts
index 0b3b2413d..c7e43a19b 100644
--- a/src/lib/converter/plugins/IncludePlugin.ts
+++ b/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);
diff --git a/src/test/converter2/issues/gh2800.ts b/src/test/converter2/issues/gh2800.ts
new file mode 100644
index 000000000..ce094852f
--- /dev/null
+++ b/src/test/converter2/issues/gh2800.ts
@@ -0,0 +1,6 @@
+/**
+ * Module docs
+ * {@includeCode ./gh2800.ts}
+ * @module
+ */
+export const bug = true;
diff --git a/src/test/issues.c2.test.ts b/src/test/issues.c2.test.ts
index 591c12f82..fa0d03f06 100644
--- a/src/test/issues.c2.test.ts
+++ b/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");