chore: add doc generation for AI

docs/modules/Configuration.ts.md

@@ -53,6 +53,8 @@ export declare const ConfigurationSchema: Schema.Struct<{
   examplesCompilerOptions: Schema.optional<
     Schema.Union<[typeof Schema.String, Schema.Record$<typeof Schema.String, typeof Schema.Unknown>]>
   >
+  enableAI: Schema.optional<typeof Schema.Boolean>
+  enableJson: Schema.optional<typeof Schema.Boolean>
 }>
 ```
 
@@ -77,6 +79,8 @@ export interface ConfigurationShape {
   readonly exclude: ReadonlyArray<string>
   readonly parseCompilerOptions: Record<string, unknown>
   readonly examplesCompilerOptions: Record<string, unknown>
+  readonly enableAI: boolean
+  readonly enableJson: boolean
 }
 ```
 

docs/modules/Domain.ts.md

@@ -12,6 +12,8 @@ Added in v1.0.0
 
 <h2 class="text-delta">Table of contents</h2>
 
+- [accessors](#accessors)
+  - [printablesFromModule](#printablesfrommodule)
 - [constructors](#constructors)
   - [createClass](#createclass)
   - [createConstant](#createconstant)
@@ -37,13 +39,26 @@ Added in v1.0.0
   - [Module (interface)](#module-interface)
   - [NamedDoc (interface)](#nameddoc-interface)
   - [Namespace (interface)](#namespace-interface)
+  - [Printable (type alias)](#printable-type-alias)
   - [Property (interface)](#property-interface)
   - [TypeAlias (interface)](#typealias-interface)
 - [sorting](#sorting)
   - [ByPath](#bypath)
 
 ---
 
+# accessors
+
+## printablesFromModule
+
+**Signature**
+
+```ts
+export declare const printablesFromModule: (module: Module) => ReadonlyArray<Printable>
+```
+
+Added in v1.0.0
+
 # constructors
 
 ## createClass
@@ -370,6 +385,16 @@ export interface Namespace extends NamedDoc {
 
 Added in v1.0.0
 
+## Printable (type alias)
+
+**Signature**
+
+```ts
+export type Printable = Class | Constant | Export | Function | Interface | TypeAlias | Namespace
+```
+
+Added in v1.0.0
+
 ## Property (interface)
 
 **Signature**

docs/modules/Markdown.ts.md

@@ -14,6 +14,7 @@ Added in v1.0.0
 
 - [printers](#printers)
   - [printModule](#printmodule)
+  - [printPrintableForAI](#printprintableforai)
 
 ---
 
@@ -40,3 +41,17 @@ console.log(Markdown.printModule(m, 0))
 ```
 
 Added in v1.0.0
+
+## printPrintableForAI
+
+**Signature**
+
+```ts
+export declare const printPrintableForAI: (
+  projectName: string,
+  module: Domain.Module,
+  printable: Domain.Printable
+) => Effect.Effect<string, never, never>
+```
+
+Added in v1.0.0

schema.json

@@ -95,6 +95,16 @@
           ],
           "description": "tsconfig for the examples options (or path to a tsconfig)",
           "default": {}
+        },
+        "enableAI": {
+          "type": "boolean",
+          "description": "Whether or not to enable AI for the examples",
+          "default": true
+        },
+        "enableJson": {
+          "type": "boolean",
+          "description": "Whether or not to output JSON files",
+          "default": true
         }
       },
       "additionalProperties": false

src/CLI.ts

@@ -156,6 +156,28 @@ const examplesCompilerOptions = Options.file("examples-tsconfig-file", { exists:
   Options.optional
 )
 
+const enableAI = Options.boolean("no-enable-ai", {
+  ifPresent: false,
+  negationNames: ["enable-ai"]
+}).pipe(
+  Options.withFallbackConfig(Config.boolean("enableAI")),
+  Options.withDefault(true),
+  Options.withDescription(
+    "Whether or not to generate AI documentation for the project"
+  )
+)
+
+const enableJson = Options.boolean("no-enable-json", {
+  ifPresent: false,
+  negationNames: ["enable-json"]
+}).pipe(
+  Options.withFallbackConfig(Config.boolean("enableJson")),
+  Options.withDefault(true),
+  Options.withDescription(
+    "Whether or not to generate JSON output for the project"
+  )
+)
+
 const options = {
   projectHomepage,
   srcDir,
@@ -168,7 +190,9 @@ const options = {
   runExamples,
   exclude,
   parseCompilerOptions,
-  examplesCompilerOptions
+  examplesCompilerOptions,
+  enableAI,
+  enableJson
 }
 
 /** @internal */

src/Configuration.ts

@@ -79,6 +79,14 @@ export const ConfigurationSchema = Schema.Struct({
   examplesCompilerOptions: Schema.optional(compilerOptionsSchema).annotations({
     description: "tsconfig for the examples options (or path to a tsconfig)",
     default: {}
+  }),
+  enableAI: Schema.optional(Schema.Boolean).annotations({
+    description: "Whether or not to enable AI for the examples",
+    default: true
+  }),
+  enableJson: Schema.optional(Schema.Boolean).annotations({
+    description: "Whether or not to output JSON files",
+    default: true
   })
 }).annotations({ identifier: "ConfigurationSchema" })
 
@@ -100,6 +108,8 @@ export interface ConfigurationShape {
   readonly exclude: ReadonlyArray<string>
   readonly parseCompilerOptions: Record<string, unknown>
   readonly examplesCompilerOptions: Record<string, unknown>
+  readonly enableAI: boolean
+  readonly enableJson: boolean
 }
 
 /**
@@ -244,6 +254,8 @@ export const load = (args: {
   readonly exclude: ReadonlyArray<string>
   readonly parseCompilerOptions: Option.Option<string | Record<string, unknown>>
   readonly examplesCompilerOptions: Option.Option<string | Record<string, unknown>>
+  readonly enableAI: boolean
+  readonly enableJson: boolean
 }) =>
   Effect.gen(function*(_) {
     // Extract the requisite services

src/Core.ts

@@ -8,18 +8,19 @@ import * as CommandExecutor from "@effect/platform/CommandExecutor"
 import * as FileSystem from "@effect/platform/FileSystem"
 import * as Path from "@effect/platform/Path"
 import chalk from "chalk"
-import { pipe } from "effect"
 import * as Array from "effect/Array"
 import * as Chunk from "effect/Chunk"
 import * as Effect from "effect/Effect"
+import { pipe } from "effect/Function"
+import * as Option from "effect/Option"
 import * as Stream from "effect/Stream"
 import * as String from "effect/String"
 import * as Glob from "glob"
 import * as Configuration from "./Configuration.js"
-import type * as Domain from "./Domain.js"
+import * as Domain from "./Domain.js"
 import { DocgenError } from "./Error.js"
 import * as File from "./File.js"
-import { printModule } from "./Markdown.js"
+import { printModule, printPrintableForAI } from "./Markdown.js"
 import * as Parser from "./Parser.js"
 import * as Process from "./Process.js"
 
@@ -436,7 +437,9 @@ const getMarkdown = (modules: ReadonlyArray<Domain.Module>) =>
     const index = yield* _(getMarkdownIndex)
     const yml = yield* _(getMarkdownConfigYML)
     const moduleFiles = yield* _(getModuleMarkdownFiles(modules))
-    return [homepage, index, yml, ...moduleFiles]
+    const aiFiles = yield* _(maybeGetAIMarkdownFiles(modules))
+    const jsonFiles = yield* _(maybeGetJsonFiles(modules))
+    return [homepage, index, yml, ...moduleFiles, ...aiFiles, ...jsonFiles]
   })
 
 const getMarkdownHomepage = Effect.gen(function*(_) {
@@ -538,6 +541,14 @@ const getModuleMarkdownOutputPath = (module: Domain.Module) =>
       ))
   )
 
+const getAIMarkdownOutputPath = (module: Domain.Module, printable: Domain.Printable) =>
+  Effect.map(Effect.all([Configuration.Configuration, Path.Path]), ([config, path]) =>
+    path.join(
+      config.outDir,
+      "ai",
+      `${module.path.slice(1).join("-").replace(/\.ts$/, "")}-${printable.name}.md`
+    ))
+
 const getModuleMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
   Effect.forEach(modules, (module, order) =>
     Effect.gen(function*(_) {
@@ -546,6 +557,74 @@ const getModuleMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
       return File.createFile(outputPath, content, true)
     }))
 
+const getAIMarkdownFiles = (projectName: string, modules: ReadonlyArray<Domain.Module>) =>
+  Effect.gen(function*(_) {
+    const aiModules = pipe(
+      modules,
+      Array.flatMap((module) =>
+        pipe(
+          Domain.printablesFromModule(module),
+          Array.map((printable) => ({ module, printable }))
+        )
+      ),
+      Array.filter(({ printable }) => printable.description._tag === "Some")
+    )
+
+    return yield* _(Effect.forEach(aiModules, ({ module, printable }) =>
+      Effect.gen(function*(_) {
+        const outputPath = yield* _(getAIMarkdownOutputPath(module, printable))
+        const content = yield* _(printPrintableForAI(projectName, module, printable))
+        return File.createFile(outputPath, content, true)
+      })))
+  })
+
+const getJsonFiles = (projectName: string, modules: ReadonlyArray<Domain.Module>) =>
+  Effect.gen(function*() {
+    const config = yield* Configuration.Configuration
+    const path = yield* Path.Path
+    const printables = pipe(
+      modules,
+      Array.bindTo("module"),
+      Array.bind("printable", ({ module }) => Domain.printablesFromModule(module)),
+      Array.map(({ module, printable }) => {
+        return {
+          _tag: printable._tag,
+          module: {
+            name: module.name,
+            path: module.path
+          },
+          project: projectName,
+          name: printable.name,
+          description: Option.getOrNull(printable.description),
+          deprecated: printable.deprecated,
+          examples: printable.examples.map((example) => example.body),
+          since: Option.getOrNull(printable.since),
+          category: Option.getOrNull(printable.category),
+          signature: "signature" in printable ? printable.signature : null
+        }
+      })
+    )
+
+    return [File.createFile(
+      path.join(config.outDir, `${projectName.replace("/", "-")}.json`),
+      JSON.stringify(printables, null, 2),
+      true
+    )]
+  })
+
+const maybeGetAIMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
+  Effect.flatMap(
+    Configuration.Configuration,
+    (config) =>
+      config.enableAI ? getAIMarkdownFiles(config.projectName, modules) : Effect.succeed([])
+  )
+
+const maybeGetJsonFiles = (modules: ReadonlyArray<Domain.Module>) =>
+  Effect.flatMap(
+    Configuration.Configuration,
+    (config) => config.enableJson ? getJsonFiles(config.projectName, modules) : Effect.succeed([])
+  )
+
 const writeMarkdown = (files: ReadonlyArray<File.File>) =>
   Effect.gen(function*(_) {
     const config = yield* _(Configuration.Configuration)

src/Domain.ts

@@ -147,6 +147,19 @@ export interface Namespace extends NamedDoc {
   readonly namespaces: ReadonlyArray<Namespace>
 }
 
+/**
+ * @category model
+ * @since 1.0.0
+ */
+export type Printable =
+  | Class
+  | Constant
+  | Export
+  | Function
+  | Interface
+  | TypeAlias
+  | Namespace
+
 // -------------------------------------------------------------------------------------
 // constructors
 // -------------------------------------------------------------------------------------
@@ -282,6 +295,24 @@ export const createExport = (doc: NamedDoc, signature: string): Export => ({
   signature
 })
 
+// -------------------------------------------------------------------------------------
+// accessors
+// -------------------------------------------------------------------------------------
+
+/**
+ * @category accessors
+ * @since 1.0.0
+ */
+export const printablesFromModule = (module: Module): ReadonlyArray<Printable> =>
+  [
+    module.classes,
+    module.constants,
+    module.exports,
+    module.functions,
+    module.interfaces,
+    module.typeAliases
+  ].flat()
+
 /**
  * @category constructors
  * @since 1.0.0